miniopenenv

src/client/README.md → html

src/client/ — driving the protocol from the other end

grep -c . src/client/client.c              # the whole client, comments included
grep -rn 'oe_ws_\|oe_net_' src/proto/      # -> nothing. The protocol dials nothing.
./build/rel/tests/t_client                 # the suite; part 6's cases open a socket

Two files, and one of them is a header describing a struct with six members. That is the entire client, and it is small for the same reason the server is small: every byte it sends and every rule it applies to what comes back lives in src/proto/client_codec.c. That file makes no system call and is tested with no port open.

§ 1 · The split, and where each half is tested

The split, and where each half is tested

HalfWhereWhat it decidesHow it is tested
the protocolsrc/proto/client_codec.cthe five messages a client may send, the four it may receive, which fields come from the top level, and the URL a base URL derives totests/t_client.c parts 1–5, and every recorded server frame in the corpus, with no socket
the hostsrc/client/client.cwhen to read, how long to wait, what a closed socket means, and how large a buffer to growtests/t_client.c part 6, which forks our own server and drives a real episode

client.h is the seam between them: it holds oe_dial, which is what is left of a URL once the protocol has finished with it. That is a host for the resolver, a port, the authority for the Host header, and the request target. Splitting it out is what lets the table of URLs a client will and will not dial be a test rather than a paragraph.

§ 2 · The shape of the whole thing

The shape of the whole thing

    one request frame  ->  block  ->  exactly one response frame

There is no pipelining, no correlation id, no session id and no server-initiated message, so there is no state machine, no queue and no callback. Every entry point is that line with a different type in it. The protocol's own words for this are MUSTs 8.B.7 and 8.B.16 in docs/PROTOCOL.md, which is where all twenty client requirements are published. Those are the requirements cited by number from this directory, from src/proto/client_codec.c and from the installed header.

§ 3 · One handle, one thread

One handle, one thread

An oe_client is single-thread-confined. Every call on a given handle must be made from one thread, and two calls on one handle must never overlap. This is not a lock that could be bolted on later. The handle is a single socket descriptor, three arenas that are reset out from under you at the top of almost every call, one read buffer grown and moved between reads, and a dead latch. Those are the six mutable members of struct oe_client, and there is no synchronisation over any of them. Two threads sharing one handle interleave read/write on the same fd and reset an arena while the other is still reading its result: a data race, not a slow path. There is deliberately nothing to lock, because lock-step already means a handle is doing exactly one thing at a time.

What is concurrent is a handle per thread. The client keeps no process-global mutable state: no registry, no shared buffer, no cached connection. So N threads each holding their own oe_client, each dialled to their own server, run without interference. That is the intended shape for parallel rollouts: one connection, one environment instance, one thread, N times over. The confinement is a contract this library requires, not a guarantee it makes — it adds no mutex and promises none.

§ 4 · Three rules a plausible client gets wrong

Three rules a plausible client gets wrong

Each of these has a case in tests/t_client.c named after it, and each is a place where being reasonable is being wrong:

  1. reward and done come off the TOP LEVEL of data (MUST 8.B.12). They are moved there, not copied: the reference dumps the inner model with exclude={"reward","done"} (serialization.py:155-160), so the two keys are absent from the nested observation object — not present-and-default, absent. Not one observation payload in the captured corpus carries either one, on either transport. Two shipped upstream environments read them from in there anyway; see below.
  2. reward is null, true, false, an integer or a float (MUST 8.B.13). A double field silently turns true into a number nobody sent, and this transport coerces nothing — the coercion is the HTTP encoder's, and that is the other transport.
  3. Unknown keys inside observation are normal (MUST 8.B.15). An observation is whatever the environment declared; a client that refused a key it had not heard of would work against exactly one environment.

Why a reasonable client reads the wrong place, and what it sees when it does

The trap is in the schema, not on the wire. GET /schema publishes done and reward as properties of the observation, with defaults false and null. That document is generated from the model that declares them, and the exclusion happens later, at dump time. Generate your parser from the schema and you will look inside the observation — and find nothing there.

