Binary Frame Specification (Protocol v2)
AfterLink v2.0.2 operates on Protocol v2. Every packet consists of a rigid 16-byte fixed header, followed by an optional variable-length UTF-8 routing key (0–255 bytes) and a MessagePack-encoded payload body.
Header Byte Layout Mapping
Below is the logical arrangement of AfterLink Protocol v2's 16-byte fixed header and payload layout on the TCP network wire:
Protocol v2 Frame Layout (16-Byte Fixed Header + Optional Routing Key + Payload)
2B (0xAF1C)
1B (0x02)
1B
1B (0-7)
1B
2B (u16)
1B (0-255)
3B
4B (u32)
0–255 Bytes (UTF-8)
Variable size (MessagePack bytes)
Field Definitions
| Field | Size | Wire Type | Offset (Bytes) | Description |
|---|---|---|---|---|
| magic | 2 bytes | UInt8[2] | 0 – 1 | Protocol identifier: fixed 0xAF 0x1C. Restricts incoming socket streams. |
| version | 1 byte | UInt8 | 2 | Protocol version encoder flag (0x02 in v2; supports v1/v2 negotiation). |
| type | 1 byte | UInt8 | 3 | Message type byte determining how the frame is routed. |
| priority | 1 byte | UInt8 | 4 | Priority queue level (0 = lowest/default, 7 = highest urgent priority). |
| flags | 1 byte | UInt8 | 5 | Control flags byte (compression, encryption, custom frame options). |
| seq | 2 bytes | UInt16BE | 6 – 7 | Sequence index for reliable RPC matching. Wraps at 65535. |
| route_len | 1 byte | UInt8 | 8 | Length of custom string routing key in bytes (0 to 255). |
| reserved | 3 bytes | UInt8[3] | 9 – 11 | Reserved padding bytes for 16-byte fixed header alignment and future extensions. |
| length | 4 bytes | UInt32BE | 12 – 15 | Big-endian size count of payload data in bytes (max ~4.29 GB). |
| routing_key | 0–255 bytes | String | 16 .. (16 + route_len) | Optional UTF-8 custom string routing key for topic matching and RPC endpoints. |
| payload | variable | Buffer | (16 + route_len)+ | MessagePack-encoded message body containing payload values. |
Message Types
The Message Type flag byte defines the routing channel behavior of the server:
| Hex Value | Constant | Direction | Purpose & Description |
|---|---|---|---|
| 0x01 | MSG_REQUEST | Client → Server | RPC request — expects a responsive matching reply frame. |
| 0x02 | MSG_RESPONSE | Server → Client | RPC response payload frame matched by sequence number. |
| 0x03 | MSG_PUBLISH | Client → Server | Broadcast a message frame to a Pub/Sub channel. |
| 0x04 | MSG_SUBSCRIBE | Client → Server | Subscribe to Pub/Sub channel notifications. |
| 0x05 | MSG_BROADCAST | Server → Client | Fan-out pub/sub message forwarded to active subscribers. |
| 0x06 | MSG_STREAM | Server → Client | Streaming data chunks (multi-frame chunk payloads). |
| 0x07 | MSG_STREAM_END | Server → Client | End of stream signal payload packet. |
| 0x08 | MSG_ERROR | Both | Error flag indicating payload parsing or connection errors. |
| 0x09 | ROUTE_REQUEST | Client → Server | Dynamic topic & string routing key registration/lookup request (Protocol v2). |
| 0x0A | PRIORITY_ACK | Both | Priority-aware sequence acknowledgement frame (Protocol v2). |
| 0xFE | MSG_ACK | Both | Acknowledge code payload packet matched by sequence number. |
| 0xFF | MSG_PING | Both | Keepalive heartbeat ping to check connection availability. |
Version Negotiation (v1 / v2)
Protocol v2 introduces bidirectional version negotiation during the initial connection handshake. When an AfterLink v2 client connects, it advertises support for version 0x02. If the target server is a legacy v1 endpoint, the client seamlessly falls back to the 10-byte header format.
Priority Queues (Levels 0–7)
Every Protocol v2 frame includes a 1-byte priority field supporting 8 queue levels (0 to 7):
- 0–2 (Low / Bulk): Background sync, bulk streaming, and non-critical metrics.
- 3–5 (Normal): Default priority level for standard RPC requests and Pub/Sub broadcasts.
- 6–7 (Urgent / Control): High-priority control frames (such as
PRIORITY_ACKand heartbeats) that jump execution queues ahead of lower-priority messages.
Custom String Routing Keys (0–255 Bytes)
Protocol v2 allows embedding an inline UTF-8 string routing key directly in the frame header (controlled by route_len). This enables zero-deserialization routing: servers inspect the header's routing key to route frames instantly without decoding the MessagePack payload.
Low-Level Codec Code Example
Using the @ajaymyth/core library, developers can encode and decode raw Protocol v2 frames directly on top of socket streams: