The boundary
GENERATED by tools/gendocs.sh. Do not edit this file; edit the tags and run
make docs.
Two boundaries, one index.
The first is the one this project was commissioned to draw. Every declaration
in the public headers and in src/proto/ carries exactly one tag, and it
answers the question the reference implementation makes hard to answer: which
of these names is the protocol, and which is us?
| Tag | Means | The test |
|---|---|---|
[WIRE] | bytes a non-C client sees, or a name that appears in them | change it and a Python client notices |
[SDK] | our ergonomics, zero wire footprint | change it and only C callers notice |
[POLICY] | our free choice, and yours to change | a different implementer could legitimately differ |
tools/check.sh rule 16 fails the build if an aggregate is tagged at the type
level and at some of its members but not all of them, because a half-tagged
struct is where a wrong tag hides. oe_field is the reason that rule exists:
it was once tagged [SDK] under the sentence "None of it is on the wire" while
three of its four members were copied onto the wire verbatim.
The extraction rule, stated so that a row which looks odd is explained by the rule rather than by a bug:
- A tag is either the first token of a declaration's doc comment or a trailing column on the declaration itself.
- The Symbol is the nearest thing being declared — the name inside
(*name)(for a function-pointer member, a function name before its(, the name in the closing} name;of a tagged aggregate, or the declarator otherwise. A member name may repeat across types: there are twoportrows because two different structs have one. - The Note is the first SENTENCE of the tag's comment, followed across continuation lines and cut at its full stop. A blank Note means the tag was written as a trailing column with nothing beside it — the row still answers the question this table exists for, which is the tag.
Files under src/wire/ carry no tags, and that is not an oversight: the tags
classify the protocol surface, and by construction nothing in that directory is
on it (tools/check.sh rule 5). The exception is oe_err, which is [SDK]
because it is also declared in an installed header.
[WIRE]
| Symbol | Where | Note |
|---|---|---|
oe_session_open | include/openenv/embed.h:113 | Open a session, and produce the frame that says you could not. |
oe_session_frame | include/openenv/embed.h:151 | THE PROTOCOL, LITERALLY. |
oe_ws_mcp_frame | include/openenv/embed.h:186 | One frame on WS /mcp: bare JSON-RPC 2.0, spaced, always exactly one response frame. |
oe_http_handle | include/openenv/embed.h:196 | One complete HTTP/1.1 request in, one complete HTTP/1.1 response out: status line, headers and body, ready to write to a socket. |
oe_wserr | include/openenv/openenv.h:102 | The seven WSErrorCode strings. |
oe_wserr | include/openenv/openenv.h:107 | |
oe_wserr_name | include/openenv/openenv.h:118 | "VALIDATION_ERROR", "CAPACITY_REACHED", ... — the bytes themselves. |
oe_wserr_terminal | include/openenv/openenv.h:121 | True when the reference sends this frame and then closes. |
oe_kind | include/openenv/openenv.h:171 | |
oe_reward | include/openenv/openenv.h:269 | |
oe_obs | include/openenv/openenv.h:306 | |
name | include/openenv/openenv.h:366 | The JSON-Schema property key, and the key the validator matches a request's members against, both verbatim. |
json_default | include/openenv/openenv.h:376 | JSON TEXT, e.g. |
description | include/openenv/openenv.h:389 | The schema's description string, verbatim. |
name | include/openenv/openenv.h:429 | GET /metadata .name — the reference reports the Python CLASS name here, not the manifest name, so "CounterEnvironment" is the right answer and "counter_env" is not. |
description | include/openenv/openenv.h:433 | GET /metadata .description |
task_env_name | include/openenv/openenv.h:435 | The name the TASK API answers to: the single element of GET /list_environments, and the name /{env_name}/splits is matched against, case-insensitively. |
version | include/openenv/openenv.h:449 | NULL => "1.0.0" |
readme_content | include/openenv/openenv.h:450 | NULL => JSON null |
author | include/openenv/openenv.h:451 | NULL => JSON null |
documentation_url | include/openenv/openenv.h:452 | NULL => JSON null |
tools | include/openenv/openenv.h:462 | The tool table, OE_TOOLS_END-terminated — section 9. |
reset | include/openenv/openenv.h:475 | |
step | include/openenv/openenv.h:476 | |
state | include/openenv/openenv.h:478 | YOU write episode_id and step_count here; they are base State fields the reference's environments construct too. |
last_error | include/openenv/openenv.h:487 | Set this before returning non-OK from a callback. |
max_sessions | include/openenv/openenv.h:541 | 0 => 8. |
oe_result | include/openenv/openenv.h:661 | |
oe_client_wait_healthy | include/openenv/openenv.h:697 | Poll GET {base}/health until it answers 200. |
oe_client_open | include/openenv/openenv.h:707 | base -> ws: strip trailing '/', http->ws, https->wss, a bare host becomes ws://, then append the literal "/ws". |
oe_client_reset | include/openenv/openenv.h:728 | |
oe_client_step | include/openenv/openenv.h:729 | |
oe_client_state | include/openenv/openenv.h:733 | {"type":"state"} — no data key, and the WebSocket answers the FULL state dump where GET /state whitelists two fields (WART-05). |
oe_client_pump | include/openenv/openenv.h:744 | Answer the peer's heartbeat without making a call. |
oe_client_close | include/openenv/openenv.h:760 | Sends {"type":"close"} and awaits nothing: it is the single message the reference answers with silence. |
oe_toolerr | include/openenv/openenv.h:842 | ToolErrorType — five strings, a CLOSED set, from OpenEnv's own mcp_types.py:198-205 and not from any library it imports. |
oe_toolerr | include/openenv/openenv.h:845 | |
oe_toolerr_name | include/openenv/openenv.h:867 | The five spellings, verbatim, as the error_type member of a ToolError object. |
oe_tool_out | include/openenv/openenv.h:883 | |
name | include/openenv/openenv.h:986 | as published, exact bytes. |
description | include/openenv/openenv.h:1000 | NULL => "", never an omitted key — http_server.py:951 or "" |
call | include/openenv/openenv.h:1011 | |
authority | src/client/client.h:41 | The authority exactly as it was written, brackets and port included, which is the Host header's value. |
path | src/client/client.h:49 | The request target for the upgrade — always ending in the literal /ws, because oe__client_ws_url appended it. |
base | src/client/client.h:53 | The same path without that trailing /ws: the prefix every HTTP route hangs off, so that a server behind a path-prefixing proxy is reachable at {base}/health as well as at {base}/ws. |
oe__client_encode | src/proto/client_codec.h:83 | Append one complete client frame's JSON to out, compact. |
kind | src/proto/client_codec.h:109 | which of the four response types this frame was. |
data | src/proto/client_codec.h:112 | the whole data value: the four-key envelope for an observation, the full state dump for a state, the JSON-RPC response for an mcp, the message/code object for an error. |
result | src/proto/client_codec.h:117 | the envelope, read the way MUST 8.B.12-15 say to read it. |
oe__client_decode | src/proto/client_codec.h:122 | Decode one text frame from WS /ws. |
oe__reward_of | src/proto/client_codec.h:140 | The four JSON shapes reward arrives in, as the tagged union that keeps all four (MUST 8.B.13). |
oe__wserr_of_name | src/proto/client_codec.h:146 | The seven WSErrorCode strings, read rather than written. |
oe__client_ws_url | src/proto/client_codec.h:175 | base URL -> the WebSocket URL to dial, allocated in a. |
oe_msg_kind_name | src/proto/decode.c:102 | The five wire spellings. |
oe_msg_kind_of | src/proto/decode.c:119 | The reverse. |
oe__decode_ws | src/proto/decode.h:118 | Decode one text frame from WS /ws. |
oe__decode_body | src/proto/decode.h:181 | The body-reading rule ALONE, with no request model behind it: is there a body at all, does its Content-Type make it one, is it JSON, and is that JSON an object. |
oe__decode_reset_http | src/proto/decode.h:198 | POST /reset — request model ResetRequest, extra="allow". |
oe__decode_step_http | src/proto/decode.h:213 | POST /step — request model StepRequest, extra="allow". |
oe_tool_action_kind | src/proto/decode.h:268 | |
oe_tool_action | src/proto/decode.h:276 | What a call_tool action carried. |
oe_tool_action | src/proto/decode.h:289 | |
oe__decode_tool_action | src/proto/decode.h:295 | Sniff one action object. |
oe_res_kind_name | src/proto/encode.c:521 | Declared in proto/types.h; defined here because this is the only file that puts one of these four words on a wire. |
oe__encode_begin_http | src/proto/encode.h:85 | Compact separators, CPython's float repr. |
oe__encode_begin_ws | src/proto/encode.h:89 | Compact separators, pydantic's float rule. |
oe__encode_obs_http | src/proto/encode.h:105 | reward is coerced to a JSON float and metadata is ALWAYS present, as null when it is empty. |
oe__encode_obs_ws | src/proto/encode.h:109 | reward reaches the peer exactly as the environment wrote it — null, true, 3 and 1.5 are all legal — and metadata is OMITTED when empty. |
oe__encode_state_http | src/proto/encode.h:123 | Exactly episode_id then step_count, and nothing else, whatever the environment wrote. |
oe__encode_state_ws | src/proto/encode.h:127 | The two base fields first, then every other member the environment wrote, in the order it wrote them. |
oe__encode_frame_open | src/proto/encode.h:140 | Writes {"type":"...","data": and leaves the writer expecting exactly one value: the payload. |
oe__encode_frame_close | src/proto/encode.h:144 | Closes the object the frame opened. |
oe__encode_frame_json | src/proto/encode.h:147 | The one-call form, for the two frame types whose payload is a tree somebody else already built — an error's data from errors.c, a JSON-RPC response from jsonrpc.c. |
oe__encode_tools_http | src/proto/encode.h:196 | ListToolsObservation. |
oe__encode_call_tool_http | src/proto/encode.h:210 | CallToolObservation. |
oe_wserr_name | src/proto/errors.h:80 | "VALIDATION_ERROR", "CAPACITY_REACHED", ... — the bytes themselves. |
oe_wserr_terminal | src/proto/errors.h:85 | True when the reference sends this frame and then closes. |
oe__wserr_of | src/proto/errors.h:89 | Our failure, in the peer's vocabulary. |
oe_http_error | src/proto/errors.h:129 | One row. |
oe_http_error | src/proto/errors.h:133 | |
oe__http_error | src/proto/errors.h:140 | The row for a failure. |
oe_loc_kind | src/proto/errors.h:170 | |
oe_loc | src/proto/errors.h:175 | One element of a loc path. |
oe_loc | src/proto/errors.h:184 | |
oe_ctx_kind | src/proto/errors.h:190 | The ctx object, which is present on some slugs and absent on most. |
oe_ctx_kind | src/proto/errors.h:198 | |
oe_diag_ctx | src/proto/errors.h:205 | |
oe_input_kind | src/proto/errors.h:213 | The input member: the value that was actually validated, echoed back. |
oe_input_kind | src/proto/errors.h:229 | |
oe_diag_input | src/proto/errors.h:235 | |
oe_diag_item | src/proto/errors.h:241 | One error item. |
oe_diag_item | src/proto/errors.h:244 | |
oe__diag_write_items | src/proto/errors.h:336 | The bare array, [{...},{...}]. |
oe__diag_write_detail | src/proto/errors.h:340 | The whole 422 body, {"detail":[...]}. |
oe_wserr_frame | src/proto/errors.h:369 | |
oe__error_write_data | src/proto/errors.h:391 | The data object alone: {"message":...,"code":...[,extras]}. |
oe__error_write_frame | src/proto/errors.h:394 | The whole frame: {"type":"error","data":{...}}. |
oe_rpc_method_name | src/proto/jsonrpc.c:100 | Declared in proto/types.h; defined here because this is the only file that compares one of these four strings. |
oe_rpc_method_of | src/proto/jsonrpc.c:116 | Exact byte match, and nothing else. |
oe_rpc_framing | src/proto/jsonrpc.h:161 | |
oe__rpc_dispatch | src/proto/jsonrpc.h:282 | Dispatch one already-parsed request. |
oe__rpc_dispatch_bytes | src/proto/jsonrpc.h:293 | Parse doc and dispatch it. |
oe__rpc_fail_unknown_session | src/proto/jsonrpc.h:305 | Turn a dispatched session-close into the -32602 the reference emits for an id its table does not hold: "Unknown session_id: <id>". |
oe__rpc_fail_no_mcp | src/proto/jsonrpc.h:324 | -32603 "Environment does not support MCP" — the answer for an environment whose tools member is NULL, reached by a tools/call that carried a name. |
oe__rpc_fail_tool_not_found | src/proto/jsonrpc.h:330 | -32602 "Tool not found: <name>", with name rendered as Python's str() renders it inside an f-string — bare for a string, 5 for an int, True for a bool. |
oe__rpc_fail_tool_error | src/proto/jsonrpc.h:351 | -32603 "<message>" — a tool that ran and failed. |
oe__rpc_fail_args_not_object | src/proto/jsonrpc.h:381 | -32603 for a tools/call whose arguments the tool's KEY SET refuses: a non-mapping arguments (oe__rpc_fail_args_not_object), or a mapping carrying a key the tool does not declare (oe__rpc_fail_arg_undeclared). |
oe__rpc_wants_tool_table | src/proto/jsonrpc.h:401 | True when call is a tools/list still carrying the dispatcher's own "no tool surface" answer, and therefore the one request a caller WITH a table should answer differently. |
oe__rpc_open | src/proto/jsonrpc.h:434 | Open a writer in this framing's style, and for the enveloped framing write {"type":"mcp","data": as well. |
oe__rpc_close | src/proto/jsonrpc.h:438 | Close whatever oe__rpc_open opened. |
oe__rpc_write_error | src/proto/jsonrpc.h:443 | {"jsonrpc":"2.0","id":<id>,"error":{"code":<c>,"message":<m>, "data":<d>}}. |
oe__rpc_write_call | src/proto/jsonrpc.h:448 | The same, for a call the dispatcher already decided. |
oe__rpc_write_result | src/proto/jsonrpc.h:451 | {"jsonrpc":"2.0","id":<id>,"result":<result>}. |
oe__rpc_write_session_created | src/proto/jsonrpc.h:455 | The two session results, spelled here so that a server never writes a JSON-RPC key of its own: create -> {"session_id":"<id>"} close -> {"session_id":"<id>","closed":true} closed is always true, because a close that failed is one of the errors above rather than a result with a false in it. |
oe__rpc_write_tools_list | src/proto/jsonrpc.h:464 | The whole of a successful tools/list: |
oe__openapi_write | src/proto/openapi.h:95 | Append the whole document as one JSON value to a writer the caller opened. |
oe__openapi_build | src/proto/openapi.h:105 | The whole GET /openapi.json body, appended to out. |
oe__pyrepr_input | src/proto/pyrepr.h:54 | pydantic's input_value=<repr>, truncated exactly as pydantic truncates it: at most OE_PYREPR_LIMIT bytes pass through whole, and anything longer comes back as the first OE_PYREPR_HEAD bytes, ..., and the last OE_PYREPR_TAIL — each end moved to a UTF-8 character boundary, so the result is always a legal string in a text frame. |
oe__pyrepr_str | src/proto/pyrepr.h:66 | Python's str(value), as it appears interpolated into an f-string. |
oe__pyrepr_of_str | src/proto/pyrepr.h:76 | repr() of a STRING, which is the one thing the two above cannot spell: oe__pyrepr_input reprs it and then applies pydantic's fifty-byte cut, and oe__pyrepr_str is the arm that deliberately drops the quotes. |
oe_route_id | src/proto/routes.h:33 | One identifier per row, in registration order. |
oe_route_id | src/proto/routes.h:37 | |
oe_route | src/proto/routes.h:62 | One row. |
oe_route | src/proto/routes.h:64 | |
oe__route_match | src/proto/routes.h:124 | Match a request path against the table, FIRST MATCH WINS, in table order. |
oe__route_allow | src/proto/routes.h:155 | The union of the method bits of every HTTP row whose path matches, or 0 when no row does. |
oe__schema_build | src/proto/schema.h:196 | The whole GET /schema body, appended to out. |
oe__schema_write_action | src/proto/schema.h:242 | The action model: the injected metadata field, then the author's action fields in declaration order. |
oe__schema_write_observation | src/proto/schema.h:247 | The observation model: the injected done, reward and metadata fields, then the author's observation fields in declaration order. |
oe__schema_write_state | src/proto/schema.h:252 | The state model — a CONSTANT. |
oe__schema_write_tool_args | src/proto/schema.h:288 | One tool's argument schema, appended to out. |
oe__schema_title | src/proto/schema.h:306 | Title Case, pydantic's rule: name.title().replace('_', ' '). |
oe_tool_spelling | src/proto/tool.h:141 | |
oe__tool_write_table | src/proto/tool.h:146 | The whole table as a JSON ARRAY of three-key rows, appended to w: |
oe__tool_find | src/proto/tool.h:191 | The row whose name is exactly name, or NULL. |
oe__tool_arg_undeclared | src/proto/tool.h:200 | Does args carry a key this tool does not declare? The GAP-21 gate on the AGENT door, KEY SET ONLY: true when any member of args is outside the tool's declared argument names. |
oe__tool_unknown_message | src/proto/tool.h:264 | Unknown tool: 'nope', NUL-terminated, pointing into *out. |
oe_transport | src/proto/types.h:162 | |
oe_msg_kind | src/proto/types.h:193 | |
oe_msg_kind_name | src/proto/types.h:202 | The five wire spellings. |
oe_msg_kind_of | src/proto/types.h:207 | The reverse: a type string to its kind, OE_MSG_UNKNOWN for anything else. |
oe_msg | src/proto/types.h:212 | One decoded client frame. |
oe_msg | src/proto/types.h:220 | |
oe_res_kind | src/proto/types.h:244 | |
oe_res_kind_name | src/proto/types.h:251 | the four spellings |
oe_errs_origin | src/proto/types.h:322 | |
oe_rpc_method | src/proto/types.h:360 | |
oe_rpc_method_name | src/proto/types.h:368 | the four spellings |
oe_rpc_method_of | src/proto/types.h:369 | UNKNOWN otherwise |
OE_RPC_PARSE_ERROR | src/proto/types.h:371 | The six codes. |
oe_verr_slug | src/proto/validate.h:80 | |
oe__verr_type | src/proto/validate.h:105 | The slug as it appears in type, and as the tail of url. |
oe__verr_msg | src/proto/validate.h:108 | Its msg, verbatim. |
oe__validate_coerce | src/proto/validate.h:167 | ONE value against ONE declared kind, by the lax rules of PART 3. |
[SDK]
| Symbol | Where | Note |
|---|---|---|
oe_buf_new | include/openenv/embed.h:81 | A buffer growing out of a. |
oe_buf_bytes | include/openenv/embed.h:96 | |
oe_buf_len | include/openenv/embed.h:97 | |
oe_buf_ok | include/openenv/embed.h:99 | False when the arena refused, or when a builder decided the message must not exist. |
oe_session | include/openenv/embed.h:108 | One session: one environment instance and the state block it was given. |
oe_session_free | include/openenv/embed.h:139 | End the session: run the environment's fini callback, if it declared one, and mark the handle spent. |
oe_version | include/openenv/openenv.h:50 | Our version, "0.1.0". |
oe_err | include/openenv/openenv.h:78 | |
oe_err_name | include/openenv/openenv.h:97 | The identifier as text, for logs and test output — never for a peer. |
oe_arena | include/openenv/openenv.h:140 | |
oe_buf | include/openenv/openenv.h:145 | append-only, arena-backed byte buffer |
oe_arena_new | include/openenv/openenv.h:148 | NULL on OOM |
oe_arena_reset | include/openenv/openenv.h:149 | |
oe_arena_free | include/openenv/openenv.h:150 | |
oe_arena_ok | include/openenv/openenv.h:151 | |
oe_arena_used | include/openenv/openenv.h:152 | |
oe_json | include/openenv/openenv.h:184 | |
oe_kind_of | include/openenv/openenv.h:193 | |
oe_obj_get | include/openenv/openenv.h:194 | NULL when the key is absent, when obj is not an object, or when it is NULL. |
oe_len | include/openenv/openenv.h:198 | |
oe_at | include/openenv/openenv.h:199 | |
oe_key_at | include/openenv/openenv.h:200 | |
oe_val_at | include/openenv/openenv.h:201 | |
oe_as_str | include/openenv/openenv.h:203 | oe_as_str returns fallback when the string contains an interior NUL, because a const char * cannot represent one and a TRUNCATED string is worse than none: the validator would have seen safe ; rm -rf / and you would act on safe. |
oe_as_str | include/openenv/openenv.h:207 | |
oe_as_slice | include/openenv/openenv.h:208 | |
oe_as_int | include/openenv/openenv.h:209 | |
oe_as_real | include/openenv/openenv.h:210 | |
oe_as_bool | include/openenv/openenv.h:211 | |
oe_obj_get_str | include/openenv/openenv.h:213 | |
oe_obj_get_int | include/openenv/openenv.h:214 | |
oe_obj_get_real | include/openenv/openenv.h:215 | |
oe_obj_get_bool | include/openenv/openenv.h:216 | |
oe_obj_set_null | include/openenv/openenv.h:223 | |
oe_obj_set_bool | include/openenv/openenv.h:224 | |
oe_obj_set_int | include/openenv/openenv.h:225 | |
oe_obj_set_real | include/openenv/openenv.h:226 | |
oe_obj_set_str | include/openenv/openenv.h:227 | copies |
oe_obj_set_strn | include/openenv/openenv.h:228 | Like oe_obj_set_str, for bytes that may contain an interior NUL. |
oe_obj_set_json | include/openenv/openenv.h:231 | Deep-copies v, bytes and all, into the arena obj was born in — so the source may die immediately afterwards. |
oe_obj_set_obj | include/openenv/openenv.h:234 | nested |
oe_obj_set_arr | include/openenv/openenv.h:235 | |
oe_arr_add_bool | include/openenv/openenv.h:236 | |
oe_arr_add_int | include/openenv/openenv.h:237 | |
oe_arr_add_real | include/openenv/openenv.h:238 | |
oe_arr_add_str | include/openenv/openenv.h:239 | |
oe_arr_add_obj | include/openenv/openenv.h:240 | |
oe_arr_add_arr | include/openenv/openenv.h:241 | |
oe_json_obj | include/openenv/openenv.h:246 | |
oe_json_arr | include/openenv/openenv.h:247 | |
oe_json_parse | include/openenv/openenv.h:248 | |
oe_json_dup | include/openenv/openenv.h:249 | THE ONE ESCAPE FROM THE MEMORY RULE. |
oe_json_write | include/openenv/openenv.h:254 | compact bytes |
OE_REWARD_NULL | include/openenv/openenv.h:281 | |
OE_REWARD_BOOL | include/openenv/openenv.h:282 | |
OE_REWARD_INT | include/openenv/openenv.h:283 | |
OE_REWARD_REAL | include/openenv/openenv.h:284 | |
oe_fkind | include/openenv/openenv.h:356 | |
kind | include/openenv/openenv.h:371 | Which of the six type keywords the field publishes and which coercion the validator applies. |
oe_tool | include/openenv/openenv.h:398 | One tool, declared here and DEFINED in section 9. |
oe_env | include/openenv/openenv.h:428 | |
action_fields | include/openenv/openenv.h:454 | OE_FIELDS_END-terminated |
observation_fields | include/openenv/openenv.h:455 | schema only; the bytes we emit come from oe_obs, not here |
action_schema_json | include/openenv/openenv.h:457 | the one escape hatch: |
observation_schema_json | include/openenv/openenv.h:458 | a literal schema, sent verbatim. |
state_size | include/openenv/openenv.h:472 | zeroed per session; may be 0 |
init | include/openenv/openenv.h:474 | optional |
fini | include/openenv/openenv.h:485 | optional |
oe_server | include/openenv/openenv.h:581 | |
oe_serve | include/openenv/openenv.h:583 | blocks |
oe_serve_stop | include/openenv/openenv.h:585 | Async-signal-safe. |
oe_server_new | include/openenv/openenv.h:594 | Build a server without running it. |
oe_server_fds | include/openenv/openenv.h:596 | |
oe_server_tick | include/openenv/openenv.h:597 | Advance the server by whatever the descriptors above just reported. |
oe_server_poll | include/openenv/openenv.h:599 | polls internally |
oe_server_free | include/openenv/openenv.h:600 | |
oe_main | include/openenv/openenv.h:602 | main() for an environment binary: four flags plus a healthcheck subcommand, so a FROM-scratch container with no shell can still HEALTHCHECK itself by re-executing its own binary. |
oe_client | include/openenv/openenv.h:653 | |
oe_url_verdict | include/openenv/openenv.h:674 | WHY A URL WILL NOT BE DIALLED, WHICH IS NOT THE SAME QUESTION AS WHETHER THE SERVER IS UP. |
oe_url_verdict | include/openenv/openenv.h:683 | |
oe_client_url_verdict | include/openenv/openenv.h:693 | Never OE_URL_OK for a URL oe_client_open would answer OE_EUSAGE for, and never anything else for one it would dial. |
oe_client_reset_raw | include/openenv/openenv.h:730 | |
oe_client_step_raw | include/openenv/openenv.h:731 | |
oe_client_get | include/openenv/openenv.h:738 | One of the thirteen HTTP routes, on a connection of its own — the WebSocket is upgraded and is no longer an HTTP connection. |
oe_client_arena | include/openenv/openenv.h:764 | Results are borrowed and die at your next call on this handle. |
oe_tool_null | include/openenv/openenv.h:931 | |
oe_tool_bool | include/openenv/openenv.h:932 | |
oe_tool_int | include/openenv/openenv.h:933 | |
oe_tool_real | include/openenv/openenv.h:934 | |
oe_tool_str | include/openenv/openenv.h:935 | copies |
oe_tool_obj | include/openenv/openenv.h:936 | empty object, fill and forget |
oe_tool_arr | include/openenv/openenv.h:938 | |
oe_tool_fail | include/openenv/openenv.h:940 | The failure channel. |
args | include/openenv/openenv.h:1002 | the SAME table an action uses; it generates the argument schema. |
args_schema_json | include/openenv/openenv.h:1007 | the per-tool escape hatch, and the only way to publish a schema this generator cannot produce. |
host | src/client/client.h:35 | The name or numeric address to resolve: no brackets, no port, and NUL-terminated because the resolver is a C library function and takes a C string. |
port | src/client/client.h:59 | The TCP port: the one in the URL, or the scheme's default (80 for ws, 443 for wss). |
tls | src/client/client.h:63 | The URL said wss://. |
oe__client_dial_parse | src/client/client.h:71 | A ws:// or wss:// URL — the output of oe__client_ws_url — into the four things a socket needs. |
oe_res_msg | src/proto/client_codec.h:108 | |
oe_ws_decoded | src/proto/decode.h:90 | |
oe_http_decoded | src/proto/decode.h:162 | |
oe_diag | src/proto/errors.h:253 | The report. |
oe_diag | src/proto/errors.h:261 | |
oe__diag_init | src/proto/errors.h:268 | Zero the report and fix its origin. |
oe__diag_add | src/proto/errors.h:274 | Append one zeroed item and return it, or NULL when the report is full (which also latches overflowed). |
oe__diag_loc_key | src/proto/errors.h:279 | Append one element to an item's loc path. |
oe_rpc_todo | src/proto/jsonrpc.h:181 | |
oe_rpc_call | src/proto/jsonrpc.h:212 | One dispatched request. |
oe_rpc_call | src/proto/jsonrpc.h:219 | |
oe__rpc_message | src/proto/jsonrpc.h:272 | The composed message as a slice. |
oe_pyrepr | src/proto/pyrepr.h:46 | The result, and the storage behind it. |
oe_pyrepr | src/proto/pyrepr.h:49 | |
oe__routes | src/proto/routes.h:112 | The table itself, in registration order, and its length. |
oe__route_by_id | src/proto/routes.h:118 | A row by id, or NULL for OE_ROUTE_NONE and for anything out of range. |
oe__route_id_name | src/proto/routes.h:121 | The identifier as text, for logs and test output. |
OE_SCHEMA_NAME_MAX | src/proto/schema.h:112 | The longest field name, and the longest environment name, this generator will render a title for. |
oe_schema_fault_kind | src/proto/schema.h:130 | |
oe_schema_fault | src/proto/schema.h:168 | Everything the server needs to name the mistake in one log line: |
oe_schema_fault | src/proto/schema.h:176 | |
oe__schema_fault_init | src/proto/schema.h:189 | |
oe__schema_fault_name | src/proto/schema.h:190 | |
oe__tool_out_init | src/proto/tool.h:59 | Zero out, record which door this call arrived on, and pre-create the result as JSON null in a. |
oe_tool_msg | src/proto/tool.h:257 | The storage, on the caller's stack, exactly like oe_pyrepr: the result is a C string inside it and dies with it. |
oe_tool_msg | src/proto/tool.h:260 | |
oe__verr_add | src/proto/validate.h:119 | Append one item to a report and stamp its type and msg from the slug, which is the only pair of fields that must always agree. |
oe__validate_check_defaults | src/proto/validate.h:181 | Parse every json_default in a table and coerce it to its declared kind. |
oe_version | src/proto/value.c:56 | OUR version, and not the protocol's — there is no protocol version anywhere in OpenEnv. |
oe_framing | src/server/conn.h:131 | Three answers, and the third one is the interesting one: REFUSED does not mean "malformed", it means THIS WILL NEVER BECOME A WHOLE MESSAGE — stop reading and answer with what you have. |
oe_framing | src/server/conn.h:136 | |
oe_req_scan | src/server/conn.h:142 | The cursor the HTTP predicate carries between calls. |
oe_req_scan | src/server/conn.h:151 | |
oe__request_complete | src/server/conn.h:157 | Is one whole HTTP request resident in p[0..n)? |
oe__ws_frame_complete | src/server/conn.h:160 | Is one whole WebSocket frame resident in p[0..n)? On COMPLETE, *out_len is the frame's total size, header included. |
oe_conn_state | src/server/conn.h:177 | |
oe_conn_cfg | src/server/conn.h:191 | Everything a connection needs to know about the server it belongs to, as one const block every connection points at rather than eight copies. |
oe_conn_cfg | src/server/conn.h:198 | |
oe_conn | src/server/conn.h:209 | One connection. |
oe_conn | src/server/conn.h:222 | |
oe__conn_open | src/server/conn.h:296 | Take an accepted descriptor. |
oe__conn_close | src/server/conn.h:302 | Release the session (running the environment's fini), close the descriptor and reset the arenas so the slot is ready for the next peer. |
oe__conn_release | src/server/conn.h:307 | Free the two arenas. |
oe__conn_events | src/server/conn.h:311 | Which readiness this connection is waiting for, as OE_POLL_* flags. |
oe__conn_finished | src/server/conn.h:315 | True once the connection has said everything it had to say. |
oe__conn_expired | src/server/conn.h:318 | True when the pre-upgrade deadline has passed. |
oe__conn_recv | src/server/conn.h:321 | The socket half: read what is available into the input buffer, write what is pending out of the output buffer. |
oe__conn_advance | src/server/conn.h:327 | The state machine half: consume every complete message the input buffer holds and append every answer they are owed. |
oe__conn_feed | src/server/conn.h:333 | Push bytes into the input buffer as though they had arrived on the socket, and report how many fitted. |
oe__conn_pending | src/server/conn.h:339 | The outbound half of the same pair: what the connection still owes the peer, and how much of it has left. |
oe__conn_going_away | src/server/conn.h:349 | Begin a graceful shutdown of this connection: an open WebSocket is told 1001 "going away", anything else is closed once its answer has drained. |
oe__log | src/server/conn.h:356 | One diagnostic line. |
oe__srv_const_route | src/server/handlers.h:36 | The constant surface: /health, /metadata, /schema, /openapi.json, and the six Task API rows. |
oe__srv_stateless_route | src/server/handlers.h:56 | The stateless mirror: POST /reset, POST /step, GET /state. |
oe__srv_mcp_route | src/server/handlers.h:63 | POST /mcp. |
oe__srv_mcp_bytes | src/server/handlers.h:70 | The JSON-RPC exchange itself, in whichever framing the caller arrived in. |
oe__srv_detail_body | src/server/handlers.h:99 | {"detail":"<text>"} — Starlette's shape for a plain HTTP error, inferred from the two the corpus pins ({"detail":"Not Found"} and {"detail":"Method Not Allowed"}) and applied to the three bodies this program composes: the reason phrase of a status the corpus does not contain, the Task API's second 404, and its 501. |
oe__srv_our_fault | src/server/handlers.h:109 | WHOSE FAULT WAS IT — the one thing an error code cannot say on its own. |
oe__srv_http_refusal | src/server/handlers.h:128 | THE ONE ANSWER THAT CAN STILL BE COMPOSED WHEN NOTHING ELSE CAN. |
[POLICY]
| Symbol | Where | Note |
|---|---|---|
oe_log_fn | include/openenv/openenv.h:510 | Where our diagnostics go. |
port | include/openenv/openenv.h:519 | 0 => 8000. |
host | include/openenv/openenv.h:524 | NULL => "0.0.0.0" (the observed value) |
production | include/openenv/openenv.h:526 | false => simulation mode, the default and what every corpus server but one was captured in. |
max_connections | include/openenv/openenv.h:547 | 0 => 64. |
trace | include/openenv/openenv.h:552 | dump every frame, both directions |
log | include/openenv/openenv.h:553 | NULL means silence |
log_ctx | include/openenv/openenv.h:554 | handed back to log untouched |
install_signals | include/openenv/openenv.h:556 | default true for the shipped binaries; false leaves SIGTERM/SIGINT/SIGPIPE untouched, which an embedder needs. |
stop | include/openenv/openenv.h:567 | NULL => we use our own self-pipe. |
oe_client_opts | include/openenv/openenv.h:655 | |
OE_RPC_MSG_MAX | src/proto/jsonrpc.h:120 | The longest message this file will compose, in bytes. |
oe__serve_log_stderr | src/server/serve.h:21 | The log sink the shipped binaries install: one line per record on stderr, prefixed with its level, and nothing at all when tracing is off. |
oe__serve_probe_health | src/server/serve.h:27 | One HTTP request against a running server, for the healthcheck subcommand: connect, GET /health, read the status line, hang up. |
The other boundary — SAFETY:
The threat model is one sentence: every byte from the socket is hostile. There is no authentication, no CORS and no TLS anywhere in OpenEnv, so anyone who can reach the port can reach the parser. Isolation is the container's job; refusing to crash is ours.
A SAFETY: marker is one line at a check that exists because the input is
hostile, as opposed to because the format requires it. Below is every one of
them. SECURITY.md is the argument these are the conclusion of.
| Where | The check |
|---|---|
src/client/client.c:276 | the two spans below are written into the request line and the Host header by src/wire/ws.c, which does not inspect them. A CR or LF here would let a caller's URL write a header of its own choosing into our request, so the alphabet is checked once, here, at the parse. |
src/client/client.c:700 | the declared length is a claim. It is checked against the ceiling by SUBTRACTION, so the comparison cannot itself overflow, and the buffer is only grown to a length that has already passed. |
src/client/client.c:1476 | this is spliced into a request line. It is our own caller's string rather than a peer's, and it is checked all the same — the alphabet is the one the dial parser applies to a URL, for the same reason: a space would end the target early and a CR would end the line. |
src/proto/decode.c:303 | the dedup test below is a backwards scan of this same object, so the loop is O(n^2) in the number of keys the peer sent — 128,000 of them measured at eighteen seconds of single-threaded CPU, from one unauthenticated 1.8 MB frame, on a program that runs one process by design (see OE_MAX_SESSIONS in wire/limits.h) — so that is the whole server wedged. Once the report has overflowed no later key can change a byte of the answer, so stopping here is byte-identical and bounds the total work at 33 scans. |
src/proto/decode.c:332 | loc is the peer's own key and input is the peer's own value. Neither is formatted into anything — both reach the wire only as JSON nodes handed to the writer, which escapes them. |
src/proto/decode.c:562 | the peer's bytes, reflected. They reach the wire only as a JSON string node handed to the writer, which escapes them and refuses to emit them if they are not UTF-8 — in which case the caller's one error check turns the 422 into the 400 of H_BAD_BODY (src/proto/errors.c, the OE_EUTF8 row), because on this path OE_EUTF8 means exactly what it says: the REQUEST BODY was not UTF-8. Observed: POST /step with content-type: text/plain and a body of \xff\xfe\xff answers 400 {"detail":"There was an error parsing the body"}. This is the one place that mapping is right; server-composed strings take the other route, through oe__srv_our_fault in src/server/handlers.h, and land on WART-19's 500. |
src/proto/decode.c:905 | the peer's own key and value, reaching the wire only as JSON nodes handed to the writer, exactly as check_envelope_extras reflects the envelope's own extras one level up. |
src/proto/errors.c:650 | an extra_forbidden loc is the attacker's own key. It reaches the wire only here, as a JSON string node handed to the writer, which escapes it and refuses it if it is not UTF-8. |
src/proto/errors.c:765 | the cap and the marker, argued in errors.h section 4a and applied at all FOUR of the program's reflection sites from here — errors.c:799 (the UNKNOWN_TYPE detail), src/server/http_const.c (the Task API's environment name), src/proto/jsonrpc.c's put_reflected (which serves three sentences: an unknown session id, an unknown method, and the agent door's Tool not found: <name>), and src/proto/tool.c (the trainer door's Unknown tool: '<name>'). The last is the newest and the one an attacker reaches most cheaply, since a tool name is a string a peer picks outright. |
src/proto/errors.h:372 | for UNKNOWN_TYPE this is the peer's own type value, rendered by src/proto/pyrepr.c and echoed back. It reaches the output only as a JSON string node handed to the writer, and errors.c puts it through oe__reflect — cap plus marker — before it goes anywhere. Every other code's detail is ours or the embedder's. |
src/proto/jsonrpc.c:218 | the two places this file echoes a peer's bytes back INSIDE a sentence rather than as a value of its own — an unknown method name, and an unknown session id. Capped at OE_REFLECT_MAX, the same cap the Task API's reflected environment name gets, with the cut moved back to a character boundary. Everything else in a message is ours. |
src/proto/jsonrpc.h:127 | the composer fills this buffer and stops, then moves the cut back to a UTF-8 character boundary, so an over-long message reaches the peer as a PREFIX of the right message rather than as an invalid string that would cost the whole frame (RFC 6455 section 8.1). The longest message the corpus pins is 352 bytes, so a kibibyte is threefold slack and still a fixed member of a struct a caller declares on its stack. |
src/proto/jsonrpc.h:309 | the id is the peer's own bytes coming back, capped at OE_REFLECT_MAX on a character boundary, and it reaches the wire only as a JSON string node handed to the writer. |
src/proto/jsonrpc.h:345 | the name is the peer's own bytes coming back inside a sentence, capped at OE_REFLECT_MAX on a character boundary, exactly like the two reflections above it. |
src/proto/routes.h:149 | env_name is attacker-controlled and reaches an output buffer only as a JSON string node handed to the writer. *env_name is left untouched when the match is not a templated one, so a caller that forgets to check templated gets whatever it initialised, never a stale slice. |
src/proto/tool.c:341 | THE PEER'S OWN TOOL NAME, REFLECTED — the newest of the four sites errors.h section 4a governs, and the one an attacker reaches most cheaply, since a tool name is a string a peer picks outright. oe__reflect caps it at OE_REFLECT_MAX on a UTF-8 character boundary and OE_REFLECT_MARK says that it did, so a truncation cannot be read as a short name. The buffer bound is not argued but PROVED, by the oe__tool_msg_fits array below: prefix + cap + marker + terminator must fit OE_TOOL_MSG_MAX or the file stops compiling. Measured against build/san/bin/echo_tools: a 300-byte name comes back as 64 bytes and ..., where the reference echoes all 300. |
src/proto/validate.c:354 | the ceiling is fixed before the loop so the overflow test can be a division, which cannot itself overflow, rather than a multiplication that has already wrapped by the time it is examined. |
src/proto/validate.c:483 | THE RANGE IS DECIDED ON THE DOUBLE SIDE, BEFORE A CAST EXISTS TO BE UNDEFINED. C99 6.3.1.4 says a floating-to-integer conversion whose integral part is outside the target type's range is UNDEFINED — not lossy, not implementation-defined — and the idiom this replaces, d != (double)(int64_t) d, is that undefined conversion written twice. It is reachable from one unauthenticated request: the JSON grammar has no bound on a number's length, so {"action":{"amount":1e400}} arrives as OE_REAL holding +inf, and a ninety-five-digit integer arrives as OE_REAL holding 6.7e94, because a number too large for int64_t is kept as a real (which is what CPython's arbitrary- precision ints degrade to here). On a sanitized build the conversion aborts, which makes one POST a remote kill. |
src/proto/validate.c:832 | the duplicate-key test below is a backwards scan of this same object, so without this the loop is O(n^2) in the number of keys the peer sent — measured at 4.7 seconds of CPU for one 900 KB action. Once the report has overflowed no later key can change a byte, so stopping is byte-identical and bounds the work at 33 scans. The same three lines guard the other two extra="forbid" loops, in src/proto/decode.c and src/server/http_const.c. |
src/server/conn.c:62 | detail is routinely the peer's own bytes — a request target, a frame payload — and a log line is a place an attacker would like to write a newline followed by a plausible entry of their own. Every byte outside printable ASCII becomes a dot, so nothing they send can be more than one character wide and none of it can end the line. |
src/server/conn.c:785 | a full buffer that still holds no whole request cannot ever hold one. It is not reachable today — the head cap is enforced by the scan and the body cap by the parser, and the buffer is grown to fit whatever survives both — and it is here so that a future cap which does not add up ends as a closed socket rather than a spin. |
src/server/http_const.c:72 | text may contain a path segment the peer chose. It reaches the output only here, as a JSON string node handed to the writer, which escapes it and refuses to emit it if it is not UTF-8. There is no format string anywhere on this path. |
src/server/http_const.c:306 | the duplicate-key test below is a backwards scan of this same object, so without this the loop is O(n^2) in the number of keys the peer sent — 40,000 of them in a 560 KB body measured at 1.9 seconds of CPU. Once the report has overflowed no later key can change a byte, so stopping is byte-identical and bounds the work at 33 scans. The same three lines guard the other two extra="forbid" loops, in src/proto/decode.c and src/proto/validate.c. |
src/server/http_const.c:496 | the reflected segment is the peer's own bytes, put through oe__reflect — capped at OE_REFLECT_MAX on a character boundary so an over-long path cannot inflate a response, and MARKED when the cap fired so the peer can tell sixty-four bytes from a truncation of six hundred. The reference caps nothing here; errors.h section 4a is the argument. It is written as a JSON string node either way, so it cannot forge a key. |
src/wire/arena.c:129 | rounding up is the classic place a size wraps — align_up(SIZE_MAX) is a very small number, and a small buffer returned for a gigantic request is a heap overflow with attacker-controlled length. The addition is checked rather than masked, so an unroundable size is refused instead of shrunk. |
src/wire/arena.c:146 | the budget test is a subtraction on the LIMIT, never reserved + n > limit, because that addition is the one an attacker-supplied n makes wrap — and a wrapped comparison passes. |
src/wire/base64.c:51 | the arithmetic happens before the first byte is written, so a failure here leaves the destination untouched. |
src/wire/buf.c:118 | the required capacity is the sum of two sizes, one of which came off the wire. It is added with a check, not with a +, because a wrapped total is a small allocation followed by a large memcpy. |
src/wire/http.c:72 | the target is the one attacker-controlled span this file ever writes back out, in the location of a 307. The alphabet is enforced in TWO places — here, on the way in, and again in res_is_writable() on the way out — and that is not belt-and-braces, it is the only way the property holds for every caller. Enforcing it at parse time alone makes header injection impossible only for slices that came out of THIS file's parser; oe_http_res_write is public, the router above will hand it values routing chose, and a percent-decoded path (see the note at the top of http.h) can contain CR, LF and NUL by construction. |
src/wire/http.c:347 | this value is reflected into the location of a 307, so it is held to the target's alphabet and not the looser one every other field value gets. |
src/wire/http.c:522 | the gate for every span this writer reflects. Four of the six fields of an oe_http_res are spans a CALLER chose, and three of them come from the peer by way of the router. A CR or an LF in any of them ends the header block early and everything after it is a second response of the attacker's design — verified: a target carrying CRLF produces location: http://h/health\r\n x-injected: yes\r\n\r\nHTTP/1.1 200 OK.... |
src/wire/json_parse.c:231 | divide the ceiling rather than multiply the accumulator, so the overflow test cannot itself overflow. |
src/wire/json_parse.c:564 | tested BEFORE the recursion, so a megabyte of {"a": — the largest document a server will read — costs OE_JSON_MAX_DEPTH stack frames and not one more. A depth cap applied after the call is a cap on the error message, not on the stack. (A megabyte of bare '{' is not the interesting attack: it is a missing property name, refused at byte 1, before any recursion.) |
src/wire/json_parse.c:633 | the same cap, tested the same way, for the same reason as in oe_json_object above — and this is the shape an attacker actually sends, because '[' needs no key to nest. |
src/wire/json_write.c:445 | a text frame carrying malformed UTF-8 obliges the peer to drop the connection (RFC 6455 section 8.1), so one bad byte from a caller costs the whole session. Refusing here turns that into an error the caller can answer with a well-formed frame. Strings that came from json_parse.c are already known good; this catches the ones that did not. |
src/wire/json_write.c:502 | the cap json_parse.c applies on the way in, PLUS the echo headroom argued at OE_JW_MAX_DEPTH, applied again on the way out. A tree assembled in memory is not bounded by anything a parser checked, and oe_jw_json below recurses once per level. The headroom is what lets a value read at the parser's limit be written back inside an envelope. |
src/wire/net.c:79 | read() and write() take a size_t but return a signed ssize_t, and a transfer larger than SSIZE_MAX is undefined behaviour rather than an error. Our own caps make this unreachable; it is here because "unreachable" is a property of today's callers and this is a property of the function. |
src/wire/net.c:859 | DISARM BEFORE CLOSING. A closed descriptor number is immediately reusable, and the signal handler holds the number, not the pipe. Left armed, the next open() or accept() takes the same number and the next SIGTERM writes 0x01 into it — reproduced: wake write-end fd = 4 / newly opened fd = 4 (SAME NUMBER) / bytes injected by the handler: 1. In a server that number is overwhelmingly likely to be a live client socket, so a shutdown signal would put a stray byte into a WebSocket stream (the peer reads it as a continuation-frame header and hangs up with 1002), or into the listening socket, or into a log file. It is the one write in the program to a descriptor nobody named. |
src/wire/net.c:931 | ONE ARMED PIPE PER PROCESS, AND THE SECOND CALLER IS REFUSED RATHER THAN QUIETLY SERVED. A signal handler takes no argument, so there is exactly one oe_wake_fd and whichever server armed last would own every SIGTERM — the first server would then never learn it had been asked to stop, and worse, freeing either one restores every disposition and disarms the other. Refusing here is what makes that visible: oe_server_new treats a failed install as non-fatal, so a second server in the same process simply runs without handlers and its embedder can still call oe_serve_stop(), which needs no signal at all. The alternative — taking over silently — is a program that appears to work and ignores a signal. |
src/wire/net.c:969 | the global is restored if sigaction fails. Assigning it first and leaving it assigned on the failure path is the same misdirected-write bug oe_net_wake_close guards against, reached the other way round: the first pipe's handler would still be installed and would now be writing into the second pipe. |
src/wire/net.c:1017 | zeroed first, so that a caller who ignores the return value gets a conspicuously wrong value instead of an interesting one assembled from whatever the stack happened to be holding. |
src/wire/sha1.c:108 | memcpy with a null source is undefined even for zero bytes, and "hash nothing" is a perfectly ordinary call. Leave before touching p. |
src/wire/str.c:131 | the overflow test divides the ceiling instead of multiplying the accumulator, so the check itself never wraps. v * 10 + d evaluated first and compared afterwards is the classic form that lets a nineteen-digit length become a small one. |
src/wire/str.h:190 | these two are security-critical, and they are the reason this file bans atoi and sscanf rather than merely disliking them. Every length a peer declares arrives as text and passes through here: an HTTP Content-Length, a WebSocket 126/127 payload length once it has been read as digits, a chunk size. A parser that saturates, wraps, or reports 0 for both "0" and "not a number" hands an attacker the difference between the length we believe and the length we read. |
src/wire/utf8.c:87 | classified through unsigned char, never plain char. On a signed- char target b[i] >= v->lo on a byte of 0x80 compares -128 against 128 and every multi-byte character in the stream would be rejected — or, with the comparison written the other way round, accepted. |
src/wire/ws.c:36 | a repeated field is refused rather than resolved. HTTP permits a repeat only where the value is a comma-list, and none of these four is one, so two Sec-WebSocket-Key fields mean two parties disagree about what we are about to answer. Picking one is how a request-splitting bug starts; counting them and saying no is one line. |
src/wire/ws.c:235 | no fallback. §4.1 wants a nonce "selected randomly"; its job is to stop a cache from replaying somebody else's completed handshake at us, and a value derived from the clock does not do that job. If the kernel will not give us entropy we do not connect. |
src/wire/ws.c:656 | residency is decided by SUBTRACTION on what we hold, never by header_len + payload_len > n, which is the addition that wraps and lets a 2^64-3 byte claim look like a frame that has already arrived. |
src/wire/ws.c:701 | the WHOLE frame is reserved before one byte of it is written. Writing the header first and discovering afterwards that the payload does not fit leaves a bare header announcing bytes that are not there — and oe_ws_send_close is called on the out-of-memory path, by a caller that is already failing and deliberately ignores the return, so that truncated header is what would actually go on the wire. oe_buf_reserve latches on refusal, so past this line the two appends below cannot fail independently and "half a frame is never mistaken for a frame" is a fact rather than an intention. |
src/wire/ws.c:774 | oe_utf8_truncate finds a code-point boundary; it is NOT a validator, and it hands back the length unchanged when the byte it walked to is not a lead byte at all (see wire/utf8.h). So the bytes are checked here, before they are copied. §5.5.1 says the reason is UTF-8, and a Close whose reason is not obliges the peer to answer 1007 — turning our goodbye into its error. Every reason inside this library is an ASCII literal, so this is unreachable today; it stops being unreachable the first time the layer above wants an application message in a Close, which is a natural thing to want. Dropping the reason keeps the code, which is the half that carries the meaning. |
src/wire/ws.c:956 | the cap is on the ACCUMULATED message, checked before every append. A per-frame cap alone lets a thousand maximal continuation frames assemble sixteen gigabytes one legal frame at a time. |
src/wire/ws.c:1072 | rule 3 has already bounded a control payload at 125, and this says so a second time in the language the compiler checks — because the destination is a fixed array and a bound that is only true elsewhere is a bound that a future edit can delete without noticing. |