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

    Constants

    View Source
    const EnvKey = "LUCI_CONTEXT"

      EnvKey is the environment variable key for the LUCI_CONTEXT file.

      Variables

      View Source
      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.

        View Source
        var File_go_chromium_org_luci_lucictx_sections_proto protoreflect.FileDescriptor

        Functions

        func Get

        func Get(ctx context.Context, section string, out proto.Message) 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 proto.Message) (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 proto.Message) context.Context

              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.

              func SetLUCIExe

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

                SetLUCIExe sets the LUCIExe in the LUCI_CONTEXT.

                func SetLocalAuth

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

                  SetLocalAuth sets the LocalAuth in the LUCI_CONTEXT.

                  func SetRealm

                  func SetRealm(ctx context.Context, r *Realm) context.Context

                    SetRealm sets the Realm in the LUCI_CONTEXT.

                    func SetResultDB

                    func SetResultDB(ctx context.Context, db *ResultDB) context.Context

                      SetResultDB sets the ResultDB in the LUCI_CONTEXT.

                      func SetResultSink

                      func SetResultSink(ctx context.Context, sink *ResultSink) context.Context

                        SetResultSink sets the ResultSink in the LUCI_CONTEXT.

                        func SetSwarming

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

                          SetSwarming Sets the Swarming in the LUCI_CONTEXT.

                          func SwitchLocalAccount

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

                            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.

                              func Export

                              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

                                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

                                  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 `protobuf:"bytes,1,opt,name=cache_dir,proto3" json:"cache_dir,omitempty"`
                                  	// contains filtered or unexported fields
                                  }

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

                                    func GetLUCIExe

                                    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.

                                      func (*LUCIExe) Descriptor

                                      func (*LUCIExe) Descriptor() ([]byte, []int)

                                        Deprecated: Use LUCIExe.ProtoReflect.Descriptor instead.

                                        func (*LUCIExe) GetCacheDir

                                        func (x *LUCIExe) GetCacheDir() string

                                        func (*LUCIExe) ProtoMessage

                                        func (*LUCIExe) ProtoMessage()

                                        func (*LUCIExe) ProtoReflect

                                        func (x *LUCIExe) ProtoReflect() protoreflect.Message

                                        func (*LUCIExe) Reset

                                        func (x *LUCIExe) Reset()

                                        func (*LUCIExe) String

                                        func (x *LUCIExe) String() string

                                        type LocalAuth

                                        type LocalAuth struct {
                                        
                                        	// RPCPort and Secret define how to connect to the local auth server.
                                        	RpcPort uint32 `protobuf:"varint,1,opt,name=rpc_port,proto3" json:"rpc_port,omitempty"`
                                        	Secret  []byte `protobuf:"bytes,2,opt,name=secret,proto3" json:"secret,omitempty"`
                                        	// Accounts and DefaultAccountID defines what access tokens are available.
                                        	Accounts         []*LocalAuthAccount `protobuf:"bytes,3,rep,name=accounts,proto3" json:"accounts,omitempty"`
                                        	DefaultAccountId string              `protobuf:"bytes,4,opt,name=default_account_id,proto3" json:"default_account_id,omitempty"`
                                        	// contains filtered or unexported fields
                                        }

                                          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 a copy of the current LocalAuth from LUCI_CONTEXT if it was present. If no LocalAuth is in the context, this returns nil.

                                            func (*LocalAuth) Descriptor

                                            func (*LocalAuth) Descriptor() ([]byte, []int)

                                              Deprecated: Use LocalAuth.ProtoReflect.Descriptor instead.

                                              func (*LocalAuth) GetAccounts

                                              func (x *LocalAuth) GetAccounts() []*LocalAuthAccount

                                              func (*LocalAuth) GetDefaultAccountId

                                              func (x *LocalAuth) GetDefaultAccountId() string

                                              func (*LocalAuth) GetRpcPort

                                              func (x *LocalAuth) GetRpcPort() uint32

                                              func (*LocalAuth) GetSecret

                                              func (x *LocalAuth) GetSecret() []byte

                                              func (*LocalAuth) ProtoMessage

                                              func (*LocalAuth) ProtoMessage()

                                              func (*LocalAuth) ProtoReflect

                                              func (x *LocalAuth) ProtoReflect() protoreflect.Message

                                              func (*LocalAuth) Reset

                                              func (x *LocalAuth) Reset()

                                              func (*LocalAuth) String

                                              func (x *LocalAuth) String() string

                                              type LocalAuthAccount

                                              type LocalAuthAccount struct {
                                              
                                              	// ID is logical identifier of the account, e.g. "system" or "task".
                                              	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
                                              	// Email is an account email or "-" if not available.
                                              	Email string `protobuf:"bytes,2,opt,name=email,proto3" json:"email,omitempty"`
                                              	// contains filtered or unexported fields
                                              }

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

                                                func (*LocalAuthAccount) Descriptor

                                                func (*LocalAuthAccount) Descriptor() ([]byte, []int)

                                                  Deprecated: Use LocalAuthAccount.ProtoReflect.Descriptor instead.

                                                  func (*LocalAuthAccount) GetEmail

                                                  func (x *LocalAuthAccount) GetEmail() string

                                                  func (*LocalAuthAccount) GetId

                                                  func (x *LocalAuthAccount) GetId() string

                                                  func (*LocalAuthAccount) ProtoMessage

                                                  func (*LocalAuthAccount) ProtoMessage()

                                                  func (*LocalAuthAccount) ProtoReflect

                                                  func (x *LocalAuthAccount) ProtoReflect() protoreflect.Message

                                                  func (*LocalAuthAccount) Reset

                                                  func (x *LocalAuthAccount) Reset()

                                                  func (*LocalAuthAccount) String

                                                  func (x *LocalAuthAccount) String() string

                                                  type Realm

                                                  type Realm struct {
                                                  
                                                  	// Realm name of the task.
                                                  	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` // e.g. infra:ci
                                                  	// contains filtered or unexported fields
                                                  }

                                                    Realm is a struct that may be used with the "realm" section of LUCI_CONTEXT.

                                                    func GetRealm

                                                    func GetRealm(ctx context.Context) *Realm

                                                      GetRealm returns the current Realm from LUCI_CONTEXT if it was present. nil, otherwise.

                                                      func (*Realm) Descriptor

                                                      func (*Realm) Descriptor() ([]byte, []int)

                                                        Deprecated: Use Realm.ProtoReflect.Descriptor instead.

                                                        func (*Realm) GetName

                                                        func (x *Realm) GetName() string

                                                        func (*Realm) ProtoMessage

                                                        func (*Realm) ProtoMessage()

                                                        func (*Realm) ProtoReflect

                                                        func (x *Realm) ProtoReflect() protoreflect.Message

                                                        func (*Realm) Reset

                                                        func (x *Realm) Reset()

                                                        func (*Realm) String

                                                        func (x *Realm) String() string

                                                        type ResultDB

                                                        type ResultDB struct {
                                                        	Hostname string `protobuf:"bytes,1,opt,name=hostname,proto3" json:"hostname,omitempty"` // e.g. results.api.cr.dev
                                                        	// The invocation in the current context.
                                                        	// For example, in a Buildbucket build context, it is the build's invocation.
                                                        	//
                                                        	// This is the recommended way to propagate invocation name and update token
                                                        	// to subprocesses.
                                                        	CurrentInvocation *ResultDBInvocation `protobuf:"bytes,2,opt,name=current_invocation,proto3" json:"current_invocation,omitempty"`
                                                        	// contains filtered or unexported fields
                                                        }

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

                                                          func GetResultDB

                                                          func GetResultDB(ctx context.Context) *ResultDB

                                                            GetResultDB returns the current ResultDB from LUCI_CONTEXT if it was present. nil, otherwise.

                                                            func (*ResultDB) Descriptor

                                                            func (*ResultDB) Descriptor() ([]byte, []int)

                                                              Deprecated: Use ResultDB.ProtoReflect.Descriptor instead.

                                                              func (*ResultDB) GetCurrentInvocation

                                                              func (x *ResultDB) GetCurrentInvocation() *ResultDBInvocation

                                                              func (*ResultDB) GetHostname

                                                              func (x *ResultDB) GetHostname() string

                                                              func (*ResultDB) ProtoMessage

                                                              func (*ResultDB) ProtoMessage()

                                                              func (*ResultDB) ProtoReflect

                                                              func (x *ResultDB) ProtoReflect() protoreflect.Message

                                                              func (*ResultDB) Reset

                                                              func (x *ResultDB) Reset()

                                                              func (*ResultDB) String

                                                              func (x *ResultDB) String() string

                                                              type ResultDBInvocation

                                                              type ResultDBInvocation struct {
                                                              	Name        string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`                 // e.g. "invocations/build:1234567890"
                                                              	UpdateToken string `protobuf:"bytes,2,opt,name=update_token,proto3" json:"update_token,omitempty"` // required in all mutation requests
                                                              	// contains filtered or unexported fields
                                                              }

                                                                ResultDBInvocation is a struct that contains the necessary info to update an invocation in the ResultDB service.

                                                                func (*ResultDBInvocation) Descriptor

                                                                func (*ResultDBInvocation) Descriptor() ([]byte, []int)

                                                                  Deprecated: Use ResultDBInvocation.ProtoReflect.Descriptor instead.

                                                                  func (*ResultDBInvocation) GetName

                                                                  func (x *ResultDBInvocation) GetName() string

                                                                  func (*ResultDBInvocation) GetUpdateToken

                                                                  func (x *ResultDBInvocation) GetUpdateToken() string

                                                                  func (*ResultDBInvocation) ProtoMessage

                                                                  func (*ResultDBInvocation) ProtoMessage()

                                                                  func (*ResultDBInvocation) ProtoReflect

                                                                  func (x *ResultDBInvocation) ProtoReflect() protoreflect.Message

                                                                  func (*ResultDBInvocation) Reset

                                                                  func (x *ResultDBInvocation) Reset()

                                                                  func (*ResultDBInvocation) String

                                                                  func (x *ResultDBInvocation) String() string

                                                                  type ResultSink

                                                                  type ResultSink struct {
                                                                  
                                                                  	// TCP address (e.g. "localhost:62115") where a ResultSink pRPC server is hosted.
                                                                  	Address string `protobuf:"bytes,1,opt,name=address,proto3" json:"address,omitempty"`
                                                                  	// secret string required in all ResultSink requests in HTTP header
                                                                  	// `Authorization: ResultSink <auth-token>`
                                                                  	AuthToken string `protobuf:"bytes,2,opt,name=auth_token,proto3" json:"auth_token,omitempty"`
                                                                  	// contains filtered or unexported fields
                                                                  }

                                                                  func GetResultSink

                                                                  func GetResultSink(ctx context.Context) *ResultSink

                                                                    GetResultSink returns the current ResultSink from LUCI_CONTEXT if it was present. nil, otherwise.

                                                                    func (*ResultSink) Descriptor

                                                                    func (*ResultSink) Descriptor() ([]byte, []int)

                                                                      Deprecated: Use ResultSink.ProtoReflect.Descriptor instead.

                                                                      func (*ResultSink) GetAddress

                                                                      func (x *ResultSink) GetAddress() string

                                                                      func (*ResultSink) GetAuthToken

                                                                      func (x *ResultSink) GetAuthToken() string

                                                                      func (*ResultSink) ProtoMessage

                                                                      func (*ResultSink) ProtoMessage()

                                                                      func (*ResultSink) ProtoReflect

                                                                      func (x *ResultSink) ProtoReflect() protoreflect.Message

                                                                      func (*ResultSink) Reset

                                                                      func (x *ResultSink) Reset()

                                                                      func (*ResultSink) String

                                                                      func (x *ResultSink) String() string

                                                                      type Swarming

                                                                      type Swarming struct {
                                                                      
                                                                      	// The user-supplied secret bytes specified for the task, if any. This can be
                                                                      	// used to pass application or task-specific secret keys, JSON, etc. from the
                                                                      	// task triggerer directly to the task. The bytes will not appear on any
                                                                      	// swarming UI, or be visible to any users of the swarming service.
                                                                      	SecretBytes []byte `protobuf:"bytes,1,opt,name=secret_bytes,proto3" json:"secret_bytes,omitempty"`
                                                                      	// contains filtered or unexported fields
                                                                      }

                                                                        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.

                                                                          func (*Swarming) Descriptor

                                                                          func (*Swarming) Descriptor() ([]byte, []int)

                                                                            Deprecated: Use Swarming.ProtoReflect.Descriptor instead.

                                                                            func (*Swarming) GetSecretBytes

                                                                            func (x *Swarming) GetSecretBytes() []byte

                                                                            func (*Swarming) ProtoMessage

                                                                            func (*Swarming) ProtoMessage()

                                                                            func (*Swarming) ProtoReflect

                                                                            func (x *Swarming) ProtoReflect() protoreflect.Message

                                                                            func (*Swarming) Reset

                                                                            func (x *Swarming) Reset()

                                                                            func (*Swarming) String

                                                                            func (x *Swarming) String() string