This document defines a method to serialise packets in a form that represents the packets in the built in OC network system. This does not define more than a way to serialise packets that OC uses, and details such as handling and routing are up to the implementer. In particular it is worth noting that packets that make no sense may be encoded in this format, and the handling of which is up to the user of this format.
Note that this document is written in British English, so some words, notability "serialise" may be spelled differently than US English.
Note that is is only a description of the existing system that this format tries to represent. It does not define anything new.
There are only three guaranteed values in an OC modem packet, the source address, the destination address, and the port. It is worth noting that under normal circumstances, the source address cannot be changed from the address of the "modem" that sent the message.
As a special case of the OC modem packet, there is the "tunnel". When sending, there is no port value, and when receiving, the port is reported as 0 on the receiving end. In this format, the port in this case will be represented as a null value.
After the guaranteed values, there are the optional values. By default there is a limit on the number of optional values that can be sent, as well as a total size limit (which also includes "overhead").
There can be a variable number of optional values. They can be arrays of bytes (strings), numbers, booleans, and nil.
It is worth noting, that unlike normal use in Lua, nils are preserved and transmitted. Most of the time, this will not matter, but is important to consider.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
- An "implementation" is an implementation of this standard, most likely a library, that uses a MessagePack implementation / library to convert it to a more native / accessible data format. Given rules to follow to ensure that the packets will be converted consistently.
- A "user" is the user of an implementation, such as a program. Given advice that will help with using this format.
The serialised form of packets is in "MessagePack" format. This is a binary format, and is described at https://github.com/msgpack/msgpack/blob/master/spec.md (last edited 2017-12-22, accessed 2017-05-12).
In this document, MessagePack data will be represented in the JSON format, as defined in RFC4627.
The packet can be represented as a MessagePack Object. The purpose of each member of the object MUST determined by its name. Every value is optional in this specification, but users of this format MAY decide to add their own requirements.
For illustrative purposes, JSON is used in this document to explain the layout, but care should be taken that some strings are actually byte-arrays (MsgPack "bin"), rather than strings, specified later on. Also take care to note that MessagePack stores numbers differently to JSON. JSON is only used for terminology and illustrative examples!
| Name | Type for member/value |
|---|---|
src |
String |
dst |
String |
prt |
Unsigned Integer (Number) |
len |
Unsigned Integer (Number) |
dat |
Any except object |
The rules for dat are more complicated. It SHALL be any JSON type other than an Object. If it is an Array, it represents multiple values, each of which can be any JSON type other than an Object or an Array. If it is not an Array or a Null, it MUST be treated the same as if it was a single element array with only that value. If the value is null, it MUST NOT be considered the same as a single element array containing it. Note that any Lua strings in or as dat MUST be encoded as raw data / byte array / MsgPack "bin".
Similarly, note that src and dst SHOULD be encoded as strings / MsgPack "str" (UTF-8 encoded string).
Both prt and len SHOULD be encoded as MsgPack unsigned integers!
Any value MAY be null, which MUST be treated the same as if the member/value did not exist unless it is in the dat Array.
Implementations MAY NOT treat null and no value differently, however they SHOULD preserve the difference between null and nothing.
For null in Arrays, positions MUST be preserved if a null is between elements in an Array. For example the JSON/MessagePack Array ["a", null, "b"] MUST be converted to this Lua table {[1]="a", [3]="b"}, preserving the fact that there was a null in between.
There is no way to represent null at the end of an array in Lua, so ["z", null] MAY be converted to {[1] = "z"}. However, trailing nulls SHOULD be preserved if at all possible.
It is also highly RECOMMENDED to store the length of the array in the len value/member (in practice, this will probably be needed most of the time with trailing nulls, unless both sides can handle them).
The len value MUST be equal to or greater than the actual length of the array if the value for len exists (or is not null). If the len value is greater than the length of the dat array stored, then there MUST be an indication that there would have been nulls to the user, either padding the list with nulls if supported or returning the length value. If there is no dat (or the value for dat is only null), then the list SHALL be a list made of the number of nulls indicated in the value for len.
{
"src": "c5e8ccb1-d367-4bc4-a351-d6b23e2e38d6",
"dst": "c33fc614-219c-4832-bd8e-e292a49b7dc0",
"prt": 42,
"len": 7,
"dat": ["example", null, "packet", 6, 7, null]
}{
"src": "c5e8ccb1-d367-4bc4-a351-d6b23e2e38d6",
"dst": "c33fc614-219c-4832-bd8e-e292a49b7dc0",
"prt": 42,
"dat": ["example", "packet", 2]
}{
}Due to the flexible format of MessagePack, it is possible to extend the packet to include more data. Implementations MUST accept packets with extensions that do not break any of the earlier rules, but users of those implementations MAY do whatever they want. Users SHOULD negotiate (outside the scope of this) for what extensions are used.
- Skye M. - Original author of this document.