log_io.proto

syntax = "proto3";

package varlog.snpb;

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "google/protobuf/empty.proto";

import "varlogpb/metadata.proto";
import "snpb/metadata.proto";

option go_package = "github.com/kakao/varlog/proto/snpb";

option (gogoproto.protosizer_all) = true;
option (gogoproto.marshaler_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.goproto_unkeyed_all) = false;
option (gogoproto.goproto_unrecognized_all) = false;
option (gogoproto.goproto_sizecache_all) = false;

// AppendRequest is a message to send a payload to a storage node. It contains
// a vector of storage nodes to replicate the payload.
message AppendRequest {
  option (gogoproto.equal) = true;
  option (gogoproto.populate) = true;
  option (gogoproto.testgen) = true;

  int32 topic_id = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
  repeated bytes payload = 3;
}

message AppendResult {
  varlogpb.LogEntryMeta meta = 1 [(gogoproto.nullable) = false];
  string error = 2;
}

// AppendResponse is a response message of Append RPC.
message AppendResponse {
  repeated AppendResult results = 1 [(gogoproto.nullable) = false];
}

// ReadRequest asks a storage node to retrieve log entry at the GLSN.
message ReadRequest {
  uint64 glsn = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSN"
  ];
  int32 topic_id = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 3 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
}

// ReadResponse contains the contents of the log entry which is retrieved by
// the ReadRequest.
message ReadResponse {
  uint64 glsn = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSN"
  ];
  uint64 llsn = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LLSN",
    (gogoproto.customname) = "LLSN"
  ];
  bytes payload = 3;
}

// SubscribeRequest has GLSN which indicates an inclusive starting position
// from which a client wants to receive.
message SubscribeRequest {
  uint64 glsn_begin = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSNBegin"
  ];
  uint64 glsn_end = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSNEnd"
  ];
  int32 topic_id = 3 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 4 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
}

// SubscribeResponse comprises the contents of the log entry and its GLSN.
message SubscribeResponse {
  uint64 glsn = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSN"
  ];
  uint64 llsn = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LLSN",
    (gogoproto.customname) = "LLSN"
  ];
  bytes payload = 3;
}

message SubscribeToRequest {
  int32 topic_id = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
  uint64 llsn_begin = 3 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LLSN",
    (gogoproto.customname) = "LLSNBegin"
  ];
  uint64 llsn_end = 4 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LLSN",
    (gogoproto.customname) = "LLSNEnd"
  ];
}

message SubscribeToResponse {
  varlogpb.LogEntry log_entry = 1 [(gogoproto.nullable) = false];
}

// TrimRequest contains inclusive GLSN until which a client wants to delete.
// If async field is true, the trim operation returns immediately and the
// storage node removes its log entry in the background.
message TrimDeprecatedRequest {
  int32 topic_id = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  uint64 glsn = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.GLSN",
    (gogoproto.customname) = "GLSN"
  ];
}

message LogStreamMetadataRequest {
  int32 topic_id = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
}

message LogStreamMetadataResponse {
  varlogpb.LogStreamDescriptor log_stream_descriptor = 1
    [(gogoproto.nullable) = false];
}

message LogStreamReplicaMetadataRequest {
  int32 topic_id = 1 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.TopicID",
    (gogoproto.customname) = "TopicID"
  ];
  int32 log_stream_id = 2 [
    (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.LogStreamID",
    (gogoproto.customname) = "LogStreamID"
  ];
}

message LogStreamReplicaMetadataResponse {
  LogStreamReplicaMetadataDescriptor log_stream_replica = 1
    [(gogoproto.nullable) = false];
}

service LogIO {
  // Append stores a list of log entries to the end of the log stream
  // specified by AppendRequest. The log entries are appended partially; that
  // is, some of the log entries could not be stored due to failures.
  //
  // It returns the following gRPC errors:
  // - InvalidArgument: AppendRequest has invalid fields; for instance, TopicID
  // is invalid.
  // - NotFound: The log stream replica specified by the AppendRequest does not
  // exist in the storage node. Note that it does not mean that the log stream
  // does not exist in the cluster.
  // - FailedPrecondition: The log stream may be sealed; thus, clients cannot
  // write the log entry. Clients should unseal the log stream to append a log
  // entry to the log stream.
  // - Unavailable: The storage node is shutting down, or the log stream replica
  // is not primary.
  // - Canceled: The client canceled the request.
  // - DeadlineExceeded: The client's timeout has expired.
  //
  // FIXME: Partial failures are not specified by the gRPC error codes.
  rpc Append(stream AppendRequest) returns (stream AppendResponse) {}

  // Read reads a log entry from the log stream specified by ReadRequest.
  // Deprecated: Use Subscribe or SubscribeTo.
  rpc Read(ReadRequest) returns (ReadResponse) {}
  // Subscribe reads a range of log entries specified by SubscribeRequest.
  //
  // It returns the following gRPC errors:
  // - NotFound: The log stream replica specified by the SubscribeRequest does
  // not exist in the storage node. Note that it does not mean that the log
  // stream does not exist in the cluster.
  // - Unavailable: The storage node is shutting down.
  // - InvalidArgument: The range is invalid; for example, the beginning of the
  // range is greater than or equal to the end.
  // - OutOfRange: The parts or whole range are already trimmed.
  rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse) {}
  // SubscribeTo is similar to Subscribe except that it specifies the range with
  // LLSN.
  rpc SubscribeTo(SubscribeToRequest) returns (stream SubscribeToResponse) {}
  rpc TrimDeprecated(TrimDeprecatedRequest) returns (google.protobuf.Empty) {}
  // LogStreamReplicaMetadata returns metadata of the log stream replica
  // specified by the LogStreamReplicaMetadataRequest.
  rpc LogStreamReplicaMetadata(LogStreamReplicaMetadataRequest)
    returns (LogStreamReplicaMetadataResponse) {}
}