packet

Documentation

Index

• Constants
• type JSONPkt
  • func (p *JSONPkt) Clear()
  • func (p *JSONPkt) Close() error
  • func (p *JSONPkt) Data() []byte
  • func (p *JSONPkt) Dest() string
  • func (p *JSONPkt) Marshal() (bin []byte, err error)
  • func (p *JSONPkt) Meta() Metadata
  • func (p *JSONPkt) SetDest(dest string)
  • func (p *JSONPkt) Unmarshal(bin []byte) (err error)
  • func (p *JSONPkt) Write(data []byte) (n int, err error)
  • func (p *JSONPkt) Writer() Writer
• type JSONPktCreator
  • func (pc *JSONPktCreator) NewErrPkt(ref, dest, msg string) Packet
  • func (pc *JSONPktCreator) NewPkt(ref, dest string) Packet
  • func (pc *JSONPktCreator) PutBack(pkt Packet)
  • func (pc *JSONPktCreator) Warmup(numPackets int)
• type KVMeta
  • func NewKVMeta() *KVMeta
  • func (m *KVMeta) Add(key, val string)
  • func (m *KVMeta) Clear()
  • func (m *KVMeta) Get(key string) (val string)
• type Metadata
• type Packet
• type PacketCreator
  • func NewJSONPktCreator(numPkts int) PacketCreator
• type Writer

Constants

const (
	KeySvrStatus string = "_stat"
	KeySvrMsg           = "_msg"
	KeyRef              = "_ref"
	KeyTarget           = "_tgt"
)

Metadata keys

Types

type JSONPkt

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

JSONPkt wraps the underlying wire type to provide concurrency support and manage access to the underlying packet data. It encodes and decodes to `jsonPkt`. The JSON for JSONPkt should use field names as specified in the `jsonPkt` struct tags.

func (*JSONPkt) Clear

func (p *JSONPkt) Clear()

func (*JSONPkt) Close

func (p *JSONPkt) Close() error

Close commits the data written to the buffer to the underlying packet.

func (*JSONPkt) Data

func (p *JSONPkt) Data() []byte

func (*JSONPkt) Dest

func (p *JSONPkt) Dest() string

func (*JSONPkt) Marshal

func (p *JSONPkt) Marshal() (bin []byte, err error)

func (*JSONPkt) Meta

func (p *JSONPkt) Meta() Metadata

func (*JSONPkt) SetDest

func (p *JSONPkt) SetDest(dest string)

func (*JSONPkt) Unmarshal

func (p *JSONPkt) Unmarshal(bin []byte) (err error)

Unmarshal decodes the binary data into the packet `p`.

func (*JSONPkt) Write

func (p *JSONPkt) Write(data []byte) (n int, err error)

func (*JSONPkt) Writer

func (p *JSONPkt) Writer() Writer

type JSONPktCreator

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

JSONPktCreator implements a PacketCreator for the JSONPkt type.

func (*JSONPktCreator) NewErrPkt

func (pc *JSONPktCreator) NewErrPkt(ref, dest, msg string) Packet

func (*JSONPktCreator) NewPkt

func (pc *JSONPktCreator) NewPkt(ref, dest string) Packet

func (*JSONPktCreator) PutBack

func (pc *JSONPktCreator) PutBack(pkt Packet)

func (*JSONPktCreator) Warmup

func (pc *JSONPktCreator) Warmup(numPackets int)

type KVMeta

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

KVMeta is a concurrency-safe Metadata implementation.

func NewKVMeta

func NewKVMeta() *KVMeta

func (*KVMeta) Add

func (m *KVMeta) Add(key, val string)

func (*KVMeta) Clear

func (m *KVMeta) Clear()

func (*KVMeta) Get

func (m *KVMeta) Get(key string) (val string)

type Metadata

type Metadata interface {
	Add(key, val string)
	Get(key string) (val string)
	Clear()
}

Metadata defines a key-value metadata store for Packets.

type Packet

type Packet interface {
	// Dest returns the address to which this packet is destined.
	Dest() string
	// SetDest sets the destination of the packet.
	SetDest(dest string)
	// Meta is the metadata accessor.
	Meta() Metadata
	// Data is the packet data accessor.
	Data() []byte
	// Marshal encodes the Packet to binary.
	Marshal() (bin []byte, err error)
	// Unmarshal decodes the Packet from binary.
	Unmarshal(bin []byte) (err error)

	Writer() Writer
}

Packet defines the required behaviour of a type to be serialized/deserialized for over-the-wire transport. For users, the `Data` method returns the data sent in the Packet. Applications may choose to interpret this information in any way that they wish. Packets mainly work off of metadata and the target of a packet is specified using the metadata key "_tgt".

In the case that processing fails and the Server returns a Packet, there are special metadata keys set by the server: "_stat" and "_msg". The former is an integer (as a string), representing a status code (servers use "-1" for a generic error) and the latter is a string explaining the error. There is also the "_ref" key which can be set on a packet by the client. The server then maintains this "_ref" key metadata on its response, thereby enabling the Client to determine which request the response packet corresponds to. Note that Client is responsible for setting this "_ref" metadata.

type PacketCreator

type PacketCreator interface {
	// Warmup warms the underlying pool up with the given number of packets.
	Warmup(numPackets int)
	// PutBack returns the given packet to the PacketCreator pool.
	PutBack(Packet)
	// NewPkt returns a new packet with the given ref and dest.
	NewPkt(ref, dest string) Packet
	// NewErrPkt creates error packets for Server/Client user.
	NewErrPkt(ref, dest, msg string) Packet
}

PacketCreator abstracts creation of packets so that Server types may be completely agnostic to Packet types and applications may instantiate Servers with configurable Packet types. The `ref` string is included in the following PacketCreator method signatures to indicate the importance of the `ref` metadata on requests (of course, the `ref` can also be set by using a Packet.Meta().Add(packet.KeyRef, "<ref>") call, as with any other metadata). The `ref` is important because it is the only piece of information unique to a request sent by a particular address.

The PacketCreator possesses an underlying pool of packets which could be useful in high-throughput cases to avoid the overhead of packet allocations. The Warmup method warms the pool up with a specific number of packets. The New*Pkt methods return packets from the underlying pool and the PutBack method returns packets to the pool.

func NewJSONPktCreator

func NewJSONPktCreator(numPkts int) PacketCreator

NewJSONPktCreator initializes and returns a JSONPktCreator with an underlying packet pool size of `numPkts`.

type Writer

type Writer interface {
	io.WriteCloser
	Meta() Metadata
	Clear()
}

Writer describes the behaviour of a Packet writer, used to compose Packets.