Opcodes & Messages

WebSocket communication uses a binary protocol with typed opcodes. Each opcode tells the kernel how to process the message.

Built-in Client Opcodes

These opcodes are defined as FlatBuffers enums in protocol::fbs::Opcode:

Opcode	Handler	Purpose
Opcode_WhoAmI	handlers::whoami	Get session identity
Opcode_Ping / Opcode_Pong	handlers::ping / pong	Heartbeat / keep-alive
Opcode_ClientSubscribe	handlers::subscribe	Subscribe to a channel
Opcode_ClientUnsubscribe	handlers::unsubscribe	Unsubscribe from a channel
Opcode_Publish	handlers::publish	Publish to a channel
Opcode_Send	handlers::send	Send to a specific session
Opcode_Broadcast	handlers::broadcast	Broadcast to all subscribers
Opcode_CacheGet	handlers::cache_get	Read from distributed cache
Opcode_CacheSet	handlers::cache_set	Write to distributed cache
Opcode_CacheDelete	handlers::cache_delete	Delete from distributed cache
Opcode_JobDispatch	handlers::job_dispatch	Dispatch a job
Opcode_Watch	handlers::watch	Watch a resource
Opcode_Unwatch	handlers::unwatch	Stop watching
Opcode_SetQuota	handlers::set_quota	Set rate limits
Opcode_GetQuota	handlers::get_quota	Get rate limits
Opcode_NodeMetrics	handlers::node_metrics	Request node metrics
Opcode_DashboardMetrics	handlers::dashboard_metrics	Dashboard metrics

Message Format

Messages are binary-encoded using FlatBuffers. The wire format is:

[4 bytes: frame_size] [FlatBuffers Message]

The Message FlatBuffers table contains:

Field	Type	Description
opcode	Opcode	The message type (enum).
transaction_id	UUID	Unique ID for request-response matching.
payload	[uint8]	Variable-length payload data.
timestamp	uint64	Message creation timestamp.
trace_id	UUID	Distributed tracing ID.
span_id	uint64	Tracing span ID.

The schema is defined in the repository at protocol/schema.fbs.

Custom Opcodes

Custom opcodes start at value 200 and above:

app.register_custom_handler(201, my_handler);