QuicxDocs

QXP Protocol

QXP, the Quicx Protocol, is the wire format designed for Quicx. Every frame is a 6-byte header followed by a variable-length payload. The daemon reads the length first, so parsing a frame is a couple of pointer reads.

QXP(the Quicx Protocol) is Quicx’s own protocol, designed by Dimitar Anastasov for Quicx. Producers, workers and the quicx CLI all speak it; the Java client, dev.quicx:quicx-client, is one implementation of it, and this page is enough to write another in any language. To see the frames below at work, run the quick start with a Java producer and worker.

Participants & transport#

Producer and Worker both connect to the same TCP port (server_start, server.c:265). There is no separate producer port or worker port. A connection starts as CONN_UNKNOWN and only becomes CONN_PRODUCER or CONN_WORKER once the daemon sees its first MSG_SUBMIT or MSG_READY.

The CLI (quicx status) is a different client on a different transport: it connects to a separate Unix socket (/tmp/quicx.sock) and only ever does one exchange: it sends MSG_STATS and reads back MSG_STATS_RESPONSE.

The daemon is the process in the middle running the event loop; every message below is either read by handle_readable (server.c) or written by daemon_handle_message (daemon.c).

Connections aren’t only producer or worker, either. As of v1.0.3 the TCP listener and the Unix listener get their own roles, CONN_SERVER and CONN_CLI, instead of being lumped under CONN_UNKNOWN like every other not-yet-registered socket.

Frame header#

total header = 6 bytes fixedtotal message = 6 + length bytes
version
Protocol revision. Currently 0x01. The daemon rejects any other version with MSG_ERROR 0x02 so protocol evolution is additive and opt-in.
type
Message opcode, one of the 13 types below. The daemon routes on type alone; producers and workers speak the same header shape.
length
32-bit big-endian unsigned integer: the payload size in bytes. Zero is legal for MSG_READY, MSG_WAIT, MSG_HEARTBEAT, MSG_PONG and MSG_STATS.
payload
Exactly length bytes, capped at PROTOCOL_MAX_PAYLOAD: 1024 bytes as of v1.0.3 (previously 1 MiB). Since 2.0 a task is one allocator block, the 64-byte Taskrecord with the payload right behind it, and 1,088 bytes is apool’s largest size, so every accepted payload fits. Oversized frames get a clean MSG_ERROR (ERR_PAYLOAD_TOO_BIG) instead of being truncated or read past the buffer.

Message types#

TypeNameDirection
0x01MSG_SUBMITproducer → daemon
0x02MSG_OKdaemon → producer
0x03MSG_ERRORdaemon → producer or worker
0x04MSG_READYworker → daemon
0x05MSG_DONEworker → daemon → producer
0x06MSG_FAILEDworker → daemon → producer
0x07MSG_TASKdaemon → worker
0x08MSG_WAITreserved, unused
0x09MSG_HEARTBEATworker → daemon
0x0AMSG_PONGdaemon → worker
0x0BMSG_STATSCLI → daemon (unix socket)
0x0CMSG_STATS_RESPONSEdaemon → CLI (unix socket)
0x0DMSG_SUBMIT_VALUEDproducer → daemon

Payload formats#

0x01MSG_SUBMITproducer → daemon
[type_len : 1 byte][task_type : type_len bytes][payload : rest of bytes]
type = "send_email"
payload = {"to":"user@gmail.com"}
bytes   = [10][send_email][{"to":"user@gmail.com"}]

Parsed specially in server.c, because the daemon needs the length-prefix byte before it knows how much more to read. On accept, the daemon queues a Task, tags the connection CONN_PRODUCER, replies MSG_OK, and calls try_dispach.

0x0DMSG_SUBMIT_VALUEDproducer → daemon
[level : 1 byte][type_len : 1 byte][task_type : type_len bytes][payload : rest of bytes]
level = 12, type = "analyse", payload = frame=000123
bytes = [12][7][analyse][frame=000123]

A MSG_SUBMIT with a value level in front, 0 to 15. A plain SUBMIT gets level 8. Higher levels are dispatched first, oldest first within a level. When the budget is full and admission = value, a waiting task of a lower level is evicted if its memory fits the new one, and its producer gets MSG_FAILED with the reason evicted. Level 15 is critical and never evicted. A level above 15 is a parse error.

0x02MSG_OKdaemon → producer
[task_id : 4 bytes]
task_id = 0x00000A42  (accepted task id 2626)

Acknowledges that the task was accepted into the queue, not that it ran. Outbound only: the daemon never parses an inbound MSG_OK.

