Rename ConfiguBuilderCallback -> ConfigCallback (#528)

library/runtime-core/api/runtime-core.api

@@ -1,7 +1,6 @@
 public final class io/matthewnelson/kmp/tor/runtime/core/BlocksKt {
 	public static final fun apply (Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/core/ItBlock;)Ljava/lang/Object;
 	public static final fun apply (Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/core/ThisBlock;)Ljava/lang/Object;
-	public static final fun apply (Ljava/lang/Object;Ljava/lang/Object;Lio/matthewnelson/kmp/tor/runtime/core/ThisBlock$WithIt;)Ljava/lang/Object;
 }
 
 public abstract interface class io/matthewnelson/kmp/tor/runtime/core/Destroyable {
@@ -231,10 +230,6 @@ public abstract interface class io/matthewnelson/kmp/tor/runtime/core/ThisBlock
 	public abstract fun invoke (Ljava/lang/Object;)V
 }
 
-public abstract interface class io/matthewnelson/kmp/tor/runtime/core/ThisBlock$WithIt {
-	public abstract fun invoke (Ljava/lang/Object;Ljava/lang/Object;)V
-}
-
 public abstract class io/matthewnelson/kmp/tor/runtime/core/TorEvent : io/matthewnelson/kmp/tor/runtime/core/Event {
 	public static final field Companion Lio/matthewnelson/kmp/tor/runtime/core/TorEvent$Companion;
 	public synthetic fun <init> (Ljava/lang/String;Lkotlin/jvm/internal/DefaultConstructorMarker;)V

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

@@ -39,40 +39,10 @@ package io.matthewnelson.kmp.tor.runtime.core
  *     });
  *
  * @see [ItBlock]
