src/chromite/api/binhost.proto

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;
}

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;
}

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;
}

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

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

// 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.
  rpc Get(BinhostGetRequest) returns (BinhostGetResponse) {
    option (method_options) = {
      implementation_name: "GetBinhosts",
    };
  }

  // Get the arguments from the private overlay's ACL file.
  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.
  rpc PrepareDevInstallBinhostUploads(PrepareDevInstallBinhostUploadsRequest)
    returns (PrepareDevInstallBinhostUploadsResponse);

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

  // Regenerate the builder cache.
  rpc RegenBuildCache(RegenBuildCacheRequest) returns (RegenBuildCacheResponse);
}