What you report then is your own lookup default, not a value any server sent. That distinction is the whole of it: false from a missing key is indistinguishable, in the answer, from false on the wire, and no error is raised on the way past. In the reference tree, envs/chess_env/client.py:73-74 reads obs_data.get("done", False) and obs_data.get("reward", 0.0) and hands both back as the step's own result. envs/sumo_rl_env/client.py:107-108 does the same into its observation object. That one then reads the top level for its StepResult, so only half of it is wrong — which is why the bug survives review. An episode that never ends and a reward that is never paid, both supplied by a default argument.

Run it:

make demo-two-readers

That target reads one recorded observation two ways and prints both answers side by side. It walks every observation payload in the captured corpus asserting that zero of them carry a nested reward or done, and it fails if any of that stops being true. The cases behind it are reward_and_done_are_read_from_the_top_level and the_nested_keys_are_absent_from_every_recorded_observation in tests/t_client.c.

§ 5 · The one number that is not the server's

The one number that is not the server's

OE_WS_MAX_FRAME_CLIENT is 512 KiB, twice OE_WS_MAX_FRAME, and both halves of that sentence carry an argument.

Why larger: a server chooses what it will accept, a client must accept what the peer sends. A server is dialled by strangers, sixty-four at a time, and its per-frame cap is a memory budget multiplied by that number. A client is dialled out to one address its operator chose, and it holds one peer. What that peer sends is an observation — one shipped upstream environment's is 403,316 bytes in a single unfragmented frame, measured, which the server's cap would refuse.

Why not larger still: the frame is only the beginning. What arrives is a document, and a document has to be parsed into this handle's message arena at up to 128.23 bytes of arena per byte of source — measured. The worst shape is neither a dense integer array (59.00) nor an array of one-element arrays (93.25) but an array of [ chains one level short of OE_JSON_MAX_DEPTH. So the cap is OE_CLIENT_MSG_ARENA_MAX / OE_JSON_ARENA_PER_BYTE = 128 MiB / 256, and not a number picked for how it sounds. It was 16 MiB, and a caller met an inner cap at between 1.05 MB and 4.19 MB depending on the SHAPE of the payload, with an error naming a constant nobody had advertised.

And the divisor was measured twice. It was 128, from a sweep over one shape family's inner length that never varied depth — under the true 128.23. So the division came out exact, the static assertion passed, and a maximal document of the deep shape was still refused with OE_ENOMEM at 523,775 bytes over a real socket. That is the same defect one layer up, and it is why tests/t_client.c parses a maximal document of the deep shape rather than trusting arithmetic over a measurement.

What this means for you: one number, OE_ETOOBIG past it, for every payload shape that has been measured — five families, bisected over a real socket, all stopping at 524,288 bytes. A payload over half a megabyte is refused, including string-shaped ones the old cap would have carried. So an environment shipping appreciably more than 100,800 integers per message needs the constant raised, and raising it means raising OE_CLIENT_MSG_ARENA_MAX with it. Three static assertions in client.c will not let you do one without the others — the third covers the thirteen HTTP describing routes, which parse into the same arena and were unreconciled until it existed. Budget 128 MiB per handle worst case: it is a ceiling, not a reservation, and an ordinary exchange costs a few kilobytes.

wire/limits.h carries the argument beside every constant, and wire/ws.c rule 7 is the single branch that picks between the two frame caps. In tests/t_client.c, one_frame_two_caps_and_the_reader_decides_which pins the split, and the_advertised_cap_is_a_document_this_client_can_actually_parse pins the promise.

§ 6 · Marker polarity

Marker polarity

Everything in this directory is our own hosting decision unless a marker says it is not — the same polarity as src/server/, and the opposite of src/proto/.

MarkerMeans
WART-##:the reference does this odd thing and we reproduce it — four lines: claim / reference / observed / honoured-by
GAP-##:nobody specified this and we chose — three lines: unspecified / we chose / a different implementer might
CONF-##:this line satisfies a numbered conformance MUST — one line
SAFETY:this check exists because the input is hostile — one line
POLICY:this is our free choice and yours to change

make docs turns them into docs/WARTS.md, docs/GAPS.md and docs/BOUNDARY.md, and make check fails when any of the three goes stale.

§ 7 · Two honest limits, stated here rather than discovered

Two honest limits, stated here rather than discovered