framestream

package module
Version: v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 8, 2020 License: Apache-2.0 Imports: 8 Imported by: 0

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

View Source
const CONTROL_ACCEPT = 0x01
View Source
const CONTROL_FIELD_CONTENT_TYPE = 0x01
View Source
const CONTROL_FINISH = 0x05
View Source
const CONTROL_FRAME_LENGTH_MAX = 512
View Source
const CONTROL_READY = 0x04
View Source
const CONTROL_START = 0x02
View Source
const CONTROL_STOP = 0x03
View Source
const DEFAULT_MAX_PAYLOAD_SIZE = 1048576
View Source
const MAX_CONTROL_FRAME_SIZE = 512

Variables

View Source
var ControlAccept = ControlFrame{ControlType: CONTROL_ACCEPT}
View Source
var ControlFinish = ControlFrame{ControlType: CONTROL_FINISH}
View Source
var ControlReady = ControlFrame{ControlType: CONTROL_READY}
View Source
var ControlStart = ControlFrame{ControlType: CONTROL_START}
View Source
var ControlStop = ControlFrame{ControlType: CONTROL_STOP}
View Source
var EOF = io.EOF
View Source
var ErrContentTypeMismatch = errors.New("content type mismatch")
View Source
var ErrDataFrameTooLarge = errors.New("data frame too large")
View Source
var ErrDecode = errors.New("decoding error")
View Source
var ErrShortRead = errors.New("short read")
View Source
var ErrType = errors.New("invalid type")

Functions

This section is empty.

Types

type ControlFrame

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

func (*ControlFrame) ChooseContentType added in v0.3.0

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 added in v0.3.0

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 added in v0.3.0

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 added in v0.3.0

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 added in v0.3.0

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

ContentType returns the content type negotiated with the Writer.

func (*Reader) ReadFrame added in v0.3.0

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 added in v0.3.0

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 added in v0.3.0

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

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

func NewWriter added in v0.3.0

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 added in v0.3.0

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 added in v0.3.0

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

ContentType returns the content type negotiated with Reader.

func (*Writer) Flush added in v0.3.0

func (w *Writer) Flush() error

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

func (*Writer) WriteFrame added in v0.3.0

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 added in v0.3.0

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
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL