go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/config_service/proto/config_service.proto

// Copyright 2023 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

syntax = "proto3";

package config.service.v2;

option go_package = "go.chromium.org/luci/config_service/proto;configpb";

// Allow to generate *_pb2.py files.
option py_generic_services = true;

import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

import "go.chromium.org/luci/common/proto/config/service_config.proto";


// Configs Service.
service Configs {
  // Get one configuration.
  rpc GetConfig(GetConfigRequest) returns (Config) {};

  // Get the specified project configs from all projects.
  rpc GetProjectConfigs(GetProjectConfigsRequest) returns (GetProjectConfigsResponse) {};

  // List config sets.
  rpc ListConfigSets(ListConfigSetsRequest) returns (ListConfigSetsResponse) {};

  // Get a single config set.
  rpc GetConfigSet(GetConfigSetRequest) returns (ConfigSet) {};

  // Validates configs for a config set.
  //
  // The validation workflow works as follows (assuming first time validation):
  // 1. Client sends the manifest of the config directory for validation. The
  //    manifest consists of the relative posix style path to each config file
  //    and the SHA256 hash of the content of each config file.
  // 2. Server returns grpc error status with InvalidArgument code and
  //    a `BadValidationRequestFixInfo` message in status_detail.
  //    `BadValidationRequestFixInfo` should contain a signed url for each
  //    config file and Client is responsible to upload the *gzip compressed*
  //    config to the url. Client should also fix any remaining error mentioned
  //    in `BadValidationRequestFixInfo`. Note that, if the request contains
  //    any invalid argument like malformed config set or absolute file path,
  //    LUCI Config will only return the grpc error status with InvalidArgument
  //    code but without anything in status_details because those type of errors
  //    are not fixable.
  // 3. Call the server again with the same validation request as in step 1. The
  //    Server should be able to perform the validation and return the
  //    result.
  // 4. Repeat step 1-3 for any subsequent validation request. Note that for
  //    step 2, the Server would only ask client to upload files that it has
  //    not seen their hashes in any previous validation session (for up to 1
  //    day).
  rpc ValidateConfigs(ValidateConfigsRequest) returns (config.ValidationResult) {};
}

// A request message for GetConfig rpc.
message GetConfigRequest {
  // ConfigSet where the requested config belongs to.
  //
  // Required.
  string config_set = 1;

  // Path of the config. Mutually exclusive with content_sha256.
  string path = 2;

  // Content SHA256 value of the config. Mutually exclusive with path.
  string content_sha256 = 3;

  // Fields of the Config proto to include.
  //
  // By default, all fields are included.
  //
  // Note: For content field, the client should always pass "content" to get
  // the content. Populating "raw_content" or "signed_url" is a pure server
  // side decision based on the size of the config. Therefore, explicitly
  // passing one of "raw_content" or "signed_url" may cause unexpected
  // behavior. For example, "raw_content" is passed and the content is large
  // and supposed to return by signed_url field, the client would get an
  // empty "raw_content".
  google.protobuf.FieldMask fields = 4;
}

// A single config.
message Config {
  // Name of the config set.
  // For a service config set, "services/<service_id>".
  // For a project config set, "projects/<project_id>".
  string config_set = 1;

  // Path of the config file relative to the config directory.
  string path = 2;

  // Content of the config.
  oneof content {
    // For small content where its raw content is less than 30MB and gzipped
    // size is less than 800KB, the raw and uncompressed content will be
    // included directly.
    bytes raw_content = 3;

    // For large content, a sign_url which points the actual config content
    // will be provided.
    // Note: The signed url is set to expire in 10 minutes. And it's encouraged
    // to use "Accept-Encoding: gzip" header in the request to minimize the size
    // in data transfer, and decompress it by yourself.
    string signed_url = 4;
  }

  // SHA256 value of the raw content.
  string content_sha256 = 5;

  // Size of the raw config in bytes.
  int64 size = 8;

  // Git revision
  string revision = 6;

  // Original config file url on Git repo.
  string url = 7;
}

// Get project-level configs matched with the provided path in all `projects/xxx`
// config_sets.
message GetProjectConfigsRequest {
  // Required
  // Path to the desired config in each project config set.
  //
  // TODO: In future, it can expand to support regex match in some ways, since
  // in v2, Luci-config is supposed to support multi-file configuration.
  // For example, `cr-buildbucket.cfg` can be split into smaller configs,
  // e.g. `bucket-a.cfg`, `bucket-b.cfg`, etc. But file names might be dynamic
  // and how these files are organized with other project configs are undecided.
  // It's better to implement the regex check logic when there is a concrete
  // use case.
  string path = 1;

  // Fields of Config proto to include.
  //
  // By default, all fields are included.
  google.protobuf.FieldMask fields = 2;
}

