proto

Documentation

Overview

Package proto encapsulates the types used to communicate between multiple tableroll processes at various versions, as well as the functions for reading and writing this data off the wire.

Currently, there are two protocol versions: v0 and v1. The v1 protocol exists because the v0 protocol allows for a new process to think it had notified the previous owner it was ready, even if the new owner never read that byte. The primary reason this is possible is because the protocol is over a stream oriented unix socket, not a unix dgram socket. In order to fix this issue, the v1 protocol includes a more complete 'upgrade complete' handshake which ensures both processes actively signal intent for the new process to take over.

The v1 ready handshake between N, a new process which is attempting to become an owner, and O, the current owner / old process, is the following:

N sends 'V1StartReadyHandshake' to O N sends 'VersionInformation{Version: 1}' to O O sends 'Message{Msg: V1MessageSteppingDown}' to N O closes the connection

There are two failure modes of interest here. 1. O sends 'SteppingDown' but 'N' doesn't read it. 2. O gets an error sending 'SteppingDown' and is unsure if 'N' received it.

In the case of 1. the failure mode is that there are now no owners. The expected behavior is that 'N', if it fails to complete the handshake, will return an error from 'Ready()' and exit, and will then restart and get succeed since there will now be no owner. In the case of 2, O must assume that the message sent successfully and actually step down. This again leaves us with zero owners in the failure mode, which is what we want. All other cases should result in O remaining the owner, or the ownership transfer completing successfully.

Index

• Constants
• func ReadJSONBlob(src io.Reader, obj interface{}) error
• func ReadVersionedJSONBlob(src io.Reader, obj interface{}) (uint32, error)
• func WriteJSONBlob(dst io.Writer, obj interface{}) error
• func WriteVersionedJSONBlob(dst io.Writer, obj interface{}, version uint32) error
• type Message
• type VersionInformation

Constants

const (
	// Version is the latest version of the protocol. It is implicitly 0 for
	// clients that didn't yet have a protocol version
	Version = 1

	// V0NotifyReady is the value sent at the end in the v0 protocol to indicate
	// readyness
	V0NotifyReady = 42

	// V1StartReadyHandshake is at the start of a v1 handshake
	V1StartReadyHandshake = 0x42

	// V1MessageSteppingDown is the message the old process sends in the handshake
	V1MessageSteppingDown = "stepping down"
)

Functions

func ReadJSONBlob

func ReadJSONBlob(src io.Reader, obj interface{}) error

ReadJSONBlob reads a length-prefixed json blob written by WriteJSONBlob.

func ReadVersionedJSONBlob

func ReadVersionedJSONBlob(src io.Reader, obj interface{}) (uint32, error)

ReadVersionedJSONBlob reads a JSON blob from the given writer. If the blob was written with WriteVersionedJSONBlob, it determines the version and returns it.

func WriteJSONBlob

func WriteJSONBlob(dst io.Writer, obj interface{}) error

WriteJSONBlob writes a length-prefixed json blob.

func WriteVersionedJSONBlob

func WriteVersionedJSONBlob(dst io.Writer, obj interface{}, version uint32) error

WriteVersionedJSONBlob writes a JSON blob to the given writer. It expects the blob to be read using 'ReadVersionedJSONBlob'. A version is included via a v0 compatible hack since v0 did not include the version. Specifically, the version is encoded as whitespace prefixing the json data.

Types

type Message

type Message struct {
	Msg string `json:"msg"`
}

type VersionInformation

type VersionInformation struct {
	Version int32 `json:"version"`
}

VersionInformation communicates the protocol version this process supports. Added in v1