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.
The rule
Errors propagate by
return err;. There is nogotoin 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.
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.
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:
locis a 3-element path of KEY or IDX, because["body","action"]and["body",1]are both real and a single string cannot express either- 32 item slots, because pydantic — the validation library the reference (huggingface/OpenEnv, the Python implementation this project was captured from) is built on — reports every failing field. A fixed ceiling that silently dropped the 33rd would be a lie in the same shape as a truncated string. Overflow sets a flag the caller can see
- environment messages are borrowed slices, not truncated buffers
Fallible operations vs. builders
The single most load-bearing distinction in the codebase, and it is one sentence:
Fallible operations return
oe_err; builders returnvoidand 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.
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.
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.
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 failure | On HTTP | On WS /ws |
|---|---|---|
OE_EOF, OE_EAGAIN, OE_ETIMEDOUT, OE_EIO | no answer — the socket is gone or the request is unfinished | no frame |
OE_EJSON | 422, one json_invalid item | INVALID_JSON, stays open |
OE_EDEPTH | 422 — same answer, because "this document was not acceptable" is the whole of what a peer is owed | INVALID_JSON, stays open |
OE_ETOOBIG | 413 {"detail":"Content Too Large"} | INVALID_JSON, stays open |
OE_EVALID | 422 carrying the validator's own items | VALIDATION_ERROR with errors, stays open |
OE_EENV | 500 text/plain (WART-19) | EXECUTION_ERROR, stays open |
OE_ENOMEM, OE_EUSAGE | 500 text/plain | SESSION_ERROR, closes |
OE_EPROTO | 400 {"detail":"Bad Request"} | never reaches this table: RFC 6455 answers with a close code first |
OE_EUTF8 | 400 {"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.
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:
| Status | Body | When | We 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 ship | yes, cases 91-95 |
404 Not Found | {"detail":"unknown environment '<name>'"} | env_name mismatches the registered name — the second 404, WART-15 | yes, cases 26-28 |
422 Unprocessable Content | the pydantic missing item for split | a POST task body without split | yes, case 30 |
400 Bad Request | {"detail":"Invalid task index"} | an out-of-range index, only when a provider is present | no — 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.
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:
- Not calling
acceptat all leaves the peer parked in the kernel's accept queue. Itsconnect()has already returned success, so it sends a request and then hangs until a timeout, learning nothing. The listening socket also stays readable with the table full, so the poll loop spins at the speed of the kernel's readiness reports — a busy-loop an attacker gets for free. - A silent drop —
acceptthen discard, no close — leaks the descriptor and still leaves the peer waiting on an answer that never arrives.
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.
See also
../src/wire/err.h↗ — the enum, one screen../src/proto/errors.h↗ — the two mappings, and section 4a's argument about reflectionPROTOCOL.md— what a validation error looks like on the wire, and theurlruleMEMORY.md— the model that makesreturn err;complete