README
¶
Diffeo CBOR-RPC wire format
The Diffeo Coordinate daemon uses a custom wire protocol based on the CBOR data encoding. CBOR's data model is very similar to JSON's, but with a couple of extensions, including separate "text" and "byte string" types and tag annotations.
In all cases the Python Coordinate client code sends and receives strings as UTF-8-encoded byte strings except as noted. (This may be an artifact of running it on Python 2, where the default string type is ASCII-encoded byte string.) It will accept Unicode strings over the wire but will always send back byte strings.
Request and response messages in all cases are CBOR-encoded, and the result sent as a CBOR-in-CBOR byte string with tag 24. The system uses the following tags:
- 24 (standard): tags a byte string as holding encoded CBOR
- 37 (standard): tags a length-16 byte string as holding a UUID
- 128 (non-standard): tags a list as holding a Python sequence
The client and server communicate over a persistent connection. Requests include a correlation ID. The client may "pipeline" requests by sending further requests before receiving responses. Only the client expects to close a connection in the Python code, and it typically will only do so after all outstanding requests have gotten responses.
Requests are mappings where the keys are ASCII byte strings. These have keys:
id: correlation ID, typically sequential per connectionmethod: ASCII byte string, name of RPC method to invokeparams: list of anything, parameters to the method
Responses are also mappings where the keys are ASCII byte strings. These have keys:
id: correlation ID, matches the ID of the requestresponse: on success, any object, response to the methoderror: on failure, a mapping with a single keymessageholding the error message
Examples
Consider the RPC call list_work_specs({}). This would be encoded as:
{
"id": 1,
"method": "list_work_specs",
"params": [{}]
}
and sent over the wire as:
D8 18 Tag 24, CBOR-encoded string follows
58 25 Byte string of length 37
A3 Map of three pairs
42 69 64 Byte string "id"
01 Positive integer 1
46 6D 65 74 68 6F 64 Byte string "method"
4F 6C 69 73 74 5F 77 6F 72 6B 5F 73 70 65 63 73
Byte string "list_work_specs"
46 70 61 72 61 6D 73 Byte string "params"
81 Array of length 1
A0 Map of 0 pairs
Documentation
¶
Overview ¶
Package cborrpc defines the CBOR-RPC format used by the Python Coordinate daemon.
Index ¶
- func CreateParamList(funcv reflect.Value, params []interface{}) ([]reflect.Value, error)
- func DecodeBytesAsString(from, to reflect.Type, data interface{}) (interface{}, error)
- func Destringify(obj interface{}) (string, bool)
- func Detuplify(obj interface{}) ([]interface{}, bool)
- func SetExts(cbor *codec.CborHandle) error
- func SloppyDetuplify(obj interface{}) []interface{}
- type PythonTuple
- type Request
- type Response
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateParamList ¶
CreateParamList tries to match a CBOR-RPC parameter list to a specific callable's parameter list. funcv is the reflected method to eventually call, and params is the list of parameters from the CBOR-RPC request. On success, the return value is a list of parameter values that can be passed to funcv.Call().
func DecodeBytesAsString ¶
DecodeBytesAsString is a mapstructure decode hook that accepts a byte slice where a string is expected.
func Destringify ¶
Destringify tries to turn any object into a string. If it is a string or byte slice, returns the string and true; otherwise returns empty string and false.
func Detuplify ¶
func Detuplify(obj interface{}) ([]interface{}, bool)
Detuplify removes a tuple wrapper. If obj is a tuple, returns the contained slice. If obj is a slice, returns it. Otherwise returns failure.
func SetExts ¶
func SetExts(cbor *codec.CborHandle) error
SetExts sets up the CBOR codec to understand the other objects in this package.
func SloppyDetuplify ¶
func SloppyDetuplify(obj interface{}) []interface{}
SloppyDetuplify turns any object into a slice. If it is already a PythonTuple or a slice, returns the slice as Detuplify; otherwise packages up obj into a new slice. This never fails.
Types ¶
type PythonTuple ¶
type PythonTuple struct {
Items []interface{}
}
PythonTuple is a simple Go wrapper representing a Python tuple. This is a fixed-length, ordered, immutable sequence of arbitrary items.
type Request ¶
type Request struct {
// Name of the RPC method to invoke.
Method string
// Sequential, non-unique identifier for this request.
ID uint
// List of arbitrary parameters.
Params []interface{}
}
Request defines the fields of a CBOR-RPC request.
type Response ¶
type Response struct {
// Sequential, non-unique identifier for this response. This should
// always match the identifier from the corresponding Request.
ID uint
// Arbitrary response object; should be nil on error.
Result interface{}
// Error message on failure; should be empty on success.
Error string
}
Response defines the fields of a CBOR-RPC response
Source Files