@spunto/build 0.16.0 → 0.17.1

package/src/sandbox-agent/bootstrap.sh

@@ -0,0 +1,64 @@
+#!/bin/sh
+# Spunto sandbox bootstrap (RFC 0035) — the main process of every sandbox, whatever runs it.
+#
+# Finds (or fetches) a Node >= 22, fetches the agent from the platform, and runs it forever. The
+# provider only has to run `curl -fsSL $SPUNTO_API_URL/api/sandboxes/bootstrap.sh | sh` with
+# SPUNTO_API_URL and SPUNTO_SANDBOX_TOKEN in the environment. Needs curl or wget, and glibc if the
+# image has no suitable node (the official Node binaries are not built for musl).
+#
+# Shipped in @spunto/build (`./sandbox-agent`), so any control plane can serve it (RFC 0047):
+#   SPUNTO_AGENT_URL  where the agent is fetched (default $SPUNTO_API_URL/api/sandboxes/agent.mjs)
+#   SPUNTO_NODE       a Node >= 22 the control plane mounted in the box: nothing is downloaded
+set -eu
+
+API="${SPUNTO_API_URL:?SPUNTO_API_URL is required}"
+: "${SPUNTO_SANDBOX_TOKEN:?SPUNTO_SANDBOX_TOKEN is required}"
+NODE_VERSION="${SPUNTO_NODE_VERSION:-v24.11.1}"
+AGENT_URL="${SPUNTO_AGENT_URL:-$API/api/sandboxes/agent.mjs}"
+
+DIR=/opt/spunto-sandbox
+if ! mkdir -p "$DIR" 2>/dev/null || [ ! -w "$DIR" ]; then
+  DIR="${HOME:-/tmp}/.spunto-sandbox"
+  mkdir -p "$DIR"
+fi
+
+fetch() {
+  if command -v curl >/dev/null 2>&1; then curl -fsSL --retry 5 --retry-delay 2 "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then wget -qO "$2" "$1"
+  else echo "[bootstrap] neither curl nor wget in this image" >&2; exit 1
+  fi
+}
+
+node_ok() {
+  [ -n "$1" ] && "$1" -e 'process.exit(+process.versions.node.split(".")[0] >= 22 ? 0 : 1)' 2>/dev/null
+}
+
+NODE="${SPUNTO_NODE:-}"
+node_ok "$NODE" || NODE="$(command -v node 2>/dev/null || true)"
+if ! node_ok "$NODE"; then
+  NODE="$DIR/node/bin/node"
+  if ! node_ok "$NODE"; then
+    case "$(uname -m)" in
+      x86_64|amd64) ARCH=x64 ;;
+      aarch64|arm64) ARCH=arm64 ;;
+      *) echo "[bootstrap] unsupported arch $(uname -m)" >&2; exit 1 ;;
+    esac
+    echo "[bootstrap] fetching node $NODE_VERSION ($ARCH)"
+    fetch "https://nodejs.org/dist/$NODE_VERSION/node-$NODE_VERSION-linux-$ARCH.tar.gz" "$DIR/node.tgz"
+    rm -rf "$DIR/node" && mkdir -p "$DIR/node"
+    tar -xzf "$DIR/node.tgz" -C "$DIR/node" --strip-components=1
+    rm -f "$DIR/node.tgz"
+  fi
+fi
+
+# Re-fetched on every boot, so a restart picks up a new agent without rebuilding anything.
+while true; do
+  if fetch "$AGENT_URL" "$DIR/agent.mjs.new"; then
+    mv "$DIR/agent.mjs.new" "$DIR/agent.mjs"
+  fi
+  if [ -f "$DIR/agent.mjs" ]; then
+    "$NODE" "$DIR/agent.mjs" || true
+  fi
+  echo "[bootstrap] agent exited, restarting in 3s" >&2
+  sleep 3
+done

package/src/sandbox-agent/index.ts

