trpc.proto

// Tencent is pleased to support the open source community by making tRPC available.
// Copyright (C) 2023 THL A29 Limited, a Tencent company. All rights reserved.
// If you have downloaded a copy of the tRPC source code from Tencent,
// please note that tRPC source code is licensed under the Apache 2.0 License,
// A copy of the Apache 2.0 License is included in this file.

syntax = "proto3";

package trpc;

option go_package = "trpc.group/trpc/trpc-protocol/pb/go/trpc";
option java_package = "com.tencent.trpc.proto.standard.common";
option java_outer_classname = "TRPCProtocol";

// The magic value of trpc protocol
enum TrpcMagic {
  // trpc does not use this value, it is used by the pb gen-code tool
  TRPC_DEFAULT_NONE = 0x00;

  // The magic value used by trpc protocol
  TRPC_MAGIC_VALUE = 0x930;
}

// The data frame type of the trpc protocol packet
// Two types are currently supported:
// 1. The data frame type for unary(one-response-one-response)
// 2. The data frame type for stream
enum TrpcDataFrameType {
  TRPC_UNARY_FRAME = 0x00;

  TRPC_STREAM_FRAME = 0x01;
}

// The specific frame type of trpc streaming data frame
// Four types are currently supported:
// `INIT` frame: FIXHEADER + TrpcStreamInitMeta
// `DATA` frame: FIXHEADER + body (business serialized data)
// `FEEDBACK` frame: FIXHEADER + TrpcStreamFeedBackMeta (triggered strategy: high/low water level and timer)
// `CLOSE` frame: FIXHEADER + TrpcStreamCloseMeta
enum TrpcStreamFrameType {
  TRPC_UNARY = 0x00;

  TRPC_STREAM_FRAME_INIT = 0x01;

  TRPC_STREAM_FRAME_DATA = 0x02;

  TRPC_STREAM_FRAME_FEEDBACK = 0x03;

  TRPC_STREAM_FRAME_CLOSE = 0x04;
}

// The message definition of stream `INIT` frame
message TrpcStreamInitMeta {
  // request meta information
  TrpcStreamInitRequestMeta request_meta = 1;

  // response meta information
  TrpcStreamInitResponseMeta response_meta = 2;

  // The window size is notified by the receiver to the sender
  uint32 init_window_size = 3;

  // The serialization type of the request data
  // eg: proto/json/.., default proto
  // The specific value corresponds to `TrpcContentEncodeType`
  uint32 content_type = 4;

  // The compression type of the requested data
  // eg: gzip/snappy/..., not used by default
  // The specific value corresponds to `TrpcCompressType`
  uint32 content_encoding = 5;
}

// The request meta information definition of stream `INIT` frame
message TrpcStreamInitRequestMeta {
  // Caller name
  // The specification format: trpc.application_name.server_name.proto_service_name, 4 segments
  bytes caller = 1;

  // Callee name
  // The specification format: trpc.application_name.server_name.proto_service_name[.interface_name]
  bytes callee = 2;

  // Interface name of callee
  // The specification format: /package.service_name/interface_name
  bytes func = 3;

  // The message type of the transparent transmission information
  // such as tracing, dyeing key, gray, authentication, multi-environment, set name, etc.
  // The specific value corresponds to `TrpcMessageType`
  uint32 message_type = 4;

  // The information key-value pair transparently transmitted by the framework
  // Currently divided into two parts:
  // 1 part is the information to be transparently transmitted by the framework layer,
  // and the name of the key must be started with `trpc-``
  // 2 part is the information to be transparently transmitted by the business layer,
  // and the business can set it by itself, it is recommended to start with `app-``, not `trpc-`
  // Note: The key-value pair in trans_info will be transparently transmitted through the whole link, please use it carefully for business.
  map<string, bytes> trans_info = 5;
};

// The response meta information definition of stream `INIT` frame
message TrpcStreamInitResponseMeta {
  // Error code
  // The specific value corresponds to `TrpcRetCode`
  int32 ret = 1;

  // The result information when the call fails
  bytes error_msg = 2;
};

// The meta information definition of stream `FEEDBACK` frame
message TrpcStreamFeedBackMeta {
  // increased window size
  uint32 window_size_increment = 1;
}

// The closed type of trpc stream protocol
enum TrpcStreamCloseType {
  // normal closes unidirectional flow
  TRPC_STREAM_CLOSE = 0;

  // Exception closes bidirectional stream
  TRPC_STREAM_RESET = 1;
}

