miniopenenv

docs/PORTING.md → html

Porting

This page is how to move this project to another operating system, and what a port has to keep true. The short version: rewrite one file.

§ 1 · The claim

The claim

To move this project to another platform, rewrite one file: src/wire/net.c.

It is the only translation unit in the tree with a platform conditional in it, and the only one that makes a system call. Everything above it is a pure function from bytes to bytes and can be tested with no socket at all.

Check it yourself:

$ grep -rn '#ifdef\|#if defined' src/ --include='*.[ch]'
src/wire/arena.c:41:#if defined(__has_feature)
src/wire/arena.c:46:#if defined(__SANITIZE_ADDRESS__)
src/wire/net.c:1:/* net.c — THE ONE FILE WITH #ifdefs. Not protocol; see docs/PORTING.md.
src/wire/net.c:17:#if defined(__APPLE__)
src/wire/net.c:57:#if defined(MSG_NOSIGNAL)
src/wire/net.c:157:#if defined(SO_NOSIGPIPE)
src/wire/net.c:179:#if defined(SO_KEEPALIVE)
src/wire/arena.h:169:#if defined(NDEBUG)

Seven conditionals and one banner comment — net.c announcing itself, which is the third line. Four of the seven are in net.c; a fifth, #if !defined (MSG_NOSIGNAL) && !defined(SO_NOSIGPIPE), is an #error the pattern above does not match. The three outside net.c are not about an operating system at all:

WhereWhat it testsWhy it is not a port
src/wire/net.c__APPLE__, MSG_NOSIGNAL, SO_NOSIGPIPE, SO_KEEPALIVE, _POSIX_C_SOURCEthis is the port
src/wire/arena.hNDEBUGwhether the generation stamp is asserted
src/wire/arena.c__has_feature, __SANITIZE_ADDRESS__whether ASan poisoning is available

Two of those three are about a build, not a target.


§ 2 · What you have to reimplement

What you have to reimplement

src/wire/net.h is the whole surface: about twenty functions, no callbacks, no hidden state beyond two small caller-owned structs. Grouped by what a port actually has to find:

GroupFunctionsThe platform thing behind it
listen / connectoe_net_listen, oe_net_connect, oe_net_accept, oe_net_local_portsockets, name resolution, non-blocking connect
move bytesoe_net_read, oe_net_write, oe_net_read_some, oe_net_write_allrecv/send, EINTR, EAGAIN, and suppressing SIGPIPE per call
readinessoe_net_poll, oe_net_poll_events, oe_net_poll_reventspoll or its local equivalent
the clockoe_net_now_ms, oe_net_sleep_msa monotonic millisecond source
wakeupoe_net_wake_*, oe_net_signal_wake, oe_net_signal_restore_alla self-pipe (or eventfd), and signal disposition
fd pressureoe_net_reserve_open, oe_net_reserve_closea spare descriptor for the EMFILE path
randomnessoe_net_randomthe kernel's entropy source

Five facts a port has to keep true, and they are the reason this file exists rather than a scattering of send() calls:

  1. Nothing blocks. Every descriptor handed out is non-blocking, so a peer that sends one byte and stalls cannot park a single-threaded server for the length of its patience.
  2. Sending to a departed peer returns an error and never raises SIGPIPE. Suppressed per-call (MSG_NOSIGNAL) or per-socket (SO_NOSIGPIPE) — never with a process-wide signal() disposition. That one belongs to the embedder and we do not get to change it behind them. If your target has neither mechanism, net.c has an #error waiting for you rather than a silent process-kill.
  3. EINTR is retried at every call site, and retrying never resets a deadline the caller gave us.
  4. A short move is normal, not an edge case. Every function reports how many bytes actually moved and expects the caller to come back.
  5. Randomness comes from the kernel, and when it cannot, that is a hard failure. oe_net_random reads /dev/urandom (O_CLOEXEC) and returns OE_EIO with nothing usable written. A Sec-WebSocket-Key from a predictable source is not a nonce, and "just use the clock" is the bug that signature exists to make impossible.

§ 3 · Why no platform type appears in a header

Why no platform type appears in a header

src/wire/net.h deliberately contains no ssize_t, no struct pollfd and no sigaction. A header here must compile standalone under a bare -std=c99 -pedantic-errors with no feature-test macros defined, and every one of those spellings fails that test.

So the header defines its own oe_pollfd and its own three readiness flags, and net.c translates them. That buys a second thing worth knowing about. poll's events field is a short, and POLLIN | POLLOUT promotes to int. So a short field would be a narrowing assignment that -Wconversion is right to complain about at every call site. Making the field an int moves that one narrowing into one line of net.c, where a reader can watch it happen.

The same reasoning is why the public API says oe_server_fds(int *, short *, int) rather than taking a struct pollfd *. In a prototype, an undeclared struct type declares a new incomplete type at prototype scope and breaks every caller.


§ 4 · Feature-test macros live in .c files

Feature-test macros live in .c files

At the top, before the first #include, never in a header and never in CFLAGS:

#ifndef _POSIX_C_SOURCE
#define _POSIX_C_SOURCE 200809L
#endif
#if defined(__APPLE__)
#define _DARWIN_C_SOURCE 1
#endif

Two different failures are being avoided:

make check-portability is what keeps the C99 claim honest: it compiles every translation unit and every header with exactly four flags and no -D of ours.

$ make check-portability
check-portability: 72 sources, 35 headers, flags: -std=c99 -pedantic-errors -Wall -Wextra
check-portability: ok

One honest limitation. A consumer who pins _POSIX_C_SOURCE to a pre-2008 value on the command line cannot vendor src/wire/net.c. The #ifndef above declines to raise it, and the declarations net.c needs are then not there. The error output is pasted in PACKAGING.md.


§ 5 · What "tested" means for a port

What "tested" means for a port

Almost all of this project's tests do not touch your port at all, which is the useful consequence of the layering:

TestNeeds a socket?
t_replay — the whole 103-case reference corpusno
t_conn — all five connection states, capacity refusal, handshake deadlineno
t_json_parse, t_json_write, t_ws, t_http, t_utf8, t_validate, …no
t_netyes — this is the port's own test
t_client part 6yes — forks our server and drives a real episode

So the sequence for a new platform is: rewrite net.c, run t_net, then run everything else and expect it to have been passing already.

The two supported targets today are Linux and macOS. Running make check on the second machine is also what keeps tools/ honest: every script here is POSIX sh with no grep -P, no sed -i, no readlink -f and no GNU-only find/xargs. Nothing does that for you. This repository has no build service and asks for none, so a port is proved by somebody running these targets.


§ 6 · See also

See also