Add --net-listen-allow CLI flag; add RFC 868 time-server example

Closes the gap flagged right after net.listen shipped (#215): dial's
"no CLI policy flag" limitation doesn't matter in practice since dial
defaults to allow, but listen defaults to deny, so the same gap left
net.listen completely unusable from the CLI, not just unrestricted.

--net-listen-allow pattern[:port] (repeatable) adds an allow rule to
net.listen's bind policy directly from the CLI, mapping onto the same
net_state.addListenPolicyRule the embedding API already uses. Accepts
the same pattern shapes as the embedding API (*, exact IPv4/IPv6, CIDR,
hostname wildcard) plus an optional :port suffix, bracket-safe for IPv6
literals ("[::1]:8080").

examples/time-server/ is a minimal end-to-end demonstration: RFC 868's
Time Protocol is about as simple as a network server gets (connect,
receive 4 bytes, done - no request to parse). Verified live: server and
client both run under the plain CLI, no host embedding needed, and the
decoded time matches actual UTC. Building it surfaced two real script
bugs worth noting for future examples: std.io.println does not insert
separators between arguments (concatenates directly - "listening on" +
address ran together with no space), and net.dial returns a single
Conn-or-error value, not a [value, error] pair the way net.listen and
http.get/post/fetch do - an easy mix-up given how close the two now
look in the same codebase.

Author: ganehag

CHANGELOG.md

@@ -9,12 +9,13 @@ This changelog tracks notable language/runtime changes by implementation date.
 Adds `net.listen(network, address) [Listener, error]` and `Listener.accept()/close()/local_addr()/set_accept_deadline(ms)`, so a script can bind a port and accept inbound TCP connections — an MQTT listener, an HTTP server, a TCP echo service — purely in Gengo, reusing the exact same `Conn` type and read/write/close/deadline API `net.dial` already produces for the data path.
 
 - **New CLI/embedding mechanism, not just a new function**: `net` is now gated by scope — `--cap net=dial`, `--cap net=listen`, or `--cap net=dial,listen`. Bare `--cap net` (no `=`) still means exactly what it always has (dial-only); upgrading an existing deployment never silently grants listen. The `--cap name=scope1,scope2` syntax is a general CLI mechanism (split on `=` then `,`), not `net`-specific, so any future capability that grows scopes gets the same syntax for free. `cap:net`'s import gate succeeds as long as *some* net scope is granted; each function is refused individually at call time if its own scope wasn't (`ctx.vs.net_scopes`, computed from `Runtime.enabled_capabilities` in `Runtime.activate()`) — the same shape as an `fs` operation against a path with no matching mount.
-- **Listen policy defaults to deny-all**, deliberately the opposite of dial's existing default-allow: a host must affirmatively add at least one allow rule (`engine_net_listen_policy_add`, mirroring `engine_net_policy_add`'s shape and LIFO evaluation exactly) before any `net.listen(...)` call succeeds. Separate rule list from dial's — configuring one has no effect on the other. No CLI flag exists to configure it (matching how dial policy has always been host-API-only from the CLI); `--cap net=listen` alone makes `net.listen` compile and import but refuse every call until a host adds a rule.
+- **Listen policy defaults to deny-all**, deliberately the opposite of dial's existing default-allow: a host must affirmatively add at least one allow rule before any `net.listen(...)` call succeeds. Separate rule list from dial's — configuring one has no effect on the other. Two ways to add a rule: the embedding API (`engine_net_listen_policy_add`, mirroring `engine_net_policy_add`'s shape and LIFO evaluation exactly), or the CLI's new repeatable `--net-listen-allow pattern[:port]` flag (added same day, after initially shipping this host-API-only to match dial's precedent — dial's identical "no CLI flag" gap doesn't matter in practice since dial defaults to allow, so the asymmetry meant listen's version of that gap left it completely unusable from the CLI, not just unrestricted; see #215).
 - **`net.listen`/`Listener.accept` return `[value, error]` pairs**, unlike `dial`'s single "Conn or error" value — matching `http.get`/`post`/`fetch`'s existing convention (`l, err := net.listen(...)`) rather than dial's, since that's the calling shape the language surface actually needs here.
 - Native POSIX implementation reuses existing `net_state.zig` machinery rather than inventing new plumbing: `socket()`+`bind()`+`listen()` (fixed backlog, 128) into a new `g_listeners` table (independent ceiling from `MaxConns`, default 8 — a script needing many listening ports is a different shape of program than one needing many connections); accept deadline reuses `posixSetSockOptTimeval`/`SO_RCVTIMEO` applied to the *listening* socket instead of a connection, so `EAGAIN` maps to `error.DeadlineExceeded` exactly like `netRead`'s existing arm; a successful `accept()` produces a plain connected socket wrapped in the same `NetConn` struct `dial` produces, pushed into the existing `g_conns`/`MaxConns` pool — accepted and dialed connections share one ceiling and one accounting path, not a separate parallel budget.
 - Host-mediated path (WASI/browser/embedders without POSIX sockets) extends `gengo_net_handlers_t` with optional `listen`/`accept`/`listener_close`/`listener_local_addr`/`set_accept_deadline` callbacks — `null` on a host that supports dial but not listen, reported as `CapabilityNotAvailable` rather than a crash. WASI itself gets the same treatment `dial` already has (`error.CapabilityNotAvailable`): confirmed directly against Zig's std that WASI has no `bind`/`listen`/`accept` syscall wrappers at all (only Linux's raw syscall interface does), so there was a real platform gap to gate, not a guess.
 - Tests: `compiler_test.zig` gains scope-gating and default-deny-policy tests, plus a genuine POSIX `bind`+`accept`+`read`+`write` roundtrip test using a `std.Thread`-spawned raw-socket client (kept off `net_state`'s own globals entirely to avoid a real cross-thread data race, since `net_state` has no locking) against the real listener implementation; `engine.zig` gains `engine_net_listen_policy_add`/`_clear` C API tests mirroring the existing dial-policy ones; a new `tests/spec/cap/fail/006_net_listen_scope_not_granted.gengo` conformance case.
-- Docs: `capabilities.md` (scope table, `Listener` API, default-deny policy, server-loop shape), `capability-matrix.md`, `security.md` (listen vs. dial policy defaults, why they differ, existing cross-runtime `net_state` isolation gap now also covers listeners), `cli.md` (`--cap net=scope1,scope2` syntax).
+- Docs: `capabilities.md` (scope table, `Listener` API, default-deny policy, server-loop shape), `capability-matrix.md`, `security.md` (listen vs. dial policy defaults, why they differ, existing cross-runtime `net_state` isolation gap now also covers listeners), `cli.md` (`--cap net=scope1,scope2` and `--net-listen-allow` syntax).
+- New example: `examples/time-server/` — an RFC 868 Time Protocol server and client, about as minimal a demonstration of `net.listen`/`Listener.accept` as exists (connect, receive 4 bytes, done). Runs directly under the CLI, no host embedding needed.
 - **Known, explicitly deferred, not fixed here**: `net_state.zig`'s connection/listener tables and both policy lists remain process-wide module state, not yet part of the per-instance activation set #190 tracks for `chunk`/`globals`/`heap`/`vm` — a pre-existing latent gap for dial, now also covering listeners. Not a concern for a single-`Runtime`-per-process embedding (the CLI); a host running multiple independently-untrusted scripts with `listen` enabled in one process should treat this as a real isolation gap until #190 lands, not assume it's already handled. See `dev-docs/design/net-listen-design.md` for the full design rationale.
 
 ## 2026-07-22 (v0.5.1-dev)

docs/cli.md

@@ -38,7 +38,8 @@ script from standard input instead.
 | `--test` | Run top-level `test` blocks rather than ordinary script execution. A failed test exits unsuccessfully. |
 | `--profile` | With `--test`, print each block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line. Does not affect pass/fail behavior or the exit code. Forces per-instruction instruction counting on for the run, which costs real speed — a diagnostic aid, not something to leave on by default. |
 | `--cap name` | Enable one named capability. Repeat for several capabilities. See `capabilities.md`; no capability is enabled merely by importing it. |
-| `--cap net=scope1,scope2` | Scope the `net` capability instead of granting it unscoped. Scopes are `dial` and `listen`, comma-separated (`--cap net=dial`, `--cap net=listen`, `--cap net=dial,listen`). Bare `--cap net` (no `=`) still means dial-only, unchanged from before scopes existed — upgrading never silently grants listen. `net.listen`'s policy defaults to deny-all regardless of scope; there is no CLI flag to add a listen-policy rule, so `--cap net=listen` alone makes `net.listen(...)` compile and import but refuse every call until a host adds one via the embedding API (`engine_net_listen_policy_add`). This general `name=scope1,scope2` syntax is available for any capability that defines scopes, not just `net`. |
+| `--cap net=scope1,scope2` | Scope the `net` capability instead of granting it unscoped. Scopes are `dial` and `listen`, comma-separated (`--cap net=dial`, `--cap net=listen`, `--cap net=dial,listen`). Bare `--cap net` (no `=`) still means dial-only, unchanged from before scopes existed — upgrading never silently grants listen. This general `name=scope1,scope2` syntax is available for any capability that defines scopes, not just `net`. |
+| `--net-listen-allow pattern[:port]` | Add an allow rule to `net.listen`'s bind policy, which defaults to deny-all (the opposite of `net.dial`'s default-allow — see `security.md`). Repeatable. `pattern` accepts the same shapes as the embedding API's policy rules (`"*"`, exact IPv4/IPv6, CIDR, hostname wildcard); an optional `:port` suffix restricts to one port (bracket the pattern for a literal IPv6 address with a port, e.g. `"[::1]:8080"`). With no rules, `--cap net=listen` alone still makes `net.listen(...)` compile and import but refuse every call. |
 | `--modules path` | Permit source imports from one additional directory. Repeatable, up to eight paths. The script directory remains the default source root. |
 | `--max-ops n` | Limit VM instruction execution to `n`. `0` means unlimited. This limit does not account for work inside host callbacks. |
 | `--heap size` | Set the GC heap size. A size may be bytes or end in `k`, `m`, or `g`; the default is `1m`. |

examples/time-server/README.md

@@ -0,0 +1,45 @@
+# Time server (RFC 868)
+
+The simplest possible demonstration of `net.listen`/`Listener.accept`: an
+[RFC 868](https://www.rfc-editor.org/rfc/rfc868) Time Protocol server. A
+client connects, the server writes back the current time as a single
+32-bit binary number, and closes the connection — no request to parse, no
+reply format beyond four bytes. Nothing about this example needs a host
+embedding; both scripts run directly under the `gengo` CLI.
+
+`time_server.gengo` binds a port and serves that protocol forever.
+`check_time.gengo` is a client that connects, decodes the reply, and
+prints it as a calendar time — useful for testing without reaching for
+`nc`/`xxd`.
+
+RFC 868's registered port is 37, which (like any port below 1024) requires
+root on POSIX. This example binds `7370` instead so it runs without
+special permission; change the port in both scripts together if you want
+something else.
+
+## Run it
+
+`net.listen` needs both a scope grant and a policy rule — the listen
+policy defaults to deny-all, deliberately the opposite of `net.dial`'s
+default-allow (see `docs/security.md`).
+
+```bash
+gengo --cap net=listen --net-listen-allow "*:7370" examples/time-server/time_server.gengo
+```
+
+In another terminal:
+
+```bash
+gengo --cap net=dial examples/time-server/check_time.gengo
+```
+
+Expected output from the client:
+
+```
+server time: 2026 7 25 ...
+```
+
+The server keeps running (and printing nothing further) until you stop it
+— it's written as a dedicated long-running process, the natural shape for
+`gengo server.gengo` as a standalone daemon (see "Execution model" in
+`dev-docs/design/net-listen-design.md`).

examples/time-server/check_time.gengo

@@ -0,0 +1,33 @@
+// Client for time_server.gengo: connects, reads the 4-byte RFC 868
+// response, and decodes it back to a calendar time.
+//
+// Run: gengo --cap net=dial check_time.gengo
+
+std := import("std")
+net := import("cap:net")
+
+rfc868_epoch_offset := 2208988800
+
+func checkTime() {
+    conn := net.dial("tcp", "127.0.0.1:7370")
+    if std.core.is_error(conn) {
+        std.io.println("dial failed: ", conn)
+        return
+    }
+
+    data := conn.read(4)
+    conn.close()
+
+    if std.core.bytelen(data) != 4 {
+        std.io.println("expected 4 bytes, got ", std.core.bytelen(data))
+        return
+    }
+
+    rfc868_time := std.bytes.u32be_at(data, 0)
+    unix_time := rfc868_time - rfc868_epoch_offset
+    t := std.time.from_unix(unix_time)
+    p := t.parts()
+    std.io.printf("server time: %d-%d-%d %d:%d:%d UTC\n", p.year, p.month, p.day, p.hour, p.min, p.sec)
+}
+
+checkTime()

examples/time-server/time_server.gengo

@@ -0,0 +1,41 @@
+// RFC 868 Time Protocol — about as simple as a network server gets: a
+// client connects, the server sends back the current time as a single
+// 32-bit binary number, and closes the connection. No request to parse,
+// no reply format beyond four bytes.
+//
+// Run: gengo --cap net=listen --net-listen-allow "*:7370" time_server.gengo
+// Test: printf '' | nc 127.0.0.1 7370 | xxd   (or see check_time.gengo)
+//
+// RFC 868's registered port is 37, which requires root on POSIX (any port
+// below 1024 does) — this example binds an unprivileged port instead so it
+// runs without special permission.
+
+std := import("std")
+net := import("cap:net")
+
+// RFC 868 counts seconds from 1900-01-01 00:00:00 UTC; std.time works in
+// the Unix epoch (1970-01-01). The gap between the two is exactly this
+// many seconds — a fixed, well-known constant, not something to compute.
+rfc868_epoch_offset := 2208988800
+
+func serve() {
+    l, err := net.listen("tcp", "0.0.0.0:7370")
+    if err != null {
+        std.io.println("listen failed: ", err)
+        return
+    }
+    std.io.println("time server listening on ", l.local_addr())
+
+    for {
+        conn, aerr := l.accept()
+        if aerr != null {
+            continue
+        }
+        now := std.time.now()
+        rfc868_time := now.unix() + rfc868_epoch_offset
+        conn.write(std.bytes.u32be(rfc868_time))
+        conn.close()
+    }
+}
+
+serve()

src/main.zig

@@ -23,6 +23,7 @@ const vms = @import("lang/vm_state.zig");
 const cfg = @import("runtime_config");
 const heap_rt = @import("runtime/heap.zig");
 const fs_state = @import("lang/native/fs_state.zig");
+const net_state = @import("lang/native/net_state.zig");
 const cap_env = if (build_opts.cap_env) @import("lang/native/cap_env.zig") else struct {};
 const disasm = @import("lang/disasm.zig");
 const bundle = @import("bundle.zig");
@@ -279,6 +280,30 @@ fn parseHeapSize(s: []const u8) usize {
     return n * multiplier;
 }
 
+// Splits a --net-listen-allow value into (pattern, port). Bracketed form
+// ("[::1]:8080" or bare "[::]") is IPv6-safe; otherwise splits on the last
+// ':' only when the tail parses as a port number, so a bare pattern with no
+// port (e.g. "*.example.com" or unbracketed "::1") is never misread as
+// having one. port 0 means "any port", matching net_state's own rule shape.
+fn splitPatternPort(raw: []const u8) struct { pattern: []const u8, port: u16 } {
+    if (raw.len > 0 and raw[0] == '[') {
+        if (std.mem.indexOfScalar(u8, raw, ']')) |rb| {
+            const inner = raw[1..rb];
+            if (rb + 1 < raw.len and raw[rb + 1] == ':') {
+                const port = std.fmt.parseUnsigned(u16, raw[rb + 2 ..], 10) catch 0;
+                return .{ .pattern = inner, .port = port };
+            }
+            return .{ .pattern = inner, .port = 0 };
+        }
+    }
+    if (std.mem.lastIndexOfScalar(u8, raw, ':')) |i| {
+        if (std.fmt.parseUnsigned(u16, raw[i + 1 ..], 10)) |port| {
+            return .{ .pattern = raw[0..i], .port = port };
+        } else |_| {}
+    }
+    return .{ .pattern = raw, .port = 0 };
+}
+
 fn printBundleUsage() void {
     io.write("Usage: gengo bundle --entry <archive-path.gengo> -o <bundle.zip> [options] [folder ...]\n");
     io.write("\n");
@@ -467,6 +492,9 @@ fn runCli(argv: []const []const u8) void {
             io.write("  --profile          With --test, report peak ops/heap/stack/objects per block\n");
             io.write("  --cap <name>       Enable a named capability (repeatable)\n");
             io.write("  --cap net=dial,listen  Scope the net capability (dial and/or listen)\n");
+            io.write("  --net-listen-allow pattern[:port]  Allow net.listen to bind a matching\n");
+            io.write("                     address (repeatable); listen refuses everything\n");
+            io.write("                     with no rules\n");
             io.write("  --modules <path>   Allow imports from an extra directory (repeatable)\n");
             io.write("  --max-ops <n>      Limit instruction count (0 = unlimited)\n");
             io.write("  --heap <size>      Set GC heap size, e.g. 4m, 512k (default 1m)\n");
@@ -600,6 +628,23 @@ fn runCli(argv: []const []const u8) void {
             script_index += 2;
             continue;
         }
+        if (std.mem.eql(u8, a, "--net-listen-allow")) {
+            if (script_index + 1 >= argv.len) {
+                io.werr("gengo: --net-listen-allow requires a value pattern[:port]\n");
+                die(1);
+            }
+            const v = argv[script_index + 1];
+            const split = splitPatternPort(v);
+            const rc = net_state.addListenPolicyRule(.allow, split.pattern, split.port);
+            if (rc != 0) {
+                io.werr("gengo: invalid --net-listen-allow value: ");
+                io.werr(v);
+                io.werr("\n");
+                die(1);
+            }
+            script_index += 2;
+            continue;
+        }
         if (std.mem.eql(u8, a, "--heap")) {
             if (script_index + 1 >= argv.len) {
                 io.werr("gengo: --heap requires a size (e.g. 4m, 512k, 8388608)\n");