src/chromite/api/packages.proto

syntax = "proto3";
package chromite.api;

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

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


// This can easily be generalized to a Builds method if necessary, but
// currently we have no use case for anything but Chrome, and making this
// specifically for Chrome simplifies the calling code significantly.
message BuildsChromeRequest {
  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 1;
  // The build target we are checking for.
  chromiumos.BuildTarget build_target = 2;
  // List of packages to be installed by the builder. If none are specified the
  // standard list of packages is used.
  repeated chromiumos.PackageInfo packages = 3;
}

message BuildsChromeResponse {
  // Whether or not it builds chrome.
  bool builds_chrome = 1;
}

message GetBestVisibleRequest {
  // An atom to pass to portageq, e.g. 'chromeos-chrome'.
  string atom = 1;

  // The chroot path.
  // Required if not in the default location.
  chromiumos.Chroot chroot = 2;

  // The build target to examine. Checks the chroot when not provided.
  // Required when examining a build target.
  chromiumos.BuildTarget build_target = 3;
}

message GetBestVisibleResponse {
  // TODO: is this sufficient? Needs tag too?
  chromiumos.PackageInfo package_info = 1;
}

message GetChromeVersionRequest {
  // The chroot path.
  // Required if not in the default location.
  chromiumos.Chroot chroot = 1;

  // The build target to examine.
  // Required.
  chromiumos.BuildTarget build_target = 2;
}

message GetChromeVersionResponse {
  // The chrome version.
  string version = 1;
}

message GetTargetVersionsRequest {
  // The chroot path.
  // Required if not in the default location.
  chromiumos.Chroot chroot = 1;

  // The build target to examine.
  // Required.
  chromiumos.BuildTarget build_target = 2;
}

message GetTargetVersionsResponse {
  // Android version, e.g. 5812377
  string android_version = 1;
  // Android-branch version, e.g. git_nyc
  string android_branch_version = 2;
  // Android-target version, e.g. cheets
  string android_target_version = 3;
  // Chrome version, e.g. 78.0.3877.0.
  string chrome_version = 4;
  // Full version, e.g. R78-12438.0.0.
  string full_version = 5;
  // Milestone version, e.g. 78.
  string milestone_version = 6;
  // Platform version, e.g. 12438.0.0.
  string platform_version = 7;
}

// This can easily be generalized to a HasPrebuilt method if necessary, but
// currently we have no use case for anything but Chrome, and making this
// specifically for Chrome simplifies the calling code significantly.
message HasChromePrebuiltRequest {
  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 1;
  // The build target whose prebuilt is being checked.
  chromiumos.BuildTarget build_target = 2;
  // Whether to look for internal chrome, or external chromium prebuilts.
  // Shortcut for ensuring USE=chrome_internal. Does not disable
  // chrome_internal when false if otherwise set (e.g. chroot env).
  bool chrome = 3;
}

message HasChromePrebuiltResponse {
  // Whether or not it has a prebuilt.
  bool has_prebuilt = 1;
}

// The generic version of HasChromePrebuilt.
message HasPrebuiltRequest {
  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 1;

  // The build target whose prebuilt is being checked.
  // Required.
  chromiumos.BuildTarget build_target = 2;

  // Whether to look for internal chrome, or external chromium prebuilts.
  // Shortcut for ensuring USE=chrome_internal. Does not disable
  // chrome_internal when false if otherwise set (e.g. chroot env).
  bool chrome = 3;

  // The package whose prebuilt is being queried.
  // The category and package name are required.
  chromiumos.PackageInfo package_info = 4;
}

message HasPrebuiltResponse {
  // Whether or not it has a prebuilt.
  bool has_prebuilt = 1;
}

message UprevPackagesRequest {
  // The chroot path.
  // Required if not in the default location.
  chromiumos.Chroot chroot = 1;

  // The build target(s) whose packages should be uprevved.
  // Defaults to all build targets when none are given.
  repeated chromiumos.BuildTarget build_targets = 2;

  // Required.
  // The overlay type to search against.
  chromite.api.OverlayType overlay_type = 3;

  // Optional.
  // A directory where results should be dumped.
  string output_dir = 4;
}


// TODO(evanhernandez): Support build-target specific uprevs once needed.
message UprevVersionedPackageRequest {
  // The chroot path. Required.
  chromiumos.Chroot chroot = 1;

  // The package to uprev.
  chromiumos.PackageInfo package_info = 2;

  message GitRef {
    // Relative path to the git repository.
    string repository = 1;

    // The name of the git ref.
    string ref = 2;

    // The exact sha1 of the git ref.
    string revision = 3;
  }

  // The versions to consider for an update.
  repeated GitRef versions = 3;

  // The build targets whose sysroot should be cleaned of old versions.
  repeated chromiumos.BuildTarget build_targets = 4;
}


message UprevPackagesResponse {
  message Ebuild {
    string path = 1;
  }

  // The list of ebuilds that were modified. Contains added and deleted files.
  repeated Ebuild modified_ebuilds = 1;

  // The new version that was uprevved to when an uprev was completed.
  string version = 2;
}

message UprevVersionedPackageResponse {
  // list of uprev responses.
  repeated UprevPackagesResponse responses = 1;
}

// Service for package-centric functionality.
service PackageService {
  option (service_options) = {
    module: "packages",
    service_chroot_assert: INSIDE,
  };

  // Check if the build target has chrome in its depgraph.
  rpc BuildsChrome(BuildsChromeRequest) returns (BuildsChromeResponse);

  // Find the best (highest) available version of the requested package.
  // This must be run after the chroot is set up (for chroot package lookup) or
  // after the sysroot is created (for build target package lookup).
  rpc GetBestVisible(GetBestVisibleRequest) returns (GetBestVisibleResponse);

  // Like GetBestVisible, but returns only the chrome version. The chrome
  // package version is something like 78.9.0.123_rc-r1, where the chrome
  // version itself is just 78.9.0.123. This case does not have a spec in
  // Portage, so it cannot be directly fetched by GetBestVisible.
  rpc GetChromeVersion(GetChromeVersionRequest)
    returns (GetChromeVersionResponse);

  // Return the various build version fields that can be stored (e.g. in
  // metadata.json).
  rpc GetTargetVersions(GetTargetVersionsRequest)
    returns (GetTargetVersionsResponse);

  // Check if there is an available chrome prebuilt for the most recent
  // version of chrome.
  rpc HasChromePrebuilt(HasChromePrebuiltRequest)
    returns (HasChromePrebuiltResponse);

  // Check if there is an available prebuilt for the most recent version of the
  // package.
  rpc HasPrebuilt(HasPrebuiltRequest) returns (HasPrebuiltResponse);

  // The generic uprev process -- performs uprevs for all packages in the
  // public and/or private overlays for the build target(s) specified.
  // This handles all cros_workon packages except those that have a separate
  // uprev process.
  rpc Uprev(UprevPackagesRequest) returns (UprevPackagesResponse) {
    option (method_options) = {
      method_chroot_assert: OUTSIDE,
    };
  }

  // Uprev a package that is externally versioned (e.g. Chrome).
  // This endpoint iterates over a list of git refs that represent versions
  // and searches for a new version, updating and upreving the package ebuild
  // if such a version is found. The exact behavior depends on the package.
  rpc UprevVersionedPackage(UprevVersionedPackageRequest)
    returns (UprevVersionedPackageResponse) {
    option (method_options) = {
      method_chroot_assert: OUTSIDE,
    };
  }
}