miniopenenv

docs/PACKAGING.md → html

Packaging, embedding, and the container

This page is packaging: how to get this library into your build, and how to ship it as a container. Four ways to consume it and one way to ship it, all of them tested by something that runs:

make install PREFIX=/usr/local   # and uninstall, both honouring DESTDIR
make check-embed                 # three third-party consumers, each really built and run
make docker                      # FROM scratch, then prove the container contract

make check-embed and make docker are not part of make check. One writes files and shells out to pkg-config; the other needs a docker daemon and a network to pull alpine with. make check stays hermetic and runs in about eight seconds on this machine. Both skip loudly, with the reason printed, when a tool is missing — never silently, and never as a pass.

Every number and every transcript below is real output from this machine (Linux 7.1.4, gcc 16.1.1, docker 29.6.2, pkgconf 3.0.3). Where a thing could not be measured here, it says so instead of guessing.


§ 1 · make install

1. make install

$ make install PREFIX=$TMP/opt
  $TMP/opt/lib/libopenenv.a
  $TMP/opt/include/openenv/embed.h
  $TMP/opt/include/openenv/openenv.h
  $TMP/opt/lib/pkgconfig/openenv.pc
  $TMP/opt/bin/openenv-counter
  $TMP/opt/bin/openenv-echo
  $TMP/opt/bin/openenv-rewards
  $TMP/opt/bin/openenv-agent
  $TMP/opt/bin/openenv-probe
install: openenv 0.1.0 -> $TMP/opt

Nine files. One archive, two headers, one .pc, five programs.

The binaries are renamed, and that is not cosmetic. envs/echo.c builds a program called echo. Copying that to /usr/local/bin/echo is how you find out which of /usr/local/bin and /bin comes first in your PATH — at two in the morning, from a shell script that has stopped working. Everything installed is openenv-*, and the examples' leading oe_ is dropped so the prefix is not spelled twice. The rename happens in the install recipe rather than in the build, so the names inside the tree stay the names the documentation uses.

Nothing from tour/ is installed. tour/01_minimal.c opens with a banner saying it has no length caps, no timeouts and no depth limit and must not be exposed. Putting it on PATH would be this repository contradicting its own loudest warning. tools/embed.sh asserts the absence, and derives the list from the directory rather than naming files, so a tour program added next year is covered on the day it lands.

make uninstall removes exactly those nine paths and then rmdirs $(INCLUDEDIR)/openenv, the one directory this project owns outright. It does not remove bin, lib or include, because it did not create them:

$ make uninstall PREFIX=$TMP/opt
uninstall: openenv removed from $TMP/opt
$ find $TMP/opt
.
./bin
./include
./lib
./lib/pkgconfig

Empty directories, no files. tools/embed.sh runs the same sequence against a DESTDIR staging tree and fails if find -type f returns anything.

PREFIX versus DESTDIR, which is the whole of correct staging

PREFIX is where the files will BE. DESTDIR is where they are being PUT.

