syntax = "proto3";

package chromiumos;

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

// Common message definitions.

// BuildTarget encapsulates a number of related arguments. At the moment, the
// usage of specific arguments is on a per endpoint basis, but will converge
// to support a standard set as time goes on.
// BuildTarget is a more appropriate name going forward for what we currently
// call "board".
message BuildTarget {
  // The name of the build target (a.k.a. board name).
  string name = 1;
}

// Chroot is used to define how to enter a chroot.
message Chroot {
  // Deprecated fields.
  reserved 5;

  message ChrootEnv {
    // USE flags to set.
    repeated UseFlag use_flags = 1;
    // FEATURES flags to set.
    repeated Feature features = 2;
  }

  // The directory containing the chroot.
  string path = 1;
  // The cache directory override.
  string cache_dir = 2;
  // Environment configuration.
  ChrootEnv env = 3;
  // The directory where the chrome source should be mounted.
  string chrome_dir = 4;
}

// FEATURES environment variable component message.
message Feature {
  string feature = 1;
}

message GomaConfig {
  // The goma install location.
  // Required.
  string goma_dir = 1;
  // The goma client credentials file.
  string goma_client_json = 2;
  // Path to the Goma client used for build package.
  // If None, goma_dir will be used instead.
  string chromeos_goma_dir = 3;

  // Facilitates testing new Goma approaches before rolling them out
  // more widely.
  enum GomaApproach {
    GOMA_APPROACH_UNSPECIFIED = 0;
    DEFAULT = 1;
    RBE_PROD = 2;
    RBE_STAGING = 3;
  }
  GomaApproach goma_approach = 4;

  // The directory where the goma logs will be extracted.
  SyncedDir log_dir = 5;
  // The name of the goma stats file. It will be dumped inside log_dir.
  string stats_file = 6;
  // The name of the goma counterz file. It will be dumped inside log_dir.
  string counterz_file = 7;
}

message GomaArtifacts {
  // The Goma artifacts (stats file, counterz file, and log files) are placed
  // in the directory specified by the GomaConfig.log_dir.

  // Goma stats file.
  string stats_file = 1;
  // Goma counterz file.
  string counterz_file = 2;
  // Goma log files.
  repeated string log_files = 3;
}


// Message describing a package, The corresponding variable names are from
// https://devmanual.gentoo.org/ebuild-writing/variables/index.html
message PackageInfo {
  // The package name (PN variable).
  string package_name = 1;

  // The package category (CATEGORY variable).
  string category = 2;

  // The package version and revision (PVR variable).
  string version = 3;
}

// A message to clarify inside/outside chroot paths.
message Path {
  // Location enum; whether the resource is inside or outside of the chroot.
  enum Location {
    NO_LOCATION = 0;
    INSIDE = 1;
    OUTSIDE = 2;
  }

  // The path to the resource.
  string path = 1;
  // The path location.
  Location location = 2;
}

// A message used to indicate an output location for results. Specifically,
// this is used to automatically transfer files out of the chroot when needed.
// Note: No more than one ResultPath per message can be supported.
message ResultPath {
  // Required.
  // The result directory information.
  Path path = 1;
}

// A SyncedDir will have all of its contents transferred into a tmp directory
// in the chroot before the endpoint is called, and afterwords its contents
// will be exactly what was in the tmp directory when the endpoint completed.
message SyncedDir {
  // Required.
  // The directory being synced.
  string dir = 1;
}

// See also crrev.com/c/1929452 and:
//   https://cs.corp.google.com/piper///depot/google3/third_party/luci/buildbucket/proto/common.proto?l=147-176&rcl=257714215
// A Gerrit patchset.
message GerritChange {
  // Gerrit hostname, e.g. "chromium-review.googlesource.com".
  string host = 1;
  // Gerrit project, e.g. "chromium/src".
  string project = 2;
  // Change number, e.g. 12345.
  int64 change = 3;
  // Patch set number, e.g. 1.
  int64 patchset = 4;
}

