cobs

README

COBS

A Golang module for the Consistent Overhead Byte Stuffing (COBS) algorithm.

Usage

This module provides both simple helper functions to Encode/Decode []byte arrays and Encoder/Decoder structs to stream bytes to an io.Writer instance.

Encode/Decode functions

The helper functions will allocate buffers to hold the encoded/decoded data and return a []byte slice or an error.

The following example encodes a string with embedded zeroes:

package main

import (
	"os"

	"github.com/pdgendt/cobs"
)

func main() {
	enc, _ := cobs.Encode([]byte{'H', 'e', 'l', 'l', 'o', 0x00, 'w', 'o', 'r', 'l', 'd', '!'})

	os.Stdout.write(enc)
}

Encoder/Decoder structs

The structs require an io.Writer instance on creation. As soon as data is available it is written, for the Encoder this is done for each group, with a maximum of 255 bytes, for the Decoder every byte is written individually.

The structs implement the io.Writer interface to allow chaining.

The following example encodes bytes read from os.Stdin and writes them to os.Stdout:

package main

import (
	"io"
	"os"

	"github.com/pdgendt/cobs"
)

func main() {
	enc := cobs.NewEncoder(os.Stdout)

	if _, err := io.Copy(enc, os.Stdin); err != nil {
		panic(err)
	}

	// Close needs to be called to flush the last group
	if err := enc.Close(); err != nil {
		panic(err)
	}
}

CLI tools

The cmd/ directory contains simple encode/decode command line tools that take in data from stdin and writes it to stdout.

This can be used to pipe encoded/decoded data to other processes.

$ echo "Hello world" | go run cmd/encode/main.go | go run cmd/decode/main.go
Hello world

Documentation

Overview

Package cobs implements Consistent Overhead Byte Stuffing (COBS) encoding and decoding algorithms for efficient, reliable and unambiguous packet framing.

Index

• Constants
• Variables
• func Decode(data []byte) ([]byte, error)
• func Encode(data []byte) ([]byte, error)
• type Decoder
  • func NewDecoder(w io.Writer) *Decoder
  • func (d *Decoder) NeedsMoreData() bool
  • func (d *Decoder) Write(p []byte) (int, error)
  • func (d *Decoder) WriteByte(c byte) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Close() error
  • func (e *Encoder) Write(p []byte) (int, error)
  • func (e *Encoder) WriteByte(c byte) error

Constants

const (
	Delimiter = byte(0x00) // packet framing delimiter.
)

Variables

var EOD = errors.New("EOD")

EOD is the error returned when decoding and a delimiter was written. Functions return EOD to signal a graceful end of a frame.

var ErrIncompleteFrame = errors.New("frame incomplete")

ErrIncompleteData means a decoder was closed with an incomplete frame.

var ErrUnexpectedEOD = errors.New("unexpected EOD")

ErrUnexpectedEOD means that a delimiter was encountered in a malformed frame.

Functions

func Decode

func Decode(data []byte) ([]byte, error)

Decode decodes and returns a byte slice.

func Encode

func Encode(data []byte) ([]byte, error)

Encode encodes and returns a byte slice.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder implements the io.Writer and io.ByteWriter interfaces. Data written will we be decoded and forwarded byte per byte.

func NewDecoder

func NewDecoder(w io.Writer) *Decoder

NewDecoder returns a Decoder that writes decoded data to w.

func (*Decoder) NeedsMoreData

func (d *Decoder) NeedsMoreData() bool

NeedsMoreData returns true if the decoder needs more data for a full frame.

func (*Decoder) Write

func (d *Decoder) Write(p []byte) (int, error)

Write will call WriteByte for each byte in p.

func (*Decoder) WriteByte

func (d *Decoder) WriteByte(c byte) error

WriteByte decodes a single byte c. If c is a delimiter the decoder state is validated and either EOD or ErrUnexpectedEOD is returned.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder implements the io.Writer and io.ByteWriter interfaces. Data written will we be encoded into groups and forwarded.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns an Encoder that writes encoded data to w.

func (*Encoder) Close

func (e *Encoder) Close() error

Close has to be called after writing a full frame and will write the last group.

func (*Encoder) Write

func (e *Encoder) Write(p []byte) (int, error)

Write will call WriteByte for each byte in p.

func (*Encoder) WriteByte

func (e *Encoder) WriteByte(c byte) error

WriteByte encodes a single byte c. If a group is finished it is written to w.