Stub in TorRuntime APIs (#329)

gradle/libs.versions.toml

@@ -1,4 +1,5 @@
 [versions]
+androidx-startup = "1.1.1"
 androidx-test-core = "1.5.0"
 androidx-test-runner = "1.5.2"
 
@@ -10,12 +11,13 @@ gradle-kmp-configuration = "0.1.7"
 gradle-kotlin = "1.9.21"
 gradle-publish-maven = "0.25.3"
 
-kmp-tor-core = "2.0.0-alpha05"
+kmp-tor-core = "2.0.0-alpha06"
 kmp-tor-resource = "408.10.0-SNAPSHOT"
-
+kotlincrypto-hash = "0.4.0"
 kotlinx-coroutines = "1.7.3"
 
 [libraries]
+androidx-startup-runtime = { module = "androidx.startup:startup-runtime", version.ref = "androidx-startup" }
 androidx-test-core = { module = "androidx.test:core", version.ref = "androidx-test-core" }
 androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" }
 
@@ -29,8 +31,9 @@ gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.
 gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" }
 
 kmp-tor-core-api = { module = "io.matthewnelson.kmp-tor:core-api", version.ref = "kmp-tor-core" }
+kmp-tor-core-lib-locator = { module = "io.matthewnelson.kmp-tor:core-lib-locator", version.ref = "kmp-tor-core" }
 kmp-tor-core-resource = { module = "io.matthewnelson.kmp-tor:core-resource", version.ref = "kmp-tor-core" }
-
+kotlincrypto-hash-sha2 = { module = "org.kotlincrypto.hash:sha2", version.ref = "kotlincrypto-hash" }
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-javafx = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-javafx", version.ref = "kotlinx-coroutines" }

library/runtime-ctrl-api/api/runtime-ctrl-api.api

@@ -1,5 +1,6 @@
 public final class io/matthewnelson/kmp/tor/runtime/ctrl/api/BlocksKt {
 	public static final fun apply (Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/ctrl/api/ItBlock;)Ljava/lang/Object;
+	public static final fun apply (Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/ctrl/api/ThisBlock$WithIt;Ljava/lang/Object;)Ljava/lang/Object;
 	public static final fun apply (Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/ctrl/api/ThisBlock;)Ljava/lang/Object;
 }
 
@@ -16,6 +17,10 @@ public abstract interface class io/matthewnelson/kmp/tor/runtime/ctrl/api/ThisBl
 	public abstract fun invoke (Ljava/lang/Object;)V
 }
 