@@ -0,0 +1,31 @@
+/**
+ * The in-box agent (RFC 0035, RFC 0047): the files a control plane serves to a box so that the box
+ * dials it — never imported, never read by this package.
+ *
+ * - `bootstrap.sh` — the box's main process: finds (or fetches) a Node >= 22, fetches the agent,
+ *   runs it forever. `SPUNTO_AGENT_URL` says where from (default
+ *   `$SPUNTO_API_URL/api/sandboxes/agent.mjs`), `SPUNTO_NODE` hands it a Node so it fetches none.
+ * - `agent.mjs` — one file, no dependency, served as is. It dials `SPUNTO_AGENT_CONNECT_URL`
+ *   (default `$SPUNTO_API_URL/api/sandbox-agent/connect`) and speaks `./agent-protocol`.
+ * - `runner.sh` — the project runner: the recipe once per bake key, the features' environment, then
+ *   the worker script. Handed to the agent in the plan, and run by a build in `bake-only` mode.
+ *
+ * What a consumer gets here is *where* the files are; reading and serving them is its own I/O. The
+ * same files are reachable as subpaths of the package (`@spunto/build/sandbox-agent/agent.mjs`…).
+ */
+
+export const SANDBOX_AGENT_FILES = {
+  agent: new URL("./agent.mjs", import.meta.url),
+  bootstrap: new URL("./bootstrap.sh", import.meta.url),
+  runner: new URL("./runner.sh", import.meta.url),
+} as const
+
+export type SandboxAgentFile = keyof typeof SANDBOX_AGENT_FILES
+
+/** What each file is served as. */
+export const SANDBOX_AGENT_CONTENT_TYPES: Record<SandboxAgentFile, string> = {
+  agent: "text/javascript; charset=utf-8",
+  bootstrap: "text/x-shellscript; charset=utf-8",
+  runner: "text/x-shellscript; charset=utf-8",
+}
+export * from "./recipe"

package/src/sandbox-agent/recipe.ts

