miniopenenv

docs/ERRORS.md → html

Errors

This page is the error model: how a failure travels from the byte that caused it to the peer that is owed an answer. Inside the program there is one flat enum; on the wire there is a separate, smaller vocabulary; and this page is about the gap between the two, which is deliberate.

§ 1 · The rule

The rule

Errors propagate by return err;. There is no goto in this codebase.

tools/check.sh enforces the second half. The first half is what makes the second half possible: the arena owns every allocation a function makes, so return err; is always complete cleanup and there is nothing for a goto cleanup to do. That is MEMORY.md paying for itself.


§ 2 · Two vocabularies, kept apart on purpose

Two vocabularies, kept apart on purpose

Fourteen values in one flat enum, for the whole program. No per-layer error types, no negative errnos, no error objects, no out-parameter chains. A failure that begins as a byte in the frame parser reaches the code that owes the peer an answer by being returned, unchanged, through every frame in between.

OE_OK          OE_EOF         OE_EAGAIN      OE_ETIMEDOUT   OE_EIO
OE_EPROTO      OE_EJSON       OE_EVALID      OE_ETOOBIG     OE_ENOMEM
OE_EDEPTH      OE_EUTF8       OE_EENV        OE_EUSAGE

src/wire/err.h is sixty-six lines and fits on one screen, with a one-line comment per value. It is the second file on the reading order for src/wire/.

Not one of these names ever reaches a socket. The vocabulary a peer sees is the seven WSErrorCode strings and the HTTP status codes, and it lives in a separate enum one layer up.

Keeping them apart is the point rather than tidiness. Merging them would teach that our implementation details are on the wire, which is precisely the confusion this project exists to end. It would also leak information: a peer that can distinguish OE_EJSON from OE_EVALID is a peer that has learned our internals. oe_err_name() exists for logs and test output and is documented "never for a peer".

The mapping between the two is two tables in ../src/proto/errors.c ↗: fourteen internal failures onto the seven WebSocket codes, and onto the HTTP statuses.


§ 3 · The detail a peer is owed

The detail a peer is owed

It travels in oe_diag: caller-owned, stack-allocated, fixed-size, threaded only through the parser and the validator.

It never allocates, and that is not a micro-optimisation — it is what makes reporting an out-of-memory condition work. A diagnostic that needs the allocator cannot describe the allocator failing.

Its shape follows the protocol rather than convenience:


§ 4 · Fallible operations vs. builders

Fallible operations vs. builders

The single most load-bearing distinction in the codebase, and it is one sentence:

Fallible operations return oe_err; builders return void and are always safe to call; the seam between them is exactly one function.

A builder tests oe_arena_ok() as its first statement and writes nothing when the arena has latched. So the arena is tested once, at the encode boundary, in the library. A poisoned arena becomes one clean error frame instead of an error check on every one of the eighty lines that write a key.

This is why an environment author writes no error branches at all. It is not that failures are ignored; it is that the one place they can be observed is inside the library, and by construction there is nothing partial to observe.


§ 5 · OE_TRY, and where it is legal

OE_TRY(expr) is the only control-flow macro in the codebase, and it is legal only under src/wire/. tools/check.sh rule 4 decides that.

Down in the codecs the error checks outnumber the logic and explicit ifs bury the grammar being parsed. One layer up, in src/proto/, every branch is protocol semantics, and a branch hidden inside a macro is a lesson hidden inside a macro. The ban is not stylistic; it is the same argument as the one for having two encoders that share no body.


§ 6 · Two error paths worth knowing about

Two error paths worth knowing about

A composed row reaching the generic failure writer is a contradiction, and the honest answer to a contradiction is a 500. The 200 and 422 rows carry no body of their own — the caller supplies the items. If a handler returns OE_EVALID without having written its own 422, sending the row anyway produced

HTTP/1.1 422 Unprocessable Content
content-length: 0
content-type: application/json

and returned OE_OK: a response that claims JSON and contains none, with no signal to anybody that something was missing. It was reachable from the network. write_failure in src/server/http_handle.c now degrades to WART-19's 500 instead. (A WART-nn is a reference accident this project reproduces on purpose; WARTS.md is the list.) A 500 is a complete answer, and it turns a lie into a refusal.

A usage error is never a peer error. oe_http_parse returns OE_EUSAGE from its own argument guard, before it has set *out_status. Treating it like the peer-caused statuses would therefore emit HTTP/1.1 0 Unknown for a bug that is ours. Returning it means every remaining failure carries a status the parser chose.


§ 7 · What a peer actually sees

What a peer actually sees

Fourteen internal failures collapse onto seven HTTP answers and five WebSocket ones. The collapse is the point: a peer learns that its request was unacceptable, never which of our internal conditions decided so.

