Packets

Overview

The Node Module handles data encapsulated within data units called Packets. Packets can be grouped within the following categories based on their use-case;

• Settlement Packets are used by the Transport Manager to "settle" Transports. Settlement, allows the two nodes that are the edges of the transport to decide on the Transport ID to be used, and whether the Transport is to be public. Only after a Transport is settled, can the Router have access to the Transport.

  Settlement Packets contain json encoded payload.

• Foundational Packets are used by a Router to communicate with a remote Setup Node and is used for setting up, establishing and destroying routes.

  Foundational Packets are prefixed by 3 bytes: the packet size (2 bytes) and a Type (1 byte) that contains the foundational packet type.

• Data Packets are Packets that are actually used to encapsulate data delivered between two Apps.

  Data Packets are prefixed by 6 bytes; including the packet size (2 bytes) and the Route ID (4 bytes) which can have any value other than 0x00 or 0x01.

Settlement Packets

After a Transport is established between two nodes, the nodes needs to decide on the Transport ID that describes the Transport and whether the Transport is to be public or private (public Transports are to be registered in the Transport Discovery). This process is called the Settlement Handshake.

The Packets of this handshake contain json encoded messages.

Settlement Handshake packets do not need a field for Packet-type are they are expected in a specific order.

• Request to settle transport is sent by the Transport Initiator to the Transport Responder after a Transport connection is established.

  JSON Body: Contains a transport.SignedEntry structure with the Transport Initiator's signature.

• Transport Responder should validate submitted transport.SignedEntry, and if entry is valid it should add sign it and perform transport registration in transport discovery. If registration was successful responder should send updated transport.SignedEntry back to initiator.

  JSON Body: Contains a transport.SignedEntry structure with signatures from both the Transport Initiator and the Transport Responder. If the transport is registered in Transport Discovery, the SignedTransport.Registered should contain the epoch time of registration.

If transport will fail at any step participants can chose to stop handshake procedures and close corresponding transport. Transport disconnect during the handshake should be handled appropriately by participants. Optional handshake timeout should also be supported.

Foundational Packets

Foundational packets are used for the communication between App Nodes and Setup Nodes.

The Setup Node is responsible for fulfilling Route initiating and destroying requests by communicating with the initiating, responding and intermediate nodes of the proposed route.

The following is the expected format of a Foundational Packet;

| Packet Len | Type   | JSON Body |
| 2 bytes    | 1 byte | ~         |

• Packet Len specifies the total packet length in bytes (exclusive of the Packet Len field).
• Type specifies the Foundational Packet Type.
• JSON Body is the packet body (in JSON format) that is unique depending on the packet type.

Foundational Packet Types Summary:

Type	Name
0x00	AddRules
0x01	RemoveRules
0x02	CreateLoop
0x03	ConfirmLoop
0x04	CloseLoop
0x05	LoopClosed
0xfe	ResponseFailure
0xff	ResponseSuccess

Data Packets

The follow is the structure of a Data Packet.

| Packet Len | Route ID | Payload |
| 2 bytes    | 4 bytes  | ~       |

ACK packets

Since messaging and loop communication are dependent on intermediate servers we provide acknowledgment mechanism between edge nodes. This is be done via wrapper io.ReadWriter (AckReadWriter) that augments existing communication channels with ack packets. Write calls on AckReadWrite block until corresponding ack packet is received.

ack logic works in tcp-like way: all pending ack packets are sent with subsequent write on the opposite edge. If no write has happened within a certain interval then all pending ack packets are flushed. Outstanding ack packets are also be flushed on Close call.

AckReadWriter Is able to send and receive 2 types of packets: payload(0x0) and ack (0x1):

Format of a payload packet:

| Packet Type | Packet ID | Payload |
| 0x0         | 1 byte    | ~       |

Format of an ack packet:

| Packet Type | Packet ID | SHA256   |
| 0x1         | 1 byte    | 32 bytes |

AckReadWriter Is able to prepend any amount of ack packets to a payload packet. Sequences without payload packet are valid. Example packet sequence:

| 0x1 | 0x0 | hash | 0x1 | 0x1 | hash | 0x0 | 0x2 | payload |

This packet sequence will acknowledge received packets with ids 0 and 1 and will send packet with id 2.

Upon reading ack packets receiver should validate received hash for each packet.