Wire spec

Overview

Beava ships two transports:

• HTTP/1.1 on port 8080 — plain JSON, verb-style routes, ubiquitous tooling reach (curl / load-balancers / WAFs).
• Custom-framed TCP fast-path on port 8081 — a four-byte length prefix plus a two-byte opcode, JSON payload, persistent connection, sub-millisecond P99.

Both transports carry the same JSON envelope per opcode. The only differences are framing (HTTP headers vs the binary length-prefixed frame), the route/opcode mapping, and the strict-FIFO contract on TCP. Pick HTTP for reach; pick TCP for latency.

HTTP routes

All data-plane writes and reads are POST. Verb-style URLs only — the event name and entity key live in the JSON body, not in path segments.

Errors on every route share one body shape — see Errors below.

TCP frame format

Every TCP frame — request or response — has the same envelope. All multi-byte integers are big-endian (network byte order).

[u32 length BE][u16 op BE][u8 content_type][payload: length - 3 bytes]

# length=3 (op + ct), op=0x0000 (ping), ct=0x01 (JSON), payload=∅
00 00 00 03  00 00  01

TCP opcode table

Opcodes are u16 big-endian. Opcodes outside this table return unknown_op.

Content type byte

The single-byte content_type field gates payload parsing. v0 ships one value: 0x01 = CT_JSON. Every frame the SDKs send sets this byte; server-to-client response frames also use 0x01.

Any other content-type byte returns OP_ERROR_RESPONSE with code unsupported_content_type. The connection is not closed — only that frame is rejected, so a misconfigured client doesn't tear down a healthy long-lived session.

Strict-FIFO contract

Beava's TCP transport is strict-FIFO: at most one in-flight request per connection, and the server replies in the exact order it received requests. There is no request_id field on the wire because the order is the correlation.

Concretely:

• A client writes one frame, then waits for one response frame, then writes the next.
• If a client writes two frames back-to-back, the server still replies in submission order — but the client must not interpret responses out of order or interleave reads from multiple application threads on the same socket.
• The Python SDK's TCP transport enforces this client-side: a TCP-mode bv.App serialises send/recv on the socket, and concurrent calls from multiple threads block on a per-connection lock rather than racing the wire.

Errors

Every error — HTTP or TCP — has the same body shape:

{
  "error": {
    "code":    "event_not_found",
    "path":    "/push",
    "message": "Unknown event 'PageView'"
  }
}

Over HTTP this body is returned with the appropriate 4xx / 5xx status. Over TCP it is wrapped in a frame whose opcode is OP_ERROR_RESPONSE = 0xFFFF regardless of which opcode the request used. The code field is a stable string SDK clients can match on (e.g. event_not_found, invalid_event, unknown_table, reset_disabled_in_production, unsupported_content_type, unknown_op, frame_too_large).

HTTP vs TCP — when to use which

Common questions

Where to go next

You've got the wire. The next things are the client that speaks it and the routes that consume it: