Architecture

Protocol

The RPC mechanism implements the JSONRPC protocol. You can refer to this section jsonrpc-protocol for more information.

Server

IPC

The current server implementation runs on an IPC Socket(Unix Domain Socket). This server implements an iterative server style. The implementation runs on a dedicated TSThread and as their style express, this performs blocking calls to all the registered handlers. Configuration for this particular server style can be found in the admin section Configuration.

Using the JSONRPC mechanism

As a user, currently, traffic_ctl exercises this new protocol, please refer to the traffic_ctl section.

As a developer, please refer to the Handler implementation for a more detailed guide.

JSON Parsing

Our JSONRPC protocol implementation uses lib yamlcpp for parsing incoming and outgoing requests, this allows the server to accept either JSON or YAML format messages which then will be parsed by the protocol implementation. This seems handy for user that want to feed Traffic Server with existing yaml configuration without the need to translate yaml into json.

Note

traffic_ctl have an option to read files from disc and push them into Traffic Server through the RPC server. Files should be a valid JSONRPC message. Please check traffic_ctl rpc for more details.

In order to programs communicate with Traffic Server , This one implements a simple RPC mechanism to expose all the registered API handlers.

You can check all current API by:

traffic_ctl rpc get-api

or by using the show_registered_handlers API method.

JSONRPC 2.0 Protocol

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

Overview

Note

Although most of the protocol specs are granted, we have implemented some exceptions. All the modifications will be properly documented.

There are a set of mandatory fields that must be included in a JSONRPC message as well as some optional fields, all this is documented here, you also can find this information in the JSONRPC link.

Requests

Please find the jsonrpc 2.0 request schema for reference ( mgmt2/rpc/schema/jsonrpc_request_schema.json ).

  • Mandatory fields.

    Field

    Type

    Description

    jsonrpc

    string

    Protocol version. Traffic Server follows the version 2.0 so this field should be only 2.0

    method

    string

    Method name that is intended to be invoked.

  • Optional parameters:

    • params:

      A Structured value that holds the parameter values to be used during the invocation of the method. This member may be omitted. If passed then a parameters for the rpc call must be provided as a Structured value. Either by-position through an Array or by-name through an Object.

      1. by-position array

        params must be an array, containing the values in the server expected order.

        {
   "params": [
      "apache", "traffic", "server"
   ]
}

        {
   "params": [
      1, 2, 3, 4
   ]
}

        {
   "params": [{
      "name": "Apache"
   },{
      "name": "Traffic"
   },{
      "name": "Server"
   }]
}

      2. by-name: object

        Params must be an object, with member names that match the server expected parameter names. The absence of expected names may result in an error being generated by the server. The names must match exactly, including case, to the method’s expected parameters.

        {
   "params": {
      "name": "Apache"
   }
}

    • id: string.

      An identifier established by the Client. If present, the request will be treated as a jsonrpc method and a response should be expected from the server. If it is not present, the server will treat the request as a notification and the client should not expect any response back from the server. Although a |number| can be specified here we will convert this internally to a |str|. The response will be a |str|.

Note

The JSONRPC 2.0 protocol supports batch requests so, multiple independent requests can be send to the server in a single json message. Batch request are basically an array of the above request, simply enclose them as an array [ .. ]. The response for batch requests will be also in a form of an array.

Responses

Although each individual API call will describe the response details and some specific errors, in this section we will describe a high level protocol response, some defined by the JSONRPC specs and some by Traffic Server

Please find the jsonrpc 2.0 response schema for reference( mgmt2/rpc/schema/jsonrpc_response_schema.json ).

The responses have the following structure:

Field

Type

Description

jsonrpc

string|number

A Number that indicates the error type that occurred.

result

Result of the invoked operation. See jsonrpc-result

id

string|number

It will be the same as the value of the id member in the jsonrpc-request . We will not be using null if the id could not be fetch from the request, in that case the field will not be set.

error

object

Error object, it will be present in case of an error. See jsonrpc-error

Example 1:

Request

{
   "jsonrpc": "2.0",
   "result": ["hello", 5],
   "id": "9"
}

Response

{
   "jsonrpc":"2.0",
   "error":{
      "code":5,
      "message":"Missing method field"
   },
   "id":"9"
}

As the protocol specifies Traffic Server have their own set of error, in the example above it’s clear that the incoming request is missing the method name, which Traffic Server sends a clear response error back.

