framestream

README

Frame Streams implementation in Go

https://github.com/farsightsec/golang-framestream

Frame Streams is a lightweight, binary-clean protocol that allows for the transport of arbitrarily encoded data payload sequences with minimal framing overhead.

This package provides a pure Golang implementation. The Frame Streams implementation in C is at https://github.com/farsightsec/fstrm/.

The example framestream_dump program reads a Frame Streams formatted input file and prints the data frames and frame byte counts.

Documentation

Index

• Constants
• Variables
• type ControlFrame
  • func (c *ControlFrame) ChooseContentType(ctypes [][]byte) (typ []byte, found bool)
  • func (c *ControlFrame) Decode(r io.Reader) (err error)
  • func (c *ControlFrame) DecodeEscape(r io.Reader) error
  • func (c *ControlFrame) DecodeTypeEscape(r io.Reader, ctype uint32) error
  • func (c *ControlFrame) Encode(w io.Writer) (err error)
  • func (c *ControlFrame) EncodeFlush(w *bufio.Writer) error
  • func (c *ControlFrame) MatchContentType(ctype []byte) bool
  • func (c *ControlFrame) SetContentType(ctype []byte)
  • func (c *ControlFrame) SetContentTypes(ctypes [][]byte)
• type Decoder
  • func NewDecoder(r io.Reader, opt *DecoderOptions) (*Decoder, error)
  • func (dec *Decoder) Decode() (frameData []byte, err error)
• type DecoderOptions
• type Encoder
  • func NewEncoder(w io.Writer, opt *EncoderOptions) (enc *Encoder, err error)
  • func (e *Encoder) Write(frame []byte) (int, error)
• type EncoderOptions
• type Reader
  • func NewReader(r io.Reader, opt *ReaderOptions) (*Reader, error)
  • func (r *Reader) ContentType() []byte
  • func (r *Reader) ReadFrame(b []byte) (length int, err error)
• type ReaderOptions
• type Writer
  • func NewWriter(w io.Writer, opt *WriterOptions) (writer *Writer, err error)
  • func (w *Writer) Close() (err error)
  • func (w *Writer) ContentType() []byte
  • func (w *Writer) Flush() error
  • func (w *Writer) WriteFrame(frame []byte) (n int, err error)
• type WriterOptions

Constants

const CONTROL_ACCEPT = 0x01

const CONTROL_FIELD_CONTENT_TYPE = 0x01

const CONTROL_FINISH = 0x05

const CONTROL_FRAME_LENGTH_MAX = 512

const CONTROL_READY = 0x04

const CONTROL_START = 0x02

const CONTROL_STOP = 0x03

const DEFAULT_MAX_PAYLOAD_SIZE = 1048576

const MAX_CONTROL_FRAME_SIZE = 512

Variables

var ControlAccept = ControlFrame{ControlType: CONTROL_ACCEPT}

var ControlFinish = ControlFrame{ControlType: CONTROL_FINISH}

var ControlReady = ControlFrame{ControlType: CONTROL_READY}

var ControlStart = ControlFrame{ControlType: CONTROL_START}

var ControlStop = ControlFrame{ControlType: CONTROL_STOP}

var EOF = io.EOF

var ErrContentTypeMismatch = errors.New("content type mismatch")

var ErrDataFrameTooLarge = errors.New("data frame too large")

var ErrDecode = errors.New("decoding error")

var ErrShortRead = errors.New("short read")

var ErrType = errors.New("invalid type")

Types

type ControlFrame

type ControlFrame struct {
	ControlType  uint32
	ContentTypes [][]byte
}

func (*ControlFrame) ChooseContentType

func (c *ControlFrame) ChooseContentType(ctypes [][]byte) (typ []byte, found bool)

ChooseContentType selects a content type from the ControlFrame which also exists in the supplied ctypes. Preference is given to values occurring earliest in ctypes.

ChooseContentType returns the chosen content type, which may be nil, and a bool value indicating whether a matching type was found.

If either the ControlFrame types or ctypes is empty, ChooseContentType returns nil as a matching content type.

func (*ControlFrame) Decode

func (c *ControlFrame) Decode(r io.Reader) (err error)

func (*ControlFrame) DecodeEscape

func (c *ControlFrame) DecodeEscape(r io.Reader) error

func (*ControlFrame) DecodeTypeEscape

func (c *ControlFrame) DecodeTypeEscape(r io.Reader, ctype uint32) error

func (*ControlFrame) Encode

func (c *ControlFrame) Encode(w io.Writer) (err error)

func (*ControlFrame) EncodeFlush

func (c *ControlFrame) EncodeFlush(w *bufio.Writer) error

func (*ControlFrame) MatchContentType

func (c *ControlFrame) MatchContentType(ctype []byte) bool

func (*ControlFrame) SetContentType

func (c *ControlFrame) SetContentType(ctype []byte)

func (*ControlFrame) SetContentTypes

func (c *ControlFrame) SetContentTypes(ctypes [][]byte)

type Decoder

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

A Decoder decodes Frame Streams frames read from an underlying io.Reader.

It is provided for compatibility. Use Reader instead.

func NewDecoder

func NewDecoder(r io.Reader, opt *DecoderOptions) (*Decoder, error)

NewDecoder returns a Decoder using the given io.Reader and options.

func (*Decoder) Decode

func (dec *Decoder) Decode() (frameData []byte, err error)

Decode returns the data from a Frame Streams data frame. The slice returned is valid until the next call to Decode.

type DecoderOptions

type DecoderOptions struct {
	// MaxPayloadSize is the largest frame size accepted by the Decoder.
	//
	// If the Frame Streams Writer sends a frame in excess of this size,
	// Decode() will return the error ErrDataFrameTooLarge. The Decoder
	// attempts to recover from this error, so calls to Decode() after
	// receiving this error may succeed.
	MaxPayloadSize uint32
	// The ContentType expected by the Decoder. May be left unset for no
	// content negotiation. If the Writer requests a different content type,
	// NewDecoder() will return ErrContentTypeMismatch.
	ContentType []byte
	// If Bidirectional is true, the underlying io.Reader must be an
	// io.ReadWriter, and the Decoder will engage in a bidirectional
	// handshake with its peer to establish content type and communicate
	// shutdown.
	Bidirectional bool
	// Timeout gives the timeout for reading the initial handshake messages
	// from the peer and writing response messages if Bidirectional. It is
	// only effective for underlying Readers satisfying net.Conn.
	Timeout time.Duration
}

DecoderOptions specifies configuration for a framestream Decoder.

type Encoder

type Encoder struct {
	*Writer
}

An Encoder sends data frames over a FrameStream Writer.

Encoder is provided for compatibility, use Writer instead.

func NewEncoder

func NewEncoder(w io.Writer, opt *EncoderOptions) (enc *Encoder, err error)

NewEncoder creates an Encoder writing to the given io.Writer with the given EncoderOptions.

func (*Encoder) Write

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

type EncoderOptions

type EncoderOptions struct {
	// The ContentType of the data sent by the Encoder. May be left unset
	// for no content negotiation. If the Reader requests a different
	// content type, NewEncoder() will return ErrContentTypeMismatch.
	ContentType []byte
	// If Bidirectional is true, the underlying io.Writer must be an
	// io.ReadWriter, and the Encoder will engage in a bidirectional
	// handshake with its peer to establish content type and communicate
	// shutdown.
	Bidirectional bool
	// Timeout gives the timeout for writing both control and data frames,
	// and for reading responses to control frames sent. It is only
	//  effective for underlying Writers satisfying net.Conn.
	Timeout time.Duration
}

EncoderOptions specifies configuration for an Encoder

type Reader

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

Reader reads data frames from an underlying io.Reader using the Frame Streams framing protocol.

func NewReader

func NewReader(r io.Reader, opt *ReaderOptions) (*Reader, error)

NewReader creates a Frame Streams Reader reading from the given io.Reader with the given ReaderOptions.

func (*Reader) ContentType

func (r *Reader) ContentType() []byte

ContentType returns the content type negotiated with the Writer.

func (*Reader) ReadFrame

func (r *Reader) ReadFrame(b []byte) (length int, err error)

ReadFrame reads a data frame into the supplied buffer, returning its length. If the frame is longer than the supplied buffer, Read returns ErrDataFrameTooLarge and discards the frame. Subsequent calls to Read() after this error may succeed.

type ReaderOptions

type ReaderOptions struct {
	// The ContentTypes accepted by the Reader. May be left unset for no
	// content negotiation. If the corresponding Writer offers a disjoint
	// set of ContentTypes, NewReader() will return ErrContentTypeMismatch.
	ContentTypes [][]byte
	// If Bidirectional is true, the underlying io.Reader must be an
	// io.ReadWriter, and the Reader will engage in a bidirectional
	// handshake with its peer to establish content type and communicate
	// shutdown.
	Bidirectional bool
	// Timeout gives the timeout for reading the initial handshake messages
	// from the peer and writing response messages if Bidirectional. It is
	// only effective for underlying Readers satisfying net.Conn.
	Timeout time.Duration
}

type Writer

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

A Writer writes data frames to a Frame Streams file or connection.

func NewWriter

func NewWriter(w io.Writer, opt *WriterOptions) (writer *Writer, err error)

NewWriter returns a Frame Streams Writer using the given io.Writer and options.

func (*Writer) Close

func (w *Writer) Close() (err error)

Close shuts down the Frame Streams stream by writing a CONTROL_STOP message. If the Writer is Bidirectional, Close will wait for an acknowledgement (CONTROL_FINISH) from its peer.

func (*Writer) ContentType

func (w *Writer) ContentType() []byte

ContentType returns the content type negotiated with Reader.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush ensures that any buffered data frames are written to the underlying io.Writer.

func (*Writer) WriteFrame

func (w *Writer) WriteFrame(frame []byte) (n int, err error)

WriteFrame writes the given frame to the underlying io.Writer with Frame Streams framing.

type WriterOptions

type WriterOptions struct {
	// The ContentTypes available to be written to the Writer. May be
	// left unset for no content negotiation. If the Reader requests a
	// disjoint set of content types, NewEncoder() will return
	// ErrContentTypeMismatch.
	ContentTypes [][]byte
	// If Bidirectional is true, the underlying io.Writer must be an
	// io.ReadWriter, and the Writer will engage in a bidirectional
	// handshake with its peer to establish content type and communicate
	// shutdown.
	Bidirectional bool
	// Timeout gives the timeout for writing both control and data frames,
	// and for reading responses to control frames sent. It is only
	//  effective for underlying Writers satisfying net.Conn.
	Timeout time.Duration
}