miniopenenv

src/server/README.md → html

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 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.

§ 1 · The files

The files

FileThe question it answers
session.cWhat 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.cWhich 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.hThe one handler shape those last three share, and why its return value is narrow.
conn.h/conn.cOne connection: the fixed-capacity buffer invariant, the two framing predicates, and five states drawn as a diagram in the header.
serve.cThe poll() loop: accept, dispatch, capacity, the signal self-pipe, and a shutdown that finishes inside two seconds.
main.coe_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.
§ 2 · One thread, and what that costs

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.

§ 3 · Marker polarity

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.

MarkerMeans
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.

§ 4 · The two divergences you can see from here

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.