// The meta information definition of trpc stream protocol for closing stream
message TrpcStreamCloseMeta {
  // The type of stream closure, close one end, or close all
  int32 close_type = 1;

  // Error code
  // The specific value corresponds to `TrpcRetCode`
  int32 ret = 2;

  // The result information when the call fails
  bytes msg = 3;

  // The message type of the transparent transmission information
  // such as tracing, dyeing key, gray, authentication, multi-environment, set name, etc.
  // The specific value corresponds to `TrpcMessageType`
  uint32    message_type  = 4;

  // The information key-value pair transparently transmitted by the framework
  // Currently divided into two parts:
  // 1 part is the information to be transparently transmitted by the framework layer,
  // and the name of the key must be started with `trpc-``
  // 2 part is the information to be transparently transmitted by the business layer,
  // and the business can set it by itself, it is recommended to start with `app-``, not `trpc-`
  // Note: The key-value pair in trans_info will be transparently transmitted through the whole link, please use it carefully for business.
  map<string, bytes> trans_info = 5;

  // The error code of the interface
  // 0 means success, other means failure
  int32 func_ret = 6;
}

// The version of trpc protocol
enum TrpcProtoVersion {
  TRPC_PROTO_V1  = 0;
}

// The call type of trpc protocol
enum TrpcCallType {
  // Unary(one-response-one-response), include sync and async
  TRPC_UNARY_CALL = 0;

  // Oneway
  TRPC_ONEWAY_CALL = 1;
}

// The message type of the transparent transmission information
enum TrpcMessageType {
  // trpc does not use this value, it is used by the pb gen-code tool
  TRPC_DEFAULT		  = 0x00;

  // Dyeing message
  TRPC_DYEING_MESSAGE = 0x01;

  // Tracing message
  TRPC_TRACE_MESSAGE = 0x02;

  // Multi-Environment message
  TRPC_MULTI_ENV_MESSAGE = 0x04;

  // grid message
  TRPC_GRID_MESSAGE = 0x08;

  // SetNmae message
  TRPC_SETNAME_MESSAGE = 0x10;
}

// The encoding type of the body data in the trpc protocol
// Use proto by default
// At present, it is agreed that the value in the range of 0-127 is used by the framework
enum TrpcContentEncodeType {
  // pb
  TRPC_PROTO_ENCODE = 0;

  // jce
  TRPC_JCE_ENCODE = 1;

  // json
  TRPC_JSON_ENCODE = 2;

  // flatbuffer
  TRPC_FLATBUFFER_ENCODE = 3;

  // text or binary
  TRPC_NOOP_ENCODE = 4;

  // xml
  TRPC_XML_ENCODE = 5;

  // thrift
  TRPC_THRIFT_ENCODE = 6;
}

// The compressor type of the body data in the trpc protocol
// No compression by default
enum TrpcCompressType {
  // No compression
  TRPC_DEFAULT_COMPRESS = 0;

  // gzip
  TRPC_GZIP_COMPRESS = 1;

  // snappy(Deprecated)
  // please use `TRPC_SNAPPY_STREAM_COMPRESS`/`TRPC_SNAPPY_BLOCK_COMPRESS`,
  // Because trpc-go and trpc-cpp use stream and block modes respectively,
  // the two are not compatible, and cross-language calls will make mistakes
  TRPC_SNAPPY_COMPRESS = 2;

  // zlib
  TRPC_ZLIB_COMPRESS = 3;

  // snappy stream
  TRPC_SNAPPY_STREAM_COMPRESS = 4;

  // snappy block
  TRPC_SNAPPY_BLOCK_COMPRESS = 5;

  // lz4 frame
  TRPC_LZ4_FRAME_COMPRESS = 6;

  // lz4 block
  TRPC_LZ4_BLOCK_COMPRESS = 7;
}

// The return code definition of the framework layer interface call
enum TrpcRetCode {
  // success
  TRPC_INVOKE_SUCCESS = 0;

  // server-side error code
  // Mainly divided into several categories:
  // 1. protocol related,
  // 2. interface call related,
  // 3. queue timeout or overload related
  // 4. ...

  // server-side protocol error code

  // server-side decode error
  TRPC_SERVER_DECODE_ERR = 1;
  // server-side encode error
  TRPC_SERVER_ENCODE_ERR = 2;

  // interface call error code

  // the server-side does not have a corresponding service implementation
  TRPC_SERVER_NOSERVICE_ERR = 11;
  // the server-side does not have a corresponding interface implementation
  TRPC_SERVER_NOFUNC_ERR = 12;

  // timeout/overload/limiter error code

