frames

README

Frames is a simple multiplexing protocol I use when I need to ask for
a lot of different things concurrently between two servers and I don't
want to burn lots of file descriptors or rely on pipelining timings
and such things to do it.

This should be usable anywhere you use a =net.Conn= today.  There's
some convenience support for HTTP as I'm using it quite a bit as an
HTTP transport.

* Protocol

The protocol is really simple, just a 6 byte header followed by 0 or
more bytes of data (maximum data size of 2^16).

|-------------+---------------------+-------------+----------|
| Field       | Type                | Byte Offset | Byte Len |
|-------------+---------------------+-------------+----------|
| Data Length | unsigned 16-bit int | 0           | 2        |
| Channel     | unsigned 16-bit int | 2           | 2        |
| Command     | byte                | 4           | 1        |
| Status      | byte                | 5           | 1        |


** Definitions

*** Commands

|---------+------|
| Command |   ID |
|---------+------|
| Open    | 0x00 |
| Close   | 0x01 |
| Data    | 0x02 |


*** Status

|---------+----|
| Status  | ID |
|---------+----|
| Success |  0 |
| Error   |  1 |


** Flow

A client begins by establishing a TCP connection.  To do anything
useful, it must first issue an =Open= command to get a new channel
assigned.  If this is successful (=Status= = =Success=), the client
will get a response with the Command set to =Open= and the channel
ID set to the new channel.

A client may open as many channels as necessary and then send =Data=
packets along with the corresponding data.

A client MUST =Close= the channel when you're done with it if you
intend to continue using the service.  If the client is completely
done, it MAY drop the underlying TCP connection and the server MUST
clean up after you.

Documentation

Overview

Package frames is a simple multiplexing protocol.

Index

• Constants
• Variables
• func Listen(underlying net.Conn) (net.Listener, error)
• func ListenerListener(l net.Listener) (net.Listener, error)
• type ChannelDialer
  • func NewClient(c net.Conn) ChannelDialer
• type FrameCmd
  • func (c FrameCmd) String() string
• type FramePacket
  • func PacketFromHeader(hdr []byte) FramePacket
  • func (fp FramePacket) Bytes() []byte
  • func (fp FramePacket) String() string
• type FrameStatus
  • func (c FrameStatus) String() string
• type Info
  • func (i Info) String() string

Constants

const (
	// FrameOpen is a command to open a channel on a connection.
	FrameOpen = FrameCmd(iota)
	// FrameClose is a command to close a channel on a connection.
	FrameClose
	// FrameData is a command indicating the packet contains data.
	FrameData
)

const (
	// FrameSuccess is the status indicating a successful command.
	FrameSuccess = FrameStatus(iota)
	// FrameError is the status indicating a failed command.
	FrameError
)

Variables

var ErrChannelsExhausted = errors.New("channels exhausted")

ErrChannelsExhausted is returned when we've run out of channels.

Functions

func Listen

func Listen(underlying net.Conn) (net.Listener, error)

Listen for channeled connections across connections from the given listener.

func ListenerListener

func ListenerListener(l net.Listener) (net.Listener, error)

ListenerListener is a listener that listens on a net.Listener and returns framed connections opened from connections opened by the underlying Listener.

Types

type ChannelDialer

type ChannelDialer interface {
	io.Closer
	Dial() (net.Conn, error)
	GetInfo() Info
}

ChannelDialer is the client interface from which one builds connections.

func NewClient

func NewClient(c net.Conn) ChannelDialer

NewClient converts a socket into a channel dialer.

type FrameCmd

type FrameCmd uint8

FrameCmd is the type of command on a frames stream.

func (FrameCmd) String

func (c FrameCmd) String() string

type FramePacket

type FramePacket struct {
	// The command
	Cmd FrameCmd
	// Status int
	Status FrameStatus
	// Channel over which the command should be sent.
	Channel uint16
	// Extra data for the command.
	Data []byte
	// contains filtered or unexported fields
}

A FramePacket is a packet sent or received over a connection.

func PacketFromHeader

func PacketFromHeader(hdr []byte) FramePacket

PacketFromHeader constructs a packet from the given header.

func (FramePacket) Bytes

func (fp FramePacket) Bytes() []byte

Bytes converts this packet to its network representation.

func (FramePacket) String

func (fp FramePacket) String() string

type FrameStatus

type FrameStatus uint8

FrameStatus represents a command status.

func (FrameStatus) String

func (c FrameStatus) String() string

type Info

type Info struct {
	BytesRead    uint64 `json:"read"`
	BytesWritten uint64 `json:"written"`
	ChannelsOpen int    `json:"channels"`
}

Info provides basic state of a client.

func (Info) String

func (i Info) String() string