Documentation

Index

Constants

View Source
const (
	// MaxButlerLogBundleSize is the maximum size, in bytes, of the data section
	// of a ButlerLogBundle.
	MaxButlerLogBundleSize = 10 * 1024 * 1024

	// MaxLogEntryDataSize is the maximum size, in bytes, of the data section of
	// a single log entry.
	MaxLogEntryDataSize = 10 * 1024 * 1024

	// MaxDatagramSize is the maximum size, in bytes, of datagram data.
	MaxDatagramSize int = MaxLogEntryDataSize
)
View Source
const (
	// StreamNameSep is the separator rune for stream name tokens.
	StreamNameSep = '/'
	// StreamNameSepStr is a string containing a single rune, StreamNameSep.
	StreamNameSepStr = string(StreamNameSep)

	// StreamPathSep is the separator rune between a stream prefix and its
	// name.
	StreamPathSep = '+'
	// StreamPathSepStr is a string containing a single rune, StreamPathSep.
	StreamPathSepStr = string(StreamPathSep)

	// MaxStreamNameLength is the maximum size, in bytes, of a StreamName. Since
	// stream names must be valid ASCII, this is also the maximum string length.
	MaxStreamNameLength = 4096
)
View Source
const (
	// PrefixSecretLength is the size, in bytes, of the stream secret.
	//
	// This value was chosen such that it is:
	// - Sufficiently large to avoid collisions.
	// - Can be expressed as a Base64 string without ugly padding.
	PrefixSecretLength = 36

	// OpNonceLength is the exact length that an OpNonce must be, if supplied.
	OpNonceLength = 32
)
View Source
const (
	// MaxTagKeySize is the maximum number of bytes allowed in a tag's key
	// parameter.
	MaxTagKeySize = 64

	// MaxTagValueSize is the maximum number of bytes allowed in a tag's value
	// parameter.
	MaxTagValueSize = 4096
)
View Source
const (
	// ContentTypeText is a stream content type for text streams
	ContentTypeText ContentType = "text/plain"
	// ContentTypeBinary is a stream content type for binary streams.
	ContentTypeBinary = "application/octet-stream"

	// ContentTypeLogdogDatagram is a content type for size-prefixed datagram
	// frame stream.
	ContentTypeLogdogDatagram = "application/x-logdog-datagram"
	// ContentTypeLogdogLog is a LogDog log stream.
	ContentTypeLogdogLog = "application/x-logdog-logs"
	// ContentTypeLogdogIndex is a LogDog log index.
	ContentTypeLogdogIndex = "application/x-logdog-log-index"
)

Variables

This section is empty.

Functions

func Construct