@@ -0,0 +1,65 @@
+/**
+ * A project's recipe as a box that carries the agent runs it (RFC 0042, RFC 0047): through the
+ * agent's own runner, in `bake-only` mode, so that what a build freezes into an image is exactly
+ * what a box would have baked in place — the `.baked-<key>` marker and the features' captured
+ * environment included. A box started from the result skips straight to the worker script.
+ *
+ * The runner's text is the caller's to read (`SANDBOX_AGENT_FILES.runner`): this package does no I/O.
+ */
+
+import { IMAGE_RECIPE_VERSION } from "../script/index"
+
+/** Where the agent keeps a project (`<dir of agent.mjs>/project`, the bootstrap putting it in /opt/spunto-sandbox). */
+export const SANDBOX_PROJECT_DIR = "/opt/spunto-sandbox/project"
+
+/**
+ * The key a recipe is baked under: changes whenever the recipe would bake something different
+ * (the generator's version, the base image, the script). **A format**: a builder and the agent of
+ * a box started from its result must compute the same one, or the box bakes again.
+ */
+export async function recipeBakeKey(p: { image: string; script: string; recipeVersion?: number | string }): Promise<string> {
+  const text = `${p.recipeVersion ?? IMAGE_RECIPE_VERSION}\n${p.image}\n${p.script}`
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16)
+}
+
+const shq = (v: string) => `'${v.replace(/'/g, `'\\''`)}'`
+
+/** An image's `ENV` as shell: its `PATH` in front of the one there is, the rest only where unset. */
+export function imageEnvExports(env: Record<string, string> | null | undefined): string[] {
+  return Object.entries(env ?? {})
+    .filter(([k]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+    .map(([k, v]) => (k === "PATH" ? `export PATH=${shq(v)}"\${PATH:+:$PATH}"` : `[ -n "\${${k}+x}" ] || export ${k}=${shq(v)}`))
+}
+
+/** FNV-1a, for heredoc tags: a tag only has to be absent from the body it fences. */
+function tagHash(s: string): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193) >>> 0
+  return h.toString(16).padStart(8, "0")
+}
+
+/**
+ * What a builder runs, as root, in a container of the project's image: the recipe through the
+ * runner in `bake-only` mode. Self-contained: nothing to fetch, no token, nothing personal.
+ * `imageEnv`: the image's `ENV`, for a builder booted from its files without it (a microVM).
+ */
+export function buildRecipeScript(recipe: { bakeKey: string; bake: string; runner: string }, imageEnv: Record<string, string> | null = null): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(recipe.bakeKey)) throw new Error(`Invalid bake key ${recipe.bakeKey}`)
+  const fence = (name: string, body: string) => {
+    const tag = `__SPUNTO_${name}_${tagHash(body)}__`
+    return `cat > "$DIR/${name.toLowerCase()}.sh" <<'${tag}'\n${body.replace(/\n?$/, "\n")}${tag}\n`
+  }
+  return [
+    "#!/bin/bash",
+    "set -eu",
+    `DIR=${SANDBOX_PROJECT_DIR}`,
+    ...imageEnvExports(imageEnv),
+    'mkdir -p "$DIR" && chmod 700 "$DIR"',
+    fence("BAKE", recipe.bake),
+    fence("RUNNER", recipe.runner),
+    'chmod 700 "$DIR/bake.sh" "$DIR/runner.sh"',
+    `exec bash "$DIR/runner.sh" "$DIR" ${recipe.bakeKey} bake-only`,
+    "",
+  ].join("\n")
+}

package/src/sandbox-agent/runner.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# spunto-project-runner — the recipe once per bake key, then the worker script (setup once, start always)
+#
+# One copy, two users: the in-sandbox agent (handed it in the project plan, `plan.runner`) and a
+# provider's build (`buildRecipeScript` in sandbox-project.ts, mode `bake-only`) — so what a build
+# freezes is exactly what a sandbox would have baked in place, marker and features' env included.
+DIR="$1"; KEY="$2"; MODE="$3"
+if [ ! -f "$DIR/.baked-$KEY" ]; then
+  echo "[spunto] baking the project recipe ($KEY)"
+  bash "$DIR/bake.sh" || { echo "[spunto] recipe failed"; exit 90; }
+  touch "$DIR/.baked-$KEY"
+fi
+# Features declare their environment (containerEnv: nvm's PATH…) for the image; a recipe run in
+# place leaves it only in /etc/bash.bashrc, which non-interactive shells skip. Keep what an
+# interactive shell adds over a login one, for the lifecycle commands below and for the agent.
+_skip='^(USER|HOME|LOGNAME|MAIL|PS1|PS2|PS4|SHLVL|_|PWD|OLDPWD|TERM|COLUMNS|LINES|HOSTNAME|BASH_.*|HIST.*|SHELLOPTS|BASHOPTS|LS_COLORS)$'
+# Our own profile.d file must be out of the way, or from the second boot on the login shell
+# already has what we are measuring and the difference comes out empty (seen for real).
+rm -f /etc/profile.d/spunto-features.sh
+env -i HOME=/root PATH="$PATH" bash -lc 'env -0' > "$DIR/.env.login" 2>/dev/null || true
+env -i HOME=/root PATH="$PATH" PS1='$ ' bash -ic 'env -0' > "$DIR/.env.interactive" 2>/dev/null || true
+: > "$DIR/env.list.new"; : > "$DIR/env.sh.new"
+while IFS= read -r -d '' _kv; do
+  _k="${_kv%%=*}"; [[ "$_k" =~ $_skip ]] && continue
+  grep -qzxF -- "$_kv" "$DIR/.env.login" && continue
+  printf '%s\0' "$_kv" >> "$DIR/env.list.new"
+  printf 'export %s=%q\n' "$_k" "${_kv#*=}" >> "$DIR/env.sh.new"
+done < "$DIR/.env.interactive"
+mv -f "$DIR/env.list.new" "$DIR/env.list"; mv -f "$DIR/env.sh.new" "$DIR/env.sh"
+# World-readable (no secret in it): login shells read it from profile.d, and BASH_ENV — which su
+# keeps, unlike PATH — makes the non-interactive bash of postCreate/postStart read it too.
+install -m 644 "$DIR/env.sh" /etc/profile.d/spunto-features.sh
+export BASH_ENV=/etc/profile.d/spunto-features.sh
+. "$DIR/env.sh"
+# A build stops here: what is on disk now is what the provider freezes.
+if [ "$MODE" = "bake-only" ]; then echo "[spunto] recipe baked"; exit 0; fi
+echo "[spunto] running the worker script"
+exec bash "$DIR/worker.sh"

package/src/script/setup-script.ts

@@ -1132,10 +1132,15 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
   // `project.dind` makes DinD available without the docker-in-docker feature (baked into the base
   // image, see images/worker-base) — treat it like the feature for entrypoint start + docker wait.
   const hasDinDFeature = (project.features?.some((f) => f.id === "docker-in-docker") ?? false) || !!project.dind
+  // `_MP_EP_STARTED` tells the every-start block of the same run (buildWorkerScript inlines both in
+  // one shell) not to start them a second time: the docker-in-docker feature's entrypoint doesn't
+  // check for a running daemon, and a second dockerd fails on the volume store lock — after having
+  // replaced the first one's socket, leaving Docker unreachable for postStart and everything after.
   if (project.postCreateCommand && ((project.features && project.features.length > 0) || project.dind)) {
     push(
       "",
       "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+      "  _MP_EP_STARTED=1",
       '  echo "--- Starting feature entrypoints for postCreate ---"',
       "  while IFS= read -r _ep; do",
       '    if [ -f "$_ep" ]; then',
@@ -1299,9 +1304,11 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
   }
 
   // ── 2. Feature entrypoints ────────────────────────────────────────────────
+  // Skipped when the first-start setup of this same run already started them for postCreate
+  // (`_MP_EP_STARTED`, see buildSetupScript §6).
   push(
     "",
-    "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+    "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ] && [ -z \"${_MP_EP_STARTED:-}\" ]; then",
     '  echo "--- Starting feature entrypoints ---"',
     "  while IFS= read -r _ep; do",
     '    if [ -f "$_ep" ]; then',