Protocol GClasses

Message framing and protocol parsing. Protocol GClasses sit between a transport (C_TCP) and the application logic, translating raw bytes into structured events.

Source: kernel/c/root-linux/src/c_prot_http_cl.c, c_prot_http_sr.c, c_prot_tcp4h.c, c_prot_raw.c, c_websocket.c

C_PROT_HTTP_CL¶

HTTP client protocol — sends requests and parses responses. Can deliver the body incrementally (raw_body_data) or as a complete message.

Key attributes¶

C_PROT_HTTP_SR¶

HTTP server protocol — parses incoming HTTP requests and produces structured events for the application.

Key attributes¶

C_PROT_TCP4H¶

Frame protocol with a 4-byte binary header containing the payload length. Works in both client and server modes.

Key attributes¶

The length of a frame is the peer’s word, in the 4-byte header (big-endian, counting the header itself) before any of its payload. The payload buffer starts at 4 KB and grows with what arrives, up to what the frame needs; up to 7.25.21 the whole length was reserved at the header, so a peer that wrote only headers announcing the max block reserved it each time, with no payload sent.

uint32_t len = htonl(payload_len + 4);      // the header counts itself
gbuffer_append(gbuf, &len, sizeof(len));
gbuffer_append(gbuf, payload, payload_len);

tests/c/c_prot_tcp4h (test1): a frame of 60000 bytes in three parts arrives whole, and the header of a frame of 10 MB with no payload does not grow the yuno’s memory.

C_PROT_RAW¶

Raw pass-through protocol — forwards data without adding or removing headers. Useful for transparent proxying.

Key attributes¶

C_WEBSOCKET¶

WebSocket protocol (RFC 6455) — supports both client and server roles with frame masking, ping/pong, and graceful close handshake.

Key attributes¶

The length of a frame is the peer’s word, written in its header before any of its payload. The payload buffer starts at 4 KB and grows with what arrives, up to what the frame needs (a frame of exactly max_payload_size included: up to 7.25.21 it never ended, a gbuffer holding one byte less than its max); up to 7.25.21 the whole length was reserved at the header, so a few connections that each announced the max block reserved it each with a few bytes sent.

{
    "name": "input",
    "gclass": "C_WEBSOCKET",
    "kw": {
        "iamServer": true,
        "max_payload_size": 1048576
    }
}

Closing¶

ws_close() -- a timeout, a protocol error, a received Close -- moves the gobj to ST_DISCONNECTED at once and sends its Close frame. A server drops the TCP connection there and then. A client keeps it, as RFC 6455 asks: the server closes the TCP connection (7.1.1), and an endpoint that sent a Close may go on receiving (5.5.1). The client drops it itself when timeout_close runs out (warning “Timeout waiting websocket disconnected”).

What arrives in between -- the rest of the frame the client gave up on, the server’s own Close -- belongs to a session that is over: it is discarded, and nothing is published (the debug trace level logs it). Up to 7.25.10 ST_DISCONNECTED did not declare EV_RX_DATA, and each such read logged “Event NOT DEFINED in state”; a controller too busy to read a frame in time showed it. A client configured to give a slow peer more time:

{
    "name": "output",
    "gclass": "C_WEBSOCKET",
    "kw": {
        "timeout_payload": 10000,
        "timeout_close": 5000
    }
}

Test: tests/c/c_websocket (test_websocket_test1).