message GitilesCommit {
  // Gitiles hostname, e.g. "chromium.googlesource.com".
  string host = 1;
  // Repository name on the host, e.g. "chromium/src".
  string project = 2;
  // Commit HEX SHA1.
  string id = 3;
  // Commit ref, e.g. "refs/heads/master".
  // NOT a branch name: if specified, must start with "refs/".
  string ref = 4;
  // Defines a total order of commits on the ref. Requires ref field.
  uint32 position = 5;
}

// Message for USE flags.
message UseFlag {
  // The use flag.
  string flag = 1;
}

// The types of images that can be built.
// These correspond to support types in lib/constants.py such
// as IMAGE_TYPE_BASE, IMAGE_TYPE_RECOVERY, and so on.
enum ImageType {
  IMAGE_TYPE_UNDEFINED = 0;
  BASE = 1;
  DEV = 2;
  TEST = 3;
  BASE_VM = 4;
  TEST_VM = 5;
  RECOVERY = 6;
  FACTORY = 7;
  FIRMWARE = 8;
  CR50_FIRMWARE = 9;
  BASE_GUEST_VM = 10;
  TEST_GUEST_VM = 11;
}

// The various channels that we release through.
enum Channel {
  CHANNEL_UNSPECIFIED = 0;
  CHANNEL_STABLE = 1;
  CHANNEL_BETA = 2;
  CHANNEL_DEV = 3;
  CHANNEL_CANARY = 4;
}

// A wrapper around a serialized protocol buffer.
message ProtoBytes {
  bytes serialized_proto = 1;
}

// TODO(crbug.com/1020615): Drop this from chromite/api/toolchain.proto (and
// here) once usage has migrated to BuilderConfig.Artifacts.ArtifactType.
// Meanwhile, keep this in sync with chromite/api/toolchain.proto.  The various
// toolchain optimization artifact types.
enum AFDOArtifactType {
  // No AFDO artifact type specified.
  NONE_TYPE = 0;

  // The type is orderfile.
  ORDERFILE = 1;

  // The type is Chrome AFDO files generated by benchmarks.
  BENCHMARK_AFDO = 2;

  // The type is kernel AFDO files.
  KERNEL_AFDO = 3;

  // The type is Chrome AFDO used in release builders.
  CHROME_AFDO = 4;
}

// Additional information about artifacts used by PrepareForBuild endpoints.
// TODO(crbug/1019868): This is migrating to ArtifactProfileInfo.
message PrepareForBuildAdditionalArgs {
  oneof prepare_for_build_args {
    // ToolchainService Chrome AFDO artifacts require profile name.
    string chrome_cwp_profile = 1;

    // ToolchainService Kernel AFDO artifacts require a kernel version.
    string kernel_version = 2;
  }
}

// ToolchainService Unverified Release AFDO artifacts require information
// about the builder that created the image used to generate the unverified
// chrome benchmark perf file.
message AfdoRelease {
  // ToolchainService Chrome AFDO artifacts require profile name.
  string chrome_cwp_profile = 1;

  // The build id of the image_build.  Used to generate the location for the
  // image archive.
  int64 image_build_id = 2;
}

// Artifact profile information used by artifact prepare/bundle endpoints in
// addition to input_artifacts.
message ArtifactProfileInfo {
  oneof artifact_profile_info {
    // ToolchainService Chrome AFDO artifacts require profile name.
    string chrome_cwp_profile = 1;

    // ToolchainService Kernel AFDO artifacts require a kernel version.
    string kernel_version = 2;

    // ToolchainService Unverified Release AFDO artifacts require more.
    AfdoRelease afdo_release = 3;
  }
}

