eArango/VelocyStream_zh.md

Client / Server Communication (VST 1.1)
=======================================

Version 1.1.0 of 23 November 2016

# HTTP
    使用VelocyPack作为身体。内容类型为"application/vpack"

Binary Protocol
---------------
    这不是请求/响应协议。它是对称的（原则上）。消息可以来回发送，流水线，多路复用，单向或双向。
    可能会生成一条消息
    没有反应
    只是一个回应
    多重回应
    
    该VelocyStream并没有强加或指定或要求上述行为之一。
    应用程序必须在一般情况下或根据每个请求定义行为，
    请参见下文。然后，服务器和客户端必须实现该行为。

### Message vs. Chunk
    使用者（客户端或服务器）将处理消息。一条消息包含一个或多个VelocyPack（在某些情况下是二进制数据的某些部分）。
    消息中有多少VelocyPacks完全取决于应用程序，请参阅下文了解ArangoDB。

    消息可能很大。由于可以通过一个连接对消息进行多路复用，因此需要将大消息拆分为多个块。
    发送者/接收者类将接受一个VelocyPacks向量，将其分割成块，通过导线发送这些块，组装这些块，
    生成一个VelocyPacks向量并将其传递给消费者。

### Chunks
    为了允许重组块，每个程序包都以一个 header 作为前缀。块始终至少为24个字节长。字节顺序始终是小端。
    块的格式如下，无论它是消息中的第一个消息还是随后的消息：

    名称	            类型	                描述
    length	        uint32_t	        当前块（包括此标头）的总长度（以字节为单位）
    chunkX	        uint32_t	        chunk / isFirstChunk（高31位/最低位），详细信息请参见下文
    messageId	    uint64_t	        唯一标识符，发送方有责任生成这样的标识符（zero is reserved for not set ID）
    messageLength	uint64_t	        the total size of the message.
    Binary data	    binary data blob	size b1 |

    声明："chunk" and "isFirstChunk" are combined into an unsigned 32bit value.
    Therefore it will be encoded as
    uint32_t chunkX and extracted as

    chunk = chunkX >> 1
    isFirstChunk = chunkX & 0x1
    
    对于消息的第一块，设置第二个uint32_t的低位，对于所有后续消息，将其复位。
    在消息的第一个块中，数字 chunk 是消息中的块总数，在所有后续块中，数字 chunk 是该块的当前number。

    数据包的总大小为（24 + b1）字节。此数字存储在length字段中。
    如果需要发送大于UINT32_MAX的消息，则必须将这些消息分块。通常，最好将最大大小限制为几兆字节。

