PSRT protocol specifications
Contents
Common
Default IANA-standardized port: 2873
All numbers are processed as little-endian.
PROTOCOL VERSION: 1
LEN = data length (4 bytes = u32)
Response codes:
0x00 - NOP (pings, should be sent every N < timeout seconds to make sure the socket is alive)
0x01 - OK
0x02 - OK_WAITING (waiting for data, used in replication only)
0xE0 - NOT_REQUIRED (used in replication only)
0xFE - ERR_ACCESS (pub/sub access denied)
0xFF - ERROR (all other errors)
Data sockets usually use the same port as control ones.
Priority byte is not used at the moment (reserved for future) and should be always 0x7F.
Control socket
Greetings
Client: EE AA <00 / 01 for STARTTLS>
Server: sets mode or disconnects
Server (4 byte): EE AA 01 00 (01 00 - protocol version)
Client: LEN LOGIN 00 PASSWORD (for anonymous login send = 01 00 00 00 00)
Server: 32 bytes (client token) or closes the socket
### Keep-alive pings
The client MUST ping the server by sending OP_NOP with frequency higher than the server timeout, otherwise the socket is automatically closed by the server.
Any other control frame can be used as keep-alive signal as well. So if the client sends many control frames, ping frames can be delayed or omitted.
Subscribe
OP_SUBCRIBE = 0x02
Client:
0x02 LEN TOPIC (or multiple topics split with 0x00)
Server:
OK/ERROR
Unsubscribe
OP_UNSUBCRIBE = 0x03
Client:
0x03 LEN TOPIC (or multiple topics split with 0x00)
Server:
OK/ERROR
Publish
OP_PUBLISH = 0x01
Client:
0x01 PRI(u8=7F) LEN TOPIC x0 MESSAGE
Server:
OK/ERROR
Publish if subscribed (replicate)
OP_PUBLISH_REPL = 0x11
Client:
0x11 LEN TOPIC
Server:
OK_WAIT/ERROR/NOT_REQIRED
Client (if required)
PRIO(u8=7F) TIMESTAMP(u64, nanoseconds) LEN MESSAGE
Bye
OP_BYE = 0xFF
Client:
0xFF
Server: closes the socket
Data socket
Note: A data socket is forcibly disconnected by the server when the client is disconnected from the control socket.
Greetings
Client: 0xEE 0xAB <0x00 / 0x01 for STARTTLS>
Server: sets mode or disconnects
Server (4 byte): EE AB 01 00 (01 00 - protocol version)
Client: 32 bytes (client token) TIMEOUT_SEC (u8)
Server: OK or closes the socket
The client can have only one data socket with the same token. The client may close the data socket and then reuse the token to open a new one.
Keep-alive pings
The server pings the client by sending OP_NOP with frequency TIMEOUT_SEC / 2, where TIMEOUT_SEC is the value reported by the client during greetings.
Message push
Server:
x01 PRI(u8=7F) LEN TOPIC 00 MESSAGE
The server also sends beacon OP_NOP messages with TIMEOUT/2 interval.
Bye
Not required. The client can close the data socket at any time.
UDP
0x01 - OP_PUBLISH
0x21 - OP_PUBLISH_NO_ACK
Plain
Client:
EE AA 01 00 (VERSION) 00 (PLAIN) LOGIN 00 PASSWORD 00 OP PRIO(u8=7F) TOPIC 00 DATA
Server (if ack required):
CONTROL_HEADER (2 bytes) PROTOCOL_VER (2 bytes) OK
Encrypted
Client:
EE AA 01 00 (VERSION) ENC_TYPE LOGIN 00 NONCE(12 bytes) ENC_BLOCK+DIGEST
where ENC_TYPE:
0x02 - AES128-GCM
0x03 - AES256-GCM
and ENC_BLOCK: OP PRIO(u8=7F) TOPIC 00 DATA
Server (if ack required):
CONTROL_HEADER (2 bytes) PROTOCOL_VER (2 bytes) OK