Memory
This page is the memory model: how every allocation in this library works, and what that asks of the people who call it. The whole library allocates from arenas — regions of memory reclaimed all at once, at a reset, never value by value — and one rule falls out of that.
The rule an author has to carry
Nothing this library hands you needs freeing. Everything this library hands you dies at your next call on that handle.
That is the whole contract. It is temporal, not structural. That is what makes it checkable by a human rather than by a tool: you can look at your own code and see whether you kept a pointer across a call.
Exactly three types have a _free, and you can name them: oe_arena,
oe_server, oe_client. Need something to outlive the next call?
oe_json_dup(v, your_arena).
The proof that the rule is small enough to be true is envs/echo.c: a complete
environment, 45 statements, with zero arena tokens, zero malloc, zero free
and zero error branches. tools/check.sh fails the build if that stops being
so.
There is exactly one exception to the rule, and it is named rather than hidden.
oe_client_pump(c, 0) does not invalidate the previous result. A keepalive
that invalidated the observation you were reasoning about would be unusable in
the loop it exists for. src/client/README.md argues it.
Three claims about the implementation
src/wire/arena.cis the only translation unit in the program that callsmallocorfree.tools/check.shrule 3 enforces it.grep -rnE '(^|[^A-Za-z0-9_])(malloc|calloc|realloc|free)\(' src # one file- Every arena carries a mandatory hard byte budget, supplied at construction. That budget is the single place an attacker-derived size is refused. So no individual call site needs a guard of its own, and the call sites are short enough to read.
- Exhaustion returns NULL and latches; it never returns a short buffer.
The third is a security property before it is an ergonomic one:
An allocator that hands back a small scratch buffer when it cannot satisfy a large request is a remote heap-overflow primitive with attacker-chosen length and attacker-chosen contents.
Past the budget oe_arena_alloc returns NULL and sets ok = false, and it stays
false until the next reset — even for a later request that would have fit.
Builders — the functions that write pieces of a message — test oe_arena_ok()
first and write nothing. So fallible operations return oe_err, and builders
return void and are always safe to call. The seam between the two is exactly
one function, called once at the encode boundary. Half a message is never
mistaken for a message.
Three arenas, strictly nested
| Arena | Lifetime | Budget | Holds |
|---|---|---|---|
perm | the process | OE_PERM_ARENA_MAX, 1 MiB | constant responses, built once at startup |
session | one connection | OE_SESSION_ARENA_MAX, 1 MiB | the zeroed per-connection state block |
msg | one request or one frame | OE_CONN_MSG_MAX, 8.31 MiB at a server; OE_CLIENT_MSG_ARENA_MAX, 128 MiB at a client | the parse tree, the validated action, the reply |
The message budget is the interesting one. It is a flat ceiling, not a function of the message. That was a decision, taken against a measurement, not a corner nobody turned.
It is also the number a client derives its wire caps from, in that direction
and not the other. OE_WS_MAX_FRAME_CLIENT and OE_WS_MAX_MESSAGE are
OE_CLIENT_MSG_ARENA_MAX / OE_JSON_ARENA_PER_BYTE: 128 MiB / 256 = 512 KiB.
A client advertises what it will read, and an advertisement is only worth
what the parser behind it can honour. Three static assertions in
src/client/client.c will not compile if any of them stop agreeing. The third
covers the thirteen HTTP describing routes, which parse into the same arena and
had been left out. This is the one place in the program where a memory budget
sets a wire constant rather than the other way round. The reason: a server owes
a stranger no parse, only a defined refusal. A client owes its chosen peer the
answer it asked for.
The numerator was 64 MiB and the divisor 128, and that pair could not deliver
the cap it computed. 64 MiB / 128 is exactly 524,288, so the assertion held
with zero slack while the multiplier itself was too small. Re-measured across
shape families rather than across one family's inner lengths, an array of [
chains at depth 62 costs 128.23 bytes of arena per byte of source. Over a real
socket the old pair accepted 523,774 bytes of that shape and refused 523,775 with
OE_ENOMEM. Both numbers doubled; SECURITY.md has the sweep and what it cost.
A server's number is 8 × (32 KiB + 1 MiB) + 64 KiB: the largest request it
will accept, times a factor, once. That bounds node amplification, which is
the attack it exists for. A legal 1 MiB array of small integers is hundreds of
thousands of JSON nodes. Without a ceiling, one frame demanding its whole
value be resident is an OOM kill rather than an error frame. Multiplied out
across the connection cap it is the 668 MiB that src/wire/limits.h asks
you to check:
64 × (8,716,288 + 2,228,224) = 700,448,768 bytes. (That block said 666 until
the close-out sweep, from rounding the second term to 2.09 MiB when it is 2.125.
A number a document invites you to re-derive is a number somebody eventually
re-derives.)
The obvious refinement is to give each message 8 × its own length + 64 KiB
instead. It was implemented and measured, and it does not work. See
what was decided and why below.
SECURITY.md is the rest of the
argument; src/wire/limits.h carries all of it at the #define.
Why an arena at all
Not for speed. An arena is here to delete code from the files where readability matters most.
A codec that owns its allocations has to answer "who releases this?" at every early return. The answers are the cleanup labels, the ownership comments and the double-release bugs that make C parsers hard to read. An arena answers the question once, for everything, somewhere else: memory is reclaimed in a single call at a boundary the caller picks, and nothing in between reclaims anything.
That is what makes return err; a complete cleanup, and it is why this
codebase has no goto. The ban is enforceable rather than aspirational
precisely because the arena pays for it. See ERRORS.md.
Strings, and the class of bug that disappears
oe_str { const char *p; size_t n; } is the only internal string type:
borrowed, never NUL-terminated, never freed.
It deletes the truncation and off-by-one class outright. It is also why
<ctype.h> is unnecessary: isspace((char) 0x80) is undefined behaviour, and
every byte here came off a socket. Both are banned and both bans are checked.
It also decides one wire-visible question. A JSON string may contain an interior
NUL, and oe_str carries it faithfully. The const char * accessor
oe_as_str returns your fallback rather than a truncated prefix. The truncated
form is the dangerous one — the validator saw safe ; rm -rf / and your code
would act on safe. oe_as_slice is the faithful accessor. GAP-11.
The zero-copy invariant
A message buffer is fixed-capacity for the lifetime of one message. Nothing is ever reallocated while a slice into it is live.
That single discipline is what makes "unescaped JSON strings are slices of the
input" safe. It is stated at the top of src/server/conn.h, because that is
the file that could break it. An escaped string is the one that costs a copy,
into the arena the document was parsed in. The claim is a test rather than a
paragraph, and oe_json_str_is_slice is the predicate that makes it one.
unescaped_strings_are_slices_of_the_input in tests/t_json_parse.c asserts it
of an unescaped string, and asserts its negation of an escaped one.
a_request_becomes_slices_of_the_caller_s_own_bytes in tests/t_http.c does the
same for a request head.
The hazard this model creates, and its three antidotes
Stated plainly, because an arena design that does not ship its antidote is teaching an unsafe habit:
Everything an arena hands out dies at the same instant, and the language will not warn you. A pointer kept across
oe_arena_reset()is a use-after-release that a bump allocator will cheerfully let you read, because the bytes are still mapped and now belong to somebody else.
Three mechanisms make that loud instead of silent, and make test runs all
three:
| Antidote | What it turns the bug into |
|---|---|
| the reclaimed span is poisoned for AddressSanitizer on every reset | a diagnosed read of poisoned memory |
OE_ARENA_DEBUG_MALLOC=1 switches to one real allocation per request, released on reset | a genuine dangling pointer a sanitizer recognises, rather than a bump pointer moving backwards over live-looking bytes |
| every arena carries a 32-bit generation, advanced on reset, which values stamp themselves with | an abort at the read site instead of a plausible lie |
make test runs the whole suite twice — as built, then under ASan + UBSan with
OE_ARENA_DEBUG_MALLOC=1 — so the second and third of those are not optional.
A further consequence is visible in the API: constructors keep a visible
oe_arena *. The arena is never hidden inside a scalar value. So
grep -rn 'oe_arena \*' src/ enumerates every allocation site in the program,
and lifetime is legible at the call site. The container setters take none: a
container remembers where it grew, and an environment author must never have to.
One name that breaks the naming rule, on purpose
oe_*_new is the only suffix that transfers ownership, and there are three of
them. oe_buf_new carries the suffix and transfers nothing: the buffer header
and its bytes both belong to the arena you passed, and there is no
oe_buf_free.
It is documented at the declaration rather than renamed, because the rename is
ninety call sites of churn against a paragraph. And the rule a reader has to
carry survives it: three things you free, and oe_buf_new is not one of
them. CONVENTIONS.md §4 is where that exception is named.
What was open, and how it closed
Nothing in this project's memory model is open. The last item that was is recorded here rather than only in the header, because it is a decision about memory and this is the document about memory.
The question. A message arena's budget is a flat ceiling. Should each
message instead be given min(OE_MSG_ARENA_MAX, 8 × msg_len + 64 KiB) — its
own length, times a factor? Then a ten-byte request would not be promised the
same 8.31 MiB as a one-megabyte one. That needs one function the arena did not
have,
oe_arena_set_budget, called from begin_message in src/server/conn.c.
The answer is no, and it was measured rather than argued. The function and the call site were written, the formula was applied to the reassembled message length, and the tree was rebuilt and run.
A ceiling is not a reservation. An arena takes memory when something asks for it, never because of what it was permitted. Two arenas 133× apart in budget hold the same bytes for the same work —
t_arena.c,a_ceiling_costs_nothing_until_it_is_used. So a tighter budget cannot save memory. All it can do is refuse messages.The message arena holds the ANSWER too, and its length is not knowable in advance. On a server the answer is the large direction. A 41-byte
stepframe answered with a 400,000-byte observation costs the arena 2,804,356 bytes — 68,399× the message that asked for it, and 42× what the formula would have allowed that message.t_conn.c,the_message_arena_is_sized_by_the_answer_and_not_by_the_message, drives exactly that with no socket;t_client.cdrives it over a real one. Sizing a budget from the message sizes it from the small direction.No factor rescues it. With the formula shipped,
make testfails onan_observation_over_the_server_frame_cap_arrives_whole— seven checks, a1011the server sent itself. Bisecting the factor with a rebuild at every step, the smallest one that keeps that test green is 31,983. At that slope the formula has already saturated the flat ceiling for every frame of 271 bytes or more, and every message this protocol carries is shorter than that. It would be the ceiling wherever it did not refuse. And it would still not be safe: 31,983 is a fact about one environment's observation, not about any peer's message.
What the formula was wanted for, the peer's own length already bounds. A
parse cannot cost more than OE_JSON_ARENA_PER_BYTE times its source text, and
the flat ceiling caps that in turn. Node amplification is one clean error frame,
which is what it was always supposed to be.
The section above is the long form. The author's own notes carry a longer one
still, but they live under reference/, which is gitignored. So they are not
cited here: a citation a cloner cannot follow is worse than none.
See also
../src/wire/arena.h↗ — the model as a header, and the complete statement of it../src/wire/limits.h↗ — every budget, with its arithmeticERRORS.md— the error model this one pays forSECURITY.md— why exhaustion returns NULL rather than a bufferPACKAGING.md—nm -uon a program that includes only<openenv/embed.h>: seven of its fifteen undefined symbols are this one file