blob: cd489e77ec7aefab56766faea2fd915f5b1dc272 [file] [log] [blame]
// Copyright 2020 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
package lucictx;
option go_package = "go.chromium.org/luci/lucictx;lucictx";
// LocalAuth is a struct that may be used with the "local_auth" section of
// LUCI_CONTEXT.
message LocalAuth {
// RPCPort and Secret define how to connect to the local auth server.
uint32 rpc_port = 1 [json_name = "rpc_port"];
bytes secret = 2 [json_name = "secret"];
// Accounts and DefaultAccountID defines what access tokens are available.
repeated LocalAuthAccount accounts = 3 [json_name = "accounts"];
string default_account_id = 4 [json_name = "default_account_id"];
}
// LocalAuthAccount contains information about a service account available
// through a local auth server.
message LocalAuthAccount {
// ID is logical identifier of the account, e.g. "system" or "task".
string id = 1 [json_name = "id"];
// Email is an account email or "-" if not available.
string email = 2 [json_name = "email"];
}
// Swarming is a struct that may be used with the "swarming" section of
// LUCI_CONTEXT.
message Swarming {
// 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.
bytes secret_bytes = 1 [json_name = "secret_bytes"];
}
// LUCIExe is a struct that may be used with the "luciexe" section of
// LUCI_CONTEXT.
message LUCIExe {
// 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.
string cache_dir = 1 [json_name = "cache_dir"];
}
// Realm is a struct that may be used with the "realm" section of
// LUCI_CONTEXT.
message Realm {
// Realm name of the task.
string name = 1 [json_name = "name"]; // e.g. infra:ci
}
// ResultDB is a struct that may be used with the "resultdb" section of
// LUCI_CONTEXT.
message ResultDB {
string hostname = 1 [json_name = "hostname"]; // 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.
ResultDBInvocation current_invocation = 2 [json_name = "current_invocation"];
}
// ResultDBInvocation is a struct that contains the necessary info to update an
// invocation in the ResultDB service.
message ResultDBInvocation {
string name = 1 [json_name = "name"]; // e.g. "invocations/build:1234567890"
string update_token = 2 [json_name = "update_token"]; // required in all mutation requests
}
message ResultSink {
// TCP address (e.g. "localhost:62115") where a ResultSink pRPC server is hosted.
string address = 1 [json_name = "address"];
// secret string required in all ResultSink requests in HTTP header
// `Authorization: ResultSink <auth-token>`
string auth_token = 2 [json_name = "auth_token"];
}
// 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.
// ***
message Deadline {
// 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).
double soft_deadline = 1 [json_name = "soft_deadline"];
// 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.
double grace_period = 2 [json_name = "grace_period"];
}
// Buildbucket is a struct that contains the necessary info to update
// a buildbucket build.
//
// It may be used with the "buildbucket" section of LUCI_CONTEXT.
message Buildbucket {
// Buildbucket host name.
// E.g. cr-buildbucket.appspot.com.
string hostname = 1 [json_name = "hostname"];
// Token to use to schedule child builds for this build.
string schedule_build_token = 2 [json_name = "schedule_build_token"];
}