Jaeger TChannel——HTTP和JSON封裝

TChannel 與 HTTP 的錯誤碼對映

穩定性：不穩定

當傳送請求和響應請求時 TChannel 能夠返回不同型別的錯誤

TChannel Client Errors

作為 http 狀態機整合的一部分，tchannel 錯誤需要對映到 http 合適的錯誤碼，以方便 http 客戶端能夠區分不同型別的錯誤並作出合適的後續動作。

tchannel 錯誤碼在Jaeger TChannel ——protocol一文中已經陳述過了

http 的狀態返回碼: http status code

下面是 tchannel 與 http 的狀態錯誤碼對映關係表：

code	name	http status code
0x01	timeout	504 Gateway Timeout
0x02	cancelled	500 TChannel Cancelled
0x03	busy	429 Too Many Requests
0x04	declined	503 Service Unavailable
0x05	upexpected error	500 Internal Server Error
0x06	bad request	400 Bad Request
0x07	network error	500 TChannel Network Error
0x08	unhealthy	503
0xFF	fatal protocol error	500 TChannel Protocol Error

HTTP over TChannel

這篇文章闡述了我們怎麼樣把 HTTP 編碼進 TChannel。

對於 HTTP 請求呼叫，這個 Transport Headers 中存在 key：as， 值必須設定為http。請求時訊息型別為"call req"和響應時訊息型別為"call res"，它們帶有arg1、arg2和arg3，定義如下：

Arguments

1. arg1 是一個任意 circuit 字串，可以留空；
2. arg2 是一個編碼後的 request/response 後設資料，詳見下文；
3. arg3 是來自 http 請求/響應的原始位元組流

arg2：request meta data

Binary schema:

method~1
url~N
numHeaders: 2(headerName~2 headerValue~2){numHeaders}

例如：
method: GET
url: /v1/accounts/:account_id
numHeaders:{secret: xxxx2j02}

注意：

1. 這個 url 欄位長度是變長的。則只能根據arg2的總長度，間接計算url的變長大小

arg2：response meta data

Binary schema

statusCode:2
message~N
numHeaders:2(headerName~2 headerValue~2){numHeaders}

例如：
statusCode: 200
message: {err_code: 0, err_msg: ""}
numHeaders: {status: "00"}

注意：

1. statusCode 是 HTTP 的狀態響應碼；
2. 訊息是 utf-8 編碼；
3. 訊息長度也是一個變長；
4. headers 可以使用 multi-map 或者列表鍵值對實現這個在Appdash的RawSpan中見過；單值是不夠的

JSON over TChannel

這篇文件闡述了我們怎麼樣把 JSON 編碼進 TChannel 中

對於 JSON 的請求呼叫，則 Transport Headers 一定有 key: as，值為json的鍵值對。對於 Request 訊息型別為"call req"，和 Response 訊息型別為"call res", 都會帶有arg1，arg2和arg3，這三個引數的定義如下：

對於每個"call req"訊息，這個服務名應該設定為被呼叫的 TChannel 服務

對於每個"call res"訊息，如果這個響應是成功的，這個響應碼必須設定為0；如果這個響應是失敗的，則這個響應碼必須設定為1。

Arguments

對於"call req"和"call res"：

1. arg1一定是方法名；
2. arg2一定是 JSON 編碼的 application headers
3. arg3一定是 application response

arg1

這個方法一定是 UTF-8 編碼。建議您使用字母數字字元和_。

arg3

arg3必須是 JSON 序列化編碼

對於 “call req” 訊息，這只是一個任意的 JSON 有效載荷

對於"call req"訊息：

1. 在成功的情況下，響應是任意 JSON 負載資料；
2. 在失敗的情況下，響應時 JSON 錯誤資訊。errors 中有個message欄位，以及一個type欄位 (告知錯誤型別)

TChannel Service

客戶端庫應該註冊一個預設服務，這個服務提供有關客戶端庫和內部狀態的後設資料資訊。此預設服務應該在"tchannel"下注冊，可在不知道託管 endpoint 應用程式的服務名稱情況下使用該服務

這個 Thrift scheme 詳見meta.thrift

多語言支援

TChannel

TChannel 是一個支援多路複用和幀協議的 RPC 服務框架

這個協議當前已經支援的語言，如下所示

1. Go

   1). Guide

   2). API Documentation

2. Node

   1). Guide

   2). API Documentation

3. Python

   1). Guide

   2). API Documentation