mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 21:45:37 +00:00
Delete cc-protocol.txt
This commit is contained in:
Vicky Risk
@@ -1,185 +0,0 @@
|
||||
The CC protocol
|
||||
===============
|
||||
|
||||
We use our home-grown protocol for IPC between modules. There's a
|
||||
central daemon routing the messages.
|
||||
|
||||
Addressing
|
||||
----------
|
||||
|
||||
Each connected client gets an unique address, called ``l-name''. A
|
||||
message can be sent directly to such l-name, if it is known to the
|
||||
sender.
|
||||
|
||||
A client may subscribe to a group of communication. A message can be
|
||||
broadcasted to a whole group instead of a single client. There's also
|
||||
an instance parameter to addressing, but we didn't find any actual use
|
||||
for it and it is not used for anything. It is left in the default `*`
|
||||
for most of our code and should be done so in any new code. It wasn't
|
||||
priority to remove it yet.
|
||||
|
||||
Wire format
|
||||
-----------
|
||||
|
||||
Each message on the wire looks like this:
|
||||
|
||||
<message length><header length><header><body>
|
||||
|
||||
The message length is 4-byte unsigned integer in network byte order,
|
||||
specifying the number of bytes of the rest of the message (eg. header
|
||||
length, header and body put together).
|
||||
|
||||
The header length is 2-byte unsigned integer in network byte order,
|
||||
specifying the length of the header.
|
||||
|
||||
The header is a string representation of single JSON object. It
|
||||
specifies the type of message and routing information.
|
||||
|
||||
The body is the payload of the message. It takes the whole rest of
|
||||
size of the message (so its length is message length - 2 - header
|
||||
length). The content is not examined by the routing daemon, but the
|
||||
clients expect it to be valid JSON object.
|
||||
|
||||
The body may be empty in case the message is not to be routed to
|
||||
client, but it is instruction for the routing daemon. See message
|
||||
types below.
|
||||
|
||||
The message is sent in this format to the routing daemon, the daemon
|
||||
optionally modifies the headers and delivers it in the same format to
|
||||
the recipient(s).
|
||||
|
||||
The headers
|
||||
-----------
|
||||
|
||||
The header object can contain following information:
|
||||
|
||||
|====================================================================================================
|
||||
|Name |type |Description
|
||||
|====================================================================================================
|
||||
|from |string|Sender's l-name
|
||||
|type |string|Type of the message. The routed message is "send".
|
||||
|group |string|The group to deliver to.
|
||||
|instance |string|Instance in the group. Purpose lost in history. Defaults to "*".
|
||||
|to |string|Override recipient (group/instance ignored).
|
||||
|seq |int |Tracking number of the message.
|
||||
|reply |int |If present, contains a seq number of message this is a reply to.
|
||||
|want_answer|bool |If present and true, the daemon generates error if there's no matching recipient.
|
||||
|====================================================================================================
|
||||
|
||||
Types of messages
|
||||
-----------------
|
||||
|
||||
Get Local Name (type "getlname")
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Upon connection, this is the first message to be sent to the daemon.
|
||||
It will return the local name of this client. Each connection gets
|
||||
its own unique local name, and local names are never repeated. They
|
||||
should be considered opaque strings, in a format useful only to the
|
||||
message routing system. They are used in replies or to send to a
|
||||
specific destination.
|
||||
|
||||
To request the local name, the only element included is the
|
||||
{"type": "getlname"}
|
||||
tuple. The response is also a simple, single tuple:
|
||||
{"lname" => "Opaque utf-8 string"}
|
||||
|
||||
Until this message is sent, no other types of messages may be sent on
|
||||
this connection.
|
||||
|
||||
Regular Group Messages (type "send")
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Message routed to other client. This one expects the body to be
|
||||
non-empty.
|
||||
|
||||
Expected headers are:
|
||||
|
||||
* from
|
||||
* group
|
||||
* instance (set to "*" if no specific instance desired)
|
||||
* seq (should be unique for the sender)
|
||||
* to (set to "*" if not directed to specific client)
|
||||
* reply (optional, only if it is reply)
|
||||
* want_answer (optional, only when not a reply)
|
||||
|
||||
A client does not see its own transmissions.
|
||||
|
||||
Group Subscriptions (type "subscribe")
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Indicates the sender wants to be included in the given group.
|
||||
|
||||
Expected headers are:
|
||||
|
||||
* group
|
||||
* instance (leave at "*" for default)
|
||||
|
||||
There is no response to this message and the client is subscribed to
|
||||
the given group and instance.
|
||||
|
||||
The group can be any utf-8 string and the group doesn't have to exist
|
||||
before (it is created when at least one client is in it). A client may
|
||||
be subscribed in multiple groups.
|
||||
|
||||
Group Unsubscribe (type "unsubscribe")
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The headers to be included are "group" and "instance" and have the same
|
||||
meaning as a "subscribe" message. Only, the client is removed from the
|
||||
group.
|
||||
|
||||
Transmitted messages
|
||||
--------------------
|
||||
|
||||
These are the messages generally transmitted in the body of the
|
||||
message.
|
||||
|
||||
Command
|
||||
~~~~~~~
|
||||
|
||||
It is a command from one process to another, to do something or send
|
||||
some information. It is identified by a name and can optionally have
|
||||
parameters. It'd look like this:
|
||||
|
||||
{"command": ["name", <parameters>]}
|
||||
|
||||
The parameters may be omitted (then the array is 1 element long). If
|
||||
present, it may be any JSON element. However, the most usual is an
|
||||
object with named parameter values.
|
||||
|
||||
It is usually transmitted with the `want_answer` header turned on to
|
||||
cope with the situation the remote end doesn't exist, and sent to a
|
||||
group (eg. `to` with value of `*`).
|
||||
|
||||
Success reply
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When the command is successful, the other side answers by a reply of
|
||||
the following format:
|
||||
|
||||
{"result": [0, <result>]}
|
||||
|
||||
The result is the return value of the command. It may be any JSON
|
||||
element and it may be omitted (for the case of ``void'' function).
|
||||
|
||||
This is transmitted with the `reply` header set to the `seq` number of
|
||||
the original command. It is sent with the `to` header set.
|
||||
|
||||
Error reply
|
||||
~~~~~~~~~~~
|
||||
|
||||
In case something goes wrong, an error reply is sent. This is similar
|
||||
as throwing an exception from local function. The format is similar:
|
||||
|
||||
{"result": [ecode, "Error description"]}
|
||||
|
||||
The `ecode` is non-zero error code. Most of the current code uses `1`
|
||||
for all errors. The string after that is mandatory and must contain a
|
||||
human-readable description of the error.
|
||||
|
||||
The negative error codes are reserved for errors from the daemon.
|
||||
Currently, only `-1` is used and it is generated when a message with
|
||||
`reply` not included is sent, it has the `want_answer` header set to
|
||||
`true` and there's no recipient to deliver the message to. This
|
||||
usually means a command was sent to a non-existent recipient.
|
||||
Reference in New Issue
Block a user