milvus/internal/proto/streaming.proto

syntax = "proto3";

package milvus.proto.log;

option go_package = "github.com/milvus-io/milvus/internal/proto/streamingpb";

import "milvus.proto";
import "google/protobuf/empty.proto";

//
// Common
//

// MessageID is the unique identifier of a message.
message MessageID {
    bytes id = 1;
}

// Message is the basic unit of communication between publisher and consumer.
message Message {
    bytes payload = 1; // message body
    map<string, string> properties = 2; // message properties
}

// PChannelInfo is the information of a pchannel info.
message PChannelInfo {
    string name = 1; // channel name
    int64 term = 2; // A monotonic increasing term, every time the channel is recovered or moved to another streamingnode, the term will increase by meta server.
}

// DeliverPolicy is the policy to deliver message.
message DeliverPolicy {
    oneof policy {
        google.protobuf.Empty all = 1; // deliver all messages.
        google.protobuf.Empty latest = 2; // deliver the latest message.
        MessageID start_from = 3; // deliver message from this message id. [startFrom, ...]
        MessageID start_after = 4; // deliver message after this message id. (startAfter, ...]
    }
}

// DeliverFilter is the filter to deliver message.
message DeliverFilter {
    oneof filter {
        DeliverFilterTimeTickGT time_tick_gt = 1;
        DeliverFilterTimeTickGTE time_tick_gte = 2;
        DeliverFilterVChannel vchannel = 3;
    }
}

// DeliverFilterTimeTickGT is the filter to deliver message with time tick greater than this value.
message DeliverFilterTimeTickGT {
    uint64 time_tick = 1; // deliver message with time tick greater than this value.
}

// DeliverFilterTimeTickGTE is the filter to deliver message with time tick greater than or equal to this value.
message DeliverFilterTimeTickGTE {
    uint64 time_tick = 1; // deliver message with time tick greater than or equal to this value.
}

// DeliverFilterVChannel is the filter to deliver message with vchannel name.
message DeliverFilterVChannel {
    string vchannel = 1; // deliver message with vchannel name.
}

// StreamingCode is the error code for log internal component.
enum StreamingCode {
    STREAMING_CODE_OK = 0;
    STREAMING_CODE_CHANNEL_EXIST = 1; // channel already exist
    STREAMING_CODE_CHANNEL_NOT_EXIST = 2; // channel not exist
    STREAMING_CODE_CHANNEL_FENCED = 3; // channel is fenced
    STREAMING_CODE_ON_SHUTDOWN = 4; // component is on shutdown
    STREAMING_CODE_INVALID_REQUEST_SEQ = 5; // invalid request sequence
    STREAMING_CODE_UNMATCHED_CHANNEL_TERM = 6; // unmatched channel term
    STREAMING_CODE_IGNORED_OPERATION = 7; // ignored operation
    STREAMING_CODE_INNER = 8; // underlying service failure.
    STREAMING_CODE_EOF = 9; // end of stream, generated by grpc status.
    STREAMING_CODE_INVAILD_ARGUMENT = 10; // invalid argument
    STREAMING_CODE_UNKNOWN = 999; // unknown error
}

// StreamingError is the error type for log internal component.
message StreamingError {
    StreamingCode code = 1;
    string cause = 2;
}


//
// StreamingNodeHandlerService
//

// StreamingNodeHandlerService is the service to handle log messages.
// All handler operation will be blocked until the channel is ready read or write on that log node.
// Server: all log node. Running on every log node.
// Client: all log produce or consuming node.
service StreamingNodeHandlerService {
    // Produce is a bi-directional streaming RPC to send messages to a channel.
    // All messages sent to a channel will be assigned a unique messageID.
    // The messageID is used to identify the message in the channel.
    // The messageID isn't promised to be monotonous increasing with the sequence of responsing.
    // Error:
    // If channel isn't assign to this log node, the RPC will return error CHANNEL_NOT_EXIST.
    // If channel is moving away to other log node, the RPC will return error CHANNEL_FENCED.
    rpc Produce(stream ProduceRequest) returns (stream ProduceResponse) {};

    // Consume is a server streaming RPC to receive messages from a channel.
    // All message after given startMessageID and excluding will be sent to the client by stream.
    // If no more message in the channel, the stream will be blocked until new message coming.
    // Error:
    // If channel isn't assign to this log node, the RPC will return error CHANNEL_NOT_EXIST.
    // If channel is moving away to other log node, the RPC will return error CHANNEL_FENCED.
    rpc Consume(stream ConsumeRequest) returns (stream ConsumeResponse) {};
}

// ProduceRequest is the request of the Produce RPC.
// Channel name will be passthrough in the header of stream bu not in the request body.
message ProduceRequest {
    oneof request {
        ProduceMessageRequest produce = 2;
        CloseProducerRequest close = 3;
    }
}

