src/chromite/api/binhost.proto

// Copyright 2019 The ChromiumOS Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";
package chromite.api;

option go_package = "go.chromium.org/chromiumos/infra/proto/go/chromite/api";

import "chromite/api/build_api.proto";
import "chromite/api/sysroot.proto";
import "chromiumos/common.proto";

// Portage environment variable that points to a remote binhost.
enum BinhostKey {
  // No binhost key was specified.
  UNSPECIFIED = 0;

  // Contains prebuilts generated by the postsubmit builder.
  POSTSUBMIT_BINHOST = 1;

  // Contains prebuilts generated by the PFQ.
  LATEST_RELEASE_CHROME_BINHOST = 2;

  // Contains prebuilts generated by pre-flight builders.
  PREFLIGHT_BINHOST = 3;

  // Contains prebuilts generated by public builders.
  PUBLIC_BINHOST = 4;

  // Contains prebuilts generated by the CQ.
  CQ_BINHOST = 5;

  // Contains prebuilts generated by informational builders.
  INFORMATIONAL_BINHOST = 6;

  // Contains prebuilts generated by snapshot builders.
  SNAPSHOT_BINHOST = 7;
}

message Binhost {
  // The binhost URI.
  string uri = 1;
  // The package index file name relative to the base binhost uri.
  string package_index = 2;
}

// Local package index file message.
message PackageIndex { chromiumos.Path path = 1; }

// Get the private prebuilts' ACL args for a build target.
message AclArgsRequest {
  // Required. The build target whose Prebuilt ACL args are being fetched.
  chromiumos.BuildTarget build_target = 1;
}

message AclArgsResponse {
  // An ACL command argument.
  message AclArg {
    // The argument (usually -g or -u).
    string arg = 1;
    // The argument value ([group_id|user]:PERMISSION)
    string value = 2;
  }

  repeated AclArg args = 1;
}

// Get the binhosts for the build target.
message BinhostGetRequest {
  // Required.
  // The build target whose binhosts are being fetched.
  chromiumos.BuildTarget build_target = 1;
  // Required.
  // Whether to include private binhosts.
  bool private = 2;
  // Required when chroot not at default location.
  // The chroot where the build target's sysroot lives.
  chromiumos.Chroot chroot = 3;
}

message BinhostGetResponse {
  // The binhosts.
  repeated Binhost binhosts = 1;
}

// Describes where prebuilts will be uploaded so package index and other
// Portage metadata can be updated appropriately.
message PrepareBinhostUploadsRequest {
  // Deprecated.
  // Build target to prepare prebuilts for.
  chromiumos.BuildTarget build_target = 1;

  // Full URI where we wish to store prebuilts. Note that this service
  // call does NOT upload them, it only updates metadata.
  // Example: gs://chromeos-prebuilt/board/amd64-generic/packages/
  string uri = 2;

  // Required when chroot not at default location.
  // The chroot where the sysroot lives.
  chromiumos.Chroot chroot = 3;

  // Required.
  // The sysroot whose prebuilts are being uploaded.
  Sysroot sysroot = 4;

  // The package index files to deduplicate the prebuilt list.
  repeated PackageIndex package_index_files = 5;
}

// An upload target is a file in the uploads_dir, and is used by
// PrepareBinhostUploadsResponse and PrepareDevInstallBinhostUploadsResponse.
message UploadTarget {
  // Paths relative to uploads_dir.
  string path = 1;
}

// Return all files to upload.
message PrepareBinhostUploadsResponse {
  // Absolute chroot path to the local directory containing files to upload.
  string uploads_dir = 1;

  // All targets to be uploaded to the binhost.
  repeated UploadTarget upload_targets = 2;
}

// Describes where dev-install prebuilts will be uploaded so package index and
// other Portage metadata can be updated appropriately.
message PrepareDevInstallBinhostUploadsRequest {

  // Absolute path to the local directory that will contain all of the files to
  // upload.  This directory must already exist before calling
  // PrepareDevInstallBinhostUploads.
  string uploads_dir = 1;

  // Full URI where we wish to store prebuilts. Note that this service
  // call does NOT upload them, it only updates metadata.
  // Example: gs://chromeos-prebuilt/board/amd64-generic/packages/
  string uri = 2;

  // Required when chroot not at default location.
  // The chroot where the sysroot lives.
  chromiumos.Chroot chroot = 3;

  // Required.
  // The sysroot whose prebuilts are being uploaded.
  Sysroot sysroot = 4;
}

// Return all dev-install files to upload.
message PrepareDevInstallBinhostUploadsResponse {

  // All targets to be uploaded to the binhost.
  repeated UploadTarget upload_targets = 1;
}

// Describe where Chrome prebuilts will be uploaded so the package index and
// other Portage metadata can be updated appropriately.
message PrepareChromeBinhostUploadsRequest {
  // Required.
  // Absolute path to the local directory that contains all of the files to
  // upload.
  string uploads_dir = 1;

  // Required.
  // Full URI where we wish to store the prebuilts. Note that this service call
  // does NOT upload them, it only updates metadata.
  // Example: gs://chromeos-prebuilt/board/amd64-generic/packages/
  string uri = 2;

  // Required when the chroot is not at the default location.
  // The chroot where the sysroot lives.
  chromiumos.Chroot chroot = 3;

  // Required.
  // The sysroot whose prebuilts are being uploaded.
  Sysroot sysroot = 4;
}

// Return all Chrome files to upload.
message PrepareChromeBinhostUploadsResponse {
  // All targets to be uploaded to the binhost.
  repeated UploadTarget upload_targets = 1;
}