- * @see [WithIt]
  * @see [apply]
  * */
 public fun interface ThisBlock<in This: Any> {
     public operator fun This.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 This: Any, in It: Any?> {
-        public operator fun This.invoke(it: It)
-    }
 }
 
 /**
@@ -97,7 +67,6 @@ public fun interface ThisBlock<in This: Any> {
  *     });
  *
  * @see [ThisBlock]
- * @see [ThisBlock.WithIt]
  * @see [apply]
  * */
 public fun interface ItBlock<in It: Any?> {
@@ -110,12 +79,6 @@ public inline fun <This: Any> This.apply(block: ThisBlock<This>): This {
     return this
 }
 
-@Suppress("NOTHING_TO_INLINE")
-public inline fun <This: Any, It: Any?> This.apply(it: It, block: ThisBlock.WithIt<This, It>): This {
-    with(block) { invoke(it) }
-    return this
-}
-
 @Suppress("NOTHING_TO_INLINE")
 public inline fun <It: Any?> It.apply(block: ItBlock<It>): It {
     block(this)

library/runtime/api/runtime.api

@@ -51,13 +51,13 @@ public abstract class io/matthewnelson/kmp/tor/runtime/ActionJob : io/matthewnel
 	public final fun isStop ()Z
 }
 
-public abstract interface class io/matthewnelson/kmp/tor/runtime/ConfigBuilderCallback : io/matthewnelson/kmp/tor/runtime/core/ThisBlock$WithIt {
+public abstract interface class io/matthewnelson/kmp/tor/runtime/ConfigCallback {
+	public abstract fun invoke (Lio/matthewnelson/kmp/tor/runtime/core/config/TorConfig$BuilderScope;Lio/matthewnelson/kmp/tor/runtime/TorRuntime$Environment;)V
 }
 
-public final class io/matthewnelson/kmp/tor/runtime/ConfigBuilderCallback$Defaults : io/matthewnelson/kmp/tor/runtime/ConfigBuilderCallback {
+public final class io/matthewnelson/kmp/tor/runtime/ConfigCallback$Defaults : io/matthewnelson/kmp/tor/runtime/ConfigCallback {
 	public synthetic fun <init> (Lio/matthewnelson/kmp/tor/core/api/ResourceInstaller$Paths$Tor;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun invoke (Lio/matthewnelson/kmp/tor/runtime/core/config/TorConfig$BuilderScope;Lio/matthewnelson/kmp/tor/runtime/TorRuntime$Environment;)V
-	public synthetic fun invoke (Ljava/lang/Object;Ljava/lang/Object;)V
 }
 
 public abstract interface class io/matthewnelson/kmp/tor/runtime/FileID {
@@ -360,7 +360,7 @@ public abstract interface class io/matthewnelson/kmp/tor/runtime/TorRuntime : io
 public final class io/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope {
 	public field networkObserver Lio/matthewnelson/kmp/tor/runtime/NetworkObserver;
 	public synthetic fun <init> (Lio/matthewnelson/kmp/tor/runtime/TorRuntime$Environment;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun config (Lio/matthewnelson/kmp/tor/runtime/ConfigBuilderCallback;)Lio/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope;
+	public final fun config (Lio/matthewnelson/kmp/tor/runtime/ConfigCallback;)Lio/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope;
 	public final fun observer (Lio/matthewnelson/kmp/tor/runtime/RuntimeEvent$Observer;)Lio/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope;
 	public final fun observer (Lio/matthewnelson/kmp/tor/runtime/core/TorEvent$Observer;)Lio/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope;
 	public final fun observerStatic (Lio/matthewnelson/kmp/tor/runtime/RuntimeEvent;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/TorRuntime$BuilderScope;

library/runtime/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ConfigBuilderCallback.kt → library/runtime/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/ConfigCallback.kt

@@ -21,7 +21,6 @@ import io.matthewnelson.kmp.file.File
 import io.matthewnelson.kmp.file.resolve
 import io.matthewnelson.kmp.tor.core.api.ResourceInstaller
 import io.matthewnelson.kmp.tor.core.api.annotation.InternalKmpTorApi
-import io.matthewnelson.kmp.tor.runtime.core.ThisBlock
 import io.matthewnelson.kmp.tor.runtime.core.config.TorConfig
 import io.matthewnelson.kmp.tor.runtime.core.config.TorOption
 import io.matthewnelson.kmp.tor.runtime.core.config.builder.BuilderScopePort
@@ -33,7 +32,7 @@ import kotlin.jvm.JvmSynthetic
  *
  * e.g.
  *
- *     ConfigBuilderCallback { environment ->
+ *     ConfigCallback { environment ->
  *         TorOption.__SocksPort.configure { auto() }
  *
  *         TorOption.ClientOnionAuthDir.configure(directory =
@@ -46,31 +45,38 @@ import kotlin.jvm.JvmSynthetic
  *
  * @see [TorRuntime.BuilderScope.config]
  * */
-public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderScope, TorRuntime.Environment> {
+public fun interface ConfigCallback {
 
-    // TODO: Delete ThisBlock.WithIt. It's only used here.
-    // TODO: Rename to something better...
+    public operator fun TorConfig.BuilderScope.invoke(environment: TorRuntime.Environment)
 
     /**
-     * After all [ConfigBuilderCallback] have been applied, defaults
-     * are then configured in order to ensure minimum settings required
-     * for [TorRuntime] are had.
+     * After all [ConfigCallback] for [TorRuntime.BuilderScope.config] have
+     * been applied, defaults are then configured in order to ensure minimum
+     * settings required for [TorRuntime] are had.
      * */
     public class Defaults private constructor(
         private val paths: ResourceInstaller.Paths.Tor,
-    ): ConfigBuilderCallback {
+    ): ConfigCallback {
 
-        public override fun TorConfig.BuilderScope.invoke(it: TorRuntime.Environment) {
-            val dataDirectory = configureFilesystem(it)
+        public override fun TorConfig.BuilderScope.invoke(environment: TorRuntime.Environment) {
+            val dataDirectory = configureFilesystem(environment)
             configureControlAuthentication(dataDirectory)
             ensureSocksPort()
-            ensureControlPort(it.workDirectory)
+            ensureControlPort(environment.workDirectory)
             configureDormancy()
             configureRuntimeRequired()
         }
 
         /**
-         * TODO
+         * Ensures that the following [TorOption] are present. If they
+         * are not, then they are defined using tor's defaults and the
+         * [TorRuntime.Environment].
+         *
+         *  - [TorOption.DataDirectory]
+         *  - [TorOption.CacheDirectory]
+         *  - [TorOption.ControlPortWriteToFile]
+         *  - [TorOption.GeoIPFile]
+         *  - [TorOption.GeoIPv6File]
          * */
         protected fun TorConfig.BuilderScope.configureFilesystem(environment: TorRuntime.Environment): File {
             @OptIn(InternalKmpTorApi::class)
@@ -101,7 +107,10 @@ public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderSc
         }
 
         /**
-         * TODO
+         * Ensures that controller authentication options are present.
+         * If they are not, then [TorOption.CookieAuthentication] and
+         * [TorOption.CookieAuthFile] are defined utilizing the
+         * [TorOption.DataDirectory] location.
          * */
         protected fun TorConfig.BuilderScope.configureControlAuthentication(dataDirectory: File) {
             @OptIn(InternalKmpTorApi::class)
@@ -141,7 +150,7 @@ public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderSc
         }
 
         /**
-         * If [TorOption.SocksPort] or [TorOption.__SocksPort] is
+         * If [TorOption.SocksPort] or [TorOption.__SocksPort] are
          * not defined, add [TorOption.__SocksPort] (with its default
          * of `9050`) so that it can be checked for availability on
          * the host and set to `auto`, if needed.
@@ -167,7 +176,7 @@ public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderSc
 
         /**
          * If [TorOption.ControlPort] or [TorOption.__ControlPort] have
-         * not been defined, add [TorOption.__ControlPort]. This will
+         * not been defined, [TorOption.__ControlPort] is added. This will
          * always prefer configuring the option as a Unix Socket, if
          * available for the host and runtime environment.
          *
@@ -223,7 +232,12 @@ public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderSc
         }
 
         /**
-         * TODO
+         * Defines (and overrides if present) the following settings required for runtime
+         * operations.
+         *  - [TorOption.DisableNetwork]
+         *  - [TorOption.RunAsDaemon]
+         *  - [TorOption.__OwningControllerProcess]
+         *  - [TorOption.__ReloadTorrcOnSIGHUP]
          * */
         protected fun TorConfig.BuilderScope.configureRuntimeRequired() {
             TorOption.DisableNetwork.configure(true)
@@ -233,11 +247,19 @@ public fun interface ConfigBuilderCallback: ThisBlock.WithIt<TorConfig.BuilderSc
         }
 
         internal companion object {
-            
+
             @JvmSynthetic
-            internal fun of(
+            internal fun apply(
+                scope: TorConfig.BuilderScope,
+                environment: TorRuntime.Environment,
                 paths: ResourceInstaller.Paths.Tor,
-            ): Defaults = Defaults(paths)
+            ) {
+                with(scope) {
+                    with(Defaults(paths)) {
+                        invoke(environment)
+                    }
+                }
+            }
         }
     }
 }

library/runtime/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/TorRuntime.kt

@@ -113,7 +113,7 @@ public sealed interface TorRuntime:
     @KmpTorDsl
     public class BuilderScope private constructor(private val environment: Environment) {
 
-        private val config = mutableSetOf<ConfigBuilderCallback>()
+        private val config = mutableSetOf<ConfigCallback>()
         private val requiredTorEvents = mutableSetOf<TorEvent>()
         private val observersTorEvent = mutableSetOf<TorEvent.Observer>()
         private val observersRuntimeEvent = mutableSetOf<RuntimeEvent.Observer<*>>()
@@ -142,15 +142,15 @@ public sealed interface TorRuntime:
          * of [Action.StartDaemon] or [Action.RestartDaemon].
          *
          * **NOTE:** This can be omitted as a minimum viable configuration
-         * is always created. See [ConfigBuilderCallback.Defaults] for what
+         * is always created. See [ConfigCallback.Defaults] for what
          * settings are automatically applied.
          *
          * **NOTE:** [block] should not contain any external contextual
          * references, such as Android Activity Context.
          * */
         @KmpTorDsl
         public fun config(
-            block: ConfigBuilderCallback,
+            block: ConfigCallback,
         ): BuilderScope {
             config.add(block)
             return this

library/runtime/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/internal/TorConfigGenerator.kt

@@ -21,7 +21,7 @@ import io.matthewnelson.immutable.collections.toImmutableSet
 import io.matthewnelson.kmp.file.IOException
 import io.matthewnelson.kmp.tor.core.api.ResourceInstaller
 import io.matthewnelson.kmp.tor.core.api.annotation.InternalKmpTorApi
-import io.matthewnelson.kmp.tor.runtime.ConfigBuilderCallback
+import io.matthewnelson.kmp.tor.runtime.ConfigCallback
 import io.matthewnelson.kmp.tor.runtime.FileID
 import io.matthewnelson.kmp.tor.runtime.FileID.Companion.toFIDString
 import io.matthewnelson.kmp.tor.runtime.RuntimeEvent.*
@@ -33,7 +33,6 @@ import io.matthewnelson.kmp.tor.runtime.core.address.LocalHost
 import io.matthewnelson.kmp.tor.runtime.core.address.Port
 import io.matthewnelson.kmp.tor.runtime.core.address.Port.Ephemeral.Companion.toPortEphemeral
 import io.matthewnelson.kmp.tor.runtime.core.address.IPSocketAddress.Companion.toIPSocketAddressOrNull
-import io.matthewnelson.kmp.tor.runtime.core.apply
 import io.matthewnelson.kmp.tor.runtime.core.config.TorConfig
 import io.matthewnelson.kmp.tor.runtime.core.config.TorOption
 import io.matthewnelson.kmp.tor.runtime.core.config.TorSetting.Companion.filterByAttribute
@@ -50,7 +49,7 @@ import io.matthewnelson.kmp.tor.runtime.core.config.builder.RealBuilderScopeTorC
 @OptIn(InternalKmpTorApi::class)
 internal class TorConfigGenerator internal constructor(
     internal val environment: TorRuntime.Environment,
-    config: Set<ConfigBuilderCallback>,
+    config: Set<ConfigCallback>,
     private val isPortAvailable: suspend (LocalHost, Port) -> Boolean,
 ): FileID by environment {
 
@@ -79,8 +78,8 @@ internal class TorConfigGenerator internal constructor(
         }
 
         // Apply library consumers' configuration(s)
-        config.forEach { block -> apply(environment, block) }
-        apply(environment, ConfigBuilderCallback.Defaults.of(paths))
+        config.forEach { block -> with(block) { invoke(environment) } }
+        ConfigCallback.Defaults.apply(this, environment, paths)
     }
 
     private suspend fun TorConfig.validateTCPPorts(

library/runtime/src/commonTest/kotlin/io/matthewnelson/kmp/tor/runtime/internal/TorConfigGeneratorUnitTest.kt

@@ -20,7 +20,7 @@ import io.matthewnelson.kmp.file.path
 import io.matthewnelson.kmp.file.resolve
 import io.matthewnelson.kmp.tor.core.api.ResourceInstaller
 import io.matthewnelson.kmp.tor.core.api.ResourceInstaller.Paths
-import io.matthewnelson.kmp.tor.runtime.ConfigBuilderCallback
+import io.matthewnelson.kmp.tor.runtime.ConfigCallback
 import io.matthewnelson.kmp.tor.runtime.RuntimeEvent
 import io.matthewnelson.kmp.tor.runtime.TorRuntime
 import io.matthewnelson.kmp.tor.runtime.core.address.LocalHost
@@ -75,8 +75,8 @@ class TorConfigGeneratorUnitTest {
         var invocations = 0
         newGenerator(
             config = setOf(
-                ConfigBuilderCallback { _ -> invocations++ },
-                ConfigBuilderCallback { _ -> invocations++ },
+                ConfigCallback { _ -> invocations++ },
+                ConfigCallback { _ -> invocations++ },
             )
         ).generate(notifier)
 
@@ -104,7 +104,7 @@ class TorConfigGeneratorUnitTest {
         // socks port at 9050 is automatically added
         val config = newGenerator(
             config = setOf(
-                ConfigBuilderCallback {
+                ConfigCallback {
                     TorOption.__DNSPort.configure { port(1080.toPortEphemeral()) }
                 }
             ),
@@ -121,7 +121,7 @@ class TorConfigGeneratorUnitTest {
     fun givenCookieAuthenticationEnabled_whenNoCookieAuthFile_thenAddsDefault() = runTest {
         val config = newGenerator(
             config = setOf(
-                ConfigBuilderCallback {
+                ConfigCallback {
                     TorOption.CookieAuthentication.configure(true)
                 }
             )
@@ -137,7 +137,7 @@ class TorConfigGeneratorUnitTest {
 
         val setting = newGenerator(
             config = setOf(
-                ConfigBuilderCallback {
+                ConfigCallback {
                     TorOption.CookieAuthentication.configure(true)
                     TorOption.CookieAuthFile.configure(expected)
                 }
@@ -157,7 +157,7 @@ class TorConfigGeneratorUnitTest {
 
         val setting = newGenerator(
             config = setOf(
-                ConfigBuilderCallback {
+                ConfigCallback {
                     TorOption.CookieAuthentication.configure(false)
                     TorOption.CookieAuthFile.configure(expected)
                 }
@@ -182,7 +182,7 @@ class TorConfigGeneratorUnitTest {
     fun givenAuthCookieFile_whenNoCookieAuthentication_thenEnablesIt() = runTest {
         val setting = newGenerator(
             config = setOf(
-                ConfigBuilderCallback {
+                ConfigCallback {
                     TorOption.CookieAuthFile.configure(file =
                         environment.workDirectory
                             .resolve("data")
@@ -208,7 +208,7 @@ class TorConfigGeneratorUnitTest {
 
     private fun newGenerator(
         environment: TorRuntime.Environment = this.environment,
-        config: Set<ConfigBuilderCallback> = emptySet(),
+        config: Set<ConfigCallback> = emptySet(),
         isPortAvailable: suspend (LocalHost, Port) -> Boolean = { _, _ -> true },
     ): TorConfigGenerator = TorConfigGenerator(
         environment,