0x03MSG_ERRORdaemon → producer or worker
[error_code : 1 byte][message : rest of bytes]
CodeMeaning
0x01queue full: the memory budget is used up
0x02invalid message (bad version / length / type)
0x03payload larger than 1,024 bytes
0x04unknown task type

Generic failure reply, sent to whichever peer tripped it. Outbound only: if a peer ever sent MSG_ERROR to the daemon it’d fail parsing (not a recognized inbound case) and the connection gets closed.

0x04MSG_READYworker → daemon
(no payload, length = 0)
Sent once per connection, immediately after connect, to register
the socket as an idle worker.

Registers the connection (worker_add) and tags it CONN_WORKER, then calls try_dispach in case work is already queued. If a task is waiting, MSG_TASK follows immediately. There’s no ack on success; if nothing is queued, the worker just stays blocked reading until a task arrives later.

0x05MSG_DONEworker → daemon → producer
[task_id : 4 bytes]
Worker reports success for task_id.

The daemon marks the worker idle, clears current_fd, bumps stats_task_completed, redispatches, and forwards protocol_send_done(producer_fd, task_id) to the producer that submitted the task. Parsing is now strict: exactly 4 bytes, or the frame is rejected.

0x06MSG_FAILEDworker → daemon → producer
[task_id : 4 bytes][reason : rest of bytes, max 64]
reason is a UTF-8 string propagated verbatim to the producer,
and logged by the daemon.

Worker reports failure with a reason string. The daemon forwards it as-is to the producer via Worker.current_fd (protocol_send_failed, daemon.c:87), bumps stats_task_failed, and redispatches the worker. The reason is capped at PROTOCOL_MAX_FAIL_REASON_MSG (64 bytes), validated against the buffer bound, and NUL-terminated by the daemon before forwarding.

0x07MSG_TASKdaemon → worker
[task_id : 4 bytes][type_len : 1 byte][task_type : type_len bytes][payload : rest]
Mirror of MSG_SUBMIT with the task id prepended. The worker dispatches
by type and replies with MSG_DONE or MSG_FAILED carrying the same id.

Sent by try_dispach (dispacher.c:22) when a queued task is handed to an idle worker.

0x08MSG_WAITreserved, unused
(no payload, length = 0)
Defined and accepted by server.c's parser, but daemon_handle_message
has no case for it, so it falls through to default and ERR_UNKNOWN_TYPE.

Nothing in production code calls protocol_send_wait either. Effectively dead in the current build.

0x09MSG_HEARTBEATworker → daemon
(no payload, length = 0)
Liveness probe sent by the worker. The daemon immediately replies
MSG_PONG on the same fd.

PROTOCOL_TIMEOUT_MS and PROTOCOL_HEARTBEAT_MS are defined, but nothing actually tracks last-heartbeat time to drop stale connections. The daemon only responds to heartbeats, it doesn’t enforce the timeout itself.

0x0AMSG_PONGdaemon → worker
(no payload, length = 0)
The only valid reply to MSG_HEARTBEAT.

Outbound only, like MSG_OK / MSG_ERROR: the daemon has no inbound case for it.

0x0BMSG_STATSCLI → daemon (unix socket)
(no payload, length = 0)
Request for pool, queue and worker stats.

Sent over the Unix socket at /tmp/quicx.sock, not the TCP port producers and workers use. quicx status is the only sender.

0x0CMSG_STATS_RESPONSEdaemon → CLI (unix socket)
[StatsHeader : 81 bytes, packed, network order][StatsClass : repeated class_count times]
BlockContents
StatsHeaderidle / busy worker counts, workers_registered (ever registered, not just live), queue depth, submitted / completed / failed task counters, uptime, pool_size, usable_bytes, used_bytes, tasks_evicted and class_count
StatsClass × class_countone entry per block size that holds pages right now: its block size, capacity and live blocks

_Static_assert(sizeof(StatsHeader) == 81) locks the layout. class_count is a uint8_t with no byte-swap. It used to be a uint32_t sent through htonl, with the daemon and the reader each hardcoding a different, mismatched cap (32 and 16) on how many classes they’d parse.

End-to-end flow#

one task, start to finish
Producer                Daemon                    Worker
   |--MSG_SUBMIT-------->|                            |
   |<--MSG_OK------------|                            |
   |                      |<--MSG_READY----------------|
   |                      |--MSG_TASK------------------>|
   |                      |<--MSG_DONE (or MSG_FAILED)--|
   |<--MSG_DONE / FAILED--|  (forwarded to the producer since v1.0.3)