// Describe the package index file and what changes should be made to it.
// Currently supports the following operations:
//   - Set upload location (URI and PATH) for all packages
message UpdatePackageIndexRequest {
  // Required if the package_index_file location is INSIDE.
  // The chroot which (likely) contains the package index file.
  chromiumos.Chroot chroot = 1;

  // Required.
  // The absolute path on the local filesystem to the package index file.
  // Must already exist on the local filesystem.
  // The RPC will modify this file in-place.
  chromiumos.Path package_index_file = 2;

  // If true, then the URI and PATH fields will be set for all package entries.
  bool set_upload_location = 3;

  // Required if set_upload_location is true.
  // Full URI to which the prebuilts will be uploaded.
  // Note that this service call does NOT upload them; it only updates metadata.
  // Example: gs://chromeos-prebuilts/board/amd64-host/packages/
  string uri = 4;
}

message UpdatePackageIndexResponse {}

// Set a binhost URL for the given build target.
message SetBinhostRequest {
  // Build target to update binhost for.
  chromiumos.BuildTarget build_target = 1;

  // Whether or not the binhost is private.
  bool private = 2;

  // Binhost key to set or update.
  BinhostKey key = 3;

  // URI storing all the binaries.
  string uri = 4;

  // Max URIs to store
  int32 max_uris = 5;
}

// Response for SetBinhost service call.
message SetBinhostResponse {
  // Absolute path to the updated binhost conf file.
  string output_file = 1;
}

// Overlay types for push_overlays.
enum OverlayType {
  // Not specified.
  OVERLAYTYPE_UNSPECIFIED = 0;

  // Both public and private.
  OVERLAYTYPE_BOTH = 1;

  // Only public overlays.
  OVERLAYTYPE_PUBLIC = 2;

  // Only private overlays.
  OVERLAYTYPE_PRIVATE = 3;

  // No overlays will be used.
  OVERLAYTYPE_NONE = 4;
}

// Regenerate the build cache.
message RegenBuildCacheRequest {
  // Required.
  // The type of overlays to push:  "public", "private", or "both".
  OverlayType overlay_type = 1;
  // Required if not in the default location.
  // The chroot to be used.
  chromiumos.Chroot chroot = 2;
}

message RegenBuildCacheResponse {
  // Message to encapsulate the modified overlays.
  message Overlay { string path = 1; }

  // The overlays that have outstanding cache updates.
  repeated Overlay modified_overlays = 1;
  // Overlays that failed during cache updates.
  repeated Overlay failed_overlays = 2;
}

// Get binhost conf path for the given build target.
message GetBinhostConfPathRequest {
  // Build target to get the configuration file path for.
  chromiumos.BuildTarget build_target = 1;

  // Whether or not the binhost is private.
  bool private = 2;

  // Binhost key to get.
  BinhostKey key = 3;
}

// Response for the GetBinhostConfPath service call.
message GetBinhostConfPathResponse {
  // Absolute path to the updated binhost conf file.
  string conf_path = 1;
}

// Service for reading and writing to Portage package index.
service BinhostService {
  option (service_options) = {
    module : "binhost",
    service_chroot_assert : OUTSIDE,
  };

  // Get the binhosts for a build target.  Added in R77.
  rpc Get(BinhostGetRequest) returns (BinhostGetResponse) {
    option (method_options) = {
      implementation_name : "GetBinhosts",
      method_chroot_assert : INSIDE,
    };
  }

  // Get the arguments from the private overlay's ACL file.  Added in R77.
  rpc GetPrivatePrebuiltAclArgs(AclArgsRequest) returns (AclArgsResponse);

  // Return a list of files to upload to the binhost. Importantly, this method
  // assumes that all files, once uploaded, will share the same relative path
  // on the remote disk as they do on the remote disk. E.g., package foo/bar,
  // stored locally at /mnt/bin/foo/bar, must be uploaded to <uri>/foo/bar.
  rpc PrepareBinhostUploads(PrepareBinhostUploadsRequest)
      returns (PrepareBinhostUploadsResponse);

  // Return a list of dev-install files to upload to the binhost. Like
  // PrepareBinhostUploads, this method assumes that all files, once uploaded,
  // will share the same relative path on the remote disk as they do on the
  // remote disk.  Added in R78.
  rpc PrepareDevInstallBinhostUploads(PrepareDevInstallBinhostUploadsRequest)
      returns (PrepareDevInstallBinhostUploadsResponse);

  // Return a list of Chrome files to upload to the binhost. Like
  // PrepareBinhostUploads, this method assumes that all files, once uploaded,
  // will share the same relative path on the remote disk as they do on the
  // local disk.
  rpc PrepareChromeBinhostUploads(PrepareChromeBinhostUploadsRequest)
      returns (PrepareChromeBinhostUploadsResponse);

  // UpdatePackageIndex modifies the package index (the file called 'Packages'
  // in the binhost) in-place.
  rpc UpdatePackageIndex(UpdatePackageIndexRequest)
      returns (UpdatePackageIndexResponse);

  // Update the binhost key for a build targets.
  rpc SetBinhost(SetBinhostRequest) returns (SetBinhostResponse);

  // Regenerate the builder cache.  Added in R78.
  rpc RegenBuildCache(RegenBuildCacheRequest) returns (RegenBuildCacheResponse);

  // Get the file path for the binhost conf file.
  rpc GetBinhostConfPath(GetBinhostConfPathRequest)
      returns (GetBinhostConfPathResponse);
}