lucictx

Documentation

Overview

Package lucictx implements a Go client for the protocol defined here:

https://github.com/luci/luci-py/blob/master/client/LUCI_CONTEXT.md

It differs from the python client in a couple ways:

• The initial LUCI_CONTEXT value is captured once at application start, and the environment variable is REMOVED.
• Writes are cached into the golang context.Context, not a global variable.
• The LUCI_CONTEXT environment variable is not changed automatically when using the Set function. To pass the new context on to a child process, you must use the Export function to dump the current context state to disk.

Index

• Constants
• func Get(ctx context.Context, section string, out interface{}) error
• func Lookup(ctx context.Context, section string, out interface{}) (bool, error)
• func Set(ctx context.Context, section string, in interface{}) (context.Context, error)
• func SetLocalAuth(ctx context.Context, la *LocalAuth) context.Context
• func SetSwarming(ctx context.Context, swarm *Swarming) context.Context
• type Exported
  • func Export(ctx context.Context, dir string) (Exported, error)
• type LocalAuth
  • func GetLocalAuth(ctx context.Context) *LocalAuth
  • func (la *LocalAuth) CanUseByDefault() bool
• type LocalAuthAccount
• type Swarming
  • func GetSwarming(ctx context.Context) *Swarming

Constants

const EnvKey = "LUCI_CONTEXT"

EnvKey is the environment variable key for the LUCI_CONTEXT file.

Functions

func Get

func Get(ctx context.Context, section string, out interface{}) error

Get retrieves the current section from the current LUCI_CONTEXT, and deserializes it into out. Out may be any target for json.Unmarshal. If the section exists, it deserializes it into the provided out object. If not, then out is unmodified.

func Lookup

func Lookup(ctx context.Context, section string, out interface{}) (bool, error)

Lookup retrieves the current section from the current LUCI_CONTEXT, and deserializes it into out. Out may be any target for json.Unmarshal. It returns a deserialization error (if any), and a boolean indicating if the section was actually found.

func Set

func Set(ctx context.Context, section string, in interface{}) (context.Context, error)

Set writes the json serialization of `in` as the given section into the LUCI_CONTEXT, returning the new ctx object containing it. This ctx can be passed to Export to serialize it to disk.

If in is nil, it will clear that section of the LUCI_CONTEXT.

The returned context is always safe to use, even if this returns an error. This only returns an error if `in` cannot be marshalled to a JSON Object.

func SetLocalAuth

func SetLocalAuth(ctx context.Context, la *LocalAuth) context.Context

SetLocalAuth Sets the LocalAuth in the LUCI_CONTEXT.

func SetSwarming

func SetSwarming(ctx context.Context, swarm *Swarming) context.Context

SetSwarming Sets the Swarming in the LUCI_CONTEXT.

Types

type Exported

type Exported interface {
	io.Closer

	// SetInCmd sets/replaces the LUCI_CONTEXT environment variable in an
	// exec.Cmd.
	SetInCmd(c *exec.Cmd)

	// SetInEnviron sets/replaces the LUCI_CONTEXT in an environ.Env object.
	SetInEnviron(env environ.Env)
}

Exported represents an exported on-disk LUCI_CONTEXT file. It lives for exactly the life of the callback function in Export.

func Export

func Export(ctx context.Context, dir string) (Exported, error)

Export takes the current LUCI_CONTEXT information from ctx, writes it to a file and returns a wrapping Exported object. This exported value must then be installed into the environment of any subcommands (see the methods on Exported).

It is required that the caller of this function invoke Close() on the returned Exported object, or they will leak temporary files.

'dir', if not "", specifies a directory to put the exported file in. If empty, os.TempDir() will be used.

type LocalAuth

type LocalAuth struct {
	// RPCPort and Secret define how to connect to the local auth server.
	RPCPort uint32 `json:"rpc_port"`
	Secret  []byte `json:"secret"`

	// Accounts and DefaultAccountID defines what access tokens are available.
	Accounts         []LocalAuthAccount `json:"accounts"`
	DefaultAccountID string             `json:"default_account_id"`
}

LocalAuth is a struct that may be used with the "local_auth" section of LUCI_CONTEXT.

func GetLocalAuth

func GetLocalAuth(ctx context.Context) *LocalAuth

GetLocalAuth calls Lookup and returns the current LocalAuth from LUCI_CONTEXT if it was present. If no LocalAuth is in the context, this returns nil.

func (*LocalAuth) CanUseByDefault

func (la *LocalAuth) CanUseByDefault() bool

CanUseByDefault returns true if the authentication context can be picked up by default.

TODO(vadimsh): Remove this method once all servers provide 'accounts'.

type LocalAuthAccount

type LocalAuthAccount struct {
	// ID is logical identifier of the account, e.g. "system" or "task".
	ID string `json:"id"`
}

LocalAuthAccount contains information about a service account available through a local auth server.

type Swarming

type Swarming struct {
	SecretBytes []byte `json:"secret_bytes"`
}

Swarming is a struct that may be used with the "swarming" section of LUCI_CONTEXT.

func GetSwarming

func GetSwarming(ctx context.Context) *Swarming

GetSwarming calls Lookup and returns the current Swarming from LUCI_CONTEXT if it was present. If no Swarming is in the context, this returns nil.