  // the request timed out on the server-side
  TRPC_SERVER_TIMEOUT_ERR = 21;
  // the request is overloaded on the server-side and the request is discarded
  TRPC_SERVER_OVERLOAD_ERR = 22;
  // the request is throttled on the server-side
  TRPC_SERVER_LIMITED_ERR = 23;
  // The request is timed out on the server-side due to the full link timeout
  TRPC_SERVER_FULL_LINK_TIMEOUT_ERR = 24;

  // server-side system error
  TRPC_SERVER_SYSTEM_ERR = 31;

  // the server-side request authentication failed error
  TRPC_SERVER_AUTH_ERR = 41;

  // the server-side request parameter automatic verification failed error
  TRPC_SERVER_VALIDATE_ERR = 51;

  // client-side error code
  // Mainly divided into several categories:
  // 1. timeout related,
  // 2. network or connection related,
  // 3. protocol related,
  // 4. routing related
  // 5. ...

  // timeout error code

  // the request is timed out on the client-side
  TRPC_CLIENT_INVOKE_TIMEOUT_ERR = 101;
  // the request is timed out on the client-side due to the full link timeout
  TRPC_CLIENT_FULL_LINK_TIMEOUT_ERR = 102;

  // network or connection error code

  // client-side connection error
  TRPC_CLIENT_CONNECT_ERR = 111;

  // protocol error code

  // client-side encode error
  TRPC_CLIENT_ENCODE_ERR = 121;
  // client-side decode error
  TRPC_CLIENT_DECODE_ERR = 122;

  // client-side overload/limter error code

  // the request is throttled on the client-side
  TRPC_CLIENT_LIMITED_ERR = 123;
  // The request is overloaded on the client-side and discarded
  TRPC_CLIENT_OVERLOAD_ERR = 124;

  // service routing error code
  TRPC_CLIENT_ROUTER_ERR = 131;

  // client-side network or connection error code
  TRPC_CLIENT_NETWORK_ERR = 141;

  // client-side response parameter automatic verification failed error
  TRPC_CLIENT_VALIDATE_ERR = 151;

  // upstream actively disconnected, early cancellation request error code
  TRPC_CLIENT_CANCELED_ERR = 161;

  // client-side read data frame error
  TRPC_CLIENT_READ_FRAME_ERR = 171;

  // error code of the server-side stream
  // mainly divided into several categories:
  // 1. network or connection related,
  // 2. protocol related, 
  // 3. write stream data related, 
  // 4. read stream data related,
  // 5. ...

  // server-side streaming network or connection error code
  TRPC_STREAM_SERVER_NETWORK_ERR = 201;

  // server-side streaming error code

  // stream message exceeds size limit
  TRPC_STREAM_SERVER_MSG_EXCEED_LIMIT_ERR = 211;

  // server-side streaming encode error code
  TRPC_STREAM_SERVER_ENCODE_ERR = 221;
  // server-side streaming decode error code
  TRPC_STREAM_SERVER_DECODE_ERR = 222;

  // server-side stream write error code
  TRPC_STREAM_SERVER_WRITE_END = 231;
  TRPC_STREAM_SERVER_WRITE_OVERFLOW_ERR = 232;
  TRPC_STREAM_SERVER_WRITE_CLOSE_ERR = 233;
  TRPC_STREAM_SERVER_WRITE_TIMEOUT_ERR = 234;

  // server-side stream read error code
  TRPC_STREAM_SERVER_READ_END = 251;
  TRPC_STREAM_SERVER_READ_CLOSE_ERR = 252;
  TRPC_STREAM_SERVER_READ_EMPTY_ERR = 253;
  TRPC_STREAM_SERVER_READ_TIMEOUT_ERR = 254;

  // error code of the client-side stream
  // mainly divided into several categories:
  // 1. network or connection related,
  // 2. protocol related, 
  // 3. write stream data related, 
  // 4. read stream data related,
  // 5. ...

  // client-side streaming network or connection error code
  TRPC_STREAM_CLIENT_NETWORK_ERR = 301;

  // client-side streaming error code

  // client-side stream message exceeds size limit
  TRPC_STREAM_CLIENT_MSG_EXCEED_LIMIT_ERR = 311;

  // client-side streaming encode error code
  TRPC_STREAM_CLIENT_ENCODE_ERR = 321;
  // client-side streaming decode error code
  TRPC_STREAM_CLIENT_DECODE_ERR = 322;