Our failureOn HTTPOn WS /ws
OE_EOF, OE_EAGAIN, OE_ETIMEDOUT, OE_EIOno answer — the socket is gone or the request is unfinishedno frame
OE_EJSON422, one json_invalid itemINVALID_JSON, stays open
OE_EDEPTH422 — same answer, because "this document was not acceptable" is the whole of what a peer is owedINVALID_JSON, stays open
OE_ETOOBIG413 {"detail":"Content Too Large"}INVALID_JSON, stays open
OE_EVALID422 carrying the validator's own itemsVALIDATION_ERROR with errors, stays open
OE_EENV500 text/plain (WART-19)EXECUTION_ERROR, stays open
OE_ENOMEM, OE_EUSAGE500 text/plainSESSION_ERROR, closes
OE_EPROTO400 {"detail":"Bad Request"}never reaches this table: RFC 6455 answers with a close code first
OE_EUTF8400 {"detail":"There was an error parsing the body"}likewise — close 1007

The depth cap and the string cap are ours; the reference has neither. So a peer that could tell them apart from a syntax error would be reading our configuration off the wire. That is why OE_EDEPTH and OE_ETOOBIG are INVALID_JSON on the WebSocket rather than codes of their own.

Two paths are not in this table because they never reach it. The HTTP parser answers its own 413 / 414 / 431 / 501 / 505, because only it knows which cap was hit or which byte was wrong. And validate_frame in ../src/wire/ws.c owns every close code, one numbered block per RFC 6455 rule.

Note the OE_EENV row. An environment callback reporting failure is a recoverable error frame and not a closed socket, which is why every callback in <openenv/openenv.h> returns oe_err. A void-returning step() would make EXECUTION_ERROR unreachable and a whole branch of the protocol untestable.

And note that OE_ENOMEM closing the WebSocket is marked POLICY at the line, not protocol: the message arena is per-message, so a smaller next message would succeed. We end the session anyway, because an exhausted arena means we do not know the session's state is intact — and the marker says what a different implementer might do instead.


§ 8 · The Task API's statuses, and the 400 this implementation cannot reach

The Task API's statuses, and the 400 this implementation cannot reach

The six Task API routes (PROTOCOL.md, section 2) answer with statuses that are absent from the table above. Three of the four are decided before any of our error vocabulary runs. The fourth is one we decline to reach — GAP-24, a GAP-nn being a question the protocol does not answer, listed in GAPS.md:

StatusBodyWhenWe emit it?
501 Not Implemented{"detail":"<method> is not supported for this environment"}a provider-backed route on a provider-less env — every env we shipyes, cases 91-95
404 Not Found{"detail":"unknown environment '<name>'"}env_name mismatches the registered name — the second 404, WART-15yes, cases 26-28
422 Unprocessable Contentthe pydantic missing item for splita POST task body without splityes, case 30
400 Bad Request{"detail":"Invalid task index"}an out-of-range index, only when a provider is presentno — a provider env only, case 102

The 400 is the undocumented one. It appears in no OpenAPI document the reference publishes; the five task handlers declare only their success models. It is also unreachable without a task provider, because a provider-less environment answers 501 first: _call_task_method raises NotImplementedError before the method it would call could raise IndexError (READ from http_server.py:1082-1098). This implementation ships no provider, so it never emits the 400. The corpus — the captured exchanges in tests/fixtures/reference-corpus.json — records it from interop/task_env.py (case 102) as the REFUSED divergence GAP-24 names, REFUSED being one of the four replay verdicts CONFORMANCE.md defines. The 501 and the second 404, by contrast, are ours to emit and are pinned byte for byte in src/server/http_const.c.


§ 9 · The 65th connection sees a clean close, not a hang

The 65th connection sees a clean close, not a hang

OE_MAX_CONNECTIONS is 64 (src/wire/limits.h:365). When every slot is held by a peer that has completed a request, the 65th connection is accepted and then immediately closed. oe_net_accept takes it off the kernel's accept queue, and oe_net_close hangs up on it in the same iteration of the accept loop (src/server/serve.c:723). This is a chosen answer, and the two alternatives it was chosen over are both worse:

Accept-then-close gives the peer a clean end-of-stream instead: its connect() succeeds, and its next read returns EOF. It learns at once that this server is full, rather than discovering it as a stall it must time out. It also drains the kernel backlog, which is what returns the poll loop to sleep.

One subtlety, because the cap is enforced by eviction first: a connection that opened but has never finished a request is not defended. The oldest such silent socket is dropped to make room, and the newcomer takes its slot. The 65th is accepted-then-closed only once every slot holds a peer that has actually spoken. SECURITY.md carries the slow-loris reasoning behind that ordering.


§ 10 · See also

See also