# baidu_std
# Introduction
baidu_std is a binary RPC protocol based on TCP. It utilize protobuf as data transfer format. To achieve full use of RPC, it standarize data transfer protocol between two-side based on the RPC service built-in of protobuf.

baidu_std does not consider cases for cross-TCP connection.

# Basic Protocol

## Service
Every RPC serivce will be exposed by a single port.

Each port can have multiple services. Each service should have a name in UpperCamelCase no longer than 64 character.

Ech services can have one or more methods. There is no specific requirements for naming.

4-Tuple uniquely identify a RPC method.

The required parameter should be placed inside a Protobuf message. If there is returned result, it should also be placed in a Protobuf message. Noticed that an empty Protobuf can be used to specify empty request/response.

## Request/Response
Each request/response contains two part: Header and Body (see below).

There are two different typ of message: Request and Response. Both have the same header, however will have different metadata.

## Header
Header has a fixed size of 12byte. The first four byte is used as PRPC recognition. In the middle four is a 32bit int, specifing the length of body. The last four is a 32bit int, specify body's metadata length.

## Body
Body is consists of three part: **metadata**, **data** and **attachment**.

### Metadata
To describe request & response.

message RpcMeta {
    optional RpcRequestMeta request = 1;
    optional RpcResponseMeta response = 2;response
    optional int32 compress_type = 3;
    optional int64 correlation_id = 4;
    optional int32 attachment_size = 5;
    optional ChunkInfo chuck_info = 6;
    optional bytes authentication_data = 7;
};

| Param | Description |
| ------------------- | ---------------------------------------- |
| request / response |metadata |
| compress_type | [compress algorithm](#compress_algorithm) |
| correlation_id | Request need to set it to uniquely specify a RPC request. The developer should ensured the uniquess itself. Respond then should set the same correlation_id in the field |
| attachment_size | |
| chuck_info | |
| authentication_data | |

### Request Metedata

message RpcRequestMeta {
    required string service_name = 1; 
    required string method_name = 2;
    optional int64 log_id = 3; 
};

| Param | Description |
| ------------ | ---------------------------- |
| service_name |
| method_name |
| log_id | can be used to store BFE_LOGID。optional。 |

### Response Metadata

message RpcResponseMeta { 
    optional int32 error_code = 1; 
    optional string error_text = 2; 
};

| Param | Description |
| ---------- | ------------------------------------ |
| error_code | |
| error_text | |

### Extending the Metadata
Some usecases require customed Metadata. To prevent conflict and ensure compatibiltiy betwen different implementations, every implementation must apply for its own serial number for their customed Metadata.

Take **Hulu** for example，after given a serial number 100, Hulu can use the following definition:

message RpcMeta {
    optional RpcRequestMeta request = 1;
    optional RpcResponseMeta response = 2;
    optional int32 compress_type = 3;
    optional int64 correlation_id = 4;
    optional int32 attachment_size = 5;
    optional ChunkInfo chuck_info = 6;
    optional HuluMeta hulu_meta = 100;
};
message RpcRequestMeta {
    required string service_name = 1; 
    required string method_name = 2;
    optional int64 log_id = 3; 
    optional HuluRequestMeta hulu_request_meta = 100;
};
message RpcResponseMeta { 
    optional int32 error_code = 1; 
    optional string error_text = 2; 
    optional HuluResponseMeta hulu_response_meta = 100;
};

Hulu can decide whether to add the customed metadata or not.

Currently used:

| Number | |
| ---- | ---- |
| 100 | Hulu |
| 101 | Sofa |

## Data

Self-defined Protobuf Message. Can be used to store variable or return result data.

## Attachment

In some scenario such as document up/download or media convert, it requires transfering binary data through RPC. Packeting these data into protobuf will cause unnecessary in-memory copy, hence the protocol inplement direct-tranfer of binary data using attachment.

Attachment always locate in the last part of body after data part. One should set the `attachment_size` in RpcMeta to be the size of atachment.

## Compression Algorithm

| Value | Meaning |
| ---- | -------- |
| 0 | No compression |
| 1 | Snappy |
| 2 | gzip |

# HTTP

服务应以标准的HTTP协议对外发布接口。

数据交换格式默认应使用JSON。Content-Type使用application/json。有特殊需求的接口不受此限制。例如上传文件可以使用multipart/form-data；下载文件可以根据实际内容选用合适的Content-Type。

URL和JSON中的字符编码一律使用UTF-8。

建议使用RESTful形式的Web Service接口。由于RESTful并非一个严格的规范，本规范对此不做强制规定。