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
$ 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
PREFIXis where the files will BE.DESTDIRis 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
| Route | What you write | What you need |
|---|---|---|
| pkg-config | cc $(pkg-config --cflags openenv) app.c $(pkg-config --libs openenv) | make install |
| plain paths | cc -I$PREFIX/include app.c $PREFIX/lib/libopenenv.a | make install, no pkg-config |
| vendoring | include third_party/miniopenenv/openenv.mk, then $(OPENENV_SRC) and $(OPENENV_CFLAGS) | a submodule |
| embedding | <openenv/embed.h> and nothing else | either 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
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:
| Symbols | Where they come from |
|---|---|
printf puts | pure.c's own output. gcc rewrites printf of a literal into puts |
malloc free calloc getenv fprintf fflush abort | src/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 snprintf | JSON numbers, in json_parse.c and json_write.c |
memcmp memcpy memset strlen | the 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
The contract is two sentences
Listen on port 8000, bound
0.0.0.0. AnswerGET /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:
GET /healthanswers from outside. This is also the0.0.0.0test: a server that bound the loopback would be unreachable through-p, because the published port arrives on the bridge interface and not onlo. The host probe is our own binary'shealthchecksubcommand 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.- The daemon's own
HEALTHCHECKturns the containerhealthy. That can only happen if/openenv healthcheckran successfully inside an image with no shell, no curl and no libc on disk. docker stopreturns in about a second. The grace period is ten. A server that ignoredSIGTERMwould still pass a health check, and it would cost ten seconds on every deploy, restart and scale-down.OE_SHUTDOWN_MSis 2000, and this is the single assertion that catches every way of breaking it.- 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
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:
| verdict | means | what a caller should do |
|---|---|---|
OE_URL_OK | this client will dial it | dial it |
OE_URL_NO_TLS | https:// or wss:// | this section |
OE_URL_MALFORMED | a query string, credentials, a control byte, no host | fix 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
- No amalgamation, no
dist/. A checked-in second copy of the codebase that rots.make installandopenenv.mkcover adoption. - No shared library.
libopenenv.ais 33 objects with no dependencies. A.sowould buy a soname policy, a symbol-version script and an ABI promise, in exchange for saving a few hundred kilobytes on a machine that has one consumer. The symbol namespace is checked either way:tools/check.shrule 8 saysnm -gon the archive must show onlyoe_-prefixed definitions. That is what makes it safe to link us next to a project that already has its own SHA-1 or base64 — andtests/embed/consumer.cdefines five such names on purpose. - No CMake, no autotools, no configure. There is nothing to configure.
- No
Requires:and noLibs.private:in the.pc. There is nothing to require: this library links against the C runtime and nothing else — not-lm, not-lpthread, not-lssl. A dependency list that is empty because the dependencies are genuinely absent is worth more than any feature this project could have added.