src/server/ — hosting the protocol
grep -rln 'wire/net.h' src/server/*.c # -> conn.c and serve.c, and nothing else
make test # t_replay.c and t_conn.c: no network at all
Eight source files, and the first command is the reason they are in one directory: two of them speak to a socket and six of them cannot.
src/proto/ is a pure function from one frame to one frame. This directory is
what turns that into a program, and it does it in two layers that are worth
keeping apart in your head:
- The seam —
session.c,mcp.c,http_handle.c,http_stateless.c,http_const.c. These hold state that outlives a message (a WebSocket session is an environment instance) and they route, which is why they are not insrc/proto/. They still touch no socket, no clock and no allocator. They are the four functionsinclude/openenv/embed.hexports, andtests/t_replay.creplays the entire captured reference corpus through them with no network, no port and no Python. - The loop —
conn.c,serve.c,main.c. That is where the syscalls are. It is where every question the seam refuses to answer gets answered: when a byte moves, which descriptor it moves on, what happens when there are sixty-five peers and eight session slots, and what a termination signal means.
The split is not decoration. Everything in the first layer can be embedded in
somebody else's event loop, fuzzed without a socket, and diffed against captured
bytes; nothing in the second can. And the second layer is split again along the
same line: oe__conn_advance decides and makes no system call, while
oe__conn_recv and oe__conn_send make system calls and decide nothing. That
is why tests/t_conn.c can drive all five connection states, the capacity
refusal and the handshake deadline without opening a port.
The files
| File | The question it answers |
|---|---|
session.c | What happens to one WebSocket frame? Five message types, one environment instance, and the fact that a close is answered with silence. |
mcp.c | /mcp, on all three of its wires: bare and compact over HTTP, bare and spaced over WS /mcp, enveloped and compact over /ws. |
http_handle.c | Which route, which method, and the four defaults a Starlette router emits before any application code runs. |
http_stateless.c | /reset, /step, /state — construct, run, destroy. The filename is the lesson: an episode cannot exist here. |
http_const.c | /health, /metadata, /schema, /openapi.json, and the Task API's two refusals in the order the reference makes them. |
handlers.h | The one handler shape those last three share, and why its return value is narrow. |
conn.h/conn.c | One connection: the fixed-capacity buffer invariant, the two framing predicates, and five states drawn as a diagram in the header. |
serve.c | The poll() loop: accept, dispatch, capacity, the signal self-pipe, and a shutdown that finishes inside two seconds. |
main.c | oe_main() — four flags and the healthcheck subcommand, so envs/echo.c can end in one line. That subcommand exists for one reason: the shipped image is FROM scratch and has no curl for a HEALTHCHECK to call, so the server probes itself. docs/PACKAGING.md is the container half of this file. |
One thread, and what that costs
There is no thread pool, no fork and no prefork, and the reason is on the wire
rather than in a benchmark. max_sessions is a number the server puts in a
frame, so four workers holding two sessions each would tell a refused client
2/2 while eight sessions ran. That is the server lying about itself to a peer.
OpenEnv's own answer to parallelism is one container per environment.
The cost, stated where it cannot be missed: an environment's step() runs
inside the loop, so a slow step blocks every other session and GET /health
with it. That matches the reference under a synchronous environment, where
timeout_s is validated and then never enforced. But it makes this server the
wrong host for an environment whose step makes a network call of its own.
Everything else is non-blocking: reads, writes, and a parser that is only ever
handed a complete, resident message.
Marker polarity
Everything in this directory is our own hosting decision unless a marker says
it is not. That is the opposite polarity from src/proto/, where everything
is protocol unless marked otherwise — so here, a WART-## or a CONF-## marks
the places where a decision was not free, because the reference's observable
behaviour had already made it.
| Marker | Means |
|---|---|
WART-##: | the reference does this odd thing and we reproduce it — four lines: claim / reference / observed / honoured-by |
GAP-##: | nobody specified this and we chose — three lines: unspecified / we chose / a different implementer might |
CONF-##: | this line satisfies numbered server MUST N — one line |
SAFETY: | this check exists because the input is hostile — one line |
POLICY: | this is our free choice and yours to change |
make docs turns them into docs/WARTS.md,
docs/GAPS.md and
docs/BOUNDARY.md, and make check fails when any of
the three goes stale.
The two divergences you can see from here
session.c and http_stateless.c answer the same three questions — reset,
step, state — and produce different bytes for the same environment. Read
write_observation in each of them side by side; they are eight lines apart and
share no body, and the table explaining why is the comment in the middle of
src/proto/encode.c.