path: root/src/buildtool/serve_api/serve_service/just_serve.proto

// Copyright 2023 Huawei Cloud Computing Technology Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package justbuild.just_serve;

import "build/bazel/remote/execution/v2/remote_execution.proto";

// A request message for
// [TargetLevelCache.ServeCommitTree][justbuild.just_serve.TargetLevelCache.ServeCommitTree].
message ServeCommitTreeRequest {
  // The Git commit identifier to be searched on the server.
  string commit = 1;

  // Relative path of requested tree with respect to the commit root.
  string subdir = 2;

  // If set to true and the tree is found, it will be uploaded to the
  // remote-execution end point.
  bool sync_tree = 3;
}


// A response message for
// [TargetLevelCache.ServeCommitTree][justbuild.just_serve.TargetLevelCache.ServeCommitTree].
message ServeCommitTreeResponse {
  // The requested Git tree hash.
  string tree = 1;

  enum ServeCommitTreeStatus {
    // All good
    OK = 0;

    // Failed to upload tree remotely
    SYNC_ERROR = 1;

    // Commit not found
    NOT_FOUND = 2;

    // Internally, something is very broken
    INTERNAL_ERROR = 3;
  }

  // If the status has a code `OK` or `SYNC_ERROR`, the tree is correct.
  // For any other value, the `tree` field is not set.
  ServeCommitTreeStatus status = 2;
}

// A request message for
// [TargetLevelCache.ServeArchiveTree][justbuild.just_serve.TargetLevelCache.ServeArchiveTree].
message ServeArchiveTreeRequest {
  // The git blob identifier of the archive.
  string content = 1;

  enum ArchiveType {
    TAR = 0;
    ZIP = 1;
  }

  // The type of archive this blob should be treated as.
  ArchiveType archive_type = 2;

  // Relative path of requested tree with respect to the commit root.
  string subdir = 3;

  enum SymlinksResolve {
    // Process archive as-is
    NONE = 0;

    // Ignore all symlinks
    IGNORE = 1;

    // Resolve only
    PARTIAL = 2;

    // Resolve all symlinks
    COMPLETE = 3;
  }

  // How symlinks inside the archive should be handled.
  SymlinksResolve resolve_symlinks = 4;

  // If set to true and the tree is found, it will be uploaded to the
  // remote-execution end point.
  bool sync_tree = 5;
}

// A response message for
// [TargetLevelCache.ServeArchiveTree][justbuild.just_serve.TargetLevelCache.ServeArchiveTree].
message ServeArchiveTreeResponse {
  // The requested Git tree hash.
  string tree = 1;

  enum ServeArchiveTreeStatus{
    // All good
    OK = 0;

    // Failed to upload tree remotely
    SYNC_ERROR = 1;

    // Failed to unpack as archive of the specified type
    UNPACK_ERROR = 2;

    // Failed to resolve symlinks as requested
    RESOLVE_ERROR = 3;

    // Content blob not known
    NOT_FOUND = 4;

    // Internally, something is very broken
    INTERNAL_ERROR = 5;
  }

  // If the status has a code `OK` or `SYNC_ERROR`, the tree is correct.
  // For any other value, the `tree` field is not set.
  ServeArchiveTreeStatus status = 2;
}

// A request message for
// [TargetLevelCache.ServeDistdirTree][justbuild.just_serve.TargetLevelCache.ServeDistdirTree].
message ServeDistdirTreeRequest {
  // A distfile item.
  message Distfile {
    // The name of the distfile.
    string name = 1;

    // The git blob identifier of the distfile content.
    string content = 2;

    // Whether the blob should occur executable in the resulting
    // directory.
    bool executable = 3;
  }

  // The list of distfiles.
  repeated Distfile distfiles = 1;

  // If set to true and all distfile blobs are found, the resulting tree
  // and all the content blobs will be uploaded to the remote-execution
  // end point.
  bool sync_tree = 2;
}

// A response message for
// [TargetLevelCache.ServeDistdirTree][justbuild.just_serve.TargetLevelCache.ServeDistdirTree].
message ServeDistdirTreeResponse {
  // The requested Git tree hash.
  string tree = 1;

  enum ServeDistdirTreeStatus{
    // All good
    OK = 0;

    // Failed to upload content blobs remotely
    SYNC_ERROR = 1;

    // At least one content blob is missing
    NOT_FOUND = 2;

    // Internally, something is very broken
    INTERNAL_ERROR = 3;
  }

  // If the status has a code `OK` or `SYNC_ERROR`, the tree is correct.
  // For any other value, the `tree` field is not set.
  ServeDistdirTreeStatus status = 2;
}

// A request message for
// [TargetLevelCache.ServeContent][justbuild.just_serve.TargetLevelCache.ServeContent].
message ServeContentRequest {
  // The git blob identifier of the archive.
  string content = 1;
}

