|
| 1 | +// Copyright (c) 2026 Alexander Salas Bastidas <ajsb85@firechip.dev> |
| 2 | +// SPDX-License-Identifier: MIT |
| 3 | + |
| 4 | +package dev.firechip.cobs |
| 5 | + |
| 6 | +/** |
| 7 | + * Basic Consistent Overhead Byte Stuffing (COBS). |
| 8 | + * |
| 9 | + * COBS encodes an arbitrary [ByteArray] into one that contains no zero |
| 10 | + * (`0x00`) bytes, at a small and predictable cost (at most one extra byte per |
| 11 | + * 254 bytes, plus one). That lets a single `0x00` reliably delimit packets on a |
| 12 | + * byte stream. See Cheshire & Baker, "Consistent Overhead Byte Stuffing", |
| 13 | + * IEEE/ACM Transactions on Networking, Vol. 7, No. 2, April 1999. |
| 14 | + */ |
| 15 | +public object Cobs { |
| 16 | + |
| 17 | + /** |
| 18 | + * Encodes [input] with basic COBS, returning a zero-free [ByteArray]. |
| 19 | + * |
| 20 | + * Encoding never fails: any sequence of bytes is encodable. The empty input |
| 21 | + * encodes to `[0x01]`. |
| 22 | + */ |
| 23 | + @JvmStatic |
| 24 | + public fun encode(input: ByteArray): ByteArray { |
| 25 | + val srcLen = input.size |
| 26 | + if (srcLen == 0) return byteArrayOf(0x01) |
| 27 | + |
| 28 | + // Worst-case output size; the actual output is a prefix of this buffer. |
| 29 | + val dst = ByteArray(maxEncodedLength(srcLen)) |
| 30 | + var codeIndex = 0 |
| 31 | + var writeIndex = 1 |
| 32 | + var code = 1 |
| 33 | + var readIndex = 0 |
| 34 | + |
| 35 | + while (true) { |
| 36 | + val b = input[readIndex++].toInt() and 0xFF |
| 37 | + if (b == 0) { |
| 38 | + dst[codeIndex] = code.toByte() |
| 39 | + codeIndex = writeIndex++ |
| 40 | + code = 1 |
| 41 | + if (readIndex >= srcLen) break |
| 42 | + } else { |
| 43 | + dst[writeIndex++] = b.toByte() |
| 44 | + code++ |
| 45 | + // Terminate before the 0xFF split so a chunk of exactly 254 |
| 46 | + // non-zero bytes does not emit a spurious trailing block. |
| 47 | + if (readIndex >= srcLen) break |
| 48 | + if (code == 0xFF) { |
| 49 | + dst[codeIndex] = code.toByte() |
| 50 | + codeIndex = writeIndex++ |
| 51 | + code = 1 |
| 52 | + } |
| 53 | + } |
| 54 | + } |
| 55 | + dst[codeIndex] = code.toByte() |
| 56 | + |
| 57 | + return dst.copyOf(writeIndex) |
| 58 | + } |
| 59 | + |
| 60 | + /** |
| 61 | + * Decodes basic-COBS-encoded [input], returning the original bytes. |
| 62 | + * |
| 63 | + * The empty input decodes to an empty array. Input should be a single |
| 64 | + * encoded packet with no surrounding `0x00` delimiter bytes. |
| 65 | + * |
| 66 | + * @throws CobsDecodeException if [input] contains a `0x00` byte or a length |
| 67 | + * code points past the end of the input. |
| 68 | + */ |
| 69 | + @JvmStatic |
| 70 | + public fun decode(input: ByteArray): ByteArray { |
| 71 | + val srcLen = input.size |
| 72 | + if (srcLen == 0) return ByteArray(0) |
| 73 | + |
| 74 | + val out = ByteArray(srcLen) |
| 75 | + var writeIndex = 0 |
| 76 | + var index = 0 |
| 77 | + |
| 78 | + while (true) { |
| 79 | + val code = input[index].toInt() and 0xFF |
| 80 | + if (code == 0) { |
| 81 | + throw CobsDecodeException("zero byte in COBS input", index) |
| 82 | + } |
| 83 | + index++ |
| 84 | + val blockEnd = index + code - 1 |
| 85 | + val copyEnd = if (blockEnd < srcLen) blockEnd else srcLen |
| 86 | + while (index < copyEnd) { |
| 87 | + val b = input[index].toInt() and 0xFF |
| 88 | + if (b == 0) { |
| 89 | + throw CobsDecodeException("zero byte in COBS input", index) |
| 90 | + } |
| 91 | + out[writeIndex++] = b.toByte() |
| 92 | + index++ |
| 93 | + } |
| 94 | + if (blockEnd > srcLen) { |
| 95 | + throw CobsDecodeException( |
| 96 | + "length code points past end of input", |
| 97 | + blockEnd - code, |
| 98 | + ) |
| 99 | + } |
| 100 | + if (blockEnd < srcLen) { |
| 101 | + if (code < 0xFF) out[writeIndex++] = 0 |
| 102 | + } else { |
| 103 | + break |
| 104 | + } |
| 105 | + } |
| 106 | + |
| 107 | + return out.copyOf(writeIndex) |
| 108 | + } |
| 109 | + |
| 110 | + /** See the top-level [encodingOverhead]. */ |
| 111 | + @JvmStatic |
| 112 | + public fun encodingOverhead(sourceLength: Int): Int = |
| 113 | + dev.firechip.cobs.encodingOverhead(sourceLength) |
| 114 | + |
| 115 | + /** See the top-level [maxEncodedLength]. */ |
| 116 | + @JvmStatic |
| 117 | + public fun maxEncodedLength(sourceLength: Int): Int = |
| 118 | + dev.firechip.cobs.maxEncodedLength(sourceLength) |
| 119 | +} |
0 commit comments