Protocol Reference

Protocol Reference

tyo-mq speaks plain socket.io events — any socket.io client in any language can implement the protocol. System events are ALL-CAPS; payloads are JSON objects (stringified JSON is also accepted on most events).

Authentication

Event	Direction	Payload
AUTHENTICATION	C→S	{ token } or { realm?, role?, key? }
AUTH_OK	S→C	{ realm, role }
AUTH_FAIL	S→C	{ code: 401|403, message }

With auth enabled, every other event below requires a successful AUTH_OK first (and the right role).

Identity and lifecycle

Event	Direction	Payload / notes
PRODUCER	C→S	{ name, id?, default_ttl? } — register/re-register a producer
CONSUMER	C→S	{ name, id?, consumer_id? } — register a consumer; duplicate live names are rejected with ERROR + disconnect
HELLO	C→S	{ name, type } — informational
PING	C→S (ack)	echoes back { ...payload, pong: "PONG", timestamp }
QUIT	C→S	{ id } — server-side disconnect of own socket
ERROR	S→C	{ message, code }
CONNECT-<clientId>	S→C	a peer this client relates to came online ({ event, socket, producer?|consumer? })
DISCONNECT-<clientId>	S→C	a related peer went offline
SUBSCRIBE-TO-<producerId>	S→C	a consumer subscribed to this producer ({ name, id, socket, events, online })

Producing

Event	Direction	Payload
PRODUCE	C→S	{ event, message, from, ttl?|lifespan?, guaranteed?, method?: 'broadcast', broadcast?: 'realm'|'group', group?, to? }
PRODUCE_CHUNK	C→S	{ transferId, index, total, data } — ordered fragments of a stringified PRODUCE payload > 256 KB

Subscribing and consuming

Event	Direction	Payload
SUBSCRIBE	C→S	{ event, producer, consumer, id?, scope?, durable?, consumer_id?, ack?, manual_ack?, ack_timeout?, retry?, mode?: 'topic', group? } — producer: "TYO-MQ-ALL" means any producer
UNSUBSCRIBE	C→S	subscription event string
CONSUME-<eventStr>	S→C	{ event, message, from, msgId?, msg_id?, delivery_attempt? } — eventStr is the lowercased producer-event subscription string
CONSUME_CHUNK	S→C	{ transferId, event, index, total, data } — large outbound messages
ACK	C→S (ack)	{ msgId }
ACK_OK / ACK_FAIL	S→C	{ ok, msgId } / { ok:false, code, message }

Subscription event strings: <producer>-<event> lowercased; tyo-mq-all-<event> for any-producer; <producer>-tm-all for all events of one producer; topic patterns ride in the event position with mode: 'topic'.

Authorization flow

Event	Direction	Payload
AUTHORIZATION_REQUEST	C→S (ack)	{ realm, role, client_id, client_name, client_token, challenge_response? } → { ok, request_id, status }
AUTHORIZATION_NEXT	C→S (ack)	{ body: { realm? }, proof } → { ok, request }
AUTHORIZATION_DECIDE	C→S (ack)	{ body: { request_id, approved, role?, reason? }, proof } → { ok, request }
AUTHORIZATION_APPROVED	S→C	{ request_id, realm, role } (to the requester)
AUTHORIZATION_REJECTED	S→C	{ request_id, reason }
AUTH_MANAGEMENT_COMMAND	C→S (ack)	{ body: { command, ... }, proof } → command result (Management Commands)

proof = { timestamp, nonce, signature } where signature is HMAC-SHA256(secret, action \n timestamp \n nonce \n stableJson(body)). Nonces are single-use; timestamps valid for ±5 minutes.

Remote namespace (/remote)

Event	Direction	Payload
REMOTE_TICKET_REQUEST	C→S main ns (ack)	{ session_id?, machine_id?, role: 'agent'|'viewer' } → { ok, session_id, ticket, role, expires_in }
auth	C→S /remote	{ ticket, session_id } → auth_ok / auth_error
frame	agent→viewers	binary frame
input.mouse, input.keyboard	viewer→agent	input event objects

HTTP (opt-in)

GET /health, GET /api/metrics, GET /api/stats, GET /api/realms/{realm}/dlq — see Observability HTTP API.