streamproto

Documentation

Overview

Package streamproto describes the protocol primitives used by LogDog/Butler for stream negotiation.

A LogDog Butler client wishing to create a new LogDog stream can use the Flags type to configure/send the stream.

Internally, LogDog represents the Flags properties with the Properties type.

Index

• Variables
• type Flags
  • func (f *Flags) Properties() *Properties
• type Properties
  • func (p *Properties) Clone() *Properties
  • func (p *Properties) Validate() error
• type StreamNameFlag
  • func (f StreamNameFlag) MarshalJSON() ([]byte, error)
  • func (f *StreamNameFlag) Set(v string) error
  • func (f *StreamNameFlag) String() string
  • func (f *StreamNameFlag) UnmarshalJSON(data []byte) error
• type StreamType
  • func (t StreamType) DefaultContentType() types.ContentType
  • func (t StreamType) MarshalJSON() ([]byte, error)
  • func (t *StreamType) Set(v string) error
  • func (t *StreamType) String() string
  • func (t *StreamType) UnmarshalJSON(data []byte) error
• type TagMap
  • func (t *TagMap) MarshalJSON() ([]byte, error)
  • func (t *TagMap) Set(key string) error
  • func (t TagMap) SortedKeys() []string
  • func (t *TagMap) String() string
  • func (t *TagMap) UnmarshalJSON(data []byte) error
• type TeeType
  • func (t TeeType) MarshalJSON() ([]byte, error)
  • func (t *TeeType) Set(v string) error
  • func (t *TeeType) String() string
  • func (t *TeeType) UnmarshalJSON(data []byte) error
  • func (t TeeType) Writer() io.Writer

Variables

var (
	// ProtocolFrameHeaderMagic is the number at the beginning of streams that
	// identifies the stream handshake version.
	//
	// This serves two purposes:
	//   - To disambiguate a Butler stream from some happenstance string of bytes
	//     (which probably won't start with these characters).
	//   - To allow an upgrade to the wire format, if one is ever needed. e.g.,
	//     a switch to something other than recordio/JSON.
	ProtocolFrameHeaderMagic = []byte("BTLR1\x1E")
)

var (
	// StreamTypeFlagEnum maps configuration strings to their underlying StreamTypes.
	StreamTypeFlagEnum = flagenum.Enum{
		"text":     StreamType(logpb.StreamType_TEXT),
		"binary":   StreamType(logpb.StreamType_BINARY),
		"datagram": StreamType(logpb.StreamType_DATAGRAM),
	}
)

var (
	// TeeTypeFlagEnum is a flag- and JSON-compatible enumeration mapping
	// TeeType configuration strings to their underlying TeeType values.
	TeeTypeFlagEnum = flagenum.Enum{
		"none":   TeeNone,
		"stdout": TeeStdout,
		"stderr": TeeStderr,
	}
)

Types

type Flags

type Flags struct {
	Name                StreamNameFlag `json:"name,omitempty"`
	ContentType         string         `json:"contentType,omitempty"`
	Type                StreamType     `json:"type,omitempty"`
	Timestamp           clockflag.Time `json:"timestamp,omitempty"`
	Tags                TagMap         `json:"tags,omitempty"`
	BinaryFileExtension string         `json:"binaryFileExtension,omitempty"`
	IOKeepAlive         bool           `json:"ioKeepAlive,omitempty"`

	Tee      TeeType            `json:"tee,omitempty"`
	Timeout  clockflag.Duration `json:"timeout,omitempty"`
	Deadline clockflag.Duration `json:"deadline,omitempty"`
}

Flags is a flag- and JSON-compatible collapse of Properties. It is used for stream negotiation protocol and command-line interfaces.

func (*Flags) Properties

func (f *Flags) Properties() *Properties

Properties converts the Flags to a standard Properties structure.

If the values are not valid, this conversion will return an error.

type Properties

type Properties struct {
	// The log stream's descriptor.
	//
	// Note that the Prefix value, if filled, will be overridden by the Butler's
	// Prefix.
	*logpb.LogStreamDescriptor

	// Tee is the tee configuration for this stream. If empty, the stream will
	// not be tee'd.
	Tee TeeType

	// Timeout, if specified, is the stream timeout. If a read happens without
	// filling the buffer, it will prematurely return after this period.
	Timeout time.Duration

	// Deadline, if set, specifies the maximum amount of time that data from this
	// Stream can be buffered before being sent to its Output.
	//
	// Note that this value is best-effort, as it is subject to the constraints
	// of the underlying transport medium.
	Deadline time.Duration
}

Properties is the set of properties needed to define a LogDog Butler Stream.

func (*Properties) Clone

func (p *Properties) Clone() *Properties

Clone returns a fully-independent clone of this Properties object.

func (*Properties) Validate

func (p *Properties) Validate() error

Validate validates that the configured Properties are valid and sufficient to create a Butler stream.

It skips stream Prefix validation and instead asserts that it is empty, as it should not be populated when Properties are defined.

type StreamNameFlag

type StreamNameFlag types.StreamName

StreamNameFlag is a flag and JSON-compatible type that converts to/from a types.StreamName. StreamName validation is part of the conversion.

func (StreamNameFlag) MarshalJSON

func (f StreamNameFlag) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StreamNameFlag) Set

func (f *StreamNameFlag) Set(v string) error

Set implements flag.Value.

func (*StreamNameFlag) String

func (f *StreamNameFlag) String() string

String implements flag.Value.

func (*StreamNameFlag) UnmarshalJSON

func (f *StreamNameFlag) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type StreamType

type StreamType logpb.StreamType

StreamType is a flag- and JSON-compatible wrapper around the StreamType protobuf field.

func (StreamType) DefaultContentType

func (t StreamType) DefaultContentType() types.ContentType

DefaultContentType returns the default ContentType for a given stream type.

func (StreamType) MarshalJSON

func (t StreamType) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StreamType) Set

func (t *StreamType) Set(v string) error

Set implements flag.Value.

func (*StreamType) String

func (t *StreamType) String() string

String implements flag.Value.

func (*StreamType) UnmarshalJSON

func (t *StreamType) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type TagMap

type TagMap stringmapflag.Value

TagMap is a flags-compatible map used to store stream tags.

func (*TagMap) MarshalJSON

func (t *TagMap) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*TagMap) Set

func (t *TagMap) Set(key string) error

Set implements flag.Value

func (TagMap) SortedKeys

func (t TagMap) SortedKeys() []string

SortedKeys returns a sorted slice of the keys in a TagMap.

func (*TagMap) String

func (t *TagMap) String() string

String implements flag.Value.

func (*TagMap) UnmarshalJSON

func (t *TagMap) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type TeeType

type TeeType uint

TeeType is an enumeration of tee configuration options.

const (
	// TeeNone indicates that no teeing should be performed on the stream.
	TeeNone TeeType = iota
	// TeeStdout configures the stream to tee data through STDOUT.
	TeeStdout
	// TeeStderr configures the stream to tee data through STDERR.
	TeeStderr
)

func (TeeType) MarshalJSON

func (t TeeType) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*TeeType) Set

func (t *TeeType) Set(v string) error

Set implements flag.Value.

func (*TeeType) String

func (t *TeeType) String() string

String implements flag.Value.

func (*TeeType) UnmarshalJSON

func (t *TeeType) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (TeeType) Writer

func (t TeeType) Writer() io.Writer

Writer returns the io.Writer object