luci-go: github.com/luci/luci-go/lucictx Index | Files

package lucictx

import "github.com/luci/luci-go/lucictx"

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.
* 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 and call exported.SetInCmd(cmd) to configure new command's
  environment.

Index

Package Files

exported.go local_auth.go lucictx.go luciexe.go resultdb.go swarming.go

Constants

❖
const EnvKey = "LUCI_CONTEXT"

EnvKey is the environment variable key for the LUCI_CONTEXT file.

Variables

❖
var ErrNoLocalAuthAccount = errors.New("the requested logical account is not present in LUCI_CONTEXT")

ErrNoLocalAuthAccount is returned by SwitchLocalAccount if requested account is not available in the LUCI_CONTEXT.

func Get Uses

❖
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 Uses

❖
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 Uses

❖
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 SetLUCIExe Uses

❖
func SetLUCIExe(ctx context.Context, le *LUCIExe) context.Context

SetLUCIExe sets the LUCIExe in the LUCI_CONTEXT.

func SetLocalAuth Uses

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

SetLocalAuth sets the LocalAuth in the LUCI_CONTEXT.

func SetResultDB Uses

❖
func SetResultDB(ctx context.Context, sink *ResultDB) context.Context

SetResultDB sets the ResultDB in the LUCI_CONTEXT.

func SetSwarming Uses

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

SetSwarming Sets the Swarming in the LUCI_CONTEXT.

func SwitchLocalAccount Uses

❖
func SwitchLocalAccount(ctx context.Context, accountID string) (context.Context, error)

SwitchLocalAccount changes default logical account selected in the context.

For example, it can be used to switch the context into using "system" account by default. The default account is transparently used by LUCI-aware tools.

If the requested account is available, modifies LUCI_CONTEXT["local_auth"] in the context and returns the new modified context.

If the given account is already default, returns the context unchanged.

If the given account is not available, returns (nil, ErrNoLocalAuthAccount).

type Exported Uses

❖
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.

func Export Uses

❖
func Export(ctx context.Context) (Exported, error)

Export takes the current LUCI_CONTEXT information from ctx, writes it to a file in os.TempDir 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.

Internally this function reuses existing files, when possible, so if you anticipate calling a lot of subcommands with exported LUCI_CONTEXT, you can export it in advance (thus grabbing a reference to the exported file). Then subsequent Export() calls with this context will be extremely cheap, since they will just reuse the existing file. Don't forget to release it with Close() when done.

func ExportInto Uses

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

ExportInto is like Export, except it places the temporary file into the given directory.

Exports done via this method are not reused: each individual ExportInto call produces a new temporary file.

type LUCIExe Uses

❖
type LUCIExe struct {
    // The absolute path of the base cache directory. This directory MAY be on the
    // same filesystem as CWD (but is not guaranteed to be). The available caches
    // are described in Buildbucket as CacheEntry messages.
    CacheDir string `json:"cache_dir"`
}

LUCIExe is a struct that may be used with the "luciexe" section of LUCI_CONTEXT.

func GetLUCIExe Uses

❖
func GetLUCIExe(ctx context.Context) *LUCIExe

GetLUCIExe calls Lookup and returns a copy of the current LUCIExe from LUCI_CONTEXT if it was present. If no LUCIExe is in the context, this returns nil.

type LocalAuth Uses

❖
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 Uses

❖
func GetLocalAuth(ctx context.Context) *LocalAuth

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

type LocalAuthAccount Uses

❖
type LocalAuthAccount struct {
    // ID is logical identifier of the account, e.g. "system" or "task".
    ID  string `json:"id"`
    // Email is an account email or "-" if not available.
    Email string `json:"email"`
}

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

type ResultDB Uses

❖
type ResultDB struct {
    TestResults TestResults
}

ResultDB is a struct that may be used with the "resultDB" section of LUCI_CONTEXT.

func GetResultDB Uses

❖
func GetResultDB(ctx context.Context) *ResultDB

GetResultDB returns the current ResultDB from LUCI_CONTEXT if it was present. If no ResultDB is in the context it returns nil.

type Swarming Uses

❖
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 Uses

❖
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.

type TestResults Uses

❖
type TestResults struct {
    Port      int
    AuthToken string
}

TestResults is a struct that may be used with the "resultDB.testResults" section of LUCI_CONTEXT.

Package lucictx imports 12 packages (graph) and is imported by 4 packages. Updated 2019-11-26. Refresh now. Tools for package owners.