rightsize 0.7.9 → 0.7.12

package/dist/backend-msb/commands.js

@@ -1,9 +1,14 @@
 /**
  * Pure msb CLI argv construction. Every spelling here was checked against the
  * real `msb` binary, not guessed from `--help` text alone. ATTACHED mode (no
- * `-d`) is the whole ballgame: `msb run -d` boots the microVM but never runs
- * the image's own ENTRYPOINT/CMD, only attached mode does — see
- * `MsbCliBackend.start` for the supervision this forces.
+ * `-d`) is the whole ballgame for `run()`: `msb run -d` runs the image's own
+ * ENTRYPOINT/CMD too, so attached mode isn't about starting the workload —
+ * see `MsbCliBackend.start` for the supervision it forces instead.
+ * `restore()` is a
+ * different shape entirely — see its own doc and `MsbCliBackend.bootRestoreOnce`'s
+ * for why: `msb restore` always detaches and exits once activation is
+ * confirmed, well before the sandbox itself finishes booting, and it is
+ * never held open as a supervisor the way `run` is.
  */
 export const MsbCommands = {
     run(spec) {
@@ -26,8 +31,18 @@ export const MsbCommands = {
         if (spec.networkDisabled) {
             argv.push("--net", "private");
         }
+        // One rule per linked UDP target: a bare --net-rule (no --net flag) is
+        // PREPENDED to msb's default policy, so public internet, DNS, and this
+        // sandbox's own published-port ingress all keep working — only these
+        // specific host UDP ports open up, nothing broader.
+        for (const port of spec.hostUdpEgressPorts ?? []) {
+            argv.push("--net-rule", `allow@host:udp:${port}`);
+        }
         for (const port of spec.ports) {
-            argv.push("-p", `${port.hostPort}:${port.guestPort}`);
+            // "/udp" only for a udp binding — the plain "HOST:GUEST" spelling for
+            // tcp is byte-identical to before this suffix existed, since msb (like
+            // docker) treats an unmarked port publish as tcp by default.
+            argv.push("-p", `${port.hostPort}:${port.guestPort}${port.protocol === "udp" ? "/udp" : ""}`);
         }
         for (const [key, value] of spec.env) {
             argv.push("-e", `${key}=${value}`);
@@ -50,15 +65,12 @@ export const MsbCommands = {
         for (const mount of spec.mounts) {
             argv.push("--mount-file", `${mount.hostPath}:${mount.guestPath}:${mount.readOnly ? "ro" : "rw"},nodev`);
         }
-        if (spec.checkpointRef !== undefined) {
-            // `--from-snapshot` is mutually exclusive with the IMAGE positional arg —
-            // the snapshot itself pins the image (see MsbCliBackend's own doc on
-            // fromCheckpoint/checkpointRef).
-            argv.push("--from-snapshot", spec.checkpointRef);
-        }
-        else {
-            argv.push(spec.image);
-        }
+        // `checkpointRef` never reaches here: msb 0.7.1 removed `run --from-snapshot`
+        // outright (clap rejects it as an unexpected argument now), so a spec that
+        // carries a checkpointRef is routed to `restore()` below, one layer up in
+        // `MsbCliBackend.bootOnce` — this function only ever builds an ordinary
+        // image boot.
+        argv.push(spec.image);
         if (spec.command !== undefined) {
             // undefined => the image's own ENTRYPOINT/CMD runs unmodified.
             argv.push("--", ...spec.command);
@@ -66,36 +78,194 @@ export const MsbCommands = {
         return argv;
     },
     /**
-     * `msb snapshot create --from <sandbox> <name>` — requires `sandbox`
-     * STOPPED; writes a sparse disk snapshot under `~/.microsandbox/snapshots/<name>`,
-     * or under `<destDir>/<name>` when `destDir` is given (path-ref checkpoints).
+     * `msb restore <ref> --name <name> [-m SIZE] [--no-net] [--volume
+     * SOURCE:GUEST:OPTS]... [-p HOST:GUEST]...` — the checkpoint-reboot argv,
+     * replacing the removed `run --from-snapshot` (msb 0.7.1 moved restore to
+     * this dedicated subcommand). NEVER emits `--disk-only`: EMPIRICALLY
+     * VERIFIED against a real msb 0.7.1 binary, a disk-scope snapshot — the
+     * only kind `msb snapshot create --from-sandbox` produces, and therefore
+     * the only kind this library's checkpoints ever restore — REJECTS that
+     * flag outright (`invalid config: disk_only requires a full snapshot with
+     * checkpoint state`). Restoring a disk-scope snapshot is inherently a cold
+     * boot of the captured disk with no processes/RAM resumed — the same
+     * semantics the old `run --from-snapshot` boot and the removed
+     * `--disk-only` flag both had, and the only restore mode this library's
+     * checkpoint contract documents — so nothing observable changes for
+     * callers; only the argv shrinks by one flag msb no longer accepts here.
+     *
+     * Deliberately narrower than `run()` in one respect only: `msb restore`
+     * has no `-e`/`--env` flag at all, so env is never threaded through here —
+     * a restore replays the sandbox's own captured configuration, which makes
+     * re-passing env redundant (see `GenericContainer.fromCheckpoint`'s own
+     * doc on why an env the caller has actually changed beyond the
+     * checkpoint's own is refused before this is ever reached, rather than
+     * silently dropped here). There is likewise no `--root-disk` equivalent —
+     * the snapshot pins the root disk, and `withDiskLimit()` on a
+     * `fromCheckpoint()` container is rejected at `start()` before any backend
+     * call.
+     *
+     * Mounts and network are NOT in that category — they thread through here,
+     * mirroring `run()`'s own `--mount-file`/`--net private`. Per msb's own
+     * source (`sdk/rust/lib/sandbox/restore_builder.rs`'s `RestoreBuilder::new`),
+     * every restore starts with `mounts`/`ports`/`vsock` CLEARED and
+     * `restore_resources.require_complete` true — they are the destination's
+     * OWN fresh bindings for this specific restore, not something msb
+     * re-derives from the snapshot, and an un-resupplied captured external
+     * mount is a hard failure, not a silent drop. `createCheckpoint`'s
+     * stop/snapshot/reboot cycle (see `MsbCliBackend.createCheckpoint`) hands
+     * this function `handle.spec` itself — the ORIGINAL sandbox's live
+     * `mounts`/`networkDisabled` exactly as the caller set them via
+     * `.withCopyFileToContainer()`/`.withNetworkDisabled()`, not anything
+     * "carried over from a captured spec" — so they must be re-emitted here or
+     * they silently vanish across the reboot (or, if msb classifies the
+     * now-missing mount as a required external resource, throw instead).
+     * `GenericContainer.fromCheckpoint()` is the unrelated case the checkpoints
+     * guide's "network topology, mounts, and keepAlive are never carried over
+     * from the source spec" actually describes: it never copies
+     * `cp.spec.mounts`/`networkDisabled` onto the new container's own builder
+     * state in the first place (see its own doc), so a `fromCheckpoint()`
+     * container's `spec.mounts` is `[]` and `networkDisabled` is `false`
+     * unless the caller adds them back explicitly via
+     * `.withCopyFileToContainer()`/`.withNetworkDisabled()` on it directly —
+     * in which case this function threads those through exactly the same as
+     * for any other spec, as it should.
+     *
+     * `--volume SOURCE:GUEST[:OPTIONS]` is restore's own mount flag (`-v`
+     * short form; `RestoreResourceArgs.volume` in
+     * crates/cli/lib/commands/restore.rs) — spelled differently from `run()`'s
+     * `--mount-file`, but parsed by the identical shared grammar
+     * (`parse_cli_mount_spec`, confirmed in crates/cli/lib/commands/common.rs:
+     * `--volume`'s `parse_restore_volume` and `--mount-file`'s
+     * `apply_explicit_file_mount` both call it with the same
+     * `CliMountOptionSupport`), so `run()`'s own comment on why the option
+     * block (`ro`/`rw,nodev`) is always spelled out rather than left to
+     * defaults applies here verbatim. `--no-net` is restore's equivalent of
+     * `run()`'s `--net private`: msb's own default restore network policy is
+     * open (`RestoreBuilder::new` clears mounts/ports/vsock/user but never
+     * touches the network policy field, so it keeps whatever a fresh
+     * `SandboxBuilder`'s default is — the same open-by-default policy `run()`
+     * itself relies on when `networkDisabled` is unset), so `--no-net` is
+     * emitted only when `networkDisabled` is true, exactly mirroring `run()`'s
+     * own `--net private` condition.
+     */
+    restore(spec) {
+        if (spec.checkpointRef === undefined) {
+            throw new Error("MsbCommands.restore requires spec.checkpointRef");
+        }
+        const argv = ["restore", spec.checkpointRef, "--name", spec.name];
+        if (spec.memoryLimitMb !== undefined) {
+            argv.push("-m", `${spec.memoryLimitMb}M`);
+        }
+        if (spec.networkDisabled) {
+            argv.push("--no-net");
+        }
+        // Unlike run(), a bare --net-rule here is not additive: msb's restore
+        // drops whatever CLI policy the ORIGINAL sandbox booted with and falls
+        // back to its own default, so this has to re-supply the complete
+        // replacement policy, not just the extra rule. --net-rule only parses
+        // on restore alongside --net-default (there is no --net profile flag
+        // here, unlike run's --net private), and --net-default governs BOTH
+        // directions at once — so the published-port ingress a plain default
+        // policy gives for free must be re-added explicitly as
+        // allow:ingress@any, or this sandbox's own -p bindings restore
+        // unreachable.
+        const hostUdpEgressPorts = spec.hostUdpEgressPorts ?? [];
+        if (hostUdpEgressPorts.length > 0) {
+            const rules = ["allow@public", "allow@dns", ...hostUdpEgressPorts.map((port) => `allow@host:udp:${port}`), "allow:ingress@any"];
+            argv.push("--net-default", "deny", "--net-rule", rules.join(","));
+        }
+        for (const port of spec.ports) {
+            // Same "/udp"-only-for-udp spelling as run() above — a checkpoint
+            // reboot re-publishes each binding's ORIGINAL protocol, never
+            // defaulting a udp binding back to tcp on restore.
+            argv.push("-p", `${port.hostPort}:${port.guestPort}${port.protocol === "udp" ? "/udp" : ""}`);
+        }
+        for (const mount of spec.mounts) {
+            // Same option grammar and Windows rationale as `run()`'s `--mount-file` —
+            // see this function's own doc.
+            argv.push("--volume", `${mount.hostPath}:${mount.guestPath}:${mount.readOnly ? "ro" : "rw"},nodev`);
+        }
+        return argv;
+    },
+    /**
+     * `msb snapshot create --from-sandbox <sandbox> <name>` — requires
+     * `sandbox` STOPPED. `name` is a caller-supplied label, EMPIRICALLY
+     * VERIFIED against a real msb 0.7.1 binary to no longer determine where
+     * the artifact lands: it only appears in msb's own index (as
+     * `<sandbox>:<name>`, visible in `msb snapshot list`) and in `snapshot
+     * inspect` output. The artifact itself always lands under
+     * `<destDir-or-default>/<sandbox>/snap_<32-hex-digest>` — a
+     * content-addressed path `name` has no say over — which is why
+     * `MsbCliBackend.createCheckpoint` parses it back out of this command's
+     * own stdout (see `parseSnapshotCreateArtifactPath`) instead of
+     * constructing it. `destDir` (this library's own `--dest-dir`, when the
+     * ref is a path ref) still controls the artifact's PARENT directory —
+     * `<destDir>/<sandbox>/snap_<digest>` when given, msb's own default
+     * snapshot store (`~/.microsandbox/snapshots/<sandbox>/snap_<digest>`)
+     * otherwise.
      */
     snapshotCreate(sandbox, name, destDir) {
-        const argv = ["snapshot", "create", "--from", sandbox, name];
+        const argv = ["snapshot", "create", "--from-sandbox", sandbox, name];
         if (destDir !== undefined) {
             argv.push("--dest-dir", destDir);
         }
         return argv;
     },
-    /** `msb snapshot rm <name>` — best-effort per `removeCheckpoint`'s own contract; "not found" is fine. */
-    snapshotRemove(name) {
-        return ["snapshot", "rm", name];
+    /**
+     * `msb snapshot rm <ref> -f` — best-effort per `removeCheckpoint`'s own
+     * contract; "not found" is fine. `ref` must be the snapshot's own artifact
+     * PATH, never a bare name or `group:member` form: EMPIRICALLY VERIFIED
+     * against a real msb 0.7.1 binary, name-based removal does not resolve —
+     * the artifact path is the only address that reliably works. `-f` forces
+     * the removal; without it a plain `msb snapshot rm` prompts for
+     * confirmation, which would hang a non-interactive CLI invocation forever.
+     * A non-zero exit can ALSO mean msb refused because `ref` is the current
+     * head of older siblings from the same source sandbox — see
+     * `isSnapshotHeadRemovalRefused`, which `removeCheckpoint` propagates
+     * rather than swallowing alongside an ordinary "not found."
+     */
+    snapshotRemove(ref) {
+        return ["snapshot", "rm", ref, "-f"];
     },
-    /** `msb snapshot inspect <name>` — exit 0 means the snapshot exists, non-zero means it doesn't; `hasCheckpoint`'s backend call. */
-    snapshotInspect(name) {
-        return ["snapshot", "inspect", name];
+    /**
+     * `msb snapshot inspect <ref>` — exit 0 means the snapshot exists,
+     * non-zero means it doesn't (or the probe itself failed); `hasCheckpoint`'s
+     * backend call for a bare-name ref. `ref` should be the snapshot's own
+     * artifact PATH for the same reason `snapshotRemove` requires one —
+     * EMPIRICALLY VERIFIED against a real msb 0.7.1 binary, name-based inspect
+     * does not resolve either.
+     */
+    snapshotInspect(ref) {
+        return ["snapshot", "inspect", ref];
     },
-    /** `msb snapshot save <ref> <dest>` — writes a `.tar.zst` artifact archive; deliberately never `--with-image` (its import fails an integrity check in 0.6.6, see the checkpoints guide). `exportCheckpoint`'s backend call. */
+    /**
+     * `msb snapshot save <ref> <dest>` — writes a `.tar.zst` artifact archive;
+     * deliberately never `--with-image` (see the checkpoints guide — this
+     * library doesn't bundle the OCI image into the archive yet, though
+     * upstream supports it). Upstream renamed the subcommand
+     * from `export` to `save` for msb 0.7.1 (EMPIRICALLY VERIFIED against a
+     * real 0.7.1 binary — `snapshot export` no longer exists at all); `<ref>`
+     * and `<dest>` are still plain positionals with the explicit filename
+     * preserved, so nothing about the argv shape besides the verb changes.
+     * `exportCheckpoint`'s backend call.
+     */
     snapshotExport(ref, dest) {
         return ["snapshot", "save", ref, dest];
     },
-    /** `msb snapshot load <archive>` — unpacks into a digest-derived directory under `~/.microsandbox/snapshots/`, never the original name; `importCheckpoint`'s backend call. */
-    snapshotImport(archive) {
-        return ["snapshot", "load", archive];
-    },
-    /** `msb snapshot list --format json` — full `digest`/`name`/`artifact_path`/`image_ref` entries, used to CONFIRM an imported snapshot's digest-dir basename is present (the basename itself, not the `digest` field, is the effective ref — the full digest does not resolve as a snapshot ref). */
-    snapshotList() {
-        return ["snapshot", "list", "--format", "json"];
+    /**
+     * `msb snapshot load <archive> --dest <destDir>` — upstream renamed the
+     * subcommand from `import` to `load` for msb 0.7.1 (EMPIRICALLY VERIFIED
+     * against a real 0.7.1 binary — `snapshot import` no longer exists at
+     * all) and added `--dest`, which this always passes: omitting it imports
+     * into msb's own global default snapshot store instead of this library's
+     * checkpoints directory, which is exactly the placement bug `--dest`
+     * exists to avoid (mirrors `snapshotCreate`'s own `--dest-dir`, a
+     * differently-spelled flag on a different subcommand). `destDir` is
+     * always the checkpoints cache directory (see `MsbCliBackend.importCheckpoint`).
+     * `importCheckpoint`'s backend call.
+     */
+    snapshotImport(archive, destDir) {
+        return ["snapshot", "load", archive, "--dest", destDir];
     },
     /** `msb copy -q <hostPath> <name>:<containerPath>` — host-to-guest transfer, `cp -r`-style destination naming for a directory source. */
     copyIn(hostPath, name, containerPath) {
@@ -108,6 +278,30 @@ export const MsbCommands = {
     exec(name, cmd) {
         return ["exec", name, "--", ...cmd];
     },
+    /**
+     * `msb exec -e KEY=VALUE... <name> -- <cmd...>` — the workload-revival exec
+     * variant `MsbCliBackend.reviveWorkload` spawns to restart a restored
+     * sandbox's captured workload with its ORIGINAL env (a restore's own `msb
+     * restore` has no `-e`/`--env` flag at all — see `restore()`'s own doc —
+     * so this is the one place that env reaches a restored sandbox's guest).
+     * Distinct from the plain `exec()` builder above, which every other
+     * one-shot exec call this backend makes (the `nc` probe, `/etc/hosts`
+     * alias install, `mkdir -p`, ...) uses and which never carries env — those
+     * calls have no reason to widen the guest command's environment, and
+     * `msb exec` accepts `-e` at all only because a genuine workload restart
+     * needs it. `-e` is repeatable (mirrors `run()`'s own `-e`) and is emitted
+     * right after `exec`, before the sandbox NAME positional — the same
+     * relative placement `run()` gives its own `-e` flags among its other
+     * options, ahead of the trailing positional(s).
+     */
+    execWithEnv(name, env, cmd) {
+        const argv = ["exec"];
+        for (const [key, value] of env) {
+            argv.push("-e", `${key}=${value}`);
+        }
+        argv.push(name, "--", ...cmd);
+        return argv;
+    },
     execStream(name, cmd) {
         return ["exec", "--stream", name, "--", ...cmd];
     },
@@ -119,7 +313,9 @@ export const MsbCommands = {
      * diagnostics channel, distinct from the workload log `logs()` above
      * fetches. This is where the boot-completion marker line lives (see
      * `hasSandboxStartedMarker`); the fast-exit post-mortem classification in
-     * `MsbCliBackend.bootOnce` is this builder's only caller.
+     * `MsbCliBackend.bootRunOnce` and the restore poll's own failure
+     * diagnostics in `MsbCliBackend.bootRestoreOnce` are this builder's only
+     * callers.
      */
     systemLog(name) {
         return ["logs", name, "--source", "system", "--tail", "1000"];

package/dist/backend-msb/commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/backend-msb/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/backend-msb/commands.ts"],"names":[],"mappings":"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"}

package/dist/backend-msb/network-links.d.ts

@@ -1,7 +1,92 @@
 import type { NetworkLink } from "../core/backend.js";
-/** Two siblings publishing the same guest port on one network have nowhere distinct to tunnel to. */
+/**
+ * Two siblings publishing the same guest port ON THE SAME PROTOCOL have
+ * nowhere distinct to route to — checked per (protocol, guestPort), not
+ * guestPort alone, so a container exposing one guest port on BOTH
+ * protocols (DNS's 53, say) is never flagged: its TCP and UDP links each
+ * get their own independent route (an exec-tunnel, a forwarder script) and
+ * never collide with each other.
+ */
 export declare function requireNoDuplicateGuestPorts(links: readonly NetworkLink[]): void;
 export declare function requireAliasesAreValid(links: readonly NetworkLink[]): void;
 /** The `sh -c` script that appends one `/etc/hosts` line per distinct alias. */
 export declare function hostsAliasScript(links: readonly NetworkLink[]): string;
+/** Where a UDP link's forwarder script/log live in the guest — the name itself is load-bearing: it is grepped back out of `/proc/<pid>/cmdline` by the script's own supervisor loop below. */
+export declare function udpForwarderScriptPath(guestPort: number): string;
+/** The forwarder's own launch log, tailed into a readiness-timeout error to give it something to diagnose from. */
+export declare function udpForwarderLogPath(guestPort: number): string;
+/**
+ * The in-guest UDP forwarder, one instance per linked UDP port: relays
+ * `guestPort` to `<gateway IPv4>:<targetHostPort>`, where the target's own
+ * host-published UDP port is listening. busybox `nc -u -l` locks onto the
+ * FIRST client's source port forever and never forks for a second one, so
+ * this supervises a chain of single-client listeners instead: each `nc`
+ * relays through a fresh `timeout 60 nc` leg to the target and, the moment
+ * it locks onto a client, this starts the next listener behind it. "Locked
+ * onto a client" is read from `/proc/$pid/cmdline`, not the process's own
+ * `comm` — busybox `timeout` keeps the ORIGINAL pid for the program it
+ * wraps and only forks the timer, so `comm` reads `nc` again once a client
+ * has connected, indistinguishable from the pre-connection listener by name
+ * alone. The FIRST inner wait blocks WHILE `cmdline` still contains this
+ * script's own `rz-udp-link` path: immediately after `&` forks the child,
+ * its cmdline is still THIS script's (the shell hasn't exec'd `nc` yet), and
+ * treating that as "locked" starts a flood of listeners on top of one
+ * another. The SECOND inner wait blocks WHILE `cmdline` still contains
+ * ` -l ` — the listener's own unlocked marker; once that's gone the
+ * listener has locked onto a client, and the loop starts the next one.
+ * `timeout 60` bounds each individual client's relay — msb's own UDP
+ * sessions idle out after 60s, so a client that keeps sending past that
+ * gets a fresh relay rather than a wedged one. The gateway's IPv4 literal
+ * (never the `host.microsandbox.internal` name) is read once from
+ * `/etc/hosts`; `: ${H:=host.microsandbox.internal}` falls back to the name
+ * itself when `/etc/hosts` carries no IPv4 gateway line. That name also
+ * resolves to an IPv6 gateway, which msb rewrites to `::1`, where the
+ * target's 127.0.0.1-bound port never listens.
+ *
+ * No argument here is ever quoted, and the script carries no `"` anywhere:
+ * on Windows hosts the JDK's default `ProcessBuilder` command-line building
+ * wraps an exec argument in quotes without escaping embedded ones, so a `"`
+ * reaching an exec argument this backend builds comes out mangled on
+ * `msb.exe`. Every variable in this script is a number (`$P`, `$HP`,
+ * `$pid`) or an IP literal (`$H`), so unquoted word-splitting is never a
+ * hazard.
+ */
+export declare const UDP_FORWARDER_SCRIPT = "P=$1; HP=$2\nH=$(awk -v n=host.microsandbox.internal '$2 == n && $1 ~ /^[0-9.]+$/ { print $1; exit }' /etc/hosts)\n: ${H:=host.microsandbox.internal}\nwhile true; do\n  nc -u -l -p $P -e timeout 60 nc -u $H $HP &\n  pid=$!\n  while [ -e /proc/$pid ] && grep -q rz-udp-link /proc/$pid/cmdline 2>/dev/null; do sleep 0.01; done\n  while [ -e /proc/$pid ] && tr '\\0' ' ' < /proc/$pid/cmdline 2>/dev/null | grep -q -- ' -l '; do sleep 0.05; done\n  [ -e /proc/$pid ] || sleep 0.2\ndone";
+/**
+ * Capability probe for the forwarder's own dependencies — run once per
+ * `installNetworkLinks` call, only when at least one UDP link is present.
+ * The plain `command -v nc` the TCP exec-tunnel already probes says nothing
+ * about `-e`/`-u` or `timeout`, all three of which the forwarder needs.
+ * busybox prints its own usage to STDERR on `--help` with a non-zero exit,
+ * hence the `2>&1` merge rather than trusting the exit code alone.
+ */
+export declare function udpForwarderProbeScript(): string;
+/**
+ * The "one exec" that installs and launches a UDP link's forwarder: writes
+ * `UDP_FORWARDER_SCRIPT` to `udpForwarderScriptPath(guestPort)` via a QUOTED
+ * heredoc (`<<'EOF'`, never expanded while writing — the script's own `$1`/
+ * `$P`/`$pid`/... must reach the file literally, not this shell's
+ * evaluation of them), then launches it DETACHED, redirecting its output to
+ * `udpForwarderLogPath(guestPort)`. Launched as a FILE argument to `sh`
+ * (`sh <path>`), never `sh -c` with the content inlined: the script's own
+ * pre-exec wait (see `UDP_FORWARDER_SCRIPT`'s own doc) greps the freshly
+ * forked child's cmdline for `rz-udp-link`, which is only there because the
+ * path itself carries that substring — an inlined `-c` invocation's cmdline
+ * never would. A detached background process survives this exec session;
+ * guest processes die with the sandbox, so a UDP link needs no host-side
+ * teardown, and a checkpoint reboot's link replay simply reruns this
+ * against the rebooted (tmpfs-backed) `/tmp`.
+ */
+export declare function installUdpForwarderScript(guestPort: number, targetHostPort: number): string;
+/**
+ * True (exit 0) once `guestPort` shows up bound in `/proc/net/udp` or
+ * `/proc/net/udp6` — polled at a short interval after launching the
+ * forwarder, since `nc -u -l`'s bind happens after process startup and
+ * prints nothing to signal it. Matches on the LAST 4 hex digits of the
+ * local-address column (`<addr>:<PORT-hex>`) rather than the whole column,
+ * since the address part varies (`00000000` for an unbound-interface
+ * listener) and only the port is what this needs to confirm; `NR>1` skips
+ * the header line both files start with.
+ */
+export declare function udpReadinessProbeScript(guestPort: number): string;
 //# sourceMappingURL=network-links.d.ts.map

package/dist/backend-msb/network-links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-links.d.ts","sourceRoot":"","sources":["../../src/backend-msb/network-links.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD,qGAAqG;AACrG,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAWhF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAW1E;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAGtE"}
+{"version":3,"file":"network-links.d.ts","sourceRoot":"","sources":["../../src/backend-msb/network-links.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAYhF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAW1E;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAGtE;AAED,8LAA8L;AAC9L,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,mHAAmH;AACnH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,oBAAoB,seAS5B,CAAC;AAEN;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAO3F;AAOD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMjE"}

package/dist/backend-msb/network-links.js

@@ -5,14 +5,22 @@ const BACKEND_NAME = "microsandbox";
 // that could break out of the quoting, not to enforce a strict hostname
 // grammar.
 const ALIAS_CHARSET = /^[A-Za-z0-9._-]+$/;
-/** Two siblings publishing the same guest port on one network have nowhere distinct to tunnel to. */
+/**
+ * Two siblings publishing the same guest port ON THE SAME PROTOCOL have
+ * nowhere distinct to route to — checked per (protocol, guestPort), not
+ * guestPort alone, so a container exposing one guest port on BOTH
+ * protocols (DNS's 53, say) is never flagged: its TCP and UDP links each
+ * get their own independent route (an exec-tunnel, a forwarder script) and
+ * never collide with each other.
+ */
 export function requireNoDuplicateGuestPorts(links) {
     const seen = new Set();
     for (const link of links) {
-        if (seen.has(link.guestPort)) {
-            throw new UnsupportedByBackendError(`two siblings exposing the same guest port ${link.guestPort} on one network`, BACKEND_NAME);
+        const key = `${link.protocol}:${link.guestPort}`;
+        if (seen.has(key)) {
+            throw new UnsupportedByBackendError(`two siblings exposing the same ${link.protocol} guest port ${link.guestPort} on one network`, BACKEND_NAME);
         }
-        seen.add(link.guestPort);
+        seen.add(key);
     }
 }
 export function requireAliasesAreValid(links) {
@@ -28,4 +36,111 @@ export function hostsAliasScript(links) {
     const aliases = [...new Set(links.map((l) => l.alias))];
     return aliases.map((alias) => `echo '127.0.0.1 ${alias}' >> /etc/hosts`).join("; ");
 }
+/** Where a UDP link's forwarder script/log live in the guest — the name itself is load-bearing: it is grepped back out of `/proc/<pid>/cmdline` by the script's own supervisor loop below. */
+export function udpForwarderScriptPath(guestPort) {
+    return `/tmp/rz-udp-link-${guestPort}.sh`;
+}
+/** The forwarder's own launch log, tailed into a readiness-timeout error to give it something to diagnose from. */
+export function udpForwarderLogPath(guestPort) {
+    return `/tmp/rz-udp-link-${guestPort}.log`;
+}
+/**
+ * The in-guest UDP forwarder, one instance per linked UDP port: relays
+ * `guestPort` to `<gateway IPv4>:<targetHostPort>`, where the target's own
+ * host-published UDP port is listening. busybox `nc -u -l` locks onto the
+ * FIRST client's source port forever and never forks for a second one, so
+ * this supervises a chain of single-client listeners instead: each `nc`
+ * relays through a fresh `timeout 60 nc` leg to the target and, the moment
+ * it locks onto a client, this starts the next listener behind it. "Locked
+ * onto a client" is read from `/proc/$pid/cmdline`, not the process's own
+ * `comm` — busybox `timeout` keeps the ORIGINAL pid for the program it
+ * wraps and only forks the timer, so `comm` reads `nc` again once a client
+ * has connected, indistinguishable from the pre-connection listener by name
+ * alone. The FIRST inner wait blocks WHILE `cmdline` still contains this
+ * script's own `rz-udp-link` path: immediately after `&` forks the child,
+ * its cmdline is still THIS script's (the shell hasn't exec'd `nc` yet), and
+ * treating that as "locked" starts a flood of listeners on top of one
+ * another. The SECOND inner wait blocks WHILE `cmdline` still contains
+ * ` -l ` — the listener's own unlocked marker; once that's gone the
+ * listener has locked onto a client, and the loop starts the next one.
+ * `timeout 60` bounds each individual client's relay — msb's own UDP
+ * sessions idle out after 60s, so a client that keeps sending past that
+ * gets a fresh relay rather than a wedged one. The gateway's IPv4 literal
+ * (never the `host.microsandbox.internal` name) is read once from
+ * `/etc/hosts`; `: ${H:=host.microsandbox.internal}` falls back to the name
+ * itself when `/etc/hosts` carries no IPv4 gateway line. That name also
+ * resolves to an IPv6 gateway, which msb rewrites to `::1`, where the
+ * target's 127.0.0.1-bound port never listens.
+ *
+ * No argument here is ever quoted, and the script carries no `"` anywhere:
+ * on Windows hosts the JDK's default `ProcessBuilder` command-line building
+ * wraps an exec argument in quotes without escaping embedded ones, so a `"`
+ * reaching an exec argument this backend builds comes out mangled on
+ * `msb.exe`. Every variable in this script is a number (`$P`, `$HP`,
+ * `$pid`) or an IP literal (`$H`), so unquoted word-splitting is never a
+ * hazard.
+ */
+export const UDP_FORWARDER_SCRIPT = `P=$1; HP=$2
+H=$(awk -v n=host.microsandbox.internal '$2 == n && $1 ~ /^[0-9.]+$/ { print $1; exit }' /etc/hosts)
+: \${H:=host.microsandbox.internal}
+while true; do
+  nc -u -l -p $P -e timeout 60 nc -u $H $HP &
+  pid=$!
+  while [ -e /proc/$pid ] && grep -q rz-udp-link /proc/$pid/cmdline 2>/dev/null; do sleep 0.01; done
+  while [ -e /proc/$pid ] && tr '\\0' ' ' < /proc/$pid/cmdline 2>/dev/null | grep -q -- ' -l '; do sleep 0.05; done
+  [ -e /proc/$pid ] || sleep 0.2
+done`;
+/**
+ * Capability probe for the forwarder's own dependencies — run once per
+ * `installNetworkLinks` call, only when at least one UDP link is present.
+ * The plain `command -v nc` the TCP exec-tunnel already probes says nothing
+ * about `-e`/`-u` or `timeout`, all three of which the forwarder needs.
+ * busybox prints its own usage to STDERR on `--help` with a non-zero exit,
+ * hence the `2>&1` merge rather than trusting the exit code alone.
+ */
+export function udpForwarderProbeScript() {
+    return ("command -v nc >/dev/null && command -v timeout >/dev/null && " +
+        "nc --help 2>&1 | grep -q -- '-e PROG' && nc --help 2>&1 | grep -q -- '-u'");
+}
+/**
+ * The "one exec" that installs and launches a UDP link's forwarder: writes
+ * `UDP_FORWARDER_SCRIPT` to `udpForwarderScriptPath(guestPort)` via a QUOTED
+ * heredoc (`<<'EOF'`, never expanded while writing — the script's own `$1`/
+ * `$P`/`$pid`/... must reach the file literally, not this shell's
+ * evaluation of them), then launches it DETACHED, redirecting its output to
+ * `udpForwarderLogPath(guestPort)`. Launched as a FILE argument to `sh`
+ * (`sh <path>`), never `sh -c` with the content inlined: the script's own
+ * pre-exec wait (see `UDP_FORWARDER_SCRIPT`'s own doc) greps the freshly
+ * forked child's cmdline for `rz-udp-link`, which is only there because the
+ * path itself carries that substring — an inlined `-c` invocation's cmdline
+ * never would. A detached background process survives this exec session;
+ * guest processes die with the sandbox, so a UDP link needs no host-side
+ * teardown, and a checkpoint reboot's link replay simply reruns this
+ * against the rebooted (tmpfs-backed) `/tmp`.
+ */
+export function installUdpForwarderScript(guestPort, targetHostPort) {
+    const scriptPath = udpForwarderScriptPath(guestPort);
+    const logPath = udpForwarderLogPath(guestPort);
+    return (`cat > ${scriptPath} <<'EOF'\n${UDP_FORWARDER_SCRIPT}\nEOF\n` +
+        `nohup sh ${scriptPath} ${guestPort} ${targetHostPort} >${logPath} 2>&1 &`);
+}
+/** `guestPort` as 4 uppercase hex digits — `/proc/net/udp{,6}`'s own local-address-column encoding (5000 → `"1388"`). */
+function guestPortHex(guestPort) {
+    return guestPort.toString(16).toUpperCase().padStart(4, "0");
+}
+/**
+ * True (exit 0) once `guestPort` shows up bound in `/proc/net/udp` or
+ * `/proc/net/udp6` — polled at a short interval after launching the
+ * forwarder, since `nc -u -l`'s bind happens after process startup and
+ * prints nothing to signal it. Matches on the LAST 4 hex digits of the
+ * local-address column (`<addr>:<PORT-hex>`) rather than the whole column,
+ * since the address part varies (`00000000` for an unbound-interface
+ * listener) and only the port is what this needs to confirm; `NR>1` skips
+ * the header line both files start with.
+ */
+export function udpReadinessProbeScript(guestPort) {
+    const hex = guestPortHex(guestPort);
+    return (`awk -v p=':${hex}' 'NR>1 && substr($2, length($2)-4) == p {f=1} END {exit !f}' ` +
+        "/proc/net/udp /proc/net/udp6");
+}
 //# sourceMappingURL=network-links.js.map

package/dist/backend-msb/network-links.js.map

@@ -1 +1 @@
-{"version":3,"file":"network-links.js","sourceRoot":"","sources":["../../src/backend-msb/network-links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAG9D,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,wEAAwE;AACxE,0EAA0E;AAC1E,wEAAwE;AACxE,WAAW;AACX,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C,qGAAqG;AACrG,MAAM,UAAU,4BAA4B,CAAC,KAA6B;IACxE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,yBAAyB,CACjC,6CAA6C,IAAI,CAAC,SAAS,iBAAiB,EAC5E,YAAY,CACb,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAA6B;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,yBAAyB,CACjC,kBAAkB,KAAK,GAAG,EAC1B,YAAY,EACZ,yEAAyE,CAC1E,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,KAA6B;IAC5D,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtF,CAAC"}
+{"version":3,"file":"network-links.js","sourceRoot":"","sources":["../../src/backend-msb/network-links.ts"],"names":[],"mappings":"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"}

package/dist/backend-msb/provisioner.d.ts

@@ -4,7 +4,7 @@ import type { Platform } from "./platform.js";
  * while msb 0.6.10-0.6.13 were broken on Windows (fixed upstream in 0.6.14).
  * MSB_PATH users on Windows must avoid 0.6.10-0.6.13.
  */
-export declare const MSB_VERSION = "0.6.18";
+export declare const MSB_VERSION = "0.7.1";
 /** Test seam: the full resolution logic parameterized over the release base URL, cache dir, and environment. */
 export declare function ensureInstalledAt(baseUrl: string, cacheDir: string, env: Record<string, string | undefined>): Promise<string>;
 /** Resolves (downloading and verifying if needed) a runnable `msb` binary path, using the real GitHub release base, `RIGHTSIZE_CACHE_DIR`, and `process.env`. */

package/dist/backend-msb/provisioner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../src/backend-msb/provisioner.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAW,CAAC;AAiRpC,gHAAgH;AAChH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,iKAAiK;AACjK,wBAAgB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjD;AAED,2GAA2G;AAC3G,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED,gHAAgH;AAChH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../../src/backend-msb/provisioner.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAiRnC,gHAAgH;AAChH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,iKAAiK;AACjK,wBAAgB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjD;AAED,2GAA2G;AAC3G,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED,gHAAgH;AAChH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/backend-msb/provisioner.js

@@ -12,7 +12,7 @@ import { PlatformInfo } from "./platform.js";
  * while msb 0.6.10-0.6.13 were broken on Windows (fixed upstream in 0.6.14).
  * MSB_PATH users on Windows must avoid 0.6.10-0.6.13.
  */
-export const MSB_VERSION = "0.6.18";
+export const MSB_VERSION = "0.7.1";
 function releaseBaseUrl(version) {
     return `https://github.com/superradcompany/microsandbox/releases/download/v${version}`;
 }