blob: 582b8a8a4c1086f4e0ff0846a1d72c30bc657f5f [file] [log] [blame]
// Copyright 2017 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 cipd;
option go_package = "go.chromium.org/luci/cipd/api/cipd/v1;api";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";
import "go.chromium.org/luci/cipd/api/cipd/v1/cas.proto";
// Manages CIPD packages and their associated metadata.
//
// A package is a named collection of one or more versions of a group of files.
// A package should typically be used for a single software component or
// dataset, not a conglomeration. A package instance is a concrete incarnation
// of a such version: it is a real file, and it is identified by its SHA256 (or
// SHA1 for older packages) digest, represented by ObjectRef proto in the
// protocol.
//
// A particular serialization of ObjectRef proto into a string is referred to
// as "instance ID" and it is used to identify package instances (mostly in
// the interface exposed by the CIPD command line client, but also in
// ResolveVersion RPC):
// * For legacy reasons SHA1 digests are encoded with lowercase hex encoding,
// which always results in 40 char ASCII strings).
// * Other digests are encoded using base64(digest + []byte{ref.HashAlgo}),
// where 'base64' is URL-safe and unpadded and '+' is concatenation.
// For SHA256 digests this results in 44 char ASCII strings that end with C.
//
// Instance files themselves are zip archives with some additional metadata.
// They are produced and consumed by cipd CLI client, and the backend mostly
// doesn't care about their internal structure.
//
// Package names look like rootless file system paths (e.g. "a/b/c"). The
// identifier of a package is always the full path. There's no notion of
// "relative paths", or "..", or any other similar constructs. The name of the
// last path component has no intrinsic significance either, though it is often
// used to denote a platform the package is intended for. For example
// "infra/tools/cipd/linux-amd64" package is intended for Linux running on amd64
// architecture. This is just a convention, and it is not enforced nor
// understood by the backend.
//
// Each element of the package namespace (known as "package path prefix" or just
// "prefix") can have some metadata attached to it. Currently it includes only
// an access control list (ACL) that specifies what roles are granted to what
// users for the given prefix and all packages underneath it.
//
// For example, granting READER role to user@example.com in ACL associated with
// prefix "a/b/c" gives user@example.com permission to read all package
// instances of "a/b/c" and any packages below it (e.g. "a/b/c/d"). See Role
// enum for list of roles.
//
// There's no finer permission granularity inside the package itself, e.g. it is
// not possible to allow to read some particular package instance, without
// allowing to read all instances of the package.
service Repository {
// Returns metadata associated with the given prefix.
//
// Requires the caller to have OWNER role for the requested prefix or any of
// parent prefixes, or be in a special global "cipd-prefixes-viewers" group,
// otherwise the call fails with PERMISSION_DENIED error.
//
// If the caller has OWNER permission in any of parent prefixes, but the
// requested prefix has no metadata associated with it, the call fails with
// NOT_FOUND error.
rpc GetPrefixMetadata(PrefixRequest) returns (PrefixMetadata);
// Returns metadata associated with the given prefix and all parent prefixes.
//
// Requires the caller to have OWNER role for the requested prefix or any of
// parent prefixes, or be in a special global "cipd-prefixes-viewers" group,
// otherwise the call fails with PERMISSION_DENIED error.
//
// Note that if the caller has permission to see the metadata for the
// requested prefix, they will also see metadata for all parent prefixes,
// since it is needed to assemble the final metadata for the prefix (it
// includes inherited properties from all parent prefixes).
rpc GetInheritedPrefixMetadata(PrefixRequest) returns (InheritedPrefixMetadata);
// Updates or creates metadata associated with the given prefix.
//
// Requires the caller to have OWNER role for the requested prefix or any of
// parent prefixes, otherwise the call fails with PERMISSION_DENIED error.
//
// This method checks 'fingerprint' field of the PrefixMetadata object. If the
// metadata for the given prefix already exists, and the fingerprint in the
// request doesn't match the current fingerprint, the request fails with
// FAILED_PRECONDITION error.
//
// If the metadata doesn't exist yet, its fingerprint is assumed to be empty
// string. So pass empty fingerprint when creating initial metadata objects.
//
// If the caller passes empty fingerprint, but the metadata already exists,
// the request fails with ALREADY_EXISTS error.
//
// Note that there's no way to delete metadata once it was created. Passing
// empty PrefixMetadata object is the best that can be done.
//
// On success returns PrefixMetadata object with the updated fingerprint.
rpc UpdatePrefixMetadata(PrefixMetadata) returns (PrefixMetadata);
// Returns a set of roles the caller has in the given prefix.
//
// Unlike GetPrefixMetadata call that requires special permissions (since it
// returns a lot of detailed information), GetRolesInPrefix can be called by
// anyone.
//
// It understands and expands roles inheritance, e.g. if the caller is an
// OWNER, the result will also contain WRITER and READER (as they are implied
// by being an OWNER).
//
// Returns empty set of roles if the caller has no permissions to access the
// prefix at all or such prefix doesn't exist.
rpc GetRolesInPrefix(PrefixRequest) returns (RolesInPrefixResponse);
// Lists packages and subprefixes registered under the prefix.
//
// Lists either only direct descendants or recursively all descendants. The
// result is sorted lexicographically.
//
// For example, for packages ["a", "a/b", "a/c/d", "a/c/e/f"], listing of "a"
// will be:
// * {packages: ["a/b"], prefixes: ["a/c"]} if listing non-recursively.
// * {packages: ["a/b", "a/c/d", "a/c/e/f"], prefixes: ["a/c", "a/c/e"]} if
// listing recursively.
//
// Returns only packages and prefixes visible to the caller. This applies even
// when listing a prefix the caller has no direct read access to. For example,
// recursively listing the root prefix will return all packages the caller has
// read access to (no matter when in the hierarchy they are located), even if
// the caller has no READER permission in the root. It works as if the caller
// can freely browse the repository that contains only the packages they can
// see and nothing else.
rpc ListPrefix(ListPrefixRequest) returns (ListPrefixResponse);
// HidePackage marks the package as hidden.
//
// This removes it from the ListPrefix results, but doesn't otherwise affect
// its usage (e.g. it is still fetchable).
//
// Requires OWNER role for the package prefix. Returns PERMISSION_DENIED
// otherwise.
rpc HidePackage(PackageRequest) returns (google.protobuf.Empty);
// UnhidePackage marks the package as visible again.
//
// It's reverse of HidePackage.
//
// Requires OWNER role for the package prefix. Returns PERMISSION_DENIED
// otherwise.
rpc UnhidePackage(PackageRequest) returns (google.protobuf.Empty);
// DeletePackage removes the package (along with all its instances, tags, refs
// etc) from the repository.
//
// There's no undo. Once the package is deleted, it is gone forever.
//
// This operation has a potential to break various pinned historical CIPD
// ensure files and thus should not be used casually, only in extreme cases.
// Consider just hiding the package instead of deleting it.
//
// For the reasons above, the operation requires admin access: only owners of
// the repository root can delete packages.
//
// Returns:
// PERMISSION_DENIED if the caller is not a root owner.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package doesn't exist.
rpc DeletePackage(PackageRequest) returns (google.protobuf.Empty);
// Registers a package instance in the repository (if it was uploaded to the
// storage already and wasn't registered yet) or initiates a new upload
// operation.
//
// Callers are expected to execute the following protocol:
// 1. Attempt to register a package instance by calling RegisterInstance.
// 2. On NOT_UPLOADED status, upload the package data and finalize the
// upload operation using Storage RPC service and upload_op from the
// response.
// 3. Once the upload operation is finalized, call RegisterInstance again,
// it should succeed with status REGISTERED now.
//
// If such instance is already registered by someone else, returns
// ALREADY_REGISTERED status. This is not an error.
//
// Callers must have roles WRITER or OWNER for the package prefix. Returns
// PERMISSION_DENIED otherwise.
rpc RegisterInstance(Instance) returns (RegisterInstanceResponse);
// Lists instances of a package, most recent first.
//
// Callers must have roles READER (or above) for the package prefix. Returns
// PERMISSION_DENIED otherwise.
//
// If the package doesn't exist, returns NOT_FOUND.
rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse);
// Returns package instances that have all given tags attached.
//
// Queries only instances of some particular package (i.e. this is not a
// global query).
//
// Callers must have roles READER (or above) for the package prefix. Returns
// PERMISSION_DENIED otherwise.
//
// If the package doesn't exist, returns NOT_FOUND.
rpc SearchInstances(SearchInstancesRequest) returns (SearchInstancesResponse);
// Creates a new ref or moves an existing one.
//
// A ref is a mutable named pointer to some existing package instance that
// can be used as a version identifier. For example, "latest" or "stable".
//
// Refs are namespaced to some particular package. E.g. "latest" ref in
// packages "A" and "B" are completely different entities not related to each
// other.
//
// Pointing a ref to an instance generally makes the instance "discoverable".
// For that reason the ref can be set only to instances that successfully
// passed all post-registration processing.
//
// Returns:
// PERMISSION_DENIED if the caller is not a WRITER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance the ref points to doesn't exist.
// FAILED_PRECONDITION if the instance is still being processed.
// ABORTED if the instance has some failed processors associated with it,
// such instance is effectively broken and should not be used.
rpc CreateRef(Ref) returns (google.protobuf.Empty);
// Removes a ref.
//
// Not a failure if there's no such ref.
//
// Returns:
// PERMISSION_DENIED if the caller is not a WRITER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package doesn't exist.
rpc DeleteRef(DeleteRefRequest) returns (google.protobuf.Empty);
// Lists refs defined in a package, most recently modified first.
//
// Returns:
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package doesn't exist.
rpc ListRefs(ListRefsRequest) returns (ListRefsResponse);
// Attaches one or more tags to an instance.
//
// Silently skips already attached tags.
//
// Tags are "key:value" pairs associated with a concrete package instance.
// They can be used for querying registered instances and for version
// resolution: if a tag is attached to one and only one instance of a package,
// the tag uniquely identifies this instance and such tag can be used as an
// alias of the instance ID.
//
// Tags generally should be assumed globally namespaced (e.g. it makes sense
// to query for all registered instances with a given tag, across all
// packages), and they don't have to be unique: same tag may be attached to
// multiple instances (of the same or different packages).
//
// Additionally, tags (unlike refs) are intended to be mostly static, since
// they usually relate to some properties of package instances, which are
// static entities. This is particularity important for tags used for version
// resolution.
//
// Attaching a tag to an instance generally makes the instance "discoverable".
// For that reason tags can be attached only to instances that successfully
// passed all post-registration processing.
//
// Returns:
// PERMISSION_DENIED if the caller is not a WRITER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance doesn't exist.
// FAILED_PRECONDITION if the instance is still being processed.
// ABORTED if the instance has some failed processors associated with it,
// such instance is effectively broken and should not be used.
rpc AttachTags(AttachTagsRequest) returns (google.protobuf.Empty);
// Detaches one or more tags if they were attached.
//
// This call should not be used routinely, since tags are assumed to be
// static (and thus not detachable).
//
// It is occasionally useful for fixing screw ups though. For that reason,
// DetachTags is allowed only by OWNERS of a prefix (not WRITERS, like
// AttachTags).
//
// Returns:
// PERMISSION_DENIED if the caller is not an OWNER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance doesn't exist.
rpc DetachTags(DetachTagsRequest) returns (google.protobuf.Empty);
// Attaches one or more metadata entries to an instance.
//
// An instance metadata entry is a key-value pair, where the key is a
// lowercase string and the value is an arbitrary blob up to 512 Kb in size.
//
// A single key can have multiple different values associated with it.
// Completely identical key-value pairs are deduplicated: attaching already
// attached metadata is a noop. Thus all metadata of an instance is a
// multimap, where a key maps to a set of unique values.
//
// A metadata entry is identified by its fingerprint: a hash of concatenated
// key and value (see InstanceMetadata message for details). It can be used,
// for example, to point to an entry to detach in DetachMetadata.
//
// Returns:
// PERMISSION_DENIED if the caller is not a WRITER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance doesn't exist.
// FAILED_PRECONDITION if the instance is still being processed.
// ABORTED if the instance has some failed processors associated with it,
// such instance is effectively broken and should not be used.
rpc AttachMetadata(AttachMetadataRequest) returns (google.protobuf.Empty);
// Detaches one or more metadata entries if they were attached.
//
// Entries are identified by their fingerprints. They can either be calculated
// from a key-value pair by the client (see InstanceMetadata message for
// details), by the server (if InstanceMetadata messages inside
// DetachMetadataRequest have 'key' and 'value' populated, but not
// 'fingerprint') or taken from some existing InstanceMetadata message (e.g.
// from inside a ListMetadataResponse).
//
// Detaching metadata that doesn't exist is a noop.
//
// Returns:
// PERMISSION_DENIED if the caller is not an OWNER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance doesn't exist.
rpc DetachMetadata(DetachMetadataRequest) returns (google.protobuf.Empty);
// Lists metadata entries attached to an instance.
//
// Either returns all metadata or only entries with requested keys. The list
// is sorted by the registration time of metadata entries (the most recent
// first).
//
// Returns:
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the package or the instance doesn't exist.
rpc ListMetadata(ListMetadataRequest) returns (ListMetadataResponse);
// Takes a version string and resolves it into a concrete package instance.
//
// A version string can be any of:
// * A string-encoded instance ID, e.g. "abcdef....".
// * A ref name, e.g. "latest".
// * A tag, e.g. "version:1.10.3".
//
// Returns:
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if there's no such package or version.
// FAILED_PRECONDITION if the tag resolves to multiple instances.
rpc ResolveVersion(ResolveVersionRequest) returns (Instance);
// Produces a signed URL that can be used to fetch the package instance file.
//
// Returns:
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if there's no such instance.
rpc GetInstanceURL(GetInstanceURLRequest) returns (ObjectURL);
// Returns information about a package instance.
//
// Depending on fields set in the request, returns details such as when the
// instance was registered and by whom, refs pointing to it, tags attached to
// it, state of all processors that handled it (if any).
//
// May also be used as a simple instance presence check, if all describe_*
// fields in the request are false. If the request succeeds, then the
// instance exists.
//
// Returns:
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
// NOT_FOUND if the instance doesn't exist.
rpc DescribeInstance(DescribeInstanceRequest) returns (DescribeInstanceResponse);
// Returns information about a CIPD client package.
//
// Used by the client self-update procedure.
//
// Returns:
// NOT_FOUND if the package or the instance doesn't exist.
// FAILED_PRECONDITION if the instance is still being processed.
// ABORTED if the instance has some failed processors associated with it,
// such instance is effectively broken and should not be used.
rpc DescribeClient(DescribeClientRequest) returns (DescribeClientResponse);
// Returns information about binaries extracted from bootstrap packages under
// some prefix.
//
// This is a niche functionality used by some LUCI systems.
//
// Unlike other RPC methods here, it operates with a bunch of packages at
// once. Errors that relate to a particular package instance (instead of the
// request as a whole) are returned as google.rpc.Status inside the
// corresponding BootstrapFile entry in DescribeBootstrapBundleResponse.
// Possible statuses communicated that way:
// NOT_FOUND if the requested version of the package doesn't exist.
// FAILED_PRECONDITION if the instance is still being processed or it is not
// a bootstrap package at all.
// ABORTED if the instance has failed processors associated with it,
// such instance is effectively broken and should not be used.
//
// NOTE: The CIPD package server implements a REST endpoint which can be used
// to retrieve the contents of bootstrap packages:
//
// GET /bootstrap/<package>/+/<version>
//
// which will serve a 302 redirect to a signed url for the `file` contents.
//
// Returns:
// OK if the request was accepted and (perhaps partially) processed.
// NOT_FOUND if none of the requested instances exist.
// PERMISSION_DENIED if the caller is not a READER for the prefix.
// INVALID_ARGUMENT if the request is malformed.
rpc DescribeBootstrapBundle(DescribeBootstrapBundleRequest) returns (DescribeBootstrapBundleResponse);
}
////////////////////////////////////////////////////////////////////////////////
// Roles used in package prefix ACLs.
//
// A user can have one or more such roles for a package prefix. They get
// inherited by all subprefixes.
enum Role {
ROLE_UNSPECIFIED = 0;
// Readers can fetch package instances and package metadata (e.g. list of
// instances, all tags, all refs), but not prefix metadata (e.g. ACLs).
READER = 1;
// Writers can do everything that readers can, plus create new packages,
// upload package instances, attach tags, move refs.
WRITER = 2;
// Owners can do everything that writers can, plus read prefix metadata for
// all parent prefixes and all subprefixes, and modify prefix metadata for
// all subprefixes.
OWNER = 3;
}
message PrefixRequest {
// A prefix within the repository, e.g. "a/b/c".
string prefix = 1;
}
// PrefixMetadata is metadata defined at some concrete package prefix.
//
// It applies to this prefix and all subprefixes, recursively.
message PrefixMetadata {
message ACL {
// Role that this ACL describes.
Role role = 1;
// Users and groups that have the specified role.
//
// Each entry has a form "<kind>:<value>", e.g "group:..." or "user:...".
repeated string principals = 2;
}
// Prefix this metadata is defined at, e.g. "a/b/c".
//
// Note: there's no metadata at the root, so prefix must never be "".
string prefix = 1;
// An opaque string that identifies a particular version of this metadata.
//
// Used by UpdatePrefixMetadata to prevent an accidental overwrite of changes.
string fingerprint = 2;
// When the metadata was modified the last time.
//
// Managed by the server, ignored when passed to UpdatePrefixMetadata.
google.protobuf.Timestamp update_time = 3;
// Identity string of whoever modified the metadata the last time.
//
// Managed by the server, ignored when passed to UpdatePrefixMetadata.
string update_user = 4;
// ACLs that apply to this prefix and all subprefixes, as a mapping from
// a role to a list of users and groups that have it.
repeated ACL acls = 5;
}
message InheritedPrefixMetadata {
// Per-prefix metadata that applies to a prefix, ordered by prefix length.
//
// For example, when requesting metadata for prefix "a/b/c/d" the reply may
// contain entries for "a", "a/b", "a/b/c/d" (in that order, with "a/b/c"
// skipped in this example as not having any metadata attached).
repeated PrefixMetadata per_prefix_metadata = 1;
}
message RolesInPrefixResponse {
message RoleInPrefix {
Role role = 1;
}
// Unordered set or roles the caller has in the requested prefix.
repeated RoleInPrefix roles = 1;
}
////////////////////////////////////////////////////////////////////////////////
message ListPrefixRequest {
// A prefix within the repository to list, e.g. "a/b/c". Empty prefix is also
// accepted: it means "root of the repository".
string prefix = 1;
// If false, list only direct descendants of the prefix, otherwise all.
bool recursive = 2;
// If true, include hidden packages in the result.
bool include_hidden = 3;
}
message ListPrefixResponse {
// Lexicographically sorted list of full packages names.
repeated string packages = 1;
// Lexicographically sorted list of child prefixes (without trailing '/').
repeated string prefixes = 2;
}
////////////////////////////////////////////////////////////////////////////////
// PackageRequest names a package and nothing else.
message PackageRequest {
string package = 1;
}
////////////////////////////////////////////////////////////////////////////////
// RegistrationStatus is part of RegisterInstance RPC response.
enum RegistrationStatus {
REGISTRATION_STATUS_UNSPECIFIED = 0;
REGISTERED = 1; // the instance was successfully registered just now
ALREADY_REGISTERED = 2; // the instance already exists, this is OK
NOT_UPLOADED = 3; // the instance should be uploaded to Storage first
}
// Instance is a pointer to an instance of some package.
message Instance {
// A name of the package, e.g. "a/b/c/d".
string package = 1;
// A reference to the instance file in the storage.
ObjectRef instance = 2;
// User who registered the instance (output only).
string registered_by = 3;
// When the instance was registered (output only).
google.protobuf.Timestamp registered_ts = 4;
}
message RegisterInstanceResponse {
// Outcome of the operation, see the enum for possibilities.
//
// Defines what other fields are present.
RegistrationStatus status = 1;
// For statuses REGISTERED and ALREADY_REGISTERED contains details about the
// instance. Not set for NOT_UPLOADED status.
Instance instance = 2;
// For status NOT_UPLOADED contains a new upload operation that can be used
// together with Storage service to upload the instance file. Not set for
// other statuses.
UploadOperation upload_op = 3;
}
////////////////////////////////////////////////////////////////////////////////
message ListInstancesRequest {
// Name of a package to list instances of.
string package = 1;
// Number of instances to return on one page, default is 100.
int32 page_size = 20;
// Value of 'next_page_token' from the previous response.
//
// Can be used to resume fetching.
string page_token = 21;
}
message ListInstancesResponse {
// Package instances, sorted by registration time, most recent first.
repeated Instance instances = 1;
// Value to pass as 'page_token' in ListInstancesRequest to resume fetching or
// empty string if there's no more results.
string next_page_token = 20;
}
////////////////////////////////////////////////////////////////////////////////
message SearchInstancesRequest {
// Name of a package to query instances of (required).
string package = 1;
// Tags to look for (the found instances have ALL these tags attached).
//
// Due to internal limitations, the query is most efficient only when it
// specifies one tag to filter by. All additional tags are checked in a
// separate step after the initial query. For that reason when searching for
// multiple tags it is better to specify the most limiting tags first.
repeated Tag tags = 2;
// Number of instances to return on one page, default is 100.
int32 page_size = 20;
// Value of 'next_page_token' from the previous response.
//
// Can be used to resume fetching.
string page_token = 21;
}
message SearchInstancesResponse {
// Package instances, sorted by registration time, most recent first.
repeated Instance instances = 1;
// Value to pass as 'page_token' in SearchInstancesRequest to resume fetching
// or empty string if there's no more results.
string next_page_token = 20;
}
////////////////////////////////////////////////////////////////////////////////
// Ref is a mutable named pointer to some package instance that can be used
// as a version identifier.
message Ref {
// Name of the ref, e.g. "latest".
string name = 1;
// Name of the package where the ref is defined.
string package = 2;
// A package instance the ref is pointing to.
ObjectRef instance = 3;
// User who modified this ref the last time (output only).
string modified_by = 4;
// When the ref was modified the last time (output only).
google.protobuf.Timestamp modified_ts = 5;
}
message DeleteRefRequest {
// Name of the ref, e.g. "latest".
string name = 1;
// Name of the package where the ref is defined.
string package = 2;
}
message ListRefsRequest {
// Name of a package to list refs of.
string package = 1;
}
message ListRefsResponse {
// Package refs, sorted by modification time, most recently touched first.
repeated Ref refs = 1;
}
////////////////////////////////////////////////////////////////////////////////
// Tag is a key:value pair attached to some instance.
//
// Keys don't have to be unique, only the full pair should. For example,
// it is fine to have "version:1" and "version:2" tags attached to the same
// instance.
//
// The total length of the tag (as "key:value" pair) should be less that 400
// bytes.
message Tag {
// Key is a lowercase string matching [a-z0-9_\-]+.
string key = 1;
// Value is a string matching [A-Za-z0-9$()*+,\-./:;<=>@\\_{}~ ]+.
string value = 2;
// User that attached this tag (output only).
string attached_by = 3;
// When the tag was attached (output only).
google.protobuf.Timestamp attached_ts = 4;
}
message AttachTagsRequest {
// The package that holds the instance we attach tags to.
string package = 1;
// The instance we attach tags to.
ObjectRef instance = 2;
// One or more tags to attach (order doesn't matter).
repeated Tag tags = 3;
}
message DetachTagsRequest {
// The package that holds the instance we detach tags from.
string package = 1;
// The instance we detach tags from.
ObjectRef instance = 2;
// One or more tags to detach (order doesn't matter).
repeated Tag tags = 3;
}
////////////////////////////////////////////////////////////////////////////////
message InstanceMetadata {
// Key is a lowercase string matching [a-z0-9_\-]{1,400}.
string key = 1;
// Value is an arbitrary byte blob smaller than 512 Kb.
bytes value = 2;
// Optional MIME content type of the metadata value, primarily for UI.
string content_type = 3;
// Fingerprint identifies this metadata entry.
//
// It is the first 16 bytes of SHA256("<key>:<value>") in lowercase hex
// encoding (i.e. it is 32 lowercase hex characters).
//
// Populated by the server in all responses. Ignored in AttachMetadataRequest,
// optionally used in DetachMetadataRequest.
string fingerprint = 4;
// User that attached this metadata (output only).
string attached_by = 5;
// When the metadata was attached (output only).
google.protobuf.Timestamp attached_ts = 6;
}
message AttachMetadataRequest {
// The package that holds the instance we attach metadata to.
string package = 1;
// The instance we attach metadata to.
ObjectRef instance = 2;
// One or more metadata entries to attach.
repeated InstanceMetadata metadata = 3;
}
message DetachMetadataRequest {
// The package that holds the instance we detach metadata from.
string package = 1;
// The instance we detach metadata from.
ObjectRef instance = 2;
// Entries to detach: only 'fingerprint' or 'key'+'value' are used.
repeated InstanceMetadata metadata = 3;
}
message ListMetadataRequest {
// The package that holds the instance we list metadata of.
string package = 1;
// The instance to list metadata of.
ObjectRef instance = 2;
// Metadata keys to limit the listing to or empty to list all metadata.
repeated string keys = 3;
// Number of results to return on one page. Ignored for now.
int32 page_size = 20;
// Value of 'next_page_token' from the previous response.
string page_token = 21;
}
message ListMetadataResponse {
// Discovered metadata ordered by 'attached_ts' (the most recent first).
repeated InstanceMetadata metadata = 1;
// Value to pass as 'page_token' in ListMetadataRequest to resume fetching or
// an empty string if there's no more results.
string next_page_token = 20;
}
////////////////////////////////////////////////////////////////////////////////
message ResolveVersionRequest {
// The package that contains the instance we are resolving version of.
string package = 1;
// The version string to resolve, see ResolveVersion for details.
string version = 2;
}
////////////////////////////////////////////////////////////////////////////////
message GetInstanceURLRequest {
// The package that holds the instance we want to get URL of.
string package = 1;
// The instance we want to get URL of.
ObjectRef instance = 2;
}
////////////////////////////////////////////////////////////////////////////////
// Processor describes a state of some post-registration processing step
// performed on an instance.
message Processor {
enum State {
STATE_UNSPECIFIED = 0;
PENDING = 1;
SUCCEEDED = 2;
FAILED = 3;
}
// Internal identifier of the processor, e.g. "cipd_client_binary:v1"
string id = 1;
// The state of this processor, see the enum.
State state = 2;
// When the processor finished running (successfully or not).
google.protobuf.Timestamp finished_ts = 3;
// For SUCCEEDED state, result of the processing.
google.protobuf.Struct result = 4;
// For FAILED state, the error message.
string error = 5;
}
message DescribeInstanceRequest {
// The package that holds the instance we want to get the info for.
string package = 1;
// The instance we want to get the info for.
ObjectRef instance = 2;
// Whether the response should include "refs" field.
bool describe_refs = 3;
// Whether the response should include "tags" field.
bool describe_tags = 4;
// Whether the response should include "processors" field.
bool describe_processors = 5;
}
message DescribeInstanceResponse {
// The instance with all output fields filled in.
Instance instance = 1;
// Refs pointing to the instance, sorted by modification time, most recent
// first.
//
// Present only if the request has describe_refs == true.
repeated Ref refs = 2;
// Tags attached to the instance, sorted by the tag key first, and then
// by the timestamp (most recent first).
//
// Present only if the request has describe_tags == true.
repeated Tag tags = 3;
// State of the processors that handled the instance (if any), sorted by their
// ID.
//
// Present only if the request has describe_processors == true.
repeated Processor processors = 4;
}
////////////////////////////////////////////////////////////////////////////////
message DescribeClientRequest {
// The CIPD client package we want to get info about.
//
// For example 'infra/tools/cipd/linux-amd64'.
string package = 1;
// The client instance we want to get the info about.
ObjectRef instance = 2;
}
message DescribeClientResponse {
// The instance with all output fields filled in.
Instance instance = 1;
// Reference to the extracted client binary in the storage.
//
// The hash algo here always matches the algo used when uploading the client
// package file.
//
// Clients should expect to find an algo here that they do not support (if
// the server was updated to support a better algo). They should pick the best
// algo they support from client_ref_aliases list and use it for validation.
//
// Thus this field is mostly FYI.
ObjectRef client_ref = 2;
// Signed URL pointing to the extracted client binary in the storage.
ObjectURL client_binary = 3;
// Size of the client binary in bytes.
int64 client_size = 4;
// SHA1 digest of the client binary (as hex string).
//
// Used only by old clients and present here for backward compatibility
// reasons.
//
// Newer clients must verify one of client_ref_aliases instead.
string legacy_sha1 = 5;
// Contains hashes of the client binary calculated using ALL algos supported
// by the server at the time the client package was uploaded.
//
// The callers that want to verify the client binary hash should pick the best
// algo they understand.
//
// The list at least includes 'client_ref' itself and SHA1 hash (matching
// legacy_sha1). The order is undefined.
repeated ObjectRef client_ref_aliases = 6;
}
////////////////////////////////////////////////////////////////////////////////
message DescribeBootstrapBundleRequest {
// The package prefix that contains the bootstrap packages being described.
string prefix = 1;
// If given, specifies exactly what packages to examine.
//
// Examined package names will be formed as "<prefix>/<variant>".
//
// Based on existing package naming conventions, `variants` usually would be
// an enumeration of platforms (e.g. ["linux-amd64", "mac-amd64", ...]).
//
// If empty, the CIPD backend will describe all packages directly under the
// prefix (if any). If there are no packages under the prefix, the request
// fails with NOT_FOUND.
repeated string variants = 2;
// The package version to describe, see ResolveVersion for details.
//
// Applies to all packages matching `prefix` + `variants`.
//
// If *all* packages lack this version, the request fails with NOT_FOUND.
//
// If only some packages lack this version, their corresponding BootstrapFile
// entries in DescribeBootstrapBundleRequest will have google.rpc.Status set
// to NOT_FOUND.
string version = 3;
}
message DescribeBootstrapBundleResponse {
message BootstrapFile {
string package = 1; // the package the file was extracted from
google.rpc.Status status = 2; // not OK on errors related to this package
ObjectRef instance = 3; // the resolved package instance
ObjectRef file = 4; // the extracted file in the CAS
string name = 5; // the name of the extracted file
int64 size = 6; // its size in bytes
}
repeated BootstrapFile files = 1;
}