// A response message for
// [TargetLevelCache.ServeContent][justbuild.just_serve.TargetLevelCache.ServeContent].
message ServeContentResponse {
  enum ServeContentStatus{
    // All good
    OK = 0;

    // Content blob not known
    NOT_FOUND = 1;

    // Failed to upload archive content to remote CAS
    SYNC_ERROR = 2;

    // Internally, something is very broken
    INTERNAL_ERROR = 3;
  }

  // If the status has a code `OK`, the archive content is in the remote CAS
  ServeContentStatus status = 1;
}

// A request message for
// [TargetLevelCache.ServeTree][justbuild.just_serve.TargetLevelCache.ServeTree].
message ServeTreeRequest {
  // The git tree identifier.
  string tree = 1;
}

// A response message for
// [TargetLevelCache.ServeTree][justbuild.just_serve.TargetLevelCache.ServeTree].
message ServeTreeResponse {
  enum ServeTreeStatus{
    // All good
    OK = 0;

    // Tree not known
    NOT_FOUND = 1;

    // Failed to upload tree to remote CAS
    SYNC_ERROR = 2;

    // Internally, something is very broken
    INTERNAL_ERROR = 3;
  }

  // If the status has a code `OK`, the tree is in the remote CAS
  ServeTreeStatus status = 1;
}

// A request message for
// [TargetLevelCache.CheckRootTree][justbuild.just_serve.TargetLevelCache.CheckRootTree].
message CheckRootTreeRequest {
  // The git tree identifier.
  string tree = 1;
}

// A response message for
// [TargetLevelCache.CheckRootTree][justbuild.just_serve.TargetLevelCache.CheckRootTree].
message CheckRootTreeResponse {
  enum CheckRootTreeStatus{
    // All good
    OK = 0;

    // Tree not known
    NOT_FOUND = 1;

    // Internally, something is very broken
    INTERNAL_ERROR = 2;
  }

  // If the status has a code `OK`, the tree is known locally
  CheckRootTreeStatus status = 1;
}

// A request message for
// [TargetLevelCache.GetRemoteTree][justbuild.just_serve.TargetLevelCache.GetRemoteTree].
message GetRemoteTreeRequest {
  // The git tree identifier.
  string tree = 1;
}

// A response message for
// [TargetLevelCache.GetRemoteTree][justbuild.just_serve.TargetLevelCache.GetRemoteTree].
message GetRemoteTreeResponse {
  enum GetRemoteTreeStatus{
    // All good
    OK = 0;

    // Tree is not found in remote CAS or it failed to be retrieved
    FAILED_PRECONDITION = 1;

    // Internally, something is very broken
    INTERNAL_ERROR = 2;
  }

  // If the status has a code `OK`, the tree is in the local CAS
  GetRemoteTreeStatus status = 1;
}

// Services for improved interaction with the target-level cache.
service SourceTree {
  // Retrieve the Git-subtree identifier from a given Git commit.
  //
  // There are no method-specific errors.
  rpc ServeCommitTree(ServeCommitTreeRequest) returns (ServeCommitTreeResponse) {}

  // Retrieve the Git-subtree identifier for the tree obtained
  // by unpacking an archive with a given blob identifier.
  //
  // There are no method-specific errors.
  rpc ServeArchiveTree(ServeArchiveTreeRequest) returns (ServeArchiveTreeResponse) {}

  // Compute the Git-tree identifier for the tree containing the content
  // blobs of a list of distfiles. The implementation must only return the
  // tree identifier if ALL content blobs are known.
  //
  // There are no method-specific errors.
  rpc ServeDistdirTree(ServeDistdirTreeRequest) returns (ServeDistdirTreeResponse) {}

  // Make the blob identifier of an archive content available in
  // remote CAS, if blob is known.
  //
  // There are no method-specific errors.
  rpc ServeContent(ServeContentRequest) returns (ServeContentResponse) {}

  // Make a given tree identifier available in remote CAS,
  // if tree is known.
  //
  // There are no method-specific errors.
  rpc ServeTree(ServeTreeRequest) returns (ServeTreeResponse) {}

  // Checks if a Git-tree is locally known and, if found, makes it available
  // in a location where this serve instance can build against.
  // The implementation should not interrogate the associated remote-execution
  // endpoint at any point during the completion of this request.
  //
  // There are no method-specific errors.
  rpc CheckRootTree(CheckRootTreeRequest) returns (CheckRootTreeResponse) {}

  // Retrieves a given Git-tree from the CAS of the associated
  // remote-execution endpoint and makes it available in a location where this
  // serve instance can build against.
  //
  // There are no method-specific errors.
  rpc GetRemoteTree(GetRemoteTreeRequest) returns (GetRemoteTreeResponse) {}
}