func Construct(parts ...string) string

    Construct builds a path string from a series of individual path components. Any leading and trailing separators will be stripped from the components.

    The result value will be a valid StreamName if all of the parts are valid StreamName strings. Likewise, it may be a valid StreamPath if StreamPathSep is one of the parts.

    func ValidateTag

    func ValidateTag(k, v string) error

      ValidateTag returns an error if a tag contains a nonconfirming value.

      Types

      type ContentType

      type ContentType string

        ContentType is a MIME-style content type.

        type MessageIndex

        type MessageIndex int64

          MessageIndex is a prefix or stream message index type.

          type PrefixSecret

          type PrefixSecret []byte

            PrefixSecret is the prefix secret value. It is used to assert ownership of a prefix space.

            The Prefix secret is generated by the Coordinator at prefix registration, and is included by the Butler to prove that it is the entity that registered the stream. The secret is asserted by microservices and the Coordinator during Butler-initiated stream operations.

            func NewPrefixSecret

            func NewPrefixSecret() (PrefixSecret, error)

              NewPrefixSecret generates a new, default-length secret parameter.

              func (PrefixSecret) Validate

              func (s PrefixSecret) Validate() error

                Validate confirms that this prefix secret is conformant.

                Note that this does not scan the byte contents of the secret for any security-related parameters.

                type StreamAddr

                type StreamAddr struct {
                	// Host is the LogDog host.
                	Host string `json:"host,omitempty"`
                
                	// Project is the LUCI project name that this log belongs to.
                	Project string `json:"project,omitempty"`
                
                	// Path is the LogDog stream path.
                	Path StreamPath `json:"path,omitempty"`
                }

                  StreamAddr is a fully-qualified LogDog stream address.

                  func ParseURL

                  func ParseURL(v string) (*StreamAddr, error)

                    ParseURL parses a LogDog URL into a Stream. If the URL is malformed, or if the host, project, or path is invalid, an error will be returned.

                    A LogDog URL has the form: logdog://<host>/<project>/<prefix>/+/<name>

                    func (*StreamAddr) IsZero

                    func (s *StreamAddr) IsZero() bool

                      IsZero returns true iff all fields are empty.

                      func (*StreamAddr) Set

                      func (s *StreamAddr) Set(v string) error

                        Set implements flag.Value

                        func (*StreamAddr) String

                        func (s *StreamAddr) String() string

                          String returns a string representation of this address.

                          func (*StreamAddr) URL

                          func (s *StreamAddr) URL() *url.URL

                            URL returns a LogDog URL that represents this Stream.

                            func (*StreamAddr) Validate

                            func (s *StreamAddr) Validate() error

                              Validate returns an error if the supplied StreamAddr is not valid.

                              type StreamName

                              type StreamName string

                                StreamName is a structured stream name.

                                A valid stream name is composed of segments internally separated by a StreamNameSep (/).

                                Each segment: - Consists of the following character types:

                                - Alphanumeric characters [a-zA-Z0-9]
                                - Colon (:)
                                - Underscore (_)
                                - Hyphen (-)
                                - Period (.)
                                

                                - Must begin with an alphanumeric character.

                                func MakeStreamName

                                func MakeStreamName(fill string, s ...string) (StreamName, error)

                                  MakeStreamName constructs a new stream name from its segments.

                                  This method is guaranteed to return a valid stream name. In order to ensure that the arbitrary input can meet this standard, the following transformations will be applied as needed: - If the segment doesn't begin with an alphanumeric character, the fill

                                  string will be prepended.
                                  

                                  - Any character disallowed in the segment will be replaced with an

                                  underscore. This includes segment separators within a segment string.
                                  

                                  An empty string can be passed for "fill" to just error if a replacement is needed.

                                  func (StreamName) AsNamespace

                                  func (s StreamName) AsNamespace() StreamName

                                    AsNamespace returns this streamname in namespace form.

                                    As such, the returned value may always be directly concatenated with another StreamName (i.e. with `+`) to form a valid stream name (assuming that both StreamNames are, in fact, valid in the first place).

                                    For example:

                                    "".AsNamespace() -> ""
                                    "foo".AsNamespace() -> "foo/"
                                    "bar/".AsNamespace() -> "bar/"
                                    

                                    func (StreamName) AsPathPrefix

                                    func (s StreamName) AsPathPrefix(name StreamName) StreamPath

                                      AsPathPrefix uses s as the prefix component of a StreamPath and constructs the remainder of the path with the supplied name.

                                      If name is empty, the resulting path will end in the path separator. For example, if s is "foo/bar" and name is "", the path will be "foo/bar/+".

                                      If both s and name are valid StreamNames, this will construct a valid StreamPath. If s is a valid StreamName and name is empty, this will construct a valid partial StreamPath.

                                      func (StreamName) Concat

                                      func (s StreamName) Concat(o ...StreamName) StreamName

                                        Concat constructs a StreamName by concatenating several StreamName components together.

                                        func (StreamName) Join

                                        func (s StreamName) Join(o StreamName) StreamPath

                                          Join concatenates a stream name onto the end of the current name, separating it with a separator character.

                                          func (StreamName) MarshalJSON

                                          func (s StreamName) MarshalJSON() ([]byte, error)

                                            MarshalJSON implements json.Marshaler.

                                            func (StreamName) Namespaces

                                            func (s StreamName) Namespaces() (ret []StreamName)

                                              Namespaces returns a slice of all the namespaces this StreamName is within.

                                              For example:

                                              "a/b/c".Namespaces() ->
                                                 "a/b/"
                                                 "a/"
                                                 ""
                                              

                                              func (StreamName) SegmentCount

                                              func (s StreamName) SegmentCount() int

                                                SegmentCount returns the total number of segments in the StreamName.

                                                func (StreamName) Segments

                                                func (s StreamName) Segments() []string

                                                  Segments returns the individual StreamName segments by splitting splitting the StreamName with StreamNameSep.

                                                  func (*StreamName) Set

                                                  func (s *StreamName) Set(value string) error

                                                    Set implements flag.Value.

                                                    func (StreamName) Split

                                                    func (s StreamName) Split() (prefix, last StreamName)

                                                      Split splits a StreamName on its last path element, into a prefix (everything before that element) and the last element.

                                                      Split assumes that s is a valid stream name.

                                                      If there is only one element in the stream name, prefix will be empty.

                                                      For example:

                                                      - Split("foo/bar/baz") ("foo/bar", "baz")
                                                      - Split("foo") ("", "foo")
                                                      - Split("") ("", "")
                                                      

                                                      func (*StreamName) String

                                                      func (s *StreamName) String() string

                                                        String implements flag.String.

                                                        func (StreamName) Trim

                                                        func (s StreamName) Trim() StreamName

                                                          Trim trims separator characters from the beginning and end of a StreamName.

                                                          While such a StreamName is not Valid, this method helps correct small user input errors.

                                                          func (*StreamName) UnmarshalJSON

                                                          func (s *StreamName) UnmarshalJSON(data []byte) error

                                                            UnmarshalJSON implements json.Unmarshaler.

                                                            func (StreamName) Validate

                                                            func (s StreamName) Validate() error

                                                              Validate tests whether the stream name is valid.

                                                              type StreamNameSlice

                                                              type StreamNameSlice []StreamName

                                                                StreamNameSlice is a slice of StreamName entries. It implements sort.Interface.

                                                                func (StreamNameSlice) Len

                                                                func (s StreamNameSlice) Len() int

                                                                func (StreamNameSlice) Less

                                                                func (s StreamNameSlice) Less(i, j int) bool

                                                                func (StreamNameSlice) Swap

                                                                func (s StreamNameSlice) Swap(i, j int)

                                                                type StreamPath

                                                                type StreamPath string

                                                                  A StreamPath consists of two StreamName, joined via a StreamPathSep (+) separator.

                                                                  func (StreamPath) Append

                                                                  func (p StreamPath) Append(n string) StreamPath

                                                                    Append returns a StreamPath consisting of the current StreamPath with the supplied StreamName appended to the end.

                                                                    Append will return a valid StreamPath if p and n are both valid.

                                                                    func (StreamPath) MarshalJSON

                                                                    func (p StreamPath) MarshalJSON() ([]byte, error)

                                                                      MarshalJSON implements json.Marshaler.

                                                                      func (StreamPath) SegmentCount

                                                                      func (p StreamPath) SegmentCount() int

                                                                        SegmentCount returns the total number of segments in the StreamName.

                                                                        func (StreamPath) Split

                                                                        func (p StreamPath) Split() (prefix StreamName, name StreamName)

                                                                          Split splits a StreamPath into its prefix and name components.

                                                                          If there is no divider present (e.g., foo/bar/baz), the result will parse as the stream prefix with an empty name component.

                                                                          func (StreamPath) SplitLast

                                                                          func (p StreamPath) SplitLast() (StreamPath, string)

                                                                            SplitLast splits the rightmost component from a StreamPath, returning the intermediate StreamPath.

                                                                            If the path begins with a leading separator, it will be included in the leftmost token. Note that such a path is invalid.

                                                                            If there are no components in the path, ("", p) will be returned.

                                                                            func (StreamPath) SplitParts

                                                                            func (p StreamPath) SplitParts() (prefix StreamName, sep bool, name StreamName)

                                                                              SplitParts splits a StreamPath into its prefix and name components.

                                                                              If there is no separator present (e.g., foo/bar/baz), the result will parse as the stream prefix with an empty name component. If there is a separator present but no name component, separator will be returned as true with an empty name.

                                                                              func (StreamPath) Trim

                                                                              func (p StreamPath) Trim() StreamPath

                                                                                Trim trims separator characters from the beginning and end of a StreamPath.

                                                                                While such a StreamPath is not Valid, this method helps correct small user input errors.

                                                                                func (*StreamPath) UnmarshalJSON

                                                                                func (p *StreamPath) UnmarshalJSON(data []byte) error

                                                                                  UnmarshalJSON implements json.Unmarshaler.

                                                                                  func (StreamPath) Validate

                                                                                  func (p StreamPath) Validate() error

                                                                                    Validate checks whether a StreamPath is valid. A valid stream path must have a valid prefix and name components.

                                                                                    func (StreamPath) ValidatePartial

                                                                                    func (p StreamPath) ValidatePartial() error

                                                                                      ValidatePartial checks whether a partial StreamPath is valid. A partial stream path if appending additional components to it can form a fully-valid StreamPath.