  // client-side stream write error code
  TRPC_STREAM_CLIENT_WRITE_END = 331;
  TRPC_STREAM_CLIENT_WRITE_OVERFLOW_ERR = 332;
  TRPC_STREAM_CLIENT_WRITE_CLOSE_ERR = 333;
  TRPC_STREAM_CLIENT_WRITE_TIMEOUT_ERR = 334;

  // client-side stream read error code
  TRPC_STREAM_CLIENT_READ_END = 351;
  TRPC_STREAM_CLIENT_READ_CLOSE_ERR = 352;
  TRPC_STREAM_CLIENT_READ_EMPTY_ERR = 353;
  TRPC_STREAM_CLIENT_READ_TIMEOUT_ERR = 354;

  // unspecified error code(unary)
  TRPC_INVOKE_UNKNOWN_ERR = 999;
  // unspecified error code(stream)
  TRPC_STREAM_UNKNOWN_ERR = 1000;
}

// The following key already used by trans_info, be careful not to repeat it:
// "trpc-dyeing-key": dyeing key

// The request header for unary
message RequestProtocol {
  // The version of protocol
  // The specific value corresponds to `TrpcProtoVersion`
  uint32    version                     = 1;

  // Call type
  // eg: unary, one-way
  // The specific value corresponds to `TrpcCallType`
  uint32    call_type                   = 2;

  // The unique id of the request(on the conneciton)
  uint32    request_id                  = 3;

  // The timeout of the request(ms)
  uint32    timeout                     = 4;

  // Caller name
  // The specification format: trpc.application_name.server_name.proto_service_name, 4 segments
  bytes     caller                      = 5;

  // Callee name
  // The specification format: trpc.application_name.server_name.proto_service_name[.interface_name]
  bytes     callee                      = 6;

  // Interface name of callee
  // The specification format: /package.service_name/interface_name
  bytes     func                        = 7;

  // The message type of the transparent transmission information
  // such as tracing, dyeing key, gray, authentication, multi-environment, set name, etc.
  // The specific value corresponds to `TrpcMessageType`
  uint32    message_type                = 8;

  // The information key-value pair transparently transmitted by the framework
  // Currently divided into two parts:
  // 1 part is the information to be transparently transmitted by the framework layer,
  // and the name of the key must be started with `trpc-``
  // 2 part is the information to be transparently transmitted by the business layer,
  // and the business can set it by itself, it is recommended to start with `app-``, not `trpc-`
  // Note: The key-value pair in trans_info will be transparently transmitted through the whole link, please use it carefully for business.
  map<string, bytes> trans_info         = 9;

  // The serialization type of the request data
  // eg: proto/json/.., default proto
  // The specific value corresponds to `TrpcContentEncodeType`
  uint32    content_type                = 10;

  // The compression type of the requested data
  // eg: gzip/snappy/..., not used by default
  // The specific value corresponds to `TrpcCompressType`
  uint32    content_encoding            = 11;

  // The size of attachment data
  uint32    attachment_size             = 12;
}

// The response header for unary
message ResponseProtocol {
  // The version of protocol
  // The specific value corresponds to `TrpcProtoVersion`
  uint32    version                     = 1;

  // Call type
  // eg: unary, one-way
  // The specific value corresponds to `TrpcCallType`
  uint32    call_type                   = 2;

  // The unique id of the request(on the conneciton)
  uint32    request_id                  = 3;

  // Error code
  // The specific value corresponds to `TrpcRetCode`
  int32     ret                         = 4;

  // The error code of the interface
  // 0 means success, other means failure
  int32     func_ret                    = 5;

  // The result information when the call fails
  bytes    error_msg                    = 6;

  // The message type of the transparent transmission information
  // such as tracing, dyeing key, gray, authentication, multi-environment, set name, etc.
  // The specific value corresponds to `TrpcMessageType`
  uint32    message_type                = 7;

  // The information key-value pair transparently transmitted by the framework
  // Currently divided into two parts:
  // 1 part is the information to be transparently transmitted by the framework layer,
  // and the name of the key must be started with `trpc-``
  // 2 part is the information to be transparently transmitted by the business layer,
  // and the business can set it by itself, it is recommended to start with `app-``, not `trpc-`
  map<string, bytes> trans_info         = 8;

  // The serialization type of the request data
  // eg: proto/json/.., default proto
  // The specific value corresponds to `TrpcContentEncodeType`
  uint32    content_type                = 9;

  // The compression type of the requested data
  // eg: gzip/snappy/..., not used by default
  // The specific value corresponds to `TrpcCompressType`
  uint32    content_encoding            = 10;

  // The size of attachment data
  uint32    attachment_size             = 12;
}