Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewUnregisteredFake

func NewUnregisteredFake(namespace types.StreamName) (Fake, *Client)

    NewUnregisteredFake returns a new Fake as well as a *Client for this Fake.

    Fake.StreamServerPath() will return an empty string and Unregister is a no-op.

    Aside from the returned *Client there's no way to obtain another *Client for this Fake.

    func RenderOptions

    func RenderOptions(opts ...Option) (flags streamproto.Flags, forProcess bool)

      RenderOptions is a helper function for tests and low-level code.

      Returns the cumulative effect of a list of Options.

      Types

      type Client

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

        Client is a client to a local LogDog Butler.

        The methods here allow you to open a stream (text, binary or datagram) which you can then use to send data to LogDog.

        func New

        func New(path string, namespace types.StreamName) (*Client, error)

        New instantiates a new Client instance. This type of instance will be parsed from the supplied path string, which takes the form:

        <protocol>:<protocol-specific-spec>
        

        Supported protocols

        Below is the list of all supported protocols:

        unix:/path/to/socket (POSIX only)
        

        Connects to a UNIX domain socket at "/path/to/socket". This is the preferred protocol for Linux/Mac.

        net.pipe:name (Windows only)
        

        Connects to a local Windows named pipe "\\.\pipe\name". This is the preferred protocol for Windows.

        null (All platforms)
        

        Sinks all connections and writes into a null data sink. Useful for tests, or for running programs which use logdog but you don't care about their logdog outputs.

        fake:$id
        

        Connects to an in-memory Fake created in this package by calling NewFake. The string `fake:$id` can be obtained by calling the Fake's StreamServerPath method.

        func NewLoopback

        func NewLoopback(b butler, namespace types.StreamName) *Client

          NewLoopback makes a loopback Client attached to a Butler instance.

          The `butler` interface should be, exactly:

          *"go.chromium.org/luci/logdog/client/butler".Butler
          

          The interface is merely used for import cycle management.

          NOTE: `ForProcess` will be a no-op for the created Client. If you intend to generate streams from this Client to attach to subprocesses, you would be better served by using New to create a real client.

          func (*Client) GetNamespace

          func (c *Client) GetNamespace() types.StreamName

            GetNamespace returns the LOGDOG_NAMESPACE value associated with this Client.

            Safe to call on a nil client; will return an empty StreamName.

            func (*Client) NewDatagramStream

            func (c *Client) NewDatagramStream(ctx context.Context, name types.StreamName, opts ...Option) (DatagramStream, error)

              NewDatagramStream returns a new datagram stream to the butler.

              Datagram streams allow you to send messages without having to demark the separation between messages.

              NOTE: It is an error to pass ForProcess as an Option (see documentation on ForProcess for more detail).

              func (*Client) NewStream

              func (c *Client) NewStream(ctx context.Context, name types.StreamName, opts ...Option) (io.WriteCloser, error)

                NewStream returns a new open stream to the butler.

                By default this is text-based (line-oriented); pass Binary for a binary stream.

                Text streams look for newlines to delimit log chunks. Binary streams use fixed size chunks to delimit log chunks.

                type DatagramStream

                type DatagramStream interface {
                	io.Closer
                	DatagramWriter
                }

                  DatagramStream is the interface for datagram oriented streams.

                  type DatagramWriter

                  type DatagramWriter interface {
                  	// WriteDatagram writes `dg` as a single datagram.
                  	WriteDatagram(dg []byte) error
                  }

                    DatagramWriter is the interface for writing datagrams.

                    You'll typically use DatagramStream instaed, but it's occasionally useful to separate this from io.Closer.

                    type Fake

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

                      Fake implements an in-memory sink for Client connections and data.

                      You can retrieve the collected data via the Data method.

                      func NewFake

                      func NewFake() Fake

                        NewFake makes an in-memory Fake which absorbs all data written via Clients connected to it, and allows retrieval of this data via extra methods.

                        You must call Fake.Unregister to free the collected data.

                        You can obtain a Client for this Fake by doing:

                        fake := streamclient.NewFake()
                        defer fake.Unregister()
                        client, _ := streamclient.New(fake.StreamServerPath(), "whatever")
                        

                        This is particularly useful for testing programs which use bootstrap.GetFromEnv() to obtain the Client:

                        env := environ.New(nil)
                        env.Set(bootstrap.EnvStreamServerPath, client.StreamServerPath())
                        
                        bs := bootstrap.GetFromEnv(env)   # returns Bootstrap containing `client`.
                        

                        If you JUST want a single client and don't need streamclient.New to work, consider NewUnregisteredFake.

                        func (Fake) Data

                        func (f Fake) Data() map[types.StreamName]FakeStreamData

                          Data returns all absorbed data collected by this Fake so far.

                          Note that the FakeStreamData objects are `live`, and so calling their methods will always get you the current value of those streams. You'll need to call this method again if you expect a new stream to show up, however.

                          func (Fake) SetError

                          func (f Fake) SetError(err error)

                            SetError causes New* methods for Clients of this Fake to return this error.

                            func (Fake) StreamServerPath

                            func (f Fake) StreamServerPath() string

                              StreamServerPath returns a value suitable for streamclient.New that will allow construction of a *Client which points to this Fake.

                              If this Fake was generated via NewUnregisteredFake, or you called Unregister on it, returns an empty string.

                              func (Fake) Unregister

                              func (f Fake) Unregister()

                                Unregister idempotently removes this Fake from the global registry.

                                This has no effect for a Fake created with NewUnregisteredFake.

                                After calling Unregister, StreamServerPath will return an empty string.

                                type FakeStreamData

                                type FakeStreamData interface {
                                	// GetFlags returns the stream's streamproto.Flags from when the stream was
                                	// opened.
                                	GetFlags() streamproto.Flags
                                
                                	// GetStreamData returns the written text/binary data as a string.
                                	//
                                	// If this is a datagram stream, returns "".
                                	GetStreamData() string
                                
                                	// GetDatagrams returns the written datagrams as a list of strings.
                                	//
                                	// If this is a text/binary stream, returns nil.
                                	GetDatagrams() []string
                                
                                	// Returns true iff the user of the client has closed this stream.
                                	IsClosed() bool
                                }

                                  FakeStreamData is data about a single stream for a client created with the "fake" protocol. You can retrieve this with Fake.Data().

                                  type Option

                                  type Option func(*options)

                                    Option functions are returned by the With* functions in this package and can be passed to the Client.New*Stream methods to alter their contents during initial stream setup.

                                    func Binary

                                    func Binary() Option

                                      Binary can be used with NewStream to select a binary mode stream.

                                      Using this with NewDatagramStream has no effect.

                                      func ForProcess

                                      func ForProcess() Option

                                      ForProcess is an Option which opens this stream optimized for subprocess IO (i.e. to attach to "os/exec".Cmd.Std{out,err}).

                                      Accidentally passing a non-`ForProcess` stream to a subprocess will result in an extra pipe, and an extra goroutine with a copy loop in the parent process.

                                      ForProcess is only allowed on Text and Binary streams, not datagram streams. This is because the datagram stream is "packet" oriented, but stdout/stderr are not. If an application knows enough about the butler protocol to properly frame its output, it should just open a butler connection directly, rather than emitting framed data on its standard outputs.

                                      Note that when using a stream as a replacement for a process stdout/stderr handle, it must be used in the following manner (error checks omitted for brevity). The important thing to notice is that stdout must be Close'd after Wait (which could be accomplised by a defer). Failure to do this will keep the Stream open from the butler's point of view, which will prevent the butler from closing down.

                                      stdout, _ = logdogServ.Client.NewStream(
                                        ..., streamclient.ForProcess())
                                      cmd.Stdout = stdout
                                      
                                      cmd.Start()
                                      cmd.Wait()
                                      
                                      stdout.Close()
                                      

                                      Using this has some caveats, depending on the underlying stream implementation:

                                      Local

                                      Clients created with NewLocal ignore this option.

                                      Fake

                                      Clients created with NewFake ignore this option.

                                      Null

                                      The "null" protocol will return an open File pointing to os.DevNull.

                                      Windows - NamedPipe

                                      This stream will be opened as a synchronous *os.File, and so will be suitable for os/exec's specific optimizations for this type (namely: it will be passed as a replacement HANDLE for stdout/stderr, and no extra pipe/goroutine will be allocated).

                                      Accidentally using a `ForProcess` stream in the current process will result in go falling back to its internal IO threadpool to emulate asynchrony. Without `ForProcess`, the stream will use Windows-native OVERLAPPED IO completion ports, which allows the go process to be much more efficient with its thread count.

                                      Mac and Linux - Unix Domain Sockets

                                      This stream will be dialed as a regular unix socket, but will be converted to an *os.File via `"net".UnixConn.File()`, and the original file handle ("Conn") closed.

                                      Accidentally using a `ForProcess` stream in the current process isn't extremely harmful (because Go has a decent event-based IO system for *NIX systems).

                                      func WithContentType

                                      func WithContentType(contentType string) Option

                                        WithContentType returns an Option to set the content type for a new stream.

                                        The content type can be read by LogDog clients and may be used to indicate the type of data in this stream.

                                        By default:

                                        * Text streams have the type "text/plain"
                                        * Binary streams have the type "application/octet-stream"
                                        * Datagram streams have the type "application/x-logdog-datagram"
                                        

                                        func WithTagMap

                                        func WithTagMap(tags map[string]string) Option

                                          WithTagMap allows you to add arbitrary tags to this stream (subject to the limits in `logdog/common/types.ValidateTag`).

                                          By default, streams have no additional tags.

                                          func WithTags

                                          func WithTags(keyValues ...string) Option

                                            WithTags allows you to add arbitrary tags to this stream (subject to the limits in `logdog/common/types.ValidateTag`). This is a convenience version of WithTagMap.

                                            You must supply tags in pairs of {key, value}. Otherwise this function panics.

                                            By default, streams have no additional tags.

                                            func WithTimestamp

                                            func WithTimestamp(stamp time.Time) Option

                                              WithTimestamp allows you to set the 'starting' timestamp for this stream.

                                              Panics if given a timestamp that ptypes.TimestampProto cannot handle (no real timestamps will ever fall into this range).

                                              By default the stream will be marked as starting at `clock.Now(ctx)`.

                                              GOOS=linux, GOARCH=amd64