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

Ports cobs_codec_rs 1.1.0 features; additive and byte-identical (v1.1.0).

Author: ajsb85

CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this package are documented here. This project adheres
 to [Semantic Versioning](https://semver.org).
 
+## 1.1.0
+
+### Added
+
+- **Configurable sentinel byte** for both COBS and COBS/R: `cobsEncodeWithSentinel`
+  / `cobsDecodeWithSentinel` and `cobsrEncodeWithSentinel` /
+  `cobsrDecodeWithSentinel` encode to avoid an arbitrary delimiter byte instead
+  of `0x00` (by XORing the finished encoding with the sentinel). `sentinel == 0`
+  is byte-for-byte identical to the plain codecs.
+- **In-place basic-COBS decoding**: `cobsDecodeInPlace` and
+  `cobsDecodeInPlaceWithSentinel` decode within the caller's `Uint8List` and
+  return the decoded length, needing no output buffer and with no "output too
+  small" case (COBS decoding never expands).
+- **Sentinel framing**: `cobsFrame`, `cobsUnframe`, `CobsFrameEncoder` and
+  `CobsFrameDecoder` gain an optional `sentinel` parameter (defaulting to the
+  `0x00` `cobsDelimiter`) so a non-zero byte can delimit frames on the wire, for
+  both the basic and reduced codecs.
+
 ## 1.0.0
 
 Initial release.

README.md

@@ -40,7 +40,7 @@ dart pub add cobs_codec
 
 ```yaml
 dependencies:
-  cobs_codec: ^1.0.0
+  cobs_codec: ^1.1.0
 ```
 
 ## Usage

lib/cobs_codec.dart

@@ -40,15 +40,27 @@
 library;
 
 export 'src/cobs.dart'
-    show CobsCodec, CobsDecoder, CobsEncoder, cobs, cobsDecode, cobsEncode;
+    show
+        CobsCodec,
+        CobsDecoder,
+        CobsEncoder,
+        cobs,
+        cobsDecode,
+        cobsDecodeInPlace,
+        cobsDecodeInPlaceWithSentinel,
+        cobsDecodeWithSentinel,
+        cobsEncode,
+        cobsEncodeWithSentinel;
 export 'src/cobsr.dart'
     show
         CobsrCodec,
         CobsrDecoder,
         CobsrEncoder,
         cobsr,
         cobsrDecode,
-        cobsrEncode;
+        cobsrDecodeWithSentinel,
+        cobsrEncode,
+        cobsrEncodeWithSentinel;
 export 'src/exceptions.dart' show CobsDecodeException;
 export 'src/framing.dart'
     show

lib/src/cobs.dart

@@ -130,6 +130,114 @@ Uint8List cobsDecode(List<int> input) {
   return Uint8List.sublistView(out, 0, writeIndex);
 }
 
+/// Encodes [input] with basic COBS using an arbitrary [sentinel] byte instead of
+/// `0x00`, returning a [Uint8List] that never contains the [sentinel].
+///
+/// This runs the ordinary [cobsEncode] and then XORs every output byte with
+/// [sentinel] (masked to the low 8 bits), which shifts the byte the encoding
+/// avoids from `0x00` to [sentinel]. Choosing a [sentinel] that rarely occurs in
+/// the payload minimises overhead. `sentinel == 0` is byte-for-byte identical to
+/// [cobsEncode].
+Uint8List cobsEncodeWithSentinel(List<int> input, int sentinel) {
+  final encoded = cobsEncode(input);
+  final s = sentinel & 0xFF;
+  if (s != 0) {
+    for (var i = 0; i < encoded.length; i++) {
+      encoded[i] ^= s;
+    }
+  }
+  return encoded;
+}
+
+/// Decodes basic-COBS [input] that was encoded with an arbitrary [sentinel] byte
+/// (see [cobsEncodeWithSentinel]), returning the original bytes.
+///
+/// A fresh copy of [input] is XORed back with [sentinel] (masked to the low 8
+/// bits) before decoding, so the caller's [input] is never mutated.
+/// `sentinel == 0` is identical to [cobsDecode].
+///
+/// Throws a [CobsDecodeException] if the recovered bytes are not valid COBS (for
+/// example, if [input] itself contained the [sentinel]).
+Uint8List cobsDecodeWithSentinel(List<int> input, int sentinel) {
+  final s = sentinel & 0xFF;
+  if (s == 0) return cobsDecode(input);
+  final copy = Uint8List(input.length);
+  for (var i = 0; i < copy.length; i++) {
+    copy[i] = input[i] ^ s;
+  }
+  return cobsDecode(copy);
+}
+
+/// Decodes basic-COBS data in place, overwriting [buffer] with the decoded bytes
+/// and returning their length; the decoded output occupies `buffer[0..n]`.
+///
+/// This needs no separate output buffer: COBS decoding never expands, so the
+/// write position always trails the read position — there is therefore no
+/// "output too small" case. The bytes of [buffer] beyond the returned length are
+/// left in an unspecified (partially overwritten) state.
+///
+/// Throws a [CobsDecodeException] if [buffer] is not valid COBS.
+int cobsDecodeInPlace(Uint8List buffer) {
+  final srcLen = buffer.length;
+  if (srcLen == 0) return 0;
+
+  var writeIndex = 0;
+  var index = 0;
+
+  while (true) {
+    final code = buffer[index];
+    if (code == 0) {
+      throw CobsDecodeException('zero byte in COBS input', buffer, index);
+    }
+    index++;
+    final blockEnd = index + code - 1;
+    final copyEnd = blockEnd < srcLen ? blockEnd : srcLen;
+    for (; index < copyEnd; index++) {
+      final byte = buffer[index];
+      if (byte == 0) {
+        throw CobsDecodeException('zero byte in COBS input', buffer, index);
+      }
+      // `writeIndex` trails `index` throughout, so this never clobbers a byte
+      // that has not yet been read.
+      buffer[writeIndex++] = byte;
+    }
+    if (blockEnd > srcLen) {
+      throw CobsDecodeException(
+        'length code points past end of input',
+        buffer,
+        blockEnd - code, // index of the offending length code
+      );
+    }
+    if (blockEnd < srcLen) {
+      if (code < 0xFF) buffer[writeIndex++] = 0;
+    } else {
+      break;
+    }
+  }
+
+  return writeIndex;
+}
+
+/// Decodes basic-COBS data that was encoded with an arbitrary [sentinel] byte in
+/// place, overwriting [buffer] with the decoded bytes and returning their
+/// length; the decoded output occupies `buffer[0..n]`.
+///
+/// When [sentinel] is non-zero, [buffer] is first XORed with it (masked to the
+/// low 8 bits) and then decoded in place by [cobsDecodeInPlace]. `sentinel == 0`
+/// is identical to [cobsDecodeInPlace]. As an in-place operation this
+/// necessarily consumes (overwrites) [buffer].
+///
+/// Throws a [CobsDecodeException] if [buffer] is not valid.
+int cobsDecodeInPlaceWithSentinel(Uint8List buffer, int sentinel) {
+  final s = sentinel & 0xFF;
+  if (s != 0) {
+    for (var i = 0; i < buffer.length; i++) {
+      buffer[i] ^= s;
+    }
+  }
+  return cobsDecodeInPlace(buffer);
+}
+
 /// A [Codec] that encodes and decodes bytes with basic Consistent Overhead Byte
 /// Stuffing (COBS).
 ///

lib/src/cobsr.dart

@@ -129,6 +129,43 @@ Uint8List cobsrDecode(List<int> input) {
   return Uint8List.sublistView(out, 0, writeIndex);
 }
 
+/// Encodes [input] with COBS/R using an arbitrary [sentinel] byte instead of
+/// `0x00`, returning a [Uint8List] that never contains the [sentinel].
+///
+/// This runs the ordinary [cobsrEncode] and then XORs every output byte with
+/// [sentinel] (masked to the low 8 bits), which shifts the byte the encoding
+/// avoids from `0x00` to [sentinel]. `sentinel == 0` is byte-for-byte identical
+/// to [cobsrEncode].
+Uint8List cobsrEncodeWithSentinel(List<int> input, int sentinel) {
+  final encoded = cobsrEncode(input);
+  final s = sentinel & 0xFF;
+  if (s != 0) {
+    for (var i = 0; i < encoded.length; i++) {
+      encoded[i] ^= s;
+    }
+  }
+  return encoded;
+}
+
+/// Decodes COBS/R [input] that was encoded with an arbitrary [sentinel] byte
+/// (see [cobsrEncodeWithSentinel]), returning the original bytes.
+///
+/// A fresh copy of [input] is XORed back with [sentinel] (masked to the low 8
+/// bits) before decoding, so the caller's [input] is never mutated.
+/// `sentinel == 0` is identical to [cobsrDecode].
+///
+/// Throws a [CobsDecodeException] if the recovered bytes contain a `0x00` byte
+/// (for example, if [input] itself contained the [sentinel]).
+Uint8List cobsrDecodeWithSentinel(List<int> input, int sentinel) {
+  final s = sentinel & 0xFF;
+  if (s == 0) return cobsrDecode(input);
+  final copy = Uint8List(input.length);
+  for (var i = 0; i < copy.length; i++) {
+    copy[i] = input[i] ^ s;
+  }
+  return cobsrDecode(copy);
+}
+
 /// A [Codec] that encodes and decodes bytes with Consistent Overhead Byte
 /// Stuffing — Reduced (COBS/R).
 ///

lib/src/framing.dart

@@ -23,8 +23,29 @@ const int cobsDelimiter = 0x00;
 Uint8List _asBytes(List<int> bytes) =>
     bytes is Uint8List ? bytes : Uint8List.fromList(bytes);
 
-/// Encodes [packet] with [codec] (basic [cobs] by default) and appends the
-/// [cobsDelimiter], producing a self-delimiting frame ready to transmit.
+/// Returns the frame `bytes[start..end)` XORed by [sentinel], ready to hand to a
+/// codec's plain decoder.
+///
+/// For a non-zero [sentinel] a fresh copy is made so the caller's [bytes] are
+/// never mutated; for `0` the slice is viewed without copying, preserving the
+/// zero-copy behaviour of the plain delimiter path.
+Uint8List _deSentinel(Uint8List bytes, int start, int end, int sentinel) {
+  if (sentinel == 0) return Uint8List.sublistView(bytes, start, end);
+  final frame = Uint8List(end - start);
+  for (var i = 0; i < frame.length; i++) {
+    frame[i] = bytes[start + i] ^ sentinel;
+  }
+  return frame;
+}
+
+/// Encodes [packet] with [codec] (basic [cobs] by default) and appends the frame
+/// delimiter, producing a self-delimiting frame ready to transmit.
+///
+/// By default frames are delimited by the [cobsDelimiter] (`0x00`). Pass a
+/// non-zero [sentinel] to delimit on that byte instead: the encoding is made to
+/// avoid [sentinel] (by XORing the codec's output with it) and [sentinel] is
+/// appended as the delimiter. Decode such a frame with a matching [sentinel] in
+/// [cobsUnframe] or [CobsFrameDecoder].
 ///
 /// ```dart
 /// final frame = cobsFrame([0x11, 0x00, 0x22]);
@@ -33,17 +54,29 @@ Uint8List _asBytes(List<int> bytes) =>
 Uint8List cobsFrame(
   List<int> packet, {
   Codec<List<int>, List<int>> codec = cobs,
+  int sentinel = cobsDelimiter,
 }) {
   final encoded = codec.encode(packet);
   final out = Uint8List(encoded.length + 1);
   out.setRange(0, encoded.length, encoded);
-  // out[encoded.length] is already 0x00 (the delimiter).
+  final s = sentinel & 0xFF;
+  if (s != 0) {
+    for (var i = 0; i < encoded.length; i++) {
+      out[i] ^= s;
+    }
+  }
+  out[encoded.length] = s; // the delimiter (already 0 when s == 0)
   return out;
 }
 
-/// Splits [data] on the [cobsDelimiter] and decodes each frame with [codec],
+/// Splits [data] on the frame delimiter and decodes each frame with [codec],
 /// returning the list of recovered packets.
 ///
+/// By default frames are delimited by the [cobsDelimiter] (`0x00`). Pass the
+/// non-zero [sentinel] used to frame the data to split on that byte instead and
+/// undo its XOR before decoding; the frame slice is copied before it is XORed, so
+/// [data] is never mutated.
+///
 /// Any trailing bytes after the final delimiter are treated as an incomplete
 /// frame and ignored. When [skipEmpty] is true (the default), empty frames
 /// (produced by consecutive or leading delimiters) are skipped rather than
@@ -55,17 +88,18 @@ List<Uint8List> cobsUnframe(
   List<int> data, {
   Codec<List<int>, List<int>> codec = cobs,
   bool skipEmpty = true,
+  int sentinel = cobsDelimiter,
 }) {
   final frames = <Uint8List>[];
   final bytes = _asBytes(data);
+  final s = sentinel & 0xFF;
   var start = 0;
   for (var i = 0; i < bytes.length; i++) {
-    if (bytes[i] == cobsDelimiter) {
+    if (bytes[i] == s) {
       if (i == start) {
         if (!skipEmpty) frames.add(Uint8List(0));
       } else {
-        frames.add(
-            _asBytes(codec.decode(Uint8List.sublistView(bytes, start, i))));
+        frames.add(_asBytes(codec.decode(_deSentinel(bytes, start, i, s))));
       }
       start = i + 1;
     }
@@ -80,16 +114,21 @@ List<Uint8List> cobsUnframe(
 /// outgoingPackets.transform(const CobsFrameEncoder()).pipe(serialSink);
 /// ```
 class CobsFrameEncoder extends StreamTransformerBase<List<int>, Uint8List> {
-  /// Creates a frame encoder using [codec] (basic [cobs] by default).
-  const CobsFrameEncoder({this.codec = cobs});
+  /// Creates a frame encoder using [codec] (basic [cobs] by default), delimiting
+  /// each frame with [sentinel] (the `0x00` [cobsDelimiter] by default).
+  const CobsFrameEncoder({this.codec = cobs, this.sentinel = cobsDelimiter});
 
   /// The codec used to encode each packet.
   final Codec<List<int>, List<int>> codec;
 
+  /// The byte value used to delimit frames on the wire (and that the encoding is
+  /// made to avoid). Defaults to the `0x00` [cobsDelimiter].
+  final int sentinel;
+
   @override
   Stream<Uint8List> bind(Stream<List<int>> stream) async* {
     await for (final packet in stream) {
-      yield cobsFrame(packet, codec: codec);
+      yield cobsFrame(packet, codec: codec, sentinel: sentinel);
     }
   }
 }
@@ -125,11 +164,17 @@ class CobsFrameDecoder extends StreamTransformerBase<List<int>, Uint8List> {
     this.skipEmpty = true,
     this.maxFrameLength,
     this.onInvalidFrame,
+    this.sentinel = cobsDelimiter,
   });
 
   /// The codec used to decode each frame.
   final Codec<List<int>, List<int>> codec;
 
+  /// The byte value that delimits frames on the wire (and that the encoding is
+  /// made to avoid). The stream is split on this byte and each frame is XORed
+  /// back with it before decoding. Defaults to the `0x00` [cobsDelimiter].
+  final int sentinel;
+
   /// Whether to skip empty frames (from consecutive or leading delimiters)
   /// rather than emit empty packets.
   final bool skipEmpty;
@@ -160,6 +205,7 @@ class CobsFrameDecoder extends StreamTransformerBase<List<int>, Uint8List> {
     // completes a frame — so a delimiter-less run would otherwise ignore
     // backpressure and make the subscription impossible to cancel.
     final buffer = BytesBuilder(copy: false);
+    final delimiter = sentinel & 0xFF;
     late final StreamController<Uint8List> controller;
     StreamSubscription<List<int>>? subscription;
 
@@ -177,7 +223,7 @@ class CobsFrameDecoder extends StreamTransformerBase<List<int>, Uint8List> {
       final bytes = _asBytes(chunk);
       var start = 0;
       for (var i = 0; i < bytes.length; i++) {
-        if (bytes[i] != cobsDelimiter) continue;
+        if (bytes[i] != delimiter) continue;
         // The delimiter completes a frame: buffered bytes + this chunk up to
         // (but not including) the delimiter. This sublist view is consumed
         // synchronously by takeBytes/decode below, so it need not be copied.
@@ -188,6 +234,14 @@ class CobsFrameDecoder extends StreamTransformerBase<List<int>, Uint8List> {
           if (!skipEmpty) controller.add(Uint8List(0));
           continue;
         }
+        // `frame` is owned by this decoder (from takeBytes), so undoing the
+        // sentinel XOR in place is safe; when the delimiter is 0x00 this is a
+        // no-op and the plain-COBS path is unchanged.
+        if (delimiter != 0) {
+          for (var j = 0; j < frame.length; j++) {
+            frame[j] ^= delimiter;
+          }
+        }
         try {
           controller.add(_asBytes(codec.decode(frame)));
         } on CobsDecodeException catch (error, stackTrace) {

pubspec.yaml

@@ -2,7 +2,7 @@ name: cobs_codec
 description: >-
   Consistent Overhead Byte Stuffing (COBS) and COBS/R codecs for zero-free,
   low-overhead framing of serial, UART and packet byte streams.
-version: 1.0.0
+version: 1.1.0
 repository: https://github.com/firechip/cobs_codec
 issue_tracker: https://github.com/firechip/cobs_codec/issues
 homepage: https://firechip.dev