Docs and error handling improvements (#87)

src/commonMain/kotlin/me/devnatan/yoki/Yoki.kt

@@ -13,7 +13,6 @@ import me.devnatan.yoki.resource.network.NetworkResource
 import me.devnatan.yoki.resource.secret.SecretResource
 import me.devnatan.yoki.resource.system.SystemResource
 import me.devnatan.yoki.resource.volume.VolumeResource
-import kotlin.jvm.JvmField
 import kotlin.jvm.JvmStatic
 
 /**
@@ -34,43 +33,41 @@ public inline fun Yoki(
 }
 
 /**
- * Yoki heart, where all resource accessors and other things are located.
+ * Yoki's heart where all resource accessors and other things are located.
  *
- * Create and configure a fresh Yoki instance by calling [Yoki.create] or [me.devnatan.yoki.Yoki]
+ * Create and configure a fresh Yoki instance by calling [Yoki.create] or [me.devnatan.yoki.Yoki].
  *
  * Note: This class must be a singleton, that is, don't instantiate it more than once in your code, and, implements
  * [Closeable] so be sure to [close] it after use.
  */
 @YokiDsl
-public class Yoki @PublishedApi internal constructor(
-    public val config: YokiConfig,
-) : Closeable {
+public class Yoki @PublishedApi internal constructor(public val config: YokiConfig) : Closeable {
 
     private val httpClient: HttpClient = createHttpClient(this)
     private val json: Json = Json {
         ignoreUnknownKeys = true
     }
     private val logger: Logger = createLogger()
 
-    @JvmField
+    @get:JvmName("containers")
     public val containers: ContainerResource = ContainerResource(httpClient, json, logger)
 
-    @JvmField
+    @get:JvmName("networks")
     public val networks: NetworkResource = NetworkResource(httpClient, json)
 
-    @JvmField
+    @get:JvmName("volumes")
     public val volumes: VolumeResource = VolumeResource(httpClient, json)
 
-    @JvmField
+    @get:JvmName("secrets")
     public val secrets: SecretResource = SecretResource(httpClient, json)
 
-    @JvmField
+    @get:JvmName("images")
     public val images: ImageResource = ImageResource(httpClient, json)
 
-    @JvmField
+    @get:JvmName("exec")
     public val exec: ExecResource = ExecResource(httpClient)
 
-    @JvmField
+    @get:JvmName("system")
     public val system: SystemResource = SystemResource(httpClient)
 
     public override fun close() {
@@ -84,47 +81,35 @@ public class Yoki @PublishedApi internal constructor(
          * Docker API version.
          */
         @JvmStatic
-        public fun create(): Yoki {
-            return Yoki()
-        }
+        public fun create(): Yoki = Yoki()
 
         /**
          * Creates a new Yoki instance.
          *
          * @param config Configurations to the instance.
          */
         @JvmStatic
-        public fun create(config: YokiConfig): Yoki {
-            return Yoki(config)
-        }
+        public fun create(config: YokiConfig): Yoki = Yoki(config)
 
         /**
          * Creates a new Yoki instance with the specified socket path configuration.
          *
          * @param socketPath The socket path that'll be used on connection.
          */
         @JvmStatic
-        public fun create(socketPath: String): Yoki {
-            return Yoki {
-                this.socketPath = socketPath
-            }
-        }
+        public fun create(socketPath: String): Yoki = Yoki { socketPath(socketPath) }
 
         /**
          * Creates a new Yoki instance using UNIX defaults configuration.
          */
         @JvmStatic
-        public fun createWithUnixDefaults(): Yoki {
-            return Yoki { useUnixDefaults() }
-        }
+        public fun createWithUnixDefaults(): Yoki = Yoki { useUnixDefaults() }
 
         /**
          * Creates a new Yoki instance using HTTP defaults configuration.
          */
         @JvmStatic
-        public fun createWithHttpDefaults(): Yoki {
-            return Yoki { useHttpDefaults() }
-        }
+        public fun createWithHttpDefaults(): Yoki = Yoki { useHttpDefaults() }
     }
 }
 

src/commonMain/kotlin/me/devnatan/yoki/YokiConfig.kt

@@ -4,7 +4,6 @@ import me.devnatan.yoki.net.DEFAULT_DOCKER_HTTP_SOCKET
 import me.devnatan.yoki.net.DEFAULT_DOCKER_UNIX_SOCKET
 import me.devnatan.yoki.net.HTTP_SOCKET_PREFIX
 import me.devnatan.yoki.net.UNIX_SOCKET_PREFIX
-import kotlin.jvm.JvmSynthetic
 
 /**
  * Class to store all Yoki configurations.
@@ -24,46 +23,31 @@ public class YokiConfig(
         check(socketPath.isNotBlank()) { "Socket path must be provided and cannot be blank" }
         check(apiVersion.isNotBlank()) { "Docker Remote API version must be provided and cannot be blank" }
     }
+
+    public companion object {
+        @JvmStatic
+        public fun builder(): YokiConfigBuilder = YokiConfigBuilder()
+    }
 }
 
 /**
  * Mutable builder for Yoki configuration.
  */
 public class YokiConfigBuilder {
 
-    public companion object {
-        /**
-         * Daemon socket to connect to.
-         */
-        private const val DOCKER_HOST_ENV_KEY = "DOCKER_HOST"
-
-        /**
-         * Override the negotiated Docker Remote API version.
-         */
-        private const val DOCKER_API_VERSION_ENV_KEY = "DOCKER_API_VERSION"
-
-        /**
-         * Minimum Docker Remote API version supported by Yoki.
-         */
-        public const val DEFAULT_DOCKER_API_VERSION: String = "1.41"
-    }
-
     /**
      * Docker socket file used to communicate with main Docker daemon.
      */
-    public var socketPath: String = ""
-        @JvmSynthetic
-        public set
+    private var socketPath: String = ""
 
     /**
      * The version of the Docker API that will be used during communication.
      */
-    public var apiVersion: String = envOrFallback(
+    private var apiVersion: String = envOrFallback(
         key = DOCKER_API_VERSION_ENV_KEY,
         fallback = DEFAULT_DOCKER_API_VERSION,
         prefix = null,
-    ) @JvmSynthetic
-    public set
+    )
 
     /**
      * Sets the Docker socket path.
@@ -166,4 +150,21 @@ public class YokiConfigBuilder {
             DEFAULT_DOCKER_HTTP_SOCKET
         }
     }
+
+    public companion object {
+        /**
+         * Daemon socket to connect to.
+         */
+        private const val DOCKER_HOST_ENV_KEY = "DOCKER_HOST"
+
+        /**
+         * Override the negotiated Docker Remote API version.
+         */
+        private const val DOCKER_API_VERSION_ENV_KEY = "DOCKER_API_VERSION"
+
+        /**
+         * Minimum Docker Remote API version supported by Yoki.
+         */
+        public const val DEFAULT_DOCKER_API_VERSION: String = "1.41"
+    }
 }

src/commonMain/kotlin/me/devnatan/yoki/models/IdOnlyResponse.kt

@@ -4,6 +4,4 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 @Serializable
-internal data class IdOnlyResponse(
-    @SerialName("Id") val id: String,
-)
+internal data class IdOnlyResponse(@SerialName("Id") val id: String)

src/commonMain/kotlin/me/devnatan/yoki/net/Http.kt

@@ -120,6 +120,7 @@ internal fun <T> Result<T>.mapFailureToHttpStatus(
         ?: exception
 }
 
+// TODO use Ktor exception handler instead
 internal inline fun requestCatching(
     vararg errors: Pair<HttpStatusCode, (YokiResponseException) -> Throwable>,
     request: () -> HttpResponse,

src/commonMain/kotlin/me/devnatan/yoki/resource/container/ContainerException.kt

@@ -11,6 +11,11 @@ public class ContainerAlreadyStartedException internal constructor(
     public val containerId: String,
 ) : ContainerException(cause)
 
+public class ContainerAlreadyStoppedException internal constructor(
+    cause: Throwable?,
+    public val containerId: String,
+) : ContainerException(cause)
+
 public class ContainerAlreadyExistsException internal constructor(
     cause: Throwable?,
     public val name: String,
@@ -26,6 +31,12 @@ public class ContainerRemoveConflictException internal constructor(
     public val containerId: String,
 ) : ContainerException(cause)
 
+public class ContainerRenameConflictException internal constructor(
+    cause: Throwable?,
+    public val containerId: String,
+    public val newName: String,
+) : ContainerException(cause)
+
 public class ContainerNotRunningException internal constructor(
     cause: Throwable?,
     public val containerId: String?,