Result

  • This member is required and will be present on success.

  • This member will not exist if there was an error invoking the method.

  • The value of this member is determined by the method invoked on the Server.

In Traffic Server a RPC method that does not report any error and have nothing to send back to the client will use the following format to express that the call was successfully handled and the command was executed.

Example:

{
   "id": "89fc5aea-0740-11eb-82c0-001fc69cc946",
   "jsonrpc": "2.0",
   "result": "success"
}

"result": "success" will be set.

Errors

The specs define the error fields that the client must expect to be sent back from the Server in case of any error.

Field

Type

Description

code

number

A Number that indicates the error type that occurred.

message

string

A String providing a short description of the error.

data

object

This is an optional field that contains additional error data. Depending on the API this could contain data.

# data.

This can be used for nested error so Traffic Server can inform a detailed error.

Field

Type

Description

code

string

The error code. Integer type.

message

string

The explanatory string for this error.

Examples:

# Fetch a config record response from Traffic Server

Request:

{
   "id":"0f0780a5-0758-4f51-a177-752facc7c0eb",
   "jsonrpc":"2.0",
   "method":"admin_lookup_records",
   "params":[
      {
         "record_name":"proxy.config.diags.debug.tags",
         "rec_types":[
            "1",
            "16"
         ]
      }
   ]
}

Response:

{
   "jsonrpc":"2.0",
   "result":{
      "recordList":[
         {
            "record":{
               "record_name":"proxy.config.diags.debug.tags",
               "record_type":"3",
               "version":"0",
               "raw_stat_block":"0",
               "order":"423",
               "config_meta":{
                  "access_type":"0",
                  "update_status":"0",
                  "update_type":"1",
                  "checktype":"0",
                  "source":"3",
                  "check_expr":"null"
               },
               "record_class":"1",
               "overridable":"false",
               "data_type":"STRING",
               "current_value":"rpc",
               "default_value":"http|dns"
            }
         }
      ]
   },
   "id":"0f0780a5-0758-4f51-a177-752facc7c0eb"
}

# Getting errors from Traffic Server

Request an invalid record (invalid name)

{
   "id":"f212932f-b260-4f01-9648-8332200524cc",
   "jsonrpc":"2.0",
   "method":"admin_lookup_records",
   "params":[
      {
         "record_name":"invalid.record",
         "rec_types":[
            "1",
            "16"
         ]
      }
   ]
}

Response:

{
   "jsonrpc":"2.0",
   "result":{
      "errorList":[
         {
            "code":"2000",
            "record_name":"invalid.record"
         }
      ]
   },
   "id":"f212932f-b260-4f01-9648-8332200524cc"
}

Parse Error from an incomplete request

{[[ invalid json

{
   "jsonrpc":"2.0",
   "error":{
      "code":-32700,
      "message":"Parse error"
   }
}

Invalid method invocation.

Request:

{
   "id":"f212932f-b260-4f01-9648-8332200524cc",
   "jsonrpc":"2.0",
   "method":"some_non_existing_method",
   "params":{

   }
}

Response:

Internally we have defined an enum class that keeps track of the errors that the server will inform in most of the cases. Some of this errors are already defined by the JSONRPC specs and some (>=1) are defined by Traffic Server.

class RPCErrorCode

Defines the API error codes that will be used in case of any RPC error.

enumerator INVALID_REQUEST = -32600
enumerator METHOD_NOT_FOUND = -32601
enumerator INVALID_PARAMS = -32602
enumerator INTERNAL_ERROR = -32603
enumerator PARSE_ERROR = -32700

JSONRPC defined errors.

enumerator InvalidVersion = 1

The passed version is invalid. must be 2.0

enumerator InvalidVersionType = 2

The passed version field type is invalid. must be a string

enumerator MissingVersion = 3

Version field is missing from the request. This field is mandatory.

enumerator InvalidMethodType = 4

The passed method field type is invalid. must be a string

enumerator MissingMethod = 5

Method field is missing from the request. This field is mandatory.

enumerator InvalidParamType = 6

The passed parameter field type is not valid.

enumerator InvalidIdType = 7

The passed id field type is invalid.

enumerator NullId = 8

The passed if is null

enumerator ExecutionError = 9

An error occurred during the execution of the RPC call. This error is used as a generic High level error. The details details about the error, in most cases are specified in the data field.

Development Guide