// CreateProducerRequest is the request of the CreateProducer RPC.
// CreateProducerRequest is passed in the header of stream.
message CreateProducerRequest {
    PChannelInfo pchannel = 1;
}

// ProduceMessageRequest is the request of the Produce RPC.
message ProduceMessageRequest {
    int64 request_id = 1; // request id for reply.
    Message message = 2; // message to be sent.
}

// CloseProducerRequest is the request of the CloseProducer RPC.
// After CloseProducerRequest is requested, no more ProduceRequest can be sent.
message CloseProducerRequest {
}

// ProduceResponse is the response of the Produce RPC.
message ProduceResponse {
    oneof response {
        CreateProducerResponse create = 1;
        ProduceMessageResponse produce = 2;
        CloseProducerResponse close = 3;
    }
}

// CreateProducerResponse is the result of the CreateProducer RPC.
message CreateProducerResponse {
    int64 producer_id = 1; // A unique producer id on streamingnode for this producer in streamingnode lifetime. 
                          // Is used to identify the producer in streamingnode for other unary grpc call at producer level.
}

message ProduceMessageResponse {
    int64 request_id = 1;
    oneof response {
        ProduceMessageResponseResult result = 2;
        StreamingError error = 3;
    }
}

// ProduceMessageResponseResult is the result of the produce message streaming RPC.
message ProduceMessageResponseResult {
    MessageID id = 1; // the offset of the message in the channel
}

// CloseProducerResponse is the result of the CloseProducer RPC.
message CloseProducerResponse {
}

// ConsumeRequest is the request of the Consume RPC.
// Add more control block in future.
message ConsumeRequest {
    oneof request {
        CloseConsumerRequest close = 1;
    }
}

// CloseConsumerRequest is the request of the CloseConsumer RPC.
// After CloseConsumerRequest is requested, no more ConsumeRequest can be sent.
message CloseConsumerRequest {
}

// CreateConsumerRequest is the request of the CreateConsumer RPC.
// CreateConsumerRequest is passed in the header of stream.
message CreateConsumerRequest {
    PChannelInfo pchannel = 1;
    DeliverPolicy deliver_policy = 2; // deliver policy.
    repeated DeliverFilter deliver_filters = 3; // deliver filter.
}

// ConsumeResponse is the reponse of the Consume RPC.
message ConsumeResponse {
    oneof response {
        CreateConsumerResponse create = 1;
        ConsumeMessageReponse consume = 2;
        CloseConsumerResponse close = 3;
    }
}

message CreateConsumerResponse {
}

message ConsumeMessageReponse {
    MessageID id = 1; // message id of message.
    Message message = 2; // message to be consumed.
}

message CloseConsumerResponse {
}

//
// StreamingNodeManagerService
//

// StreamingNodeManagerService is the log manage operation on log node.
// Server: all log node. Running on every log node.
// Client: log coord. There should be only one client globally to call this service on all streamingnode.
service StreamingNodeManagerService {
    // Assign is a unary RPC to assign a channel on a log node.
    // Block until the channel assignd is ready to read or write on the log node.
    // Error:
    // If the channel already exists, return error with code CHANNEL_EXIST.
    rpc Assign(StreamingNodeManagerAssignRequest) returns (StreamingNodeManagerAssignResponse) {};

    // Remove is unary RPC to remove a channel on a log node.
    // Data of the channel on flying would be sent or flused as much as possible.
    // Block until the resource of channel is released on the log node.
    // New incoming request of handler of this channel will be rejected with special error.
    // Error:
    // If the channel does not exist, return error with code CHANNEL_NOT_EXIST.
    rpc Remove(StreamingNodeManagerRemoveRequest) returns (StreamingNodeManagerRemoveResponse) {};

    // rpc CollectStatus() ...
    // CollectStatus is unary RPC to collect all avaliable channel info and load balance info on a log node.
    // Used to recover channel info on log coord, collect balance info and health check.
    rpc CollectStatus(StreamingNodeManagerCollectStatusRequest) returns (StreamingNodeManagerCollectStatusResponse) {};
}

// StreamingManagerAssignRequest is the request message of Assign RPC.
message StreamingNodeManagerAssignRequest {
    PChannelInfo pchannel = 1;
}

message StreamingNodeManagerAssignResponse {
}

message StreamingNodeManagerRemoveRequest {
    PChannelInfo pchannel = 1;
}

message StreamingNodeManagerRemoveResponse {}

message StreamingNodeManagerCollectStatusRequest {
}

message StreamingNodeBalanceAttributes {
    // TODO: traffic of pchannel or other things.
}

message StreamingNodeManagerCollectStatusResponse {
    StreamingNodeBalanceAttributes balance_attributes = 1;
}