lucictx/sections.proto

// 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"];
}