message ServeTargetRequest {
  // Digest of the blob containing the target description.
  //
  // The client has to guarantee that the blob has been uploaded to the
  // remote CAS.
  build.bazel.remote.execution.v2.Digest target_cache_key_id = 1;

  // A single property of the remote execution environment.
  message Property {
    // Property name
    string name = 1;

    // Property value
    string value = 2;
  }

  // The execution properties. The key-value pairs accumulate, with latest
  // value for each key being taken.
  repeated Property execution_properties  = 2;

  // Digest of the blob containing the endpoint configuration.
  //
  // The client has to guarantee that the blob has been uploaded to the
  // remote CAS.
  build.bazel.remote.execution.v2.Digest dispatch_info  = 3;
}

message ServeTargetResponse {
  // Digest of the blob with the JSON object containing the target-cache value
  // The implementation must guarantee that all the referenced objects are
  // present in the remote CAS.
  build.bazel.remote.execution.v2.Digest target_value = 1;
}

message ServeTargetVariablesRequest {
  // Git hash of the target-level root tree.
  string root_tree = 1;

  // Relative path of the targets file inside the root tree.
  string target_file = 2;

  // Name of the export target to look up.
  string target = 3;
}

message ServeTargetVariablesResponse {
  // List of flexible configuration variables.
  repeated string flexible_config = 1;
}

message ServeTargetDescriptionRequest {
  // Git hash of the target-level root tree.
  string root_tree = 1;

  // Relative path of the targets file inside the root tree.
  string target_file = 2;

  // Name of the export target to look up.
  string target = 3;
}

message ServeTargetDescriptionResponse {
  // Digest of the blob containing the desired target description fields.
  build.bazel.remote.execution.v2.Digest description_id = 1;
}

service Target {
  // Given a target-level caching key, returns the computed value. In doing so,
  // it can build on the associated end-point passing the
  // RemoteExecutionProperties contained in the ServeTargetRequest.
  //
  // If the status has a code different from `OK`, the response MUST not be used.
  //
  // Errors:
  // * `FAILED_PRECONDITION`: Failed to find required information in the CAS or
  //   the target cache key is malformed.
  // * `UNAVAILABLE`: Could not communicate with the remote execution endpoint.
  // * `INTERNAL`: Internally, something is very broken.
  rpc ServeTarget(ServeTargetRequest) returns (ServeTargetResponse) {}

  // Given the target-level root tree and the name of an export target, returns
  // the list of flexible variables from that target's description.
  //
  // If the status has a code different from `OK`, the response MUST not be used.
  //
  // Errors:
  // * `FAILED_PRECONDITION`: An error occurred in retrieving the configuration
  //   of the requested target, such as missing entries (target-root, target
  //   file, target name), unparsable target file, or requested target not
  //   being of "type" : "export".
  // * `INTERNAL`: Internally, something is very broken.
  rpc ServeTargetVariables(ServeTargetVariablesRequest) returns (ServeTargetVariablesResponse) {}

  // Given the target-level root tree and the name of an export target,
  // returns the digest of the blob containing the flexible variables field,
  // as well as the documentation fields pertaining tho the target and
  // its configuration variables, as taken from the target's description.
  // This information should be enough for a client to produce locally a
  // full description of said target.
  //
  // The server MUST make the returned blob available in the remote CAS.
  //
  // If the status has a code different from `OK`, the response MUST not be used.
  //
  // Errors:
  // * `FAILED_PRECONDITION`: An error occurred in retrieving the configuration
  //   of the requested target, such as missing entries (target-root, target
  //   file, target name), unparsable target file, or requested target not
  //   being of "type" : "export".
  // * `UNAVAILABLE`: Could not communicate with the remote CAS.
  // * `INTERNAL`: Internally, something is very broken.
  rpc ServeTargetDescription(ServeTargetDescriptionRequest) returns (ServeTargetDescriptionResponse) {}
}

message RemoteExecutionEndpointRequest {}

message RemoteExecutionEndpointResponse {
  string address = 1;
}

message CompatibilityRequest {}

message CompatibilityResponse {
  bool compatible = 1;
}

// This service can be used by the client to double check the server configuration
service Configuration {
  // Returns the address of the associated remote endpoint, if set,
  // or an empty string signaling that the serve endpoint acts also
  // as a remote execution endpoint.
  //
  // There are no method-specific errors.
  rpc RemoteExecutionEndpoint(RemoteExecutionEndpointRequest) returns (RemoteExecutionEndpointResponse) {}

  // Returns a flag signaling whether the associated remote execution
  // endpoint uses the standard remote-execution protocol.
  //
  // There are no method-specific errors.
  rpc Compatibility(CompatibilityRequest) returns (CompatibilityResponse) {}
}