encapsulation

Documentation

Overview

Package encapsulation implements a way of encoding variable-size chunks of data and padding into a byte stream.

Each chunk of data or padding starts with a variable-size length prefix. One bit ("d") in the first byte of the prefix indicates whether the chunk represents data or padding (1=data, 0=padding). Another bit ("c" for "continuation") is the indicates whether there are more bytes in the length prefix. The remaining 6 bits ("x") encode part of the length value.

dcxxxxxx

If the continuation bit is set, then the next byte is also part of the length prefix. It lacks the "d" bit, has its own "c" bit, and 7 value-carrying bits ("y").

cyyyyyyy

The length is decoded by concatenating value-carrying bits, from left to right, of all value-carrying bits, up to and including the first byte whose "c" bit is 0. Although in principle this encoding would allow for length prefixes of any size, length prefixes are arbitrarily limited to 3 bytes and any attempt to read or write a longer one is an error. These are therefore the only valid formats:

00xxxxxx			xxxxxx₂ bytes of padding
10xxxxxx			xxxxxx₂ bytes of data
01xxxxxx 0yyyyyyy		xxxxxxyyyyyyy₂ bytes of padding
11xxxxxx 0yyyyyyy		xxxxxxyyyyyyy₂ bytes of data
01xxxxxx 1yyyyyyy 0zzzzzzz	xxxxxxyyyyyyyzzzzzzz₂ bytes of padding
11xxxxxx 1yyyyyyy 0zzzzzzz	xxxxxxyyyyyyyzzzzzzz₂ bytes of data

The maximum encodable length is 11111111111111111111₂ = 0xfffff = 1048575. There is no requirement to use a length prefix of minimum size; i.e. 00000100 and 01000000 00000100 are both valid encodings of the value 4.

After the length prefix follow that many bytes of padding or data. There are no restrictions on the value of bytes comprising padding.

The idea for this encapsulation is sketched here: https://github.com/net4people/bbs/issues/9#issuecomment-524095186

Index

• Variables
• func MaxDataForSize(n int) int
• func ReadData(r io.Reader) ([]byte, error)
• func WriteData(w io.Writer, data []byte) (int, error)
• func WritePadding(w io.Writer, n int) (int, error)

Variables

var ErrTooLong = errors.New("length prefix is too long")

ErrTooLong is the error returned when an encoded length prefix is longer than 3 bytes, or when ReadData receives an input whose length is too large to encode in a 3-byte length prefix.

Functions

func MaxDataForSize

func MaxDataForSize(n int) int

MaxDataForSize returns the length of the longest slice that can pe passed to WriteData, whose total encoded size (including length prefix) is no larger than n. Call this to find out if a chunk of data will fit into a length budget. Panics if n == 0.

func ReadData

func ReadData(r io.Reader) ([]byte, error)

ReadData returns a new slice with the contents of the next available data chunk, skipping over any padding chunks that may come first. The returned error value is nil if and only if a data chunk was present and was read in its entirety. The returned error is io.EOF only if r ended before the first byte of a length prefix. If r ended in the middle of a length prefix or data/padding, the returned error is io.ErrUnexpectedEOF.

func WriteData

func WriteData(w io.Writer, data []byte) (int, error)

WriteData encodes a data chunk into w. It returns the total number of bytes written; i.e., including the length prefix. The error is ErrTooLong if the length of data cannot fit into a length prefix.

func WritePadding

func WritePadding(w io.Writer, n int) (int, error)

WritePadding encodes padding chunks, whose total size (including their own length prefixes) is n. Returns the total number of bytes written to w, which will be exactly n unless there was an error. The error cannot be ErrTooLong because this function will write multiple padding chunks if necessary to reach the requested size. Panics if n is negative.