src/wire/ — the plumbing does not know what it is carrying
grep -riE 'openenv|observations?|rewards?|episodes?|jsonrpc' src/wire --include='*.[ch]'
make check # rule 5, "wire/ knows no application vocabulary"
The first command prints nothing. (--include is not a technicality. This
README has to spell the banned words in order to explain the ban, and
tools/check.sh scans .c and .h files for exactly that reason.)
This is the load-bearing claim of the whole repository. Everybody says their code is layered. The claim here is that the layering is decided by a program, not by a reviewer's memory. It is checked in two tiers, because some words are genuinely generic:
- Tier A — words with no plumbing meaning at all (
observation,reward,episode,openenv). Banned outright, in code and in comments, case insensitively. - Tier B — words a byte-level layer may legitimately use (
oe_arena_reset, "the next step", a connection's state machine). Banned only in their wire form: as a quoted JSON token or a quoted URL path, which is the only way they can reach a peer.
Getting that distinction right is the difference between a check that is an index and a check people learn to work around.
The circumlocutions in these files are a consequence of the rule, not
coyness. wire/json.h describes a field whose type is null | bool | int | float without naming it, because naming it would be a violation. When you meet
a sentence that seems to be talking around something, that is what is happening,
and the thing being talked around is one layer up in src/proto/.
The order to read the twenty-seven files in
Not alphabetical, not the compiler's. This one:
| File | Why here | |
|---|---|---|
| 1 | limits.h | Every hard cap with its reason. Read it before anything that uses one |
| 2 | err.h | Fourteen values, one screen, and the only control-flow macro in the project |
| 3 | arena.h | The memory model, and the three antidotes to the bug it creates |
| 4 | str.h, buf.h | The only string type below the application layer, and the only output buffer |
| 5 | bytes.h | Overflow-checked arithmetic on numbers a peer chose |
| 6 | json.h | 3 is not 3.0, the grammar, and the three encoders the reference has |
| 7 | json_parse.c | RFC 8259 by recursive descent. The grammar is six functions, in order |
| 8 | json.c, json_write.h, json_write.c | Reading a tree; writing one, including the shortest-round-trip double |
| 9 | utf8.h | Why validation is incremental — a character can span two frames |
| 10 | http.h | THE SMUGGLING RULES, which are the whole reason this parser is small |
| 11 | sha1.h, base64.h | Two RFC primitives the handshake needs and nothing else uses |
| 12 | ws.h, ws.c | RFC 6455. validate_frame is the file; everything else is bookkeeping |
| 13 | net.h | The operating system, wrapped. The only file below with a #ifdef in it |
What is not here
No event loop, no connection object, no session, no route table, no
configuration, and no logging. Those are policy, and policy lives one layer up.
Nothing in this directory reads or writes a descriptor except net.c.