Every path the install recipe writes to is $(DESTDIR)$(SOMEDIR). Every path it writes into a file is $(SOMEDIR) alone. That single asymmetry is the entire discipline. make install DESTDIR=/tmp/stage PREFIX=/usr/local produces this (the file's forty-four-line comment header is elided here; the substance is the eleven lines below it, unaltered):

$ cat /tmp/stage/usr/local/lib/pkgconfig/openenv.pc
...
prefix=/usr/local
exec_prefix=${prefix}
libdir=${prefix}/lib
includedir=${prefix}/include

Name: openenv
Description: The OpenEnv protocol in C99 — two headers, one static library, no dependencies
URL: https://github.com/ericflo/miniopenenv
Version: 0.1.0
Cflags: -I${includedir}
Libs: -L${libdir} -lopenenv

prefix=/usr/local, not /tmp/stage/usr/local. The tarball that staging directory becomes will be unpacked at /. A .pc that recorded the staging path would send every consumer of the package to a directory that existed on the build machine for four seconds. tools/embed.sh greps the installed file for the DESTDIR it just used and fails if it finds it.

libdir=${prefix}/lib is unexpanded on purpose. It is what lets somebody point pkg-config at a staging tree from outside, with no edit — which is also what a cross-compile does with a sysroot:

PKG_CONFIG_PATH=<stage>/usr/local/lib/pkgconfig \
pkg-config --define-variable=prefix=<stage>/usr/local --cflags openenv

The Makefile rewrites $(LIBDIR) back into terms of ${prefix} on its way into the file, and only when it genuinely starts with the prefix. Somebody who says LIBDIR=/usr/lib64 PREFIX=/usr has stated a path outside the prefix, and the patsubst leaves it alone rather than mangling it.

The version is in two places and cannot drift

VERSION in the Makefile fills in openenv.pc; oe_version() in src/proto/value.c answers C callers. tools/check.sh rule 21 fails the build when they disagree, because a library that reports one version to pkg-config and another to its own callers is worse than a library with no version at all.


§ 2 · The four routes in

2. The four routes in

RouteWhat you writeWhat you need
pkg-configcc $(pkg-config --cflags openenv) app.c $(pkg-config --libs openenv)make install
plain pathscc -I$PREFIX/include app.c $PREFIX/lib/libopenenv.amake install, no pkg-config
vendoringinclude third_party/miniopenenv/openenv.mk, then $(OPENENV_SRC) and $(OPENENV_CFLAGS)a submodule
embedding<openenv/embed.h> and nothing elseeither of the above

openenv.mk is eight variables, four of them optional per-layer subsets. It defines no rule, no target and no flag, so there is nothing in it that can fight your Makefile:

include third_party/miniopenenv/openenv.mk

myapp: myapp.c $(OPENENV_SRC)
	$(CC) $(MY_FLAGS) $(OPENENV_CFLAGS) $^ -o $@ $(OPENENV_LIBS)

There is no OPENENV_DIR to set. $(lastword $(MAKEFILE_LIST)) is the path make used to reach the fragment, so the directory is derived from the include line you already wrote and cannot disagree with it.

OPENENV_CFLAGS carries two include paths, and the second is our src/, because our translation units include each other as "wire/json.h". If your tree also has a top-level wire/ or proto/, ours shadows it inside our sources — and only there, since we add nothing to your own compiles. The pkg-config route has no such effect; it needs only $(INCLUDEDIR). The choice between the two routes is really that paragraph.


§ 3 · make check-embed — three consumers, three routes

3. make check-embed — three consumers, three routes

The whole point of tests/embed/ is that these are built, not asserted. The transcript below is the actual output.

$ make check-embed
embed.sh — three consumers, three routes

--- (a) pkg-config, from a DESTDIR staging tree ---
        <stage>/usr/local/lib/libopenenv.a
        <stage>/usr/local/include/openenv/embed.h
        <stage>/usr/local/include/openenv/openenv.h
        <stage>/usr/local/lib/pkgconfig/openenv.pc
        <stage>/usr/local/bin/openenv-counter
        <stage>/usr/local/bin/openenv-echo
        <stage>/usr/local/bin/openenv-rewards
        <stage>/usr/local/bin/openenv-agent
        <stage>/usr/local/bin/openenv-probe
      install: openenv 0.1.0 -> <stage>/usr/local
ok    install: archive, both headers, openenv.pc, renamed binaries
ok    tour/ is not installed (its banners say do not expose it)
ok    openenv.pc records PREFIX and not DESTDIR
      pkg-config --modversion openenv -> 0.1.0
      pkg-config --cflags     openenv -> -I<stage>/usr/local/include
      pkg-config --libs       openenv -> -L<stage>/usr/local/lib -lopenenv
      consumer[pkg-config]: openenv 0.1.0
        ok    GET /health
        ok    WS reset
        ok    WS step {"n":7}
        ok    oe_serve and oe_client_open link
      consumer[pkg-config]: OK
ok    a consumer builds and runs from pkg-config alone
ok    uninstall removes exactly what install wrote

--- (b) vendored sources, compiled with a hostile flag set ---
      their flags:  cc -std=gnu17 -O2 -Wall -Wextra -Werror -D_GNU_SOURCE -D_FORTIFY_SOURCE=2 -DNDEBUG -funsigned-char -fvisibility=hidden -fno-common
      our flags:    none. 33 of our .c files on that same line.
      consumer[vendored]: openenv 0.1.0
        ok    GET /health
        ok    WS reset
        ok    WS step {"n":7}
        ok    oe_serve and oe_client_open link
      consumer[vendored]: OK
ok    the sources compile AND RUN under a flag set that is not ours

--- (c) embed.h alone: the protocol with no socket in the binary ---
ok    the control: build/rel/libopenenv.a does reference socket()
ok    no socket, no poll, no signal, no clock in the finished program
      nm -u build/embed/pure — everything it needs:
        abort  calloc  fflush  fprintf  free  getenv  malloc  memcmp
        memcpy  memset  printf  puts  snprintf  strlen  strtod
      pure: no socket, no clock, no server — just frames
        ok    {"type":"reset","data":{}}
              -> {"type":"observation","data":{"observation":{"metadata":{},"ticks":0},"reward":null,"done":false}}
        ok    {"type":"step","data":{"n":7}}
              -> {"type":"observation","data":{"observation":{"metadata":{},"ticks":7},"reward":7,"done":true}}
        ok    {"type":"teleport"}
              -> {"type":"error","data":{"message":"Unknown message type: teleport","code":"UNKNOWN_TYPE"}}
      pure: OK
ok    and it speaks the protocol: reset, step, and an error frame

embed.sh: all cases passed

(Absolute paths shortened to <stage>; nothing else is edited. The nm -u list is one symbol per line in the real output.)

Three things in there are worth reading twice.

Case (b) is why our feature-test macros live in the .c files. Every #ifndef _POSIX_C_SOURCE / #define _POSIX_C_SOURCE 200809L / #endif in this tree sits at the top of a source file, above its first #include, and never in CFLAGS and never in a header. In CFLAGS it works right up until somebody vendors you, at which point their flags apply instead and <netdb.h> quietly stops declaring getaddrinfo. Case (b) compiles 33 of our source files with a flag set that has nothing in common with ours — no -std=c99, -D_GNU_SOURCE, -funsigned-char, -DNDEBUG, -Werror. Then it runs the result and diffs protocol bytes, because -funsigned-char changing a UTF-8 decision is a behaviour bug and not a compile error.

The honest limitation is in tests/embed/README.md: a consumer who pins _POSIX_C_SOURCE to an old value on the command line breaks the vendored build of src/wire/net.c. The real output is pasted there; an #ifndef guard can raise nothing. Raise the value or take the pkg-config route.

Case (c) is the strongest claim in this repository. pure.c includes <openenv/embed.h> and nothing else of ours, and it links the whole libopenenv.a — the archive that contains the accept loop, the client and src/wire/net.c. A static archive is a bag of translation units, and the linker takes only what is referenced. So the fifteen libc functions above are the entire operating-system dependency of the OpenEnv protocol. Where each one comes from, since the list is short enough to account for completely:

SymbolsWhere they come from
printf putspure.c's own output. gcc rewrites printf of a literal into puts
malloc free calloc getenv fprintf fflush abortsrc/wire/arena.c, the one translation unit allowed to own memory. getenv is the OE_ARENA_DEBUG_MALLOC switch; the last three are the message it prints before aborting on a pointer that outlived its reset
strtod snprintfJSON numbers, in json_parse.c and json_write.c
memcmp memcpy memset strlenthe string primitives, shared with pure.c

The positive control matters as much as the assertion. A negative result about something that is not there proves nothing, so the test first asserts that nm does find socket inside the archive. Without that line, an empty library would pass.


§ 4 · The container

4. The container

The contract is two sentences

Listen on port 8000, bound 0.0.0.0. Answer GET /health.

That is the whole of what an OpenEnv runtime provider requires of an image: no protocol version, no registration call, no sidecar, no environment variable that must be set. Providers map the container side to 8000 and several refuse any other value, and they never read /health's body — a 200 is the answer. Our server's defaults are exactly those two sentences, so docker run with no arguments is a conforming server.

HEALTHCHECK without curl

The reference image declares HEALTHCHECK CMD curl -f localhost:8000/health. An image built FROM scratch has no curl to run and no shell to run it in. So the server probes itself:

HEALTHCHECK --interval=5s --timeout=3s --start-period=1s --retries=3 \
    CMD ["/openenv", "healthcheck"]

openenv healthcheck opens a connection to 127.0.0.1:8000, sends GET /health, and exits 0 only for a 200. It is a handful of lines in src/server/main.c reusing the client's own connect path, and it is why this image needs nothing in it but one file. The CMD is exec form — a JSON array — because shell form would be run as /bin/sh -c "..." and there is no /bin/sh.

make docker — build, then prove it

$ make docker
--- build ---
ok    built miniopenenv:counter

--- the container contract ---
      5dc58d9d610b -> 127.0.0.1:32769
ok    GET /health answers from outside — so it bound 0.0.0.0, not loopback
      HTTP/1.1 200 OK
      content-length: 20
      content-type: application/json
      connection: close

      {"status":"healthy"}
ok    HEALTHCHECK reports healthy — the binary probed itself, with no curl in the image
ok    docker stop returned in 1s (the grace period is 10)

--- size ---
  miniopenenv:counter                              210632 bytes
  ghcr.io/huggingface/openenv-base:latest       467705200 bytes

  ratio: 2220x

docker: the container contract holds

Four assertions, in the order a runtime provider discovers them:

  1. GET /health answers from outside. This is also the 0.0.0.0 test: a server that bound the loopback would be unreachable through -p, because the published port arrives on the bridge interface and not on lo. The host probe is our own binary's healthcheck subcommand rather than curl, so the assertion does not depend on a tool another machine might not have. curl only prints the bytes, because a transcript is worth more than an exit code.
  2. The daemon's own HEALTHCHECK turns the container healthy. That can only happen if /openenv healthcheck ran successfully inside an image with no shell, no curl and no libc on disk.
  3. docker stop returns in about a second. The grace period is ten. A server that ignored SIGTERM would still pass a health check, and it would cost ten seconds on every deploy, restart and scale-down. OE_SHUTDOWN_MS is 2000, and this is the single assertion that catches every way of breaking it.
  4. The size, measured.

The size, and what it is fair to compare

  miniopenenv:counter                              210632 bytes    (211 kB)
  ghcr.io/huggingface/openenv-base:latest       467705200 bytes    (468 MB)

Both numbers are docker image inspect --format '{{.Size}}' on linux/amd64, on the same machine, on the same day: uncompressed on-disk size, measured the same way. The ratio is 2220×.

docker history says the image is one layer and that layer is the binary. The CREATED and COMMENT columns are cut for width and the metadata rows below LABEL are elided; nothing else is changed:

$ docker history miniopenenv:counter
IMAGE          CREATED BY                                      SIZE
ca73ab97d739   ENTRYPOINT ["/openenv"]                         0B
<missing>      HEALTHCHECK {Test:[CMD /openenv healthcheck]…   0B
<missing>      STOPSIGNAL SIGTERM                              0B
<missing>      USER 65532:65532                                0B
<missing>      EXPOSE [8000/tcp]                               0B
<missing>      COPY /openenv /openenv # buildkit               211kB
<missing>      LABEL org.opencontainers.image.licenses=Apac…   0B
...

210,632 bytes is also, exactly, the size of the stripped static binary inside it — the image has no second file to account for.

What that ratio is not. openenv-base is a base image: it carries CPython, pip, and the dependency set every OpenEnv environment inherits. An environment built on it adds its own layers on top. Ours is a finished server with one environment compiled in. So this compares a Python runtime with batteries to a static C binary. That is a real and useful thing to know when you are paying to pull it onto a hundred nodes, and it is not a claim that anyone did anything wrong. The comparable statement is the narrow one: the smallest image that can answer GET /health and run an episode is 211 kB, and 468 MB is what you start from if the answer is written in Python.

Both numbers were measured here. If ghcr.io/huggingface/openenv-base is not on your machine, tools/docker.sh prints not on this machine and the words UNMEASURED HERE rather than quoting this page's number back at you. A test that needs a registry is a test that fails on an aeroplane.

Why FROM scratch and not alpine

Alpine is a fine base and it is about 8 MB before you add anything. Every one of those megabytes is a package a scanner will find CVEs in and an attacker who reaches RCE will find tools in. A server that opens no file, spawns no process and reads no configuration has no use for a filesystem — and this one does not. That is what the nm -u list in case (c) above is evidence of. USER 65532:65532 works with no /etc/passwd, which is fortunate, because there is no /etc either.

If you want a shell in your image for debugging, change the last FROM. That is a policy choice, not a protocol one.

The build, end to end

$ time docker build --no-cache -t miniopenenv:counter --build-arg OE_ENV=counter .
#6 [build 2/5] RUN apk add --no-cache build-base                        DONE 9.3s
#9 [build 5/5] RUN make check-portability && make LDFLAGS=-static ...   DONE 4.3s
#10 [stage-1 1/1] COPY --from=build /openenv /openenv                   DONE 0.0s

real    0m14.703s

(Three of eleven #n steps, the rest being sub-second loads and metadata.) Fifteen seconds from nothing, and nine of them are apk. The builder stage runs make check-portability first: every translation unit under exactly -std=c99 -pedantic-errors -Wall -Wextra and no -D of ours. An artefact nobody will recompile is the right place to spend two seconds confirming the C99 claim on a second libc:

check-portability: 73 sources, 35 headers, flags: -std=c99 -pedantic-errors -Wall -Wextra

LDFLAGS=-static is the only flag passed in. The Makefile defines no -D and needs no configuration, so there is nothing else to say.

OE_ENV selects the environment: make docker OE_ENV=echo builds an image from envs/echo.c instead. counter is the default because it is the literal port of the Python environment the captured corpus was recorded against. An image built from it therefore answers the reference's own conformance suite.

.dockerignore, and one trap worth naming

build/ is excluded and the reason is not size. COPY preserves modification times, so a host build directory copied into the image would arrive with object files newer than the sources beside them. make would then skip the compile and try to link x86-64 glibc objects with musl. The failure reads like a toolchain bug and is a stale cache.


§ 5 · No TLS, and the proxy that is the answer

5. No TLS, and the proxy that is the answer

Neither half of this project speaks TLS. The server listens in plaintext and the client dials in plaintext. https:// is refused by name rather than downgraded, and there is no build flag, no --insecure and no vendored crypto anywhere in the tree. openenv.pc has no Libs.private: because there is nothing private to link — not -lm, not -lpthread, and not -lssl.

That is a limitation, and this section is what it costs: one process in front, and no change to anything else.

The refusal, and why it has a name of its own

Both example programs refuse the two TLS schemes by name, in the same words — oe_probe with a string compare of its own, because it links none of our protocol code, and oe_agent by asking the library:

$ ./build/rel/bin/oe_agent https://127.0.0.1:8443
oe_agent: no TLS. This program speaks plaintext only;
          put a local reverse proxy in front of the
          server and point this at it. The transcript
          is docs/PACKAGING.md section 5.
$ echo $?
2

The library underneath has to answer the same question without printing anything, and for a while it could not. oe_client_open and oe_client_wait_healthy returned a bare OE_EUSAGE for https://, which is the same value they return for a typo. So oe_agent reported "never became healthy" about a host it had never opened a socket to. oe_client_url_verdict in ../include/openenv/openenv.h ↗ is that distinction, and it is the whole of the fix:

verdictmeanswhat a caller should do
OE_URL_OKthis client will dial itdial it
OE_URL_NO_TLShttps:// or wss://this section
OE_URL_MALFORMEDa query string, credentials, a control byte, no hostfix the URL

OE_EIO and OE_ETIMEDOUT remain what they always were: a server that is down. The point is that "TLS unsupported" and "server down" are now different answers, and tests/t_client.c pins that the verdict and the call agree row for row.

The reference does exactly this

This is not a workaround invented here. The reference's own Hugging Face Spaces provider cannot reach its sandbox in plaintext either, so it starts a local proxy and hands the client that proxy's http:// address:

# reference/OpenEnv/src/openenv/core/containers/runtime/hf_sandbox_provider.py
self._proxy = _LocalAuthProxy(                       # :286-292
    target_url=self._sandbox.proxy_url_for(_DEFAULT_PORT, "/"),
    headers=self._sandbox.proxy_headers,
)
return self._proxy.start()

class _LocalAuthProxy:                               # :99-110
    @property
    def base_url(self) -> str:
        return f"http://127.0.0.1:{self.port}"

Their proxy also injects an auth header, which is the part that is theirs. The shape — plaintext on the loopback, TLS on the far side, and the client never learns — is the same one below.

The two directions, as one-liners

Inbound, so a stranger can reach our server over https://: terminate TLS, forward plaintext to the port the environment binds.

socat OPENSSL-LISTEN:8443,reuseaddr,fork,cert=cert.pem,key=key.pem,verify=0 \
      TCP:127.0.0.1:8000

Outbound, so our client can reach a server that only speaks https:// — the _LocalAuthProxy case, and the one oe_agent's refusal is about: listen in plaintext on the loopback, speak TLS upstream. Then pass http://127.0.0.1:8000 as the base URL.

socat TCP-LISTEN:8000,reuseaddr,fork,bind=127.0.0.1 \
      OPENSSL:env.example.com:443

The same two in stunnel, which is the other spelling and wants a file:

[openenv-in]                      [openenv-out]
accept  = 0.0.0.0:8443            client  = yes
connect = 127.0.0.1:8000          accept  = 127.0.0.1:8000
cert    = /etc/stunnel/oe.pem     connect = env.example.com:443

Neither socat nor stunnel was on the machine this section was measured on, so neither block above is a transcript. They are the two recipes, written out, and they are unrun here. What follows is a transcript. The terminator in it is the twenty-nine lines below, doing the one thing both recipes do: copy bytes, with TLS on one side. It lives in this document rather than in the tree on purpose. The thing to actually use is socat, and a project that shipped its own proxy would be answering the question it just said it was not answering.

Use a byte forwarder, not an HTTP-aware proxy, unless you know what you are doing. socat and stunnel operate below HTTP, so the RFC 6455 upgrade crosses them without their having an opinion about it. An HTTP-aware reverse proxy has to be told to pass Upgrade and Connection through. The failure when it is not told is a /health that works and a WS /ws that returns 400 — which looks like our bug and is not.

The transcript

One environment, one TLS terminator in front of it, and one plaintext front for the client — so both directions above are exercised in a single chain. The agent's bytes go oe_agent → plaintext → TLS → plaintext → counter, and neither C program links a TLS library.

tlsfwd.py, in full — a stand-in for socat, so that what follows is real:

import socket, ssl, sys, threading

mode, lport, host, port = sys.argv[1], int(sys.argv[2]), sys.argv[3], int(sys.argv[4])
srv = socket.create_server(("127.0.0.1", lport), reuse_port=False)
if mode == "in":                                  # TLS here, plaintext upstream
    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
    ctx.load_cert_chain(sys.argv[5], sys.argv[6])
    srv = ctx.wrap_socket(srv, server_side=True)

def pump(a, b):
    try:
        while True:
            d = a.recv(65536)
            if not d:
                break
            b.sendall(d)
    except OSError:
        pass
    a.close(); b.close()

while True:
    down, _ = srv.accept()
    up = socket.create_connection((host, port))
    if mode == "out":                             # plaintext here, TLS upstream
        c = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
        c.check_hostname, c.verify_mode = False, ssl.CERT_NONE
        up = c.wrap_socket(up, server_hostname=host)
    for a, b in ((down, up), (up, down)):
        threading.Thread(target=pump, args=(a, b), daemon=True).start()
$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
      -days 1 -nodes -subj "/CN=localhost"
$ ./build/rel/bin/counter --host 127.0.0.1 --port 8010 &
openenv info   listening on: 127.0.0.1:8010  max_sessions=8 max_connections=64
$ python3 tlsfwd.py in  8443 127.0.0.1 8010 cert.pem key.pem &   # inbound
$ python3 tlsfwd.py out 8011 127.0.0.1 8443 &                    # outbound

Inbound first — a TLS client reaching the plaintext server, which is what a reader gets by pointing anything at all at 8443:

$ curl -sk -i https://127.0.0.1:8443/health
HTTP/1.1 200 OK
content-length: 20
content-type: application/json
connection: close

{"status":"healthy"}

Those are our server's own bytes — lowercase header names, connection: close, {"status":"healthy"} — arriving through a TLS handshake it knows nothing about. Now the outbound direction, with the whole client in it:

$ ./build/rel/bin/oe_agent http://127.0.0.1:8011 --episodes 1 --max-steps 4
oe_agent — a random agent that has never heard of this environment.
  target      http://127.0.0.1:8011
  it knows    GET /schema, and nothing else
  it contains no field name and no fallback for any environment

--- what GET /schema says an action is -----------------------------------
  title: CounterAction
  metadata       object     the framework's, not the environment's — left alone
  amount         integer    default 1
  note           string     default ""

--- episode 1 ------------------------------------------------
  reset  -> done=false
  step 1   {"amount":5,"note":""}
           -> reward 5      (float) done=true

GET /schema, the RFC 6455 upgrade, the masking keys, the Sec-WebSocket-Accept token and every frame of the episode crossed a TLS connection. No line of this repository changed to make that work. The base URL is an http:// one, which is the entire configuration.

(Measured here: OpenSSL 3.6.3, Python 3.14.6, curl 8.21.0, Linux 7.1.4. Port 8000 was occupied on this machine, hence 8010.)

Proved in the suite, not only in this document

A transcript is a thing that happened once. tests/t_client.c case an_episode_through_a_proxy_is_an_episode forks a plaintext forwarder in front of the test server and drives a whole episode through it, on every make test, under ASan and UBSan.

It is plaintext on both sides on purpose. What the case establishes is the only property the workaround actually rests on: this client's requirement on its peer is a plaintext TCP endpoint and nothing else. It establishes it with a forwarder that parses nothing, so the forwarder cannot accidentally be the thing that makes the exchange work. A TLS terminator would add a certificate and a handshake on the side of the seam the client cannot see. Testing our own forwarder's TLS would be testing OpenSSL, and an API this repository cannot exercise with real TLS is a claim it cannot check. That is also why there is no pluggable transport in oe_client: a seam with no second implementation is an interface pretending to be evidence.


§ 6 · What is deliberately not here

6. What is deliberately not here