### **Notes:**
    发送（小）消息时，（出于性能原因）确保仅发送一个TCP数据包非常重要。
    例如，通过在Linux下使用sendmmsg
    ([https://blog.cloudflare.com/how-to-receive-a-million-packets](https://blog.cloudflare.com/how-to-receive-a-million-packets/))
    但是，实现者应该意识到，在TCP / IP中不能强制执行此操作，因此实现者必须始终意识到，
    网络堆栈的某些部分可以拆分数据包，并且有效负载可能分成多个部分！

ArangoDB
========
### Request / Response
    对于ArangoDB客户端，请求的格式如下，该数组是VelocyPack数组：
    [
        /* 0 - version: */     1,                    // [int]
        /* 1 - type: */        1,                    // [int] 1=Req, 2=Res,..
        /* 2 - database: */    "test",               // [string]
        /* 3 - requestType: */ 1,                    // [int] 0=Delete, ...
        /* 4 - request: */     "/_api/collection",   // [string\]
        /* 5 - parameter: */   { force: true },      // [[string]->[string]]   http的请求参数列表
        /* 6 - meta: */        { x-arangodb: true }  // [[string]->[string]]   http的header
    ]
    Body (binary data)
    
    如果数据库未设置（entry is `null`），则数据库为“ _system”。

#### type：
    1 = Request
    2 = Response (final response for this message id)
    3 = Response (but at least one more response will follow)
    1000 = Authentication
#### requestType：
    0 = DELETE
    1 = GET
    2 = POST
    3 = PUT
    4 = HEAD (not used in VPP)
    5 = PATCH
    6 = OPTIONS (not used in VPP)
    
### For example:
    HTTP请求
        http://localhost:8529/_db/test/_admin/echo?a=1&b=2&c[]=1&c[]=3
    With header:：
        X-ArangoDB-Async: true
    is equivalent to
        [
          1,               // version
          1,               // type
          "test",          // database
          1,               // requestType GET
          "/_admin/echo",  // request path
          {                // parameters
            a: 1,
            b: 2,
            c: [ 1, 3 ]
          },
          {                // meta
            x-arangodb-async: true
          }
        ]
        
    该请求是一条以VelocyPack开头的消息。这个VelocyPack始终包含标题字段，参数和请求路径。
    如果meta字段不包含内容类型，则采用默认值 "application/vpack"，并且正文将是一个或多个VelocyPack对象。

#### The response will be
    [
      1,                // 0 - version
      2 or 3,           // 1 - type
      400,              // 2 - responseCode
      { etag: "1234" }  // 3 - meta: [[str]->[str]]
    ]

#### Body (binary data)
    请求可以通过管道传输或混合。使用标头中的“ messageId”映射响应。发送者有责任生成合适的“ messageId”值。

    默认内容类型为"application/vpack"。

### Authentication
    A connection can be authenticated with the following message:
    [
      1,              // version
      1000,           // type
      "plain",        // encryption
      "admin",        // user
      "plaintext",    // password
    ]
    or
    [
      1,              // version
      1000,           // type
      "jwt",          // encryption
      "abcd..."       // token
    ]
    The response is
    { "error": false }
    
    if successful or
    { 
      "error": true,
      "errorMessage": "MESSAGE",
      "errorCode": CODE
    }
    
    如果不成功，则在这种情况下服务器将关闭连接。可以使用/_open/auth与HTTP版本相同的语义，使用未经身份验证的开放式路由，以与HTTP相同的方式获取JWT令牌。这样，可以通过JWT在单个会话中完成完整的身份验证。

### Content-Type and Accept
    通常，内容类型将是VPP，即主体是存储为VelocyPack的对象。
    有时有必要使用非结构化数据（例如文本，css或html）进行响应。主体将是一个仅包含二进制属性的VelocyPack对象，并将相应地设置content-type。

规则如下。

#### Http
    Request: Content-Type
        "application/json"`: the body contains the JSON string representation
        `"application/vpack"`: the body contains a velocy pack

    有一些处理程序允许JSON列表（由换行符分隔）。在这种情况下，我们还允许不使用任何分隔符的多个速度包。

    Request: Accept
        "application/json"：如果可能，在正文中发送JSON字符串表示形式
        "application/vpack"：如果可能的话，在体内发送速度包

    如果请求是"application/json"或"application/vpack"处理程序产生了其他请求（即"application/html"），那么将忽略接受。
    
    如果请求被请求"application/json"并且处理程序产生 "application/vpack"，则VPACK将转换为JSON。
    
    如果请求被请求"application/vpack"，并且处理程序生成“ application / json”，则JSON将转换为VPACK。
    
#### VPP
    与HTTP相似，不同之处在于：不支持“ Accept”标头，并且"application/json"始终将其转换为“ application / vpack”。这意味着主体包含一个或多个速度包。通常，它将包含一个-值得注意的例外是导入。
    
    如果处理程序产生了其他东西（即"application/html"），则主体将是一个二进制blob（而不是一个velocy-pack），并且将相应地设置content-type。
    
    连接后发送的第一个字节（“客户端”端-即使程序是双向的，也有服务器在监听端口，而客户端在连接端口）

    VST/1.1\r\n\r\n
(11 Bytes)