// GetProjectConfigsResponse is the response of GetProjectConfigs rpc.
//
// Note: When the sum of the first ith config.Content size larger than 200MB,
// the rest of config.Content will be always a signed url.
message GetProjectConfigsResponse {
  // The requested configs in each project.
  repeated Config configs = 1;
}

// ValidateConfigsRequest is the request of ValidateConfigs rpc.
message ValidateConfigsRequest {
  message FileHash {
    // Relative path to the config file in POSIX style.
    string path = 1;
    // The SHA256 hash of the config file.
    string sha256 = 2;
  }
  // ConfigSet to validate against.
  //
  // See: https://pkg.go.dev/go.chromium.org/luci/config#Set
  string config_set = 1;
  // FileHashes represent the manifest of the config directory.
  repeated FileHash file_hashes = 2;
}

// BadValidationRequestFixInfo describes the problem in `ValidateConfigsRequest`
// and provide the fix instruction. The server will include this message in
// grpc error status details[1] and return InvalidArgument error code.
//
// [1]: https://github.com/googleapis/googleapis/blob/f36c65081b19e0758ef5696feca27c7dcee5475e/google/rpc/status.proto#L48
message BadValidationRequestFixInfo {
  message UploadFile {
    // Relative path to the config file in POSIX style.
    string path = 1;
    // The url to upload the config.
    //
    // The caller SHOULD send compressed config and include following headers
    //  * Content-Encoding: gzip
    //  * x-goog-content-length-range: 0,$max_config_size
    string signed_url = 2;
    // Maximum config size in bytes that client can upload.
    int64 max_config_size = 3;
  }
  // The files that have NOT been seen by LUCI Config and need to be uploaded.
  repeated UploadFile upload_files = 1;
  // Files that none of the services can validate and SHOULD NOT be included
  // in the ValidateConfigsRequest.
  repeated string unvalidatable_files = 2;
}

// ListConfigSetsRequest is the request of ListConfigSets rpc.
message ListConfigSetsRequest {
  enum ConfigSetDomain {
    // The default value when domain is omitted. Used to retrieve config sets
    // in all domains.
    ALL = 0;
    // Service domain.
    SERVICE = 1;
    // Project domain.
    PROJECT = 2;
  }

  // List config sets in the specified domain.
  ConfigSetDomain domain = 1;

  // Fields of ConfigSet proto to include.
  // By default, only return config_set, url and revision fields.
  // Note: "file_paths" and "configs" is not supported in this rpc and only be
  // supported in GetConfigSet rpc.
  google.protobuf.FieldMask fields = 2;
}

// ListConfigSetsResponse is the response of ListConfigSets rpc.
message ListConfigSetsResponse {
  // A list of config sets.
  repeated ConfigSet config_sets = 1;
}

// A single ConfigSet.
message ConfigSet {
  message Revision {
    // Revision id.
    string id = 1;
    // Repo url points to this revision of config set.
    string url = 2;
    // Committer email who commit this revision
    string committer_email = 3;
    // The commit author email.
    string author_email = 5;
    // Time of this committed revision.
    google.protobuf.Timestamp timestamp = 4;
  }

  // Attempt information about importing this config set.
  message Attempt {
    // Human-readable message of the attempt.
    string message = 1;
    // Whether this attempt is successful or not.
    bool success = 2;
    // Git revision attempt to import
    Revision revision = 3;
    // Time of this attempt.
    google.protobuf.Timestamp timestamp = 4;
    // The validation result in this import attempt.
    config.ValidationResult validationResult = 5;
  }

  // Name of the config set.
  string name = 1;

  // Git Repo url which holds configs of this config set.
  string url = 2;

  // Latest imported Git revision.
  Revision revision = 3;

  // All file paths related to the corresponding config set location.
  //
  // Use `configs` instead.
  repeated string file_paths = 4 [deprecated = true];

  // Last import attempt information.
  Attempt last_import_attempt = 5;

  // Metadata of all config files in the set.
  //
  // Messages here exclude `raw_content` and `signed_url`. Use separate
  // GetConfig call to fetch the full config file body.
  repeated Config configs = 6;
}

// GetConfigSetRequest is the request of GetConfigSet rpc.
message GetConfigSetRequest {
  // Config set to fetch.
  string config_set = 1;

  // Fields of ConfigSet proto to include.
  // By default, only return config_set, url and revision fields.
  google.protobuf.FieldMask fields = 2;
}