miniopenenv

docs/MEMORY.md → html

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.

§ 1 · The rule an author has to carry

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.


§ 2 · Three claims about the implementation

Three claims about the implementation

  1. src/wire/arena.c is the only translation unit in the program that calls malloc or free. tools/check.sh rule 3 enforces it.
    grep -rnE '(^|[^A-Za-z0-9_])(malloc|calloc|realloc|free)\(' src   # one file
  2. 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.
  3. 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.


§ 3 · Three arenas, strictly nested

Three arenas, strictly nested

ArenaLifetimeBudgetHolds
permthe processOE_PERM_ARENA_MAX, 1 MiBconstant responses, built once at startup
sessionone connectionOE_SESSION_ARENA_MAX, 1 MiBthe zeroed per-connection state block
msgone request or one frameOE_CONN_MSG_MAX, 8.31 MiB at a server; OE_CLIENT_MSG_ARENA_MAX, 128 MiB at a clientthe 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.


§ 4 · Why an arena at all

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.


§ 5 · Strings, and the class of bug that disappears

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.


§ 6 · The hazard this model creates, and its three antidotes

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:

AntidoteWhat it turns the bug into
the reclaimed span is poisoned for AddressSanitizer on every reseta diagnosed read of poisoned memory
OE_ARENA_DEBUG_MALLOC=1 switches to one real allocation per request, released on reseta 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 withan 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.


§ 7 · One name that breaks the naming rule, on purpose

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.


§ 8 · What was open, and how it closed

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.

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

  2. 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 step frame 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.c drives it over a real one. Sizing a budget from the message sizes it from the small direction.

  3. No factor rescues it. With the formula shipped, make test fails on an_observation_over_the_server_frame_cap_arrives_whole — seven checks, a 1011 the 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.


§ 9 · See also

See also