go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/logdog/api/endpoints/coordinator/logs/v1/logs.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/logs/v1;logdog";

import "go.chromium.org/luci/logdog/api/endpoints/coordinator/logs/v1/state.proto";
import "go.chromium.org/luci/logdog/api/logpb/log.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

// GetRequest is the request structure for the user Get endpoint.
//
// If the requested log stream exists, a valid GetRequest will succeed
// regardless of whether the requested log range was available.
//
// Note that this endpoint may return fewer logs than requested due to either
// availability or internal constraints.
message GetRequest {
  // The request project to request.
  string project = 1;
  // The path of the log stream to get.
  //
  // This can either be a LogDog stream path or the SHA256 hash of a LogDog
  // stream path.
  //
  // Some utilities may find passing around a full LogDog path to be cumbersome
  // due to its length. They can opt to pass around the hash instead and
  // retrieve logs using it.
  string path = 2;

  // If true, requests that the log stream's state is returned.
  bool state = 3;

  // The initial log stream index to retrieve.
  int64 index = 4;

  // The maximum number of bytes to return. If non-zero, it is applied as a
  // constraint to limit the number of logs that are returned.
  //
  // This only returns complete logs. Assuming logs are available, it will
  // return at least one log (even if it violates the size constraint) and as
  // many additional logs as it can without exceeding this constraint.
  int32 byte_count = 5;

  // The maximum number of log records to request.
  //
  // If this value is zero, no count constraint will be applied. If this value
  // is less than zero, no log entries will be returned. This can be used to
  // fetch log stream descriptors without fetching any log records.
  int32 log_count = 6;

  // If true, allows the range request to return non-contiguous records.
  //
  // A contiguous request (default) will iterate forwards from the supplied
  // Index and stop if either the end of stream is encountered or there is a
  // missing stream index. A NonContiguous request will remove the latter
  // condition.
  //
  // For example, say the log stream consists of:
  // [3, 4, 6, 7]
  //
  // A contiguous request with Index 3 will return: [3, 4], stopping because
  // 5 is missing. A non-contiguous request will return [3, 4, 6, 7].
  bool non_contiguous = 7;

  // If supplied, the response will contain a SignedUrls message with the
  // requested signed URLs. If signed URLs are not supported by the log's
  // current storage system, the response message will be empty.
  message SignURLRequest {
    // The lifetime that the signed URL will be bound to.. The
    google.protobuf.Duration lifetime = 1;

    // Return a signed URL for the log's RecordIO protobuf data.
    bool stream = 2;
    // Return a signed URL for the log's LogIndex protobuf.
    bool index = 3;
  }
  SignURLRequest get_signed_urls = 8;
}

// TailRequest is the request structure for the user Tail endpoint. It returns
// the last log in a given log stream at the time of the request.
message TailRequest {
  // The request project to request.
  string project = 1;
  // The path of the log stream to get.
  //
  // This can either be a LogDog stream path or the SHA256 hash of a LogDog
  // stream path.
  //
  // Some utilities may find passing around a full LogDog path to be cumbersome
  // due to its length. They can opt to pass around the hash instead and
  // retrieve logs using it.
  string path = 2;

  // If true, requests that the log stream's state is returned.
  bool state = 3;
}

// GetResponse is the response structure for the user Get endpoint.
message GetResponse {
  // Project is the project name that these logs belong to.
  string project = 1;

  // Realm is the realm (within the project) the stream is associated with.
  string realm = 6;

  // The log stream descriptor and state for this stream.
  //
  // It can be requested by setting the request's State field to true. If the
  // Proto field is true, the State's Descriptor field will not be included.
  LogStreamState state = 2;

  // The expanded LogStreamDescriptor protobuf. It is intended for JSON
  // consumption.
  //
  // If the GetRequest's Proto field is false, this will be populated;
  // otherwise, the serialized protobuf will be written to the DescriptorProto
  // field.
  logpb.LogStreamDescriptor desc = 3;

  // Log represents the set of retrieved log records.
  repeated logpb.LogEntry logs = 4;

  // Holds information about the log stream's signed entry URL.
  message SignedUrls {
    // The time when this signed URL will expire.
    google.protobuf.Timestamp expiration = 1;

    // The signed log stream URL, if requested.
    string stream = 2;
    // The signed log index URL, if requested.
    string index = 3;
  }
  // An optional signed log entry RecordIO protobuf URL, if requested via
  // "sign_entry_url_lifetime".
  SignedUrls signed_urls = 5;
}

