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
- Variables
- func CurrentRealm(ctx context.Context) (project, realm string)
- func Get(ctx context.Context, section string, out proto.Message) error
- func Lookup(ctx context.Context, section string, out proto.Message) (bool, error)
- func Set(ctx context.Context, section string, in proto.Message) context.Context
- func SetDeadline(ctx context.Context, d *Deadline) context.Context
- func SetLUCIExe(ctx context.Context, le *LUCIExe) context.Context
- func SetLocalAuth(ctx context.Context, la *LocalAuth) context.Context
- func SetRealm(ctx context.Context, r *Realm) context.Context
- func SetResultDB(ctx context.Context, db *ResultDB) context.Context
- func SetResultSink(ctx context.Context, sink *ResultSink) context.Context
- func SetSwarming(ctx context.Context, swarm *Swarming) context.Context
- func SoftDeadlineDone(ctx context.Context) (ret <-chan DeadlineEvent)
- func SwitchLocalAccount(ctx context.Context, accountID string) (context.Context, error)
- func TrackSoftDeadline(ctx context.Context, reserveGracePeriod time.Duration) (newCtx context.Context, shutdown func())
- type Deadline
- func (*Deadline) Descriptor() ([]byte, []int)deprecated
- func (x *Deadline) GetGracePeriod() float64
- func (x *Deadline) GetSoftDeadline() float64
- func (d *Deadline) GracePeriodDuration() time.Duration
- func (*Deadline) ProtoMessage()
- func (x *Deadline) ProtoReflect() protoreflect.Message
- func (x *Deadline) Reset()
- func (d *Deadline) SetSoftDeadline(t time.Time)
- func (d *Deadline) SoftDeadlineTime() time.Time
- func (x *Deadline) String() string
- type DeadlineEvent
- type Exported
- type LUCIExe
- type LocalAuth
- func (*LocalAuth) Descriptor() ([]byte, []int)deprecated
- func (x *LocalAuth) GetAccounts() []*LocalAuthAccount
- func (x *LocalAuth) GetDefaultAccountId() string
- func (x *LocalAuth) GetRpcPort() uint32
- func (x *LocalAuth) GetSecret() []byte
- func (*LocalAuth) ProtoMessage()
- func (x *LocalAuth) ProtoReflect() protoreflect.Message
- func (x *LocalAuth) Reset()
- func (x *LocalAuth) String() string
- type LocalAuthAccount
- func (*LocalAuthAccount) Descriptor() ([]byte, []int)deprecated
- func (x *LocalAuthAccount) GetEmail() string
- func (x *LocalAuthAccount) GetId() string
- func (*LocalAuthAccount) ProtoMessage()
- func (x *LocalAuthAccount) ProtoReflect() protoreflect.Message
- func (x *LocalAuthAccount) Reset()
- func (x *LocalAuthAccount) String() string
- type Realm
- type ResultDB
- func (*ResultDB) Descriptor() ([]byte, []int)deprecated
- func (x *ResultDB) GetCurrentInvocation() *ResultDBInvocation
- func (x *ResultDB) GetHostname() string
- func (*ResultDB) ProtoMessage()
- func (x *ResultDB) ProtoReflect() protoreflect.Message
- func (x *ResultDB) Reset()
- func (x *ResultDB) String() string
- type ResultDBInvocation
- func (*ResultDBInvocation) Descriptor() ([]byte, []int)deprecated
- func (x *ResultDBInvocation) GetName() string
- func (x *ResultDBInvocation) GetUpdateToken() string
- func (*ResultDBInvocation) ProtoMessage()
- func (x *ResultDBInvocation) ProtoReflect() protoreflect.Message
- func (x *ResultDBInvocation) Reset()
- func (x *ResultDBInvocation) String() string
- type ResultSink
- type Swarming
Constants ¶
const DefaultGracePeriod = 30 * time.Second
DefaultGracePeriod is the value of Deadline.grace_period to assume if Deadline is entirely missing in LUCI_CONTEXT.
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.
var File_go_chromium_org_luci_lucictx_sections_proto protoreflect.FileDescriptor
Functions ¶
func CurrentRealm ¶
CurrentRealm grab the result of GetRealm and parses it into parts.
Returns empty strings if there's no "realm" section in the LUCI_CONTEXT.
func Get ¶
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 ¶
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 ¶
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 SetDeadline ¶
SetDeadline sets the raw Deadline information in the context.
If d is nil, sets a default deadline of:
{grace_period: DefaultGracePeriod}
If d.deadline == 0, adjusts it to ctx.Deadline() - d.grace_period.
You probably want to use AdjustDeadline instead.
func SetLUCIExe ¶
SetLUCIExe sets the LUCIExe in the LUCI_CONTEXT.
func SetLocalAuth ¶
SetLocalAuth sets the LocalAuth in the LUCI_CONTEXT.
func SetResultDB ¶
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 ¶
SetSwarming Sets the Swarming in the LUCI_CONTEXT.
func SoftDeadlineDone ¶
func SoftDeadlineDone(ctx context.Context) (ret <-chan DeadlineEvent)
SoftDeadlineDone is the counterpart of TrackSoftDeadline, and returns a channel which unblocks when the soft deadline of ctx is met, or `ctx` has been shut down/interrupted.
If ctx does not come from TrackSoftDeadline(), this returns a nil channel (i.e. blocks forever)
func SwitchLocalAccount ¶
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).
func TrackSoftDeadline ¶
func TrackSoftDeadline(ctx context.Context, reserveGracePeriod time.Duration) (newCtx context.Context, shutdown func())
TrackSoftDeadline returns a context containing a channel for the `SoftDeadlineDone` function in this package.
The "soft" deadline is somewhat like context.WithDeadline, except that it participates in the LUCI_CONTEXT['deadline'] protocol as well. On hitting the soft deadline (or on an external interrupt signal), the SoftDeadlineDone() channel will produce a stream of DeadlineEvents. Once this happens, the program has LUCI_CONTEXT['deadline']['grace_period'] seconds until ctx.Done(). This is meant to give your program time to do cleanup actions with a non-canceled Context.
The soft deadline expires based on the earlier of:
- LUCI_CONTEXT['deadline']['soft_deadline']
- ctx.Deadline() - LUCI_CONTEXT['deadline']['grace_period']
If LUCI_CONTEXT['deadline'] is missing, it is assumed to be:
{soft_deadline: infinity, grace_period: 30}
This function additionally allows you to reserve a portion of the grace_period with `reserveGracePeriod`. This will have the effect of adjusting LUCI_CONTEXT['deadline']['grace_period'] in the returned context, as well as canceling the returned context that much earlier.
NOTE: If you want to reduce LUCI_CONTEXT['deadline']['soft_deadline'], you should do so by applying a Deadline/Timeout to the context prior to invoking this function.
Panics if:
- reserveGracePeriod < 0.
- LUCI_CONTEXT['deadline']['grace_period'] (or its default 30s value) is insufficient to cover reserveGracePeriod.
Example:
func MainFunc(ctx context.Context) { // ctx.Deadline = <unset> // soft_deadline = t0 + 5:00 // grace_period = 40 newCtx, shutdown := lucictx.TrackSoftDeadline(ctx, 500*time.Millisecond) defer shutdown() ScopedFunction(newCtx) } func ScopedFunction(newCtx context.Context) { // hard deadline is (soft_deadline + grace_period - reserveGracePeriod) // newCtx.Deadline = unix(t0+5:39.5) // // soft_deadline is unchanged // soft_deadline = t0 + 5:00 // // grace_period is reduced by reserveGracePeriod // grace_period = 39.5 go func() { // unblocked at SIGTERM, soft_deadline or shutdown(), whichever is first. <-lucictx.SoftDeadlineDone() // have 39.5s to do something (say, send SIGTERM to a child, or start // tearing down work in-process) before newCtx.Done(). }() }
NOTE: In the event that `ctx` is canceled from outside, `newCtx` will also immediately cancel, and SoftDeadlineDone will also move to the ClosureEvent state.
Types ¶
type Deadline ¶
type Deadline struct { // The soft deadline for execution for this context as a 'float' unix // timestamp (seconds past unix epoch). This is the same as python's // `time.time()` representation. // // If this value is set, processes SHOULD rely on their parent process // to send SIGTERM/Ctrl-Break at this time. // // Parent processes adjusting or setting `soft_deadline` MUST enforce it by // sending SIGTERM/Ctrl-Break as close to this time as possible, followed // by SIGKILL/Terminate after `grace_period` additional time. // // If `soft_deadline` is 0 consider there to be no stated deadline (i.e. // infinite). // // Processes reading this value can use it to determine if a timeout will // actually be honored; i.e. if the user asks for 30s to run a process, but // soft_deadline indicates an end in 10s, your program can react accordingly // (print warning, adjust user-requested timeout, refuse to run user's // process, etc.). // // Processes can also observe this value in conjunction with // receiving a signal (i.e. I got a signal after `soft_deadline` then I'm likely // in a timeout state). SoftDeadline float64 `protobuf:"fixed64,1,opt,name=soft_deadline,proto3" json:"soft_deadline,omitempty"` // The amount of time (in fractional seconds), processes in this context have // time to react to a SIGTERM/Ctrl-Break before being SIGKILL/Terminated. // // If an intermediate process has a lot of cleanup work to do after its child // quits (e.g. flushing stats/writing output files/etc.) it SHOULD reduce this // value for the child process by an appropriate margin. GracePeriod float64 `protobuf:"fixed64,2,opt,name=grace_period,proto3" json:"grace_period,omitempty"` // contains filtered or unexported fields }
Deadline represents an externally-imposed termination criteria for the process observing the `LUCI_CONTEXT`.
Additionally, this contains `grace_period` which can be used to communicate how long the external process will allow for clean up once it sends SIGTERM/Ctrl-Break.
Intermediate applications MUST NOT increase `soft_deadline` or `grace_period`.
If the entire Deadline is missing from `LUCI_CONTEXT`, it should be assumed to be:
{soft_deadline: infinity, grace_period: 30}
Intermediate applications can 'reserve' portions of `soft_deadline` and `grace_period` by reducing them and then enforcing the reduced times.
*** note **WARNING:** Reducing `soft_deadline` may adversely affect the parent process's ability to accurately assess if `soft_deadline` was exceeded. This could affect reporting indicators such as 'timeout occurred', because the child process may terminate itself before the parent can send a signal and mark that it has done so.
Most applications SHOULD only reserve time from `grace_period`. Those reserving from `soft_deadline` should take care to ensure that timeout status will still be accurately communicated to their parent process, if that's important for the application. ***
func GetDeadline ¶
GetDeadline retrieves the raw Deadline information from the context.
You probably want to use AdjustDeadline instead.
func (*Deadline) Descriptor
deprecated
func (*Deadline) GetGracePeriod ¶
func (*Deadline) GetSoftDeadline ¶
func (*Deadline) GracePeriodDuration ¶
GracePeriodDuration returns the GracePeriod as a time.Duration.
If d == nil, returns DefaultGracePeriod.
func (*Deadline) ProtoMessage ¶
func (*Deadline) ProtoMessage()
func (*Deadline) ProtoReflect ¶
func (x *Deadline) ProtoReflect() protoreflect.Message
func (*Deadline) SetSoftDeadline ¶
SetSoftDeadline sets the SoftDeadline from a time.Time.
If t.IsZero, this sets the SoftDeadline to 0 as well.
func (*Deadline) SoftDeadlineTime ¶
SoftDeadlineTime returns the SoftDeadline as a time.Time.
If SoftDeadline is 0 (or *Deadline is nil) this returns a Zero Time.
type DeadlineEvent ¶
type DeadlineEvent int
DeadlineEvent is the type pushed into the cleanup channel returned by AdjustDeadline.
const ( // ClosureEvent occurs when the context returned by AdjustDeadline is Done. // This is the value you'll get from `cleanup` when it's closed. ClosureEvent DeadlineEvent = iota // InterruptEvent occurs when a SIGTERM/os.Interrupt was handled to unblock // the cleanup channel. InterruptEvent // TimeoutEvent occurs when the cleanup channel was unblocked due to // a timeout on deadline-gracePeriod. TimeoutEvent )
The cleanup channel, when it unblocks, will have an infinite supply of one of the following event types.
func (DeadlineEvent) String ¶
func (de DeadlineEvent) String() string
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 ¶
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.
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 ¶
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
deprecated
func (*LUCIExe) GetCacheDir ¶
func (*LUCIExe) ProtoMessage ¶
func (*LUCIExe) ProtoMessage()
func (*LUCIExe) ProtoReflect ¶
func (x *LUCIExe) ProtoReflect() protoreflect.Message
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 ¶
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
deprecated
func (*LocalAuth) GetAccounts ¶
func (x *LocalAuth) GetAccounts() []*LocalAuthAccount
func (*LocalAuth) GetDefaultAccountId ¶
func (*LocalAuth) GetRpcPort ¶
func (*LocalAuth) ProtoMessage ¶
func (*LocalAuth) ProtoMessage()
func (*LocalAuth) ProtoReflect ¶
func (x *LocalAuth) ProtoReflect() protoreflect.Message
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
deprecated
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 ¶
GetRealm returns the current "realm" section from LUCI_CONTEXT if it was present or nil otherwise.
func (*Realm) Descriptor
deprecated
func (*Realm) ProtoMessage ¶
func (*Realm) ProtoMessage()
func (*Realm) ProtoReflect ¶
func (x *Realm) ProtoReflect() protoreflect.Message
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 ¶
GetResultDB returns the current ResultDB from LUCI_CONTEXT if it was present. nil, otherwise.
func (*ResultDB) Descriptor
deprecated
func (*ResultDB) GetCurrentInvocation ¶
func (x *ResultDB) GetCurrentInvocation() *ResultDBInvocation
func (*ResultDB) GetHostname ¶
func (*ResultDB) ProtoMessage ¶
func (*ResultDB) ProtoMessage()
func (*ResultDB) ProtoReflect ¶
func (x *ResultDB) ProtoReflect() protoreflect.Message
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
deprecated
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
deprecated
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 ¶
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
deprecated
func (*Swarming) GetSecretBytes ¶
func (*Swarming) ProtoMessage ¶
func (*Swarming) ProtoMessage()
func (*Swarming) ProtoReflect ¶
func (x *Swarming) ProtoReflect() protoreflect.Message