message

Documentation

Overview

Package message implements the wire protocol between clients and servers

Index

• Variables
• func RandomBytes() []byte
• func RandomString() string
• func RandomTag() uint16
• func RandomVersion() uint64
• type Decoder
  • func (d *Decoder) Decode(r io.Reader, m *Message) error
• type Encoder
  • func (e *Encoder) Encode(w io.Writer, m Message) error
• type Kind
  • func (k Kind) String() string
• type Message
  • func NewAuthMessage(tag uint16, password string) Message
  • func NewErrorMessage(tag uint16, message string) Message
  • func NewGetMessage(tag uint16, key string) Message
  • func NewPutMessage(tag uint16, key string, value string, version uint64) Message
  • func (m Message) ForBroadcast() Message
  • func (Message) Generate(rand *rand.Rand, size int) reflect.Value
  • func (m Message) Key() string
  • func (m Message) Kind() Kind
  • func (m Message) String() string
  • func (m Message) Tag() uint16
  • func (m Message) Value() string
  • func (m Message) Version() uint64
• type MonotoneTags
  • func NewMonotoneTags() *MonotoneTags
  • func (t *MonotoneTags) Next() uint16
  • func (t *MonotoneTags) Stop()

Variables

var (
	// ErrUnderflow is returned when not all bytes can be written (in the encoder)
	// or read (in the decoder).
	ErrUnderflow = errors.New("underflow")

	// ErrBadMessage could be returned by Encoder.Encode, which would never happen
	// if messages are constructed via the provided helper message, e.g.,
	// NewGetMessage.
	ErrBadMessage = errors.New("bad message")
)

Functions

func RandomBytes

func RandomBytes() []byte

RandomBytes is a test helper.

func RandomString

func RandomString() string

RandomString is a test helper.

func RandomTag

func RandomTag() uint16

RandomTag is a test helper.

func RandomVersion

func RandomVersion() uint64

RandomVersion is a test helper.

Types

type Decoder

type Decoder struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Decoder is responsible for deserializing message from any reader (bytes to structs).

func (*Decoder) Decode

func (d *Decoder) Decode(r io.Reader, m *Message) error

Decode deserializes bytes from the given reader into the given message. It will return the first read error encountered in the process, if any. It will internally serialize concurrent calls, while the client should serialize access to the reader as necessary.

type Encoder

type Encoder struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Encoder is responsible for encoding any message to any writer (e.g., a network connection, a file, a byte buffer...).

func (*Encoder) Encode

func (e *Encoder) Encode(w io.Writer, m Message) error

Encode serializes the given message to the given writer, typically a network connection. Concurrent calls to Encode will be serialized, to preserve internal state of the Encoder, but it is up to the client to serialize access to the writer as necessary.

type Kind

type Kind uint8

Kind is a number representing the kind of a message—get, put, or error.

const (
	// KindGet is a message from the client to the server, stating the client wants
	// to know the latest version of the value for a given key. It is never sent
	// from the server to the client. This kind of message should only be issued
	// when the client does not have a version of the value for the given key, or
	// the client knows the version is stale, e.g., because of a put error.
	KindGet Kind = iota

	// KindPut is a message that can be sent both by the client and the server. It
	// is used by clients to update a key's corresponding value with a new version.
	// The server responds with the exact same put message if the put is accepted,
	// or with and error message. The server also fans out accepted put messages to
	// all clients that are connected, so they can keep up to date. This way,
	// clients should not need to issue get messages often.
	KindPut

	// KindError is a message that is only sent from the server to the client. That
	// can be in response to a get message (in case the requested key is not known)
	// or in response to a put message (in case the put version number is wrong).
	// The version number in a put message should match the one in the server,
	// proving that the client is up to date. If the put is stale, the client may
	// be overwriting some value, so the client should get the latest version and
	// possibly redo the put with the correct version, or give up the put). Other
	// error conditions might arise.
	KindError

	// KindAuth is sent with a password value from client to server (only over a
	// TLS connection) to authorize the client. It is sent with an empty value
	// from server to client upon successful authorization. If the password does
	// not match, the server response will be of KindError.
	KindAuth
)

func (Kind) String

func (k Kind) String() string

String implements fmt.Stringer.

type Message

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

Message is a container for exchanging messages between clients and servers

func NewAuthMessage

func NewAuthMessage(tag uint16, password string) Message

NewAuthMessage constructs a message of KindAuth kind.

func NewErrorMessage

func NewErrorMessage(tag uint16, message string) Message

NewErrorMessage constructs a message of KindError kind.

func NewGetMessage

func NewGetMessage(tag uint16, key string) Message

NewGetMessage constructs a message of KindGet kind.

func NewPutMessage

func NewPutMessage(tag uint16, key string, value string, version uint64) Message

NewPutMessage constructs a message of KindPut kind.

func (Message) ForBroadcast

func (m Message) ForBroadcast() Message

ForBroadcast returns a copy of the message that's suitable to be broadcasted to many connections.

func (Message) Generate

func (Message) Generate(rand *rand.Rand, size int) reflect.Value

Generate implements quick.Generator.

func (Message) Key

func (m Message) Key() string

Key returns a key-value pair's key from the message. Call only for KindGet and KindPut, else it'll panic.

func (Message) Kind

func (m Message) Kind() Kind

Kind returns the kind of a message, which should inform how the message should be used.

func (Message) String

func (m Message) String() string

String implements fmt.Stringer. Keys and values will be printed in hex form if they contain any non-printable character. Also, they will be clipped at 10 runes (not necessarily 10 bytes).

func (Message) Tag

func (m Message) Tag() uint16

Tag returns the tag of a message (call for all message kinds). Used to correlate requests with responses.

func (Message) Value

func (m Message) Value() string

Value returns a key-value pair's value from the message. Call only for KindAuth, KindError and KindPut, else it'll panic.

func (Message) Version

func (m Message) Version() uint64

Version returns the version of a key-value pair. Call only for KindPut messages, or it'll panic.

type MonotoneTags

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

MonotoneTags provides thread-safe increasing tag numbers. It's a facility for metadata server clients. (Each client should generate messages with distinct tags. Tags are used to correlate requests with responses.)

func NewMonotoneTags

func NewMonotoneTags() *MonotoneTags

NewMonotoneTags creates a new instance MonotoneTags

func (*MonotoneTags) Next

func (t *MonotoneTags) Next() uint16

Next returns the next tag. It will loop around and start back from 1 after 65535. The zero tag is reserved for broadcast messages (not answers to any request). (Hopefully no client will have more than 65535 requests in flight.)

func (*MonotoneTags) Stop

func (t *MonotoneTags) Stop()

Stop stops the goroutine that generates tag numbers. Calling Next after Stop will panic.