go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/logdog/api/endpoints/coordinator/services/v1/service.proto

// Copyright 2016 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 logdog;

option go_package = "go.chromium.org/luci/logdog/api/endpoints/coordinator/services/v1;logdog";

import "go.chromium.org/luci/logdog/api/endpoints/coordinator/services/v1/state.proto";
import "go.chromium.org/luci/logdog/api/endpoints/coordinator/services/v1/tasks.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";

// Error is a projection of a gRPC error.
//
// NOTE: This and its helper functions may be useful more generally. Maybe
// transplant this to a more general place such as "//grpc" if it ends up being
// useful.
message Error {
  // The gRPC code for this error.
  int32 grpc_code = 1;
  // Transient is true if this is a transient error.
  bool transient = 2;
  // An optional associated message.
  string msg = 3;
}

// RegisterStreamRequest is the set of caller-supplied data for the
// RegisterStream Coordinator service endpoint.
message RegisterStreamRequest {
  // The log stream's project.
  string project = 1;
  // The log stream's secret.
  bytes secret = 2;

  // The protobuf version string for this stream.
  string proto_version = 3;
  // The serialized LogStreamDescriptor protobuf for this stream.
  bytes desc = 4;

  // The stream's terminal index. If >= 0, the terminal index will be set
  // in the registration request, avoiding the need for an additional
  // termination RPC.
  int64 terminal_index = 5;
}

// The response message for the RegisterStream RPC.
message RegisterStreamResponse {
  // The Coordinator ID of the log stream.
  string id = 1;
  // The state of the requested log stream.
  InternalLogStreamState state = 2;

  // Error is the error response.
  Error error = 3;
}

// LoadStreamRequest loads the current state of a log stream.
message LoadStreamRequest {
  // The log stream's project.
  string project = 1;
  // The log stream's path Coordinator ID.
  string id = 2;

  // If true, include the log stream descriptor.
  bool desc = 3;
}

// The response message for the LoadStream RPC.
message LoadStreamResponse {
  // The state of the requested log stream.
  InternalLogStreamState state = 1;

  // If requested, the serialized log stream descriptor. The protobuf version
  // of this descriptor will match the "proto_version" field in "state".
  bytes desc = 2;

  // The age of the log stream.
  google.protobuf.Duration age = 3;

  // The archival key of the log stream. If this key doesn't match the key in
  // the archival request, the request is superfluous and should be deleted.
  bytes archival_key = 4;
}

// TerminateStreamRequest is the set of caller-supplied data for the
// TerminateStream service endpoint.
message TerminateStreamRequest {
  // The log stream's project.
  string project = 1;
  // The log stream's path Coordinator ID.
  string id = 2;
  // The log stream's secret.
  bytes secret = 3;

  // The terminal index of the stream.
  int64 terminal_index = 4;
}

// ArchiveStreamRequest is the set of caller-supplied data for the ArchiveStream
// service endpoint.
message ArchiveStreamRequest {
  // The log stream's project.
  string project = 1;
  // The Coordinator ID of the log stream that was archived.
  string id = 2;
  // The number of log entries that were archived.
  int64 log_entry_count = 3;
  // The highest log stream index that was archived.
  int64 terminal_index = 4;
  // If not empty, there was an archival error.
  //
  // This field serves to indicate that an error occurred (being non-empty) and
  // to supply an value that will show up in the Coordinator ArchiveStream
  // endpoint logs.
  string error = 5;

  // The archive URL of the log stream's stream data.
  string stream_url = 10;
  // The size of the log stream's stream data.
  int64 stream_size = 11;

  // The archive URL of the log stream's index data.
  string index_url = 20;
  // The size of the log stream's index data.
  int64 index_size = 21;

  reserved "data_url", "data_size";
  reserved 30, 31;
}

// BatchRequest is a batch of individual requests to make to the Coordinator.
message BatchRequest {
  // The collection of batched requests.
  message Entry {
    oneof value {
      RegisterStreamRequest register_stream = 1;
      LoadStreamRequest load_stream = 2;
      TerminateStreamRequest terminate_stream = 3;
      ArchiveStreamRequest archive_stream = 4;
    };
  }
  repeated Entry req = 1;
}

// BatchResponse is a response to a BatchRequest.
message BatchResponse {
  // The collection of batched requests.
  //
  // Each entry corresponds to the BatchRequest entry with the specified index.
  //
  // Entry objects may appear out of order with their request indexes. Some
  // responses may also be missing, if the remote end could not provide them
  // due to constraints (e.g., size, time).
  message Entry {
    // The index in the BatchRequest for this entry.
    int32 index = 1;

    oneof value {
      Error err = 2;

      RegisterStreamResponse register_stream = 3;
      LoadStreamResponse load_stream = 4;
    };
  }
  repeated Entry resp = 1;
}

message LeaseRequest {
  int64 max_tasks = 1;
  google.protobuf.Duration lease_time = 2;
}

message LeaseResponse {
  // Tasks are tasks leased to the caller.  Only Project and Id are filled.
  repeated ArchiveTask tasks = 1;
}

message DeleteRequest {
  // Tasks are tasks the caller wants to delete.  Only Project and Id are required.
  repeated ArchiveTask tasks = 1;
}

// Services service is a LogDog Coordinator endpoint that interfaces with
// LogDog processing services.
service Services {
  // RegisterStream is an idempotent stream state register operation.
  rpc RegisterStream(RegisterStreamRequest) returns (RegisterStreamResponse);

  // LoadStream loads the current state of a log stream.
  rpc LoadStream(LoadStreamRequest) returns (LoadStreamResponse);

  // TerminateStream is an idempotent operation to update the stream's terminal
  // index.
  rpc TerminateStream(TerminateStreamRequest) returns (google.protobuf.Empty);

  // ArchiveStream is an idempotent operation to record a log stream's archival
  // parameters. It is used by the Archivist service upon successful stream
  // archival.
  rpc ArchiveStream(ArchiveStreamRequest) returns (google.protobuf.Empty);

  // Batch is a series of requests submitted in batch. It returns a
  // BatchResponse containing the same number of entries, with each entry index
  // corresponding to its request index.
  rpc Batch(BatchRequest) returns (BatchResponse);

  // TaskQueueLease is a passthrough to appengine's taskqueue.Lease.
  // TODO(hinoka): Remove this when https://cloud.google.com/tasks/ is out of Beta.
  rpc LeaseArchiveTasks(LeaseRequest) returns (LeaseResponse);

  // TaskQueueDeleteMulti is a passthrough to appengine's taskqueue.DeleteMulti
  // TODO(hinoka): Remove this when https://cloud.google.com/tasks/ is out of Beta.
  rpc DeleteArchiveTasks(DeleteRequest) returns (google.protobuf.Empty);
}