PSRT protocol specifications

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