feat(common): decodeBinaryString, allowing ISO8859-1 or Base64

Author: iseki0

src/commonMain/kotlin/space/iseki/bencoding/Bencode.kt

@@ -23,28 +23,28 @@ interface Bencode : BinaryFormat {
 
 
     companion object : Bencode {
-        private val defaultOptions = BencodeOptionsData()
+        private val defaultOptions = BencodeConfigureScope0().build()
         override val options: BencodeOptions
             get() = defaultOptions
     }
 
 }
 
-fun Bencode(configure: BencodeConfigureScope.() -> Unit): Bencode {
-    val scope = object : BencodeConfigureScope {
-        override var floatStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow
-        override var doubleStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow
-    }
-    scope.configure()
-    return object : Bencode {
-        override val options: BencodeOptions = BencodeOptionsData(scope.floatStrategy, scope.doubleStrategy)
-    }
+fun Bencode(configure: BencodeConfigureScope.() -> Unit): Bencode = object : Bencode {
+    override val options: BencodeOptions = BencodeConfigureScope0().apply(configure).build()
 }
 
 
 interface BencodeConfigureScope {
     var floatStrategy: FloatNumberStrategy
     var doubleStrategy: FloatNumberStrategy
+    var binaryStringStrategy: BinaryStringStrategy
 }
 
+private class BencodeConfigureScope0 : BencodeConfigureScope {
+    override var floatStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow
+    override var doubleStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow
+    override var binaryStringStrategy: BinaryStringStrategy = BinaryStringStrategy.ISO88591
+    fun build() = BencodeOptionsData(floatStrategy, doubleStrategy, binaryStringStrategy)
+}
 

src/commonMain/kotlin/space/iseki/bencoding/BencodeCompositeDecoder.kt

@@ -7,4 +7,5 @@ interface BencodeCompositeDecoder : CompositeDecoder {
     fun decodeByteArrayElement(descriptor: SerialDescriptor, index: Int): ByteArray
     fun reportError(message: String, descriptor: SerialDescriptor, index: Int): Nothing =
         throw BencodeDecodeException(-1, message)
+    val options: BencodeOptions
 }

src/commonMain/kotlin/space/iseki/bencoding/BencodeDecoder.kt

@@ -4,6 +4,7 @@ import kotlinx.serialization.encoding.Decoder
 
 interface BencodeDecoder : Decoder {
     fun decodeByteArray(): ByteArray
-    fun decodeStringIso88591(): String
+    fun decodeBinaryString(strategy: BinaryStringStrategy): String
     fun reportError(message: String): Nothing = throw BencodeDecodeException(-1, message)
+    val options: BencodeOptions
 }

src/commonMain/kotlin/space/iseki/bencoding/BencodeDecoder0.kt

@@ -10,7 +10,9 @@ import kotlinx.serialization.modules.SerializersModule
 
 @OptIn(ExperimentalSerializationApi::class)
 internal class BencodeDecoder0(
-    private val lexer: Lexer, override val serializersModule: SerializersModule, val options: BencodeOptions
+    private val lexer: Lexer,
+    override val serializersModule: SerializersModule,
+    override val options: BencodeOptions,
 ) : BencodeDecoder, BencodeCompositeDecoder {
 
     private fun unsupported(kind: String): Nothing = throw BencodeDecodeException(
@@ -68,8 +70,9 @@ internal class BencodeDecoder0(
 
     override fun decodeShortElement(descriptor: SerialDescriptor, index: Int) = el(descriptor, index, ::decodeShort)
     override fun decodeStringElement(descriptor: SerialDescriptor, index: Int) = el(descriptor, index) {
-        if (descriptor.getElementAnnotations(index).any { it is StringInIso88591 }) {
-            decodeStringIso88591()
+        val anno = descriptor.binaryStringAnnotation(index)
+        if (anno != null) {
+            decodeBinaryString(anno.strategy)
         } else {
             decodeString()
         }
@@ -90,7 +93,8 @@ internal class BencodeDecoder0(
     override fun decodeNull(): Nothing? = null
     override fun decodeShort(): Short = decodeInt().toShort()
     override fun decodeString(): String = lexer.nextBytes().decodeToString()
-    override fun decodeStringIso88591(): String = bytes2StringIso88591(lexer.nextBytes())
+    override fun decodeBinaryString(strategy: BinaryStringStrategy): String =
+        options.binaryStringStrategy.decodeString(strategy)
     override fun reportError(message: String): Nothing {
         throw BencodeDecodeException(lexer.pos(), message)
     }

src/commonMain/kotlin/space/iseki/bencoding/BencodeOptions.kt

@@ -3,10 +3,12 @@ package space.iseki.bencoding
 interface BencodeOptions {
     val floatStrategy: FloatNumberStrategy
     val doubleStrategy: FloatNumberStrategy
+    val binaryStringStrategy: BinaryStringStrategy
 }
 
 internal data class BencodeOptionsData(
-    override val floatStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow,
-    override val doubleStrategy: FloatNumberStrategy = FloatNumberStrategy.Disallow,
+    override val floatStrategy: FloatNumberStrategy,
+    override val doubleStrategy: FloatNumberStrategy,
+    override val binaryStringStrategy: BinaryStringStrategy,
 ) : BencodeOptions
 

…pace/iseki/bencoding/StringInIso88591.kt …in/space/iseki/bencoding/BinaryString.ktsrc/commonMain/kotlin/space/iseki/bencoding/StringInIso88591.kt renamed to src/commonMain/kotlin/space/iseki/bencoding/BinaryString.kt src/commonMain/kotlin/space/iseki/bencoding/StringInIso88591.kt renamed to src/commonMain/kotlin/space/iseki/bencoding/BinaryString.kt

@@ -2,9 +2,11 @@ package space.iseki.bencoding
 
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.MetaSerializable
+import kotlinx.serialization.SerialInfo
 
 @OptIn(ExperimentalSerializationApi::class)
 @Target(AnnotationTarget.PROPERTY)
 @Retention(AnnotationRetention.RUNTIME)
+@SerialInfo
 @MetaSerializable
-annotation class StringInIso88591
+annotation class BinaryString(val strategy: BinaryStringStrategy = BinaryStringStrategy.Default)

src/commonMain/kotlin/space/iseki/bencoding/BinaryStringStrategy.kt

@@ -0,0 +1,36 @@
+package space.iseki.bencoding
+
+import kotlin.io.encoding.ExperimentalEncodingApi
+
+/**
+ * Represent the strategy to handle the binary data in [String].
+ *
+ * Because the bencoding standard and the serialization framework does not support [ByteArray], we convert it to [String] when decoding/encoding.
+ * But many platforms haven't a standard way to store binary data in [String], so we provide some strategies to handle it.
+ */
+enum class BinaryStringStrategy {
+    /**
+     * Use ISO-8859-1 to encode/decode the binary data.
+     */
+    ISO88591,
+
+    /**
+     * Use Base64 to encode/decode the binary data.
+     */
+    Base64,
+
+    /**
+     * Use the default strategy that configured in the [BencodeOptions].
+     */
+    Default, ;
+
+    context(BencodeDecoder)
+    @OptIn(ExperimentalEncodingApi::class)
+    internal fun decodeString(strategy: BinaryStringStrategy): String {
+        return when (if (strategy == Default) options.binaryStringStrategy else strategy) {
+            ISO88591, Default -> bytes2StringIso88591(decodeByteArray())
+            Base64 -> kotlin.io.encoding.Base64.encode(decodeByteArray())
+        }
+    }
+
+}

src/commonMain/kotlin/space/iseki/bencoding/FloatNumberStrategy.kt

@@ -28,8 +28,7 @@ enum class FloatNumberStrategy {
     /**
      * Allow the [Double] and [Float] number, but convert them to decimal-string when encoding/decoding.
      */
-    DecimalString,
-    ;
+    DecimalString, ;
 
     context(BencodeDecoder)
     internal fun decodeDouble(): Double {
@@ -71,3 +70,4 @@ enum class FloatNumberStrategy {
         }
     }
 }
+

src/commonMain/kotlin/space/iseki/bencoding/Utils.kt

@@ -2,6 +2,13 @@
 
 package space.iseki.bencoding
 
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.descriptors.SerialDescriptor
+
 internal expect fun bytes2Long(bytes: ByteArray, off: Int, len: Int): Long
 internal expect fun bytes2StringIso88591(bytes: ByteArray, off: Int = 0, len: Int = bytes.size): String
 internal expect fun string2BytesIso88591(s: String): ByteArray
+
+@OptIn(ExperimentalSerializationApi::class)
+internal fun SerialDescriptor.binaryStringAnnotation(childIndex: Int) =
+    getElementAnnotations(childIndex).firstOrNull { it is BinaryString } as BinaryString?