+public abstract interface class io/matthewnelson/kmp/tor/runtime/ctrl/api/ThisBlock$WithIt {
+	public abstract fun invoke (Ljava/lang/Object;Ljava/lang/Object;)V
+}
+
 public final class io/matthewnelson/kmp/tor/runtime/ctrl/api/TorConfig {
 	public static final field Companion Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorConfig$Companion;
 	public final field settings Ljava/util/Set;

library/runtime-ctrl-api/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ctrl/api/Blocks.kt

@@ -19,52 +19,85 @@ package io.matthewnelson.kmp.tor.runtime.ctrl.api
 
 /**
  * Helper for non-Kotlin consumers instead of using
- * `T.() -> Unit` which would force a return of `Unit`.
  *
- * e.g.
+ *     T.() -> Unit
+ *
+ * which would force a return of `Unit`.
+ *
+ * e.g. (Kotlin)
+ *
+ *     My.Builder {
+ *         add(My.Factory) { enable = true }
+ *     }
+ *
+ * e.g. (Java)
  *
- *     // Java
  *     My.Builder(b -> {
  *         b.add(My.Factory.Companion, s -> {
  *             s.enable = true;
  *         });
  *     });
  *
- *     // Kotlin
- *     My.Builder {
- *         add(My.Factory) {
- *             enable = true
- *         }
- *     }
- *
  * @see [ItBlock]
+ * @see [WithIt]
  * @see [apply]
  * */
 public fun interface ThisBlock<in T: Any> {
     public operator fun T.invoke()
+
+    /**
+     * Helper for non-Kotlin consumers instead of using
+     *
+     *     T.(V) -> Unit
+     *
+     * which would force a return of `Unit`.
+     * 
+     * e.g. (Kotlin)
+     * 
+     *     My.Builder {
+     *         add(My.Factory) { arg -> enable = arg.someLogic() }
+     *     }
+     *
+     * e.g. (Java)
+     *
+     *     My.Builder(b -> {
+     *         b.add(My.Factory.Companion, (s, arg) -> {
+     *             s.enable = arg.someLogic();
+     *         });
+     *     });
+     * 
+     * @see [ThisBlock]
+     * @see [ItBlock]
+     * @see [apply]
+     * */
+    public fun interface WithIt<in T: Any, in V: Any> {
+        public operator fun T.invoke(it: V)
+    }
 }
 
 /**
  * Helper for non-Kotlin consumers instead of using
- * `(T) -> Unit` which would force a return of `Unit`.
  *
- * e.g.
+ *     (T) -> Unit
+ *
+ * which would force a return of `Unit`.
+ *
+ * e.g. (Kotlin)
+ *
+ *     My.Builder {
+ *         it.add(My.Factory) { s -> s.enable = true }
+ *     }
+ *
+ * e.g. (Java)
  *
- *     // Java
  *     My.Builder(b -> {
  *         b.add(My.Factory.Companion, s -> {
  *             s.enable = true;
  *         });
  *     });
  *
- *     // Kotlin
- *     My.Builder {
- *         it.add(My.Factory) { s ->
- *             s.enable = true
- *         }
- *     }
- *
  * @see [ThisBlock]
+ * @see [ThisBlock.WithIt]
  * @see [apply]
  * */
 public fun interface ItBlock<in T: Any> {
@@ -77,6 +110,12 @@ public inline fun <T: Any> T.apply(block: ThisBlock<T>): T {
     return this
 }
 
+@Suppress("NOTHING_TO_INLINE")
+public inline fun <T: Any, V: Any> T.apply(block: ThisBlock.WithIt<T, V>, arg: V): T {
+    with(block) { invoke(arg) }
+    return this
+}
+
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <T: Any> T.apply(block: ItBlock<T>): T {
     block(this)

library/runtime-ctrl-api/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent.kt

@@ -189,17 +189,18 @@ public enum class TorEvent {
 
     /**
      * Create an observer for the given [TorEvent]
+     * to register via [Processor.add]
      *
      * e.g. (Kotlin)
      *
-     *     val bwObserver = TorEvent.BW.observer { event ->
-     *         updateNotification(event.formatBandwidth())
+     *     TorEvent.BW.observer { output ->
+     *         updateNotification(output.formatBandwidth())
      *     }
      *
      * e.g. (Java)
      *
-     *     TorEvent.Observer bwObserver = TorEvent.BW.observer(e -> {
-     *         updateNotification(formatBandwidth(e));
+     *     TorEvent.BW.observer(output -> {
+     *         updateNotification(formatBandwidth(output));
      *     });
      *
      * @param [block] the callback to pass the event text to
@@ -209,22 +210,23 @@ public enum class TorEvent {
     ): Observer = observer("", block)
 
     /**
-     * Create an observer for the given [TorEvent] and [tag].
+     * Create an observer for the given [TorEvent] and [tag]
+     * to register via [Processor.add]
      *
      * This is useful for lifecycle aware components, all of which
      * can be removed with a single call using the [tag] upon
      * component destruction.
      *
      * e.g. (Kotlin)
      *
-     *     val bwObserver = TorEvent.BW.observer("my service") { event ->
-     *         updateNotification(event.formatBandwidth())
+     *     TorEvent.BW.observer("my service") { output ->
+     *         updateNotification(output.formatBandwidth())
      *     }
      *
      * e.g. (Java)
      *
-     *     TorEvent.Observer bwObserver = TorEvent.BW.observer("my service", e -> {
-     *         updateNotification(formatBandwidth(e));
+     *     TorEvent.BW.observer("my service", output -> {
+     *         updateNotification(formatBandwidth(output));
      *     });
      *
      * @param [tag] Any non-blank string value

library/runtime-ctrl-api/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ctrl/api/address/IPAddress.kt

@@ -23,6 +23,9 @@ import kotlin.jvm.JvmStatic
 
 /**
  * Base abstraction for denoting a String value as an ip address
+ *
+ * @see [V4]
+ * @see [V6]
  * */
 public sealed class IPAddress private constructor(value: String): Address(value) {
 

library/runtime-ctrl-api/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ctrl/api/address/OnionAddress.kt

@@ -29,6 +29,8 @@ import kotlin.jvm.JvmStatic
 
 /**
  * Base abstraction for denoting a String value as a `.onion` address
+ *
+ * @see [V3]
  * */
 public sealed class OnionAddress private constructor(value: String): Address(value) {
 

library/runtime-ctrl-api/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ctrl/api/address/Port.kt

@@ -23,6 +23,8 @@ import kotlin.jvm.JvmStatic
 
 /**
  * Holder for a port between 0 and 65535 (inclusive)
+ *
+ * @see [Proxy]
  * */
 public open class Port private constructor(
     @JvmField

library/runtime-ctrl/api/runtime-ctrl.api

@@ -1,8 +1,12 @@
 public abstract class io/matthewnelson/kmp/tor/runtime/ctrl/AbstractTorEventProcessor : io/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent$Processor {
+	protected static final field Companion Lio/matthewnelson/kmp/tor/runtime/ctrl/AbstractTorEventProcessor$Companion;
 	public final fun add (Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent$Observer;)V
 	public final fun add ([Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent$Observer;)V
 	public fun clearObservers ()V
+	protected final fun isDestroyed ()Z
+	protected final fun isStaticTag (Ljava/lang/String;)Z
 	protected final fun notifyObservers (Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent;Ljava/lang/String;)V
+	protected fun onDestroy ()V
 	public final fun remove (Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent$Observer;)V
 	public final fun remove ([Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent$Observer;)V
 	public final fun removeAll (Lio/matthewnelson/kmp/tor/runtime/ctrl/api/TorEvent;)V
@@ -11,3 +15,6 @@ public abstract class io/matthewnelson/kmp/tor/runtime/ctrl/AbstractTorEventProc
 	protected final fun withObservers (Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 }
 
+protected final class io/matthewnelson/kmp/tor/runtime/ctrl/AbstractTorEventProcessor$Companion {
+}
+