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.
The split, and where each half is tested
| Half | Where | What it decides | How it is tested |
|---|---|---|---|
| the protocol | src/proto/client_codec.c | the 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 to | tests/t_client.c parts 1–5, and every recorded server frame in the corpus, with no socket |
| the host | src/client/client.c | when to read, how long to wait, what a closed socket means, and how large a buffer to grow | tests/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.
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.
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.
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:
rewardanddonecome off the TOP LEVEL ofdata(MUST 8.B.12). They are moved there, not copied: the reference dumps the inner model withexclude={"reward","done"}(serialization.py:155-160), so the two keys are absent from the nestedobservationobject — 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.rewardisnull,true,false, an integer or a float (MUST 8.B.13). Adoublefield silently turnstrueinto a number nobody sent, and this transport coerces nothing — the coercion is the HTTP encoder's, and that is the other transport.- Unknown keys inside
observationare 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.
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.
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/.
| Marker | Means |
|---|---|
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.
Two honest limits, stated here rather than discovered
No TLS.
wss://is refused atoe_client_openwith a sentence naming the problem, not attempted and failed. The reference's own HF Spaces provider answers this by running a local plaintext proxy and pointing the client at it (hf_sandbox_provider.py:286-292), which is the same answer.No background pong. The pong this client owes a server's ping is written when you next call, not by a thread you did not ask for. The reference server pings at 20 s and closes at 40 s (uvicorn's stock
ws_ping_intervalandws_ping_timeout; measured — a step at 30 s idle isOE_OK, the same step at 42 s isOE_EOFwith keepalive ping timeout). Since OpenEnv has no session id, a reconnect is a new environment instance, so the rollout is lost rather than delayed.oe_client_pump(c, 0)is the answer where a thread would have been: it reads whatever control frames have arrived, writes the pongs they oblige, and returns. Put it in your think loop. It is the one call on a handle that does not obey the memory rule: the previous result is still live afterwards. A keepalive that invalidated the observation you are reasoning about would be unusable in the loop it exists for.