luci: go.chromium.org/luci/logdog/client/butlerlib/streamproto Index | Files

package streamproto

import "go.chromium.org/luci/logdog/client/butlerlib/streamproto"

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

Package Files

doc.go magic.go properties.go streamName.go streamType.go tag.go tee.go

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,
    }
)

type Flags Uses

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 Uses

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 Uses

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 Uses

func (p *Properties) Clone() *Properties

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

func (*Properties) Validate Uses

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 Uses

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 Uses

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

MarshalJSON implements json.Marshaler.

func (*StreamNameFlag) Set Uses

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

Set implements flag.Value.

func (*StreamNameFlag) String Uses

func (f *StreamNameFlag) String() string

String implements flag.Value.

func (*StreamNameFlag) UnmarshalJSON Uses

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

UnmarshalJSON implements json.Unmarshaler.

type StreamType Uses

type StreamType logpb.StreamType

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

func (StreamType) DefaultContentType Uses

func (t StreamType) DefaultContentType() types.ContentType

DefaultContentType returns the default ContentType for a given stream type.

func (StreamType) MarshalJSON Uses

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

MarshalJSON implements json.Marshaler.

func (*StreamType) Set Uses

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

Set implements flag.Value.

func (*StreamType) String Uses

func (t *StreamType) String() string

String implements flag.Value.

func (*StreamType) UnmarshalJSON Uses

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

UnmarshalJSON implements json.Unmarshaler.

type TagMap Uses

type TagMap stringmapflag.Value

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

func (*TagMap) MarshalJSON Uses

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

MarshalJSON implements the json.Marshaler interface.

func (*TagMap) Set Uses

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

Set implements flag.Value

func (TagMap) SortedKeys Uses

func (t TagMap) SortedKeys() []string

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

func (*TagMap) String Uses

func (t *TagMap) String() string

String implements flag.Value.

func (*TagMap) UnmarshalJSON Uses

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

UnmarshalJSON implements the json.Unmarshaler interface.

type TeeType Uses

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 Uses

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

MarshalJSON implements json.Marshaler.

func (*TeeType) Set Uses

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

Set implements flag.Value.

func (*TeeType) String Uses

func (t *TeeType) String() string

String implements flag.Value.

func (*TeeType) UnmarshalJSON Uses

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

UnmarshalJSON implements json.Unmarshaler.

func (TeeType) Writer Uses

func (t TeeType) Writer() io.Writer

Writer returns the io.Writer object

Package streamproto imports 14 packages (graph) and is imported by 21 packages. Updated 2018-08-14. Refresh now. Tools for package owners.