// QueryRequest is the request structure for the user Query endpoint.
message QueryRequest {
  // Trinary represents a trinary value.
  enum Trinary {
    // Both positive and negative results will be returned.
    BOTH = 0;
    // Only positive results will be returned.
    YES = 1;
    // Only negative results will be returned.
    NO = 2;
  }

  // (required) The project to query from.
  string project = 1;

  // (required) The stream query parameter.
  //
  // Paths are of the form "full/path/prefix/+/stream/name", where the
  // "stream/name" portion can contain glob-style "*" and "**" operators.
  //
  // If this is just "full/path/prefix", then the stream/name is assumed to be
  // "**" (meaning all streams).
  //
  // Omitting the full path prefix is an error (no wildcards are permitted).
  string path = 2;

  // If true, returns that the streams' full state is returned instead of just
  // its Path.
  bool state = 3;

  // If true, causes the requested state to be returned as serialized protobuf
  // data instead of deserialized JSON structures.
  bool proto = 4;

  // Next, if not empty, indicates that this query should continue at the point
  // where the previous query left off.
  string next = 5;

  // MaxResults is the maximum number of query results to return.
  //
  // If MaxResults is zero, no upper bound will be indicated. However, the
  // returned result count is still be subject to internal constraints.
  int32 max_results = 6;

  // ContentType, if not empty, restricts results to streams with the supplied
  // content type.
  string content_type = 10;

  // The stream type to filter on.
  message StreamTypeFilter {
    // The StreamType value to filter on.
    logpb.StreamType value = 1;
  }
  StreamTypeFilter stream_type = 11;

  // [DEPRECATED] `newer` restricts results to streams created after the specified date.
  reserved "newer";
  reserved 12;

  // [DEPRECATED] `older` restricts results to streams created before the specified date.
  reserved "older";
  reserved 13;

  // [DEPRECATED] If not empty, constrains the results to those whose protobuf
  // version string matches the supplied version.
  reserved "proto_version";
  reserved 14;

  // Tags is the set of tags to constrain the query with.
  //
  // A Tag entry may either be:
  // - A key/value query, in which case the results are constrained by logs
  //   whose tag includes that key/value pair.
  // - A key with an missing (nil) value, in which case the results are
  //   constraints by logs that have that tag key, regardless of its value.
  map<string, string> tags = 15;

  // Purged restricts the query to streams that have or haven't been purged.
  Trinary purged = 16;
}

// QueryResponse is the response structure for the user Query endpoint.
message QueryResponse {
  // Project is the project name that all responses belong to.
  string project = 1;

  // Realm is the realm (within the project) all streams are associated with.
  string realm = 4;

  // Stream represents a single query response stream.
  message Stream {
    // Path is the log stream path.
    string path = 1;

    // State is the log stream descriptor and state for this stream.
    //
    // It can be requested by setting the request's State field to true. If the
    // Proto field is true, the State's Descriptor field will not be included.
    LogStreamState state = 2;

    // The JSON-packed log stream descriptor protobuf.
    //
    // A Descriptor entry corresponds to the Path with the same index.
    //
    // If the query request's State field is set, the descriptor will be
    // populated. If the Proto field is false, Descriptor will be populated;
    // otherwise, DescriptorProto will be populated with the serialized descriptor
    // protobuf.
    logpb.LogStreamDescriptor desc = 3;
    // The serialized log stream Descriptor protobuf.
    bytes desc_proto= 4;
  }

  // The list of streams that were identified as the result of the query.
  repeated Stream streams = 2;

  // If not empty, indicates that there are more query results available.
  // These results can be requested by repeating the Query request with the
  // same Path field and supplying this value in the Next field.
  string next = 3;
}

// Logs is the user-facing log access and query endpoint service.
service Logs {
  // Get returns state and log data for a single log stream.
  rpc Get(GetRequest) returns (GetResponse);

  // Tail returns the last log in the log stream at the time of the request.
  rpc Tail(TailRequest) returns (GetResponse);

  // Query returns log stream paths that match the requested query.
  rpc Query(QueryRequest) returns (QueryResponse);
}