feat: add configurable sentinel, in-place decode, sentinel framing

ajsb85 · ajsb85 · commit 904d80ab56a5 · 2026-07-04T17:59:19.000+02:00
Ports cobs_codec_rs 1.1.0 features; additive and byte-identical (v1.1.0).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this library are documented here. This project adheres
+to [Semantic Versioning](https://semver.org).
+
+## 1.1.0
+
+### Added
+
+- **Configurable sentinel**: `encodeWithSentinel` / `decodeWithSentinel` on both
+  `Cobs` and `Cobsr`, for framing with a delimiter other than `0x00`. The
+  encoded output never contains the chosen sentinel byte, and a sentinel of `0`
+  is byte-for-byte identical to the plain codecs.
+- **In-place decoding**: `Cobs.decodeInPlace` (with an optional `sentinel`
+  overload), which decodes basic COBS within the same buffer and returns the
+  decoded length — no second array required.
+- **Framing sentinel**: `CobsFraming.frame` / `unframe` and `CobsStreamDecoder`
+  gained a trailing `sentinel` parameter (defaulting to the `0x00`
+  `COBS_DELIMITER`), so a stream can be framed on a non-`0x00` delimiter.
+
+All additions are backward compatible.
+
+## 1.0.0
+
+Initial release.
+
+### Added
+
+- **Basic COBS** and **COBS/R** encode/decode (`Cobs`, `Cobsr`).
+- **Stream framing** for `0x00`-delimited links: `CobsFraming.frame` /
+  `unframe`, and the incremental `CobsStreamDecoder` with a `maxFrameLength`
+  guard.
+- Size helpers `maxEncodedLength` and `encodingOverhead`.
+- `CobsDecodeException` for invalid encoded input.
+- Golden-vector tests plus a conformance test against
+  [firechip/cobs-conformance](https://github.com/firechip/cobs-conformance),
+  byte-identical to the reference.
diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ repositories {
 }
 
 dependencies {
-    implementation("dev.firechip:cobs_codec:1.0.0")
+    implementation("dev.firechip:cobs_codec:1.1.0")
 }
 ```
 
@@ -67,7 +67,7 @@ authentication:
 
 ```kotlin
 dependencies {
-    implementation(files("libs/cobs_codec-1.0.0.aar"))
+    implementation(files("libs/cobs_codec-1.1.0.aar"))
 }
 ```
 
diff --git a/cobs/build.gradle.kts b/cobs/build.gradle.kts
@@ -6,7 +6,7 @@ plugins {
 }
 
 group = "dev.firechip"
-version = "1.0.0"
+version = "1.1.0"
 
 android {
     namespace = "dev.firechip.cobs"
diff --git a/cobs/src/main/kotlin/dev/firechip/cobs/Cobs.kt b/cobs/src/main/kotlin/dev/firechip/cobs/Cobs.kt
@@ -57,6 +57,27 @@ public object Cobs {
         return dst.copyOf(writeIndex)
     }
 
+    /**
+     * Encodes [input] with basic COBS using an arbitrary [sentinel] byte instead
+     * of `0x00`, returning a [ByteArray] that never contains the [sentinel] byte.
+     *
+     * This runs the ordinary encode and then XORs every output byte with
+     * [sentinel], so `sentinel` (rather than `0x00`) may be used to delimit
+     * packets. Choosing a sentinel that rarely occurs in the payload minimises
+     * overhead. A [sentinel] of `0` is byte-for-byte identical to [encode].
+     */
+    @JvmStatic
+    public fun encodeWithSentinel(input: ByteArray, sentinel: Byte): ByteArray {
+        val out = encode(input)
+        val s = sentinel.toInt() and 0xFF
+        if (s != 0) {
+            for (i in out.indices) {
+                out[i] = (out[i].toInt() xor s).toByte()
+            }
+        }
+        return out
+    }
+
     /**
      * Decodes basic-COBS-encoded [input], returning the original bytes.
      *
@@ -107,6 +128,100 @@ public object Cobs {
         return out.copyOf(writeIndex)
     }
 
+    /**
+     * Decodes basic-COBS [input] that was encoded with an arbitrary [sentinel]
+     * byte (see [encodeWithSentinel]), returning the original bytes.
+     *
+     * A fresh copy of [input] is XORed back with [sentinel] before decoding, so
+     * the caller's array is never mutated. A [sentinel] of `0` is identical to
+     * [decode].
+     *
+     * @throws CobsDecodeException if [input] contains the [sentinel] byte or a
+     *   length code points past the end of the input.
+     */
+    @JvmStatic
+    public fun decodeWithSentinel(input: ByteArray, sentinel: Byte): ByteArray {
+        val s = sentinel.toInt() and 0xFF
+        if (s == 0) return decode(input)
+        val src = input.copyOf()
+        for (i in src.indices) {
+            src[i] = (src[i].toInt() xor s).toByte()
+        }
+        return decode(src)
+    }
+
+    /**
+     * Decodes basic-COBS data in place, overwriting [buffer] with the decoded
+     * output and returning its length; the decoded bytes occupy the first `len`
+     * elements of [buffer].
+     *
+     * This needs no output buffer: COBS decoding never expands, so the write
+     * position always trails the read position.
+     *
+     * @throws CobsDecodeException if [buffer] contains a `0x00` byte or a length
+     *   code points past the end of the input.
+     */
+    @JvmStatic
+    public fun decodeInPlace(buffer: ByteArray): Int = decodeInPlace(buffer, COBS_DELIMITER)
+
+    /**
+     * Decodes basic-COBS data that was encoded with an arbitrary [sentinel] byte
+     * in place, overwriting [buffer] with the decoded output and returning its
+     * length. A [sentinel] of `0` is identical to [decodeInPlace].
+     *
+     * When [sentinel] is non-zero the buffer is first XORed back to its
+     * `0x00`-based form in place, then decoded in place.
+     *
+     * @throws CobsDecodeException if [buffer] is not valid encoded data.
+     */
+    @JvmStatic
+    public fun decodeInPlace(buffer: ByteArray, sentinel: Byte): Int {
+        val srcLen = buffer.size
+        if (srcLen == 0) return 0
+
+        val s = sentinel.toInt() and 0xFF
+        if (s != 0) {
+            for (i in 0 until srcLen) {
+                buffer[i] = (buffer[i].toInt() xor s).toByte()
+            }
+        }
+
+        var writeIndex = 0
+        var index = 0
+
+        while (true) {
+            val code = buffer[index].toInt() and 0xFF
+            if (code == 0) {
+                throw CobsDecodeException("zero byte in COBS input", index)
+            }
+            index++
+            val blockEnd = index + code - 1
+            val copyEnd = if (blockEnd < srcLen) blockEnd else srcLen
+            while (index < copyEnd) {
+                val b = buffer[index].toInt() and 0xFF
+                if (b == 0) {
+                    throw CobsDecodeException("zero byte in COBS input", index)
+                }
+                // writeIndex < index throughout, so this never clobbers unread input.
+                buffer[writeIndex++] = b.toByte()
+                index++
+            }
+            if (blockEnd > srcLen) {
+                throw CobsDecodeException(
+                    "length code points past end of input",
+                    blockEnd - code,
+                )
+            }
+            if (blockEnd < srcLen) {
+                if (code < 0xFF) buffer[writeIndex++] = 0
+            } else {
+                break
+            }
+        }
+
+        return writeIndex
+    }
+
     /** See the top-level [encodingOverhead]. */
     @JvmStatic
     public fun encodingOverhead(sourceLength: Int): Int =
diff --git a/cobs/src/main/kotlin/dev/firechip/cobs/Cobsr.kt b/cobs/src/main/kotlin/dev/firechip/cobs/Cobsr.kt
@@ -64,6 +64,25 @@ public object Cobsr {
         return dst.copyOf(writeIndex)
     }
 
+    /**
+     * Encodes [input] with COBS/R using an arbitrary [sentinel] byte instead of
+     * `0x00`, returning a [ByteArray] that never contains the [sentinel] byte.
+     *
+     * This runs the ordinary encode and then XORs every output byte with
+     * [sentinel]. A [sentinel] of `0` is byte-for-byte identical to [encode].
+     */
+    @JvmStatic
+    public fun encodeWithSentinel(input: ByteArray, sentinel: Byte): ByteArray {
+        val out = encode(input)
+        val s = sentinel.toInt() and 0xFF
+        if (s != 0) {
+            for (i in out.indices) {
+                out[i] = (out[i].toInt() xor s).toByte()
+            }
+        }
+        return out
+    }
+
     /**
      * Decodes COBS/R-encoded [input], returning the original bytes. The empty
      * input decodes to an empty array.
@@ -108,4 +127,25 @@ public object Cobsr {
 
         return out.copyOf(writeIndex)
     }
+
+    /**
+     * Decodes COBS/R [input] that was encoded with an arbitrary [sentinel] byte
+     * (see [encodeWithSentinel]), returning the original bytes.
+     *
+     * A fresh copy of [input] is XORed back with [sentinel] before decoding, so
+     * the caller's array is never mutated. A [sentinel] of `0` is identical to
+     * [decode].
+     *
+     * @throws CobsDecodeException if [input] contains the [sentinel] byte.
+     */
+    @JvmStatic
+    public fun decodeWithSentinel(input: ByteArray, sentinel: Byte): ByteArray {
+        val s = sentinel.toInt() and 0xFF
+        if (s == 0) return decode(input)
+        val src = input.copyOf()
+        for (i in src.indices) {
+            src[i] = (src[i].toInt() xor s).toByte()
+        }
+        return decode(src)
+    }
 }
diff --git a/cobs/src/main/kotlin/dev/firechip/cobs/Framing.kt b/cobs/src/main/kotlin/dev/firechip/cobs/Framing.kt
@@ -17,20 +17,38 @@ public object CobsFraming {
 
     /**
      * Encodes [packet] (with COBS/R when [reduced] is true, otherwise basic
-     * COBS) and appends the [COBS_DELIMITER], producing a self-delimiting frame.
+     * COBS) and appends the delimiter, producing a self-delimiting frame.
+     *
+     * [sentinel] selects the delimiter byte (and the byte the encoding avoids);
+     * it defaults to the `0x00` [COBS_DELIMITER]. The packet is encoded with the
+     * same [sentinel], so the output never contains it before the trailing
+     * delimiter.
      */
     @JvmStatic
     @JvmOverloads
-    public fun frame(packet: ByteArray, reduced: Boolean = false): ByteArray {
-        val encoded = if (reduced) Cobsr.encode(packet) else Cobs.encode(packet)
-        // copyOf pads the extra byte with 0x00, which is the delimiter.
-        return encoded.copyOf(encoded.size + 1)
+    public fun frame(
+        packet: ByteArray,
+        reduced: Boolean = false,
+        sentinel: Byte = COBS_DELIMITER,
+    ): ByteArray {
+        val encoded = if (reduced) {
+            Cobsr.encodeWithSentinel(packet, sentinel)
+        } else {
+            Cobs.encodeWithSentinel(packet, sentinel)
+        }
+        val framed = encoded.copyOf(encoded.size + 1)
+        framed[encoded.size] = sentinel
+        return framed
     }
 
     /**
-     * Splits [data] on the [COBS_DELIMITER] and decodes each frame, returning
-     * the recovered packets. Trailing bytes after the final delimiter are
-     * ignored. Empty frames are skipped when [skipEmpty] is true.
+     * Splits [data] on the delimiter and decodes each frame, returning the
+     * recovered packets. Trailing bytes after the final delimiter are ignored.
+     * Empty frames are skipped when [skipEmpty] is true.
+     *
+     * [sentinel] selects the delimiter byte (and the byte each frame was encoded
+     * to avoid); it defaults to the `0x00` [COBS_DELIMITER] and must match the
+     * sentinel used to frame.
      *
      * @throws CobsDecodeException if a complete frame is not valid encoded data.
      */
@@ -40,16 +58,23 @@ public object CobsFraming {
         data: ByteArray,
         reduced: Boolean = false,
         skipEmpty: Boolean = true,
+        sentinel: Byte = COBS_DELIMITER,
     ): List<ByteArray> {
         val frames = ArrayList<ByteArray>()
         var start = 0
         for (i in data.indices) {
-            if (data[i].toInt() != 0) continue
+            if (data[i] != sentinel) continue
             if (i == start) {
                 if (!skipEmpty) frames.add(ByteArray(0))
             } else {
                 val slice = data.copyOfRange(start, i)
-                frames.add(if (reduced) Cobsr.decode(slice) else Cobs.decode(slice))
+                frames.add(
+                    if (reduced) {
+                        Cobsr.decodeWithSentinel(slice, sentinel)
+                    } else {
+                        Cobs.decodeWithSentinel(slice, sentinel)
+                    },
+                )
             }
             start = i + 1
         }
@@ -58,22 +83,27 @@ public object CobsFraming {
 }
 
 /**
- * A stateful, incremental decoder for a stream of [COBS_DELIMITER]-framed data,
- * for reading COBS packets from a serial/UART link where bytes arrive in
- * arbitrarily sized chunks that do not align with frame boundaries.
+ * A stateful, incremental decoder for a stream of delimiter-framed data, for
+ * reading COBS packets from a serial/UART link where bytes arrive in arbitrarily
+ * sized chunks that do not align with frame boundaries.
  *
  * Feed raw bytes with [feed]; it returns any packets completed by a delimiter,
  * buffering the rest until a later call. [maxFrameLength] (when greater than 0)
  * bounds how many bytes are buffered for a single unterminated frame, guarding
  * against unbounded memory use on a noisy link that never sends the delimiter.
  * A frame that fails to decode is passed to [onInvalidFrame] if provided
  * (decoding then continues), otherwise the [CobsDecodeException] is thrown.
+ *
+ * [sentinel] selects the delimiter byte (and the byte each frame was encoded to
+ * avoid); it defaults to the `0x00` [COBS_DELIMITER] and must match the sentinel
+ * used to frame the stream.
  */
 public class CobsStreamDecoder @JvmOverloads constructor(
     private val reduced: Boolean = false,
     private val skipEmpty: Boolean = true,
     private val maxFrameLength: Int = 0,
     private val onInvalidFrame: ((CobsDecodeException, ByteArray) -> Unit)? = null,
+    private val sentinel: Byte = COBS_DELIMITER,
 ) {
     // Concatenation allocates a fresh array, so buffered bytes never alias a
     // caller-supplied chunk that may be reused for the next read.
@@ -86,7 +116,7 @@ public class CobsStreamDecoder @JvmOverloads constructor(
         val out = ArrayList<ByteArray>()
         var start = 0
         for (i in chunk.indices) {
-            if (chunk[i].toInt() != 0) continue
+            if (chunk[i] != sentinel) continue
             val frame = buffer + chunk.copyOfRange(start, i)
             buffer = ByteArray(0)
             start = i + 1
@@ -95,7 +125,13 @@ public class CobsStreamDecoder @JvmOverloads constructor(
                 continue
             }
             try {
-                out.add(if (reduced) Cobsr.decode(frame) else Cobs.decode(frame))
+                out.add(
+                    if (reduced) {
+                        Cobsr.decodeWithSentinel(frame, sentinel)
+                    } else {
+                        Cobs.decodeWithSentinel(frame, sentinel)
+                    },
+                )
             } catch (e: CobsDecodeException) {
                 val handler = onInvalidFrame ?: throw e
                 handler(e, frame)
diff --git a/cobs/src/test/kotlin/dev/firechip/cobs/FeaturesTest.kt b/cobs/src/test/kotlin/dev/firechip/cobs/FeaturesTest.kt

Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ repositories {`
`49`	`49`	`}`
`50`	`50`
`51`	`51`	`dependencies {`
`52`		`- implementation("dev.firechip:cobs_codec:1.0.0")`
	`52`	`+ implementation("dev.firechip:cobs_codec:1.1.0")`
`53`	`53`	`}`
`54`	`54`	```
`55`	`55`
`@@ -67,7 +67,7 @@ authentication:`
`67`	`67`
`68`	`68`	```kotlin
`69`	`69`	`dependencies {`
`70`		`- implementation(files("libs/cobs_codec-1.0.0.aar"))`
	`70`	`+ implementation(files("libs/cobs_codec-1.1.0.aar"))`
`71`	`71`	`}`
`72`	`72`	```
`73`	`73`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ plugins {`
`6`	`6`	`}`
`7`	`7`
`8`	`8`	`group = "dev.firechip"`
`9`		`-version = "1.0.0"`
	`9`	`+version = "1.1.0"`
`10`	`10`
`11`	`11`	`android {`
`12`	`12`	`namespace = "dev.firechip.cobs"`