// Artifact information. Used bythe  ArtifactsService.PrepareForBuild and
// BundleArtifacts endpoints to dispatch the appropriate service routines to
// prepare or bundle as a batch.
message ArtifactsByService {
  // TODO(crbug/1034529): Drop this message.
  // Artifacts handled within the ArtifactsService endpoints directly.
  message Legacy {
    // Legacy artifacts, handled in cros_artifacts.  DO NOT ADD TO THIS.
    enum ArtifactType {
      UNSPECIFIED = 0;
      // Indicates wanting a zip file of everything in the image directory.
      // TODO(crbug/1034529): moves to ArtifactsByService.Image
      IMAGE_ZIP = 1;
      // Indicates wanting update payloads.
      // TODO(crbug/1034529): moves to ArtifactsByService.Test
      TEST_UPDATE_PAYLOAD = 2;
      // Indicates wanting the autotest tarballs.
      // TODO(crbug/1034529): moves to ArtifactsByService.Test
      AUTOTEST_FILES = 3;
      // Indicates wanting a tarball containing private TAST test bundles.
      // TODO(crbug/1034529): moves to ArtifactsByService.Test
      TAST_FILES = 4;
      // Indicates wanting a tarball containing guest images and test bundles.
      // TODO(crbug/1034529): moves to ArtifactsByService.Test
      PINNED_GUEST_IMAGES = 5;
      // Indicates wanting an archive of firmware images built from source.
      // TODO(crbug/1034529): moves to ArtifactsByService.Package
      FIRMWARE = 6;
      // Indicates wanting a tarball of the Ebuilds logs.
      // TODO(crbug/1034529): moves to ArtifactsByService.Sysroot
      EBUILD_LOGS = 7;
      // Indicates wanting an archive of the ChromeOS Config.
      // TODO(crbug/1034529): moves to ArtifactsByService.Sysroot
      CHROMEOS_CONFIG = 8;
      // Indicates wanting the CPE report.
      // TODO(crbug/1034529): moves to ArtifactsByService.Package
      CPE_REPORT = 9;
      // Indicates wanting a tar.xz archive for each image created.
      // TODO(crbug/1034529): moves to ArtifactsByService.Image
      IMAGE_ARCHIVES = 10;

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 11 to 23;
    }
    // Information about one or more artifacts.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      reserved 3;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Legacy legacy = 1;

  message Toolchain {
    // Artifacts which the ArtifactsService endpoints pass to ToolchainService.
    enum ArtifactType {
      UNSPECIFIED = 0;

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 1 to 10;

      // Indicates an unvetted orderfile for Chrome.
      UNVERIFIED_CHROME_LLVM_ORDERFILE = 11;
      // Indicates a vetted orderfile for Chrome.
      VERIFIED_CHROME_LLVM_ORDERFILE = 12;
      // Indicates a clang-tidy artifact.
      CHROME_CLANG_WARNINGS_FILE = 13;
      // Indicates a PGO artifact for the compiler.
      UNVERIFIED_LLVM_PGO_FILE = 14;

      // Indicates an unvetted AFDO Chrome profile.  (Generated by HW Tests in
      // the benchmark-afdo-generate builder.)
      UNVERIFIED_CHROME_BENCHMARK_AFDO_FILE = 15;
      // Indicates a vetted AFDO Chrome profile.
      VERIFIED_CHROME_BENCHMARK_AFDO_FILE = 16;

      // Indicates a vetted AFDO Kernel profile.
      VERIFIED_KERNEL_CWP_AFDO_FILE = 17;
      // Indicates an unvetted AFDO Kernel CWP profile.
      UNVERIFIED_KERNEL_CWP_AFDO_FILE = 18;

      // Indicates an unvetted AFDO Chrome CWP profile.
      UNVERIFIED_CHROME_CWP_AFDO_FILE = 19;
      // Indicates a vetted AFDO Chrome CWP profile.
      VERIFIED_CHROME_CWP_AFDO_FILE = 20;
      // Indicates a vetted AFDO profile for release.
      VERIFIED_RELEASE_AFDO_FILE = 21;

      // Indicates an unvetted AFDO perf data file (from HW Test).
      UNVERIFIED_CHROME_BENCHMARK_PERF_FILE = 22;
      // Indicates an unstripped Chrome binary.
      CHROME_DEBUG_BINARY = 23;
    }
    // Information about one or more artifacts.  This should match the rest of
    // the ArtifactInfo definitions in ArtifactsByService, other than having
    // it's own (service-specific) definition for ArtifactType.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      // specifying those here.  Examples include AFDO artifacts and release
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Toolchain toolchain = 2;

  message Image {
    // Artifacts which the ArtifactsService endpoints pass to ImageService.
    enum ArtifactType {
      UNSPECIFIED = 0;

      // TODO(crbug/1034529): once an IMAGE_ZIP value is added here, please
      // update the build planner (in chromiumos/infra/go), where it says
      // "use the new output artifacts IMAGE_ZIP"

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 1 to 23;
    }
    // Information about one or more artifacts.  This should match the rest of
    // the ArtifactInfo definitions in ArtifactsByService, other than having
    // it's own (service-specific) definition for ArtifactType.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Image image = 3;

  message Package {
    // Artifacts which the ArtifactsService endpoints pass to PackageService.
    enum ArtifactType {
      UNSPECIFIED = 0;

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 1 to 23;
    }
    // Information about one or more artifacts.  This should match the rest of
    // the ArtifactInfo definitions in ArtifactsByService, other than having
    // it's own (service-specific) definition for ArtifactType.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Package package = 4;

  message Sysroot {
    // Artifacts which the ArtifactsService endpoints pass to SysrootService.
    enum ArtifactType {
      UNSPECIFIED = 0;

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 1 to 23;
    }
    // Information about one or more artifacts.  This should match the rest of
    // the ArtifactInfo definitions in ArtifactsByService, other than having
    // it's own (service-specific) definition for ArtifactType.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Sysroot sysroot = 5;

  message Test {
    // Artifacts which the ArtifactsService endpoints pass to TestService.
    enum ArtifactType {
      UNSPECIFIED = 0;

      // TODO(crbug/1034529): BuilderConfig.Artifacts.ArtifactTypes is a common
      // namespace for all services.  We must reserve numbers until that is
      // gone.
      reserved 1 to 23;
    }
    // Information about one or more artifacts.  This should match the rest of
    // the ArtifactInfo definitions in ArtifactsByService, other than having
    // it's own (service-specific) definition for ArtifactType.
    message ArtifactInfo {
      // The ArtifactType.  One or more types to which the rest of the fields
      // apply.
      repeated ArtifactType artifact_types = 1;

      // GS location in which to upload artifacts ("gs://" is prepended).
      // Several fields can be logically specified:
      //   %(kind)s: BuilderConfig.Id.Type with underscores turned into hyphens.
      //   %(version)s: Chromeos version (e.g., R81-12813.0.0)
      //   %(build_id)s: Buildbucket job ID.
      //   %(target)s: build target name.
      //   %(builder_name)s: The builder name (e.g. octopus-cq), lowercase with
      //       underscores turned into hyphens.
      //   %(gs_path)s: "%(builder_name)s/%(version)s-%(build_id)s".
      //   %(artifact_name)s: The name of the artifact being published.
      //
      // BuilderConfig.Artifacts.artifacts_gs_location is used for all
      // artifacts.  Artifact can be published to additional locations by
      // specifying those here.  Examples: include AFDO artifacts and Release
      // images.
      repeated string gs_locations = 2;

      // Any acl to apply, such as "public-read".
      string acl_name = 4;
    }
    // Input artifact information
    repeated ArtifactInfo input_artifacts = 1;

    // Output artifact information
    repeated ArtifactInfo output_artifacts = 2;
  }
  Test test = 6;

  // Profile information needed by the artifact handler, if any.
  ArtifactProfileInfo profile_info = 7;
}

// Artifact information. Used bythe  ArtifactsService.PrepareForBuild and
// BundleArtifacts endpoints Response messages.
message UploadedArtifactsByService {
  // Legacy artifacts, handled directly ArtifactsService.
  // Artifacts handled within the ArtifactsService endpoints directly.
  // TODO(crbug/1034529): Drop this message.
  message Legacy {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Legacy.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Legacy legacy = 1;

  message Toolchain {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Toolchain.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Toolchain toolchain = 2;

  message Image {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Image.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Image image = 3;

  message Package {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Package.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Package package = 4;

  message Sysroot {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Sysroot.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Sysroot sysroot = 5;

  message Test {
    message ArtifactPaths {
      // The ArtifactType.
      ArtifactsByService.Test.ArtifactType artifact_type = 1;

      // Absolute path to the artifact file.
      repeated string paths = 2;
    }
    repeated ArtifactPaths artifacts = 1;
  }
  Test test = 6;
}