Deprecate Resource.Builder.isExecutable in favor of defining a mode (#105)

Author: 05nelsonm

library/common-core/api/common-core.api

@@ -111,8 +111,9 @@ public final class io/matthewnelson/kmp/tor/common/core/PlatformResource$Builder
 public final class io/matthewnelson/kmp/tor/common/core/Resource {
 	public final field alias Ljava/lang/String;
 	public final field isExecutable Z
+	public final field mode Ljava/lang/String;
 	public final field platform Lio/matthewnelson/kmp/tor/common/core/PlatformResource;
-	public synthetic fun <init> (Ljava/lang/String;ZLio/matthewnelson/kmp/tor/common/core/PlatformResource;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Lio/matthewnelson/kmp/tor/common/core/PlatformResource;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun equals (Ljava/lang/Object;)Z
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
@@ -121,6 +122,7 @@ public final class io/matthewnelson/kmp/tor/common/core/Resource {
 public final class io/matthewnelson/kmp/tor/common/core/Resource$Builder {
 	public final field alias Ljava/lang/String;
 	public field isExecutable Z
+	public final fun mode (Ljava/lang/String;)Lio/matthewnelson/kmp/tor/common/core/Resource$Builder;
 	public final fun platform (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/kmp/tor/common/core/Resource$Builder;
 }
 

library/common-core/api/common-core.klib.api

@@ -40,6 +40,8 @@ final class io.matthewnelson.kmp.tor.common.core/Resource { // io.matthewnelson.
         final fun <get-alias>(): kotlin/String // io.matthewnelson.kmp.tor.common.core/Resource.alias.<get-alias>|<get-alias>(){}[0]
     final val isExecutable // io.matthewnelson.kmp.tor.common.core/Resource.isExecutable|{}isExecutable[0]
         final fun <get-isExecutable>(): kotlin/Boolean // io.matthewnelson.kmp.tor.common.core/Resource.isExecutable.<get-isExecutable>|<get-isExecutable>(){}[0]
+    final val mode // io.matthewnelson.kmp.tor.common.core/Resource.mode|{}mode[0]
+        final fun <get-mode>(): kotlin/String // io.matthewnelson.kmp.tor.common.core/Resource.mode.<get-mode>|<get-mode>(){}[0]
     final val platform // io.matthewnelson.kmp.tor.common.core/Resource.platform|{}platform[0]
         final fun <get-platform>(): io.matthewnelson.kmp.tor.common.core/PlatformResource // io.matthewnelson.kmp.tor.common.core/Resource.platform.<get-platform>|<get-platform>(){}[0]
 
@@ -55,6 +57,7 @@ final class io.matthewnelson.kmp.tor.common.core/Resource { // io.matthewnelson.
             final fun <get-isExecutable>(): kotlin/Boolean // io.matthewnelson.kmp.tor.common.core/Resource.Builder.isExecutable.<get-isExecutable>|<get-isExecutable>(){}[0]
             final fun <set-isExecutable>(kotlin/Boolean) // io.matthewnelson.kmp.tor.common.core/Resource.Builder.isExecutable.<set-isExecutable>|<set-isExecutable>(kotlin.Boolean){}[0]
 
+        final fun mode(kotlin/String?): io.matthewnelson.kmp.tor.common.core/Resource.Builder // io.matthewnelson.kmp.tor.common.core/Resource.Builder.mode|mode(kotlin.String?){}[0]
         final fun platform(kotlin/Function1<io.matthewnelson.kmp.tor.common.core/PlatformResource.Builder, kotlin/Unit>): io.matthewnelson.kmp.tor.common.core/Resource.Builder // io.matthewnelson.kmp.tor.common.core/Resource.Builder.platform|platform(kotlin.Function1<io.matthewnelson.kmp.tor.common.core.PlatformResource.Builder,kotlin.Unit>){}[0]
     }
 

library/common-core/src/commonMain/kotlin/io/matthewnelson/kmp/tor/common/core/Resource.kt

@@ -20,6 +20,7 @@ import io.matthewnelson.immutable.collections.toImmutableSet
 import io.matthewnelson.kmp.file.File
 import io.matthewnelson.kmp.file.IOException
 import io.matthewnelson.kmp.file.canonicalFile2
+import io.matthewnelson.kmp.file.chmod2
 import io.matthewnelson.kmp.file.delete2
 import io.matthewnelson.kmp.file.mkdirs2
 import io.matthewnelson.kmp.file.wrapIOException
@@ -36,11 +37,18 @@ public class Resource private constructor(
     @JvmField
     public val alias: String,
     @JvmField
-    public val isExecutable: Boolean,
+    public val mode: String,
     @JvmField
     public val platform: PlatformResource,
 ) {
 
+    @JvmField
+    @Deprecated("Use mode")
+    public val isExecutable: Boolean = when (mode.first()) {
+        '7', '5', '3', '1' -> true
+        else -> false
+    }
+
     @InternalKmpTorApi
     public class Config private constructor(
         @JvmField
@@ -205,11 +213,38 @@ public class Resource private constructor(
         public val alias: String
     ) {
 
+        private var _mode: String? = null
+
         @JvmField
+        @Deprecated("Use mode")
         public var isExecutable: Boolean = false
 
         private var platform: PlatformResource? = null
 
+        /**
+         * Set the file permissions for the newly extracted resource.
+         *
+         * @see [File.chmod2]
+         *
+         * @throws [IllegalArgumentException] If [value] is inappropriate.
+         * */
+        @KmpTorDsl
+        public fun mode(
+            value: String?,
+        ): Builder {
+            if (value == null) {
+                _mode = value
+                return this
+            }
+
+            require(value.length == 3) { "Invalid mode.length[${value.length}]. Must be 3 digits[0-7] (e.g. 764)" }
+            value.forEach { c ->
+                require(c in '0'..'7') { "Invalid mode[$value]. Must be 3 digits[0-7] (e.g. 764)" }
+            }
+            _mode = value
+            return this
+        }
+
         @KmpTorDsl
         public fun platform(
             block: PlatformResource.Builder.() -> Unit
@@ -221,8 +256,13 @@ public class Resource private constructor(
         @JvmSynthetic
         internal fun build(): Resource? {
             val p = platform ?: return null
+            var m = _mode
+            if (m == null) {
+                @Suppress("DEPRECATION")
+                m = if (isExecutable) "500" else "400"
+            }
 
-            return Resource(alias, isExecutable, p)
+            return Resource(alias, m, p)
         }
     }
 
@@ -232,8 +272,8 @@ public class Resource private constructor(
         appendLine("Resource: [")
         appendIndent("alias: ")
         appendLine(alias)
-        appendIndent("isExecutable: ")
-        appendLine(isExecutable)
+        appendIndent("mode: ")
+        appendLine(mode)
         appendIndent("platform: [")
         appendLine()
 

library/common-core/src/commonTest/kotlin/io/matthewnelson/kmp/tor/common/core/CommonResourceUnitTest.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2025 Matthew Nelson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+package io.matthewnelson.kmp.tor.common.core
+
+import io.matthewnelson.kmp.tor.common.api.InternalKmpTorApi
+import kotlin.test.Test
+import kotlin.test.assertFailsWith
+
+@OptIn(InternalKmpTorApi::class)
+class CommonResourceUnitTest {
+
+    @Test
+    fun givenMode_whenInappropriate_thenThrowsIllegalArgumentException() {
+        val b = Resource.Builder("alias")
+
+        assertFailsWith<IllegalArgumentException> { b.mode("") }
+        assertFailsWith<IllegalArgumentException> { b.mode("800") }
+        assertFailsWith<IllegalArgumentException> { b.mode("2000") }
+    }
+}

library/common-core/src/jsWasmJsMain/kotlin/io/matthewnelson/kmp/tor/common/core/internal/JsWasmJsPlatform.kt

@@ -57,7 +57,7 @@ internal actual fun Resource.extractTo(destinationDir: File, onlyIfDoesNotExist:
         }
     }
 
-    val excl = OpenExcl.MustCreate.of(mode = if (isExecutable) "500" else "400")
+    val excl = OpenExcl.MustCreate.of(mode = mode)
     try {
         destination.write(excl, buffer)
     } catch (e: IOException) {

library/common-core/src/jsWasmJsTest/kotlin/io/matthewnelson/kmp/tor/common/core/JsResourceUnitTest.kt

@@ -34,7 +34,7 @@ class JsResourceUnitTest {
         val alias = "hello_gzip"
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform {
                     moduleName = "kmp-tor-core-test-resources"
                     resourcePath = "/io/matthewnelson/kmp/tor/core/resource/hello_world.gz"
@@ -64,7 +64,7 @@ class JsResourceUnitTest {
         val alias = "hello"
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform {
                     moduleName = "kmp-tor-core-test-resources"
                     resourcePath = "/io/matthewnelson/kmp/tor/core/resource/hello_world"

library/common-core/src/jvmMain/kotlin/io/matthewnelson/kmp/tor/common/core/internal/-JvmPlatform.kt

@@ -60,7 +60,7 @@ internal actual fun Resource.extractTo(destinationDir: File, onlyIfDoesNotExist:
         }
     }
 
-    val excl = OpenExcl.MustCreate.of(mode = if (isExecutable) "500" else "400")
+    val excl = OpenExcl.MustCreate.of(mode = mode)
 
     try {
         resourceStream.use { iStream ->

library/common-core/src/jvmTest/kotlin/io/matthewnelson/kmp/tor/common/core/JvmResourceUnitTest.kt

@@ -33,7 +33,7 @@ class JvmResourceUnitTest {
         val alias = "hello_gzip"
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform {
                     resourceClass = JvmResourceUnitTest::class.java
                     resourcePath = "/io/matthewnelson/kmp/tor/common/core/hello_world.gz"
@@ -63,7 +63,7 @@ class JvmResourceUnitTest {
         val alias = "hello"
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform {
                     resourceClass = JvmResourceUnitTest::class.java
                     resourcePath = "/io/matthewnelson/kmp/tor/common/core/hello_world"

library/common-core/src/nativeMain/kotlin/io/matthewnelson/kmp/tor/common/core/internal/NativePlatform.kt

@@ -62,7 +62,7 @@ internal actual fun Resource.extractTo(destinationDir: File, onlyIfDoesNotExist:
     dest.delete2(ignoreReadOnly = true)
     destFinal?.delete2(ignoreReadOnly = true)
 
-    val excl = OpenExcl.MustCreate.of(mode = if (isExecutable) "500" else "400")
+    val excl = OpenExcl.MustCreate.of(mode = mode)
     try {
         dest.openWrite(excl = if (destFinal == null) excl else null).use { s ->
             platform.nativeResource.read { buf, len ->

library/common-core/src/nativeTest/kotlin/io/matthewnelson/kmp/tor/common/core/NativeResourceUnitTest.kt

@@ -50,7 +50,7 @@ class NativeResourceUnitTest {
 
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform { nativeResource = resource_LoremIpsum_gz }
             }
         }
@@ -81,7 +81,7 @@ class NativeResourceUnitTest {
 
         val config = Resource.Config.create {
             resource(alias) {
-                isExecutable = false
+                mode("400")
                 platform { nativeResource = resource_lorem_ipsum }
             }
         }