1tube 0.1.42 → 0.1.44

package/README.md

@@ -41,7 +41,12 @@ in-process on filesystem changes (including newly created function folders).
 ## npm CLI
 
 The published npm package exposes a `1tube` binary. It is a tiny Node shim that
-launches this repo's Deno CLI, so machines using it need Deno on `PATH`.
+launches this repo's Deno CLI, so machines using it need Deno on `PATH` (set
+`DENO_BIN` to point at a specific `deno` if it isn't). **Prefer this launcher
+over a hand-rolled `deno run … src/server.ts` line** — it applies 1tube's
+recommended defaults (see [minimum dependency age](#minimum-dependency-age)
+below) before Deno starts, which a flag added _inside_ the gateway can no longer
+do.
 
 ```bash
 # Show CLI help
@@ -57,6 +62,44 @@ npx 1tube package --functions supabase/functions --in dist --out fw.1tube --sign
 This replaces local-source invocations such as
 `deno run -A ../1tube/src/cli.ts ...` in downstream CI pipelines.
 
+### Passing deno flags through the launcher
+
+Arguments before a standalone `--` are 1tube CLI args; everything **after** `--`
+is forwarded verbatim to `deno run` (inserted before the entrypoint). This lets
+the launcher fully replace a project's bespoke `deno run … src/server.ts`
+command — including project-level deno flags like `--config`, `--env-file`,
+`--node-modules-dir` and `--no-lock`:
+
+```bash
+npx 1tube serve --functions ./supabase/functions --dev --hmr \
+  -- --no-lock --env-file=.env --config ./supabase/functions/deno.json --node-modules-dir=false
+```
+
+- If your passthrough includes its own `--config`, the launcher does **not** add
+  1tube's bundled `deno.json` — your import map wins (the gateway's own sources
+  use fully-qualified `npm:`/`jsr:` specifiers, so they resolve regardless).
+- Prefer keeping the command line clean? Set the same flags in
+  `1TUBE_DENO_ARGS` (space-separated) instead of after `--`. CLI passthrough
+  takes precedence on any duplicate flag.
+
+### Minimum dependency age
+
+Deno 2.9 turns on a **24-hour minimum dependency age** by default: a function
+that pins a just-published npm version fails to resolve locally with
+_"… is newer than the specified minimum dependency date"_. Because Deno
+snapshots npm config at process startup, this can only be changed by the
+launcher, not from inside the running gateway.
+
+The `1tube` launcher (and the .NET host) therefore export
+`NPM_CONFIG_MIN_RELEASE_AGE=0` for the Deno child **unless you've already set
+it**. That env var is the lowest explicit tier in Deno's precedence chain
+(`--minimum-dependency-age` > `deno.json` `minimumDependencyAge` > `.npmrc`
+`min-release-age` > this env var > the 24h built-in default), so it cancels
+_only_ the new built-in default — any age you configure through `.npmrc`,
+`deno.json`, or the CLI flag still wins. To re-enable a guard, set
+`NPM_CONFIG_MIN_RELEASE_AGE` (e.g. `24h`) yourself or use any higher-precedence
+mechanism.
+
 ### Deno npm lifecycle scripts
 
 Deno does not run npm `postinstall` / build scripts unless you allow them.
@@ -67,12 +110,12 @@ dependency install — **1tube’s runtime graph is just Hono + JSR std**.
 
 ## Endpoints
 
-| Path                       | Description                                                                                                         |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `GET /`                    | Liveness probe (`{"status":"ok"}`) — intentionally minimal so unauthenticated callers don't see the function map.   |
-| `POST /functions/v1/:name` | Invoke an edge function                                                                                             |
-| `GET /health`              | Auth-gated health (`Authorization: Bearer $INTERNAL_KEY`); without auth returns the same minimal `{"status":"ok"}`. |
-| `GET /metrics`             | Auth-gated Prometheus exposition (same scheme).                                                                     |
+| Path                       | Description                                                                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /`                    | Liveness probe (`{"status":"ok"}`) — intentionally minimal so unauthenticated callers don't see the function map.                                   |
+| `POST /functions/v1/:name` | Invoke an edge function                                                                                                                             |
+| `GET /health`              | Auth-gated health (`Authorization: Bearer $INTERNAL_KEY`); without auth returns the same minimal `{"status":"ok"}`.                                 |
+| `GET /metrics`             | Auth-gated Prometheus exposition (same scheme).                                                                                                     |
 | `GET /1tube/warmup`        | Boot progress (deferred boot): `{ready, total, loaded, loading, queued, failed}`. CORS-enabled so frontends can poll it to drive a warm-up overlay. |
 
 ## Configuration
@@ -94,6 +137,12 @@ All knobs default to safe-but-backwards-compatible values. The TS gateway
 | `1TUBE_BODY_LIMIT_MB`                                       | `30`                   | Hono `bodyLimit`; matches Supabase. Returns 413 before the handler runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `1TUBE_BODY_READ_MS`                                        | `30000`                | Slow-loris guard. Max idle gap (ms) between body chunks before the request is aborted with **408**. NOT a total body-read deadline — large but fast uploads pass through. Set `0` to disable.                                                                                                                                                                                                                                                                                                                                    |
 | `1TUBE_CORS_ORIGIN`                                         | `*` (dev only)         | Comma-separated allowlist or `*`. In prod, leaving unset disables CORS.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `1TUBE_CORS_ALLOW_HEADERS`                                  | Supabase defaults      | Comma-separated `Access-Control-Allow-Headers`. Replaces the built-in default list (`authorization, x-client-info, apikey, content-type`, …) when set.                                                                                                                                                                                                                                                                                                                                                                            |
+| `1TUBE_CORS_ALLOW_METHODS`                                  | Supabase defaults      | Comma-separated `Access-Control-Allow-Methods` (default `GET, POST, PUT, PATCH, DELETE, OPTIONS`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `1TUBE_CORS_EXPOSE_HEADERS`                                 | 1tube internals        | Comma-separated `Access-Control-Expose-Headers`. **Merged with** (not replacing) the headers 1tube must always expose (e.g. `X-1tube-Warming`).                                                                                                                                                                                                                                                                                                                                                                                   |
+| `1TUBE_CORS_MAX_AGE`                                        | unset                  | Seconds for `Access-Control-Max-Age` (preflight cache). Omitted when unset.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `1TUBE_CORS_ALLOW_CREDENTIALS`                              | off                    | `1`/`true` emits `Access-Control-Allow-Credentials: true`. Per the Fetch spec this is incompatible with `Origin: *`, so when credentials are on, a literal `*` allowlist is rejected — set an explicit origin.                                                                                                                                                                                                                                                                                                                     |
+| `--route-prefix` / `1TUBE_ROUTE_PREFIX`                     | `/functions/v1`        | URL prefix functions are mounted under. Change it to e.g. `/api` to serve at `/api/<name>`. Normalized to a leading-slash, no-trailing-slash form; logging and rate-limiting follow it automatically.                                                                                                                                                                                                                                                                                                                              |
 | `1TUBE_TRUSTED_PROXIES`                                     | empty                  | Comma-separated list of remote IPs whose `X-Forwarded-For` is honored. Anything else uses the raw socket address — XFF spoofing no longer mints fresh rate-limit buckets.                                                                                                                                                                                                                                                                                                                                                        |
 | `1TUBE_SHUTDOWN_GRACE_MS`                                   | `10000`                | SIGINT/SIGTERM drain budget.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `INTERNAL_KEY`                                              | unset                  | Required to read detailed `/health` and `/metrics`. Header-only: `Authorization: Bearer $INTERNAL_KEY`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -105,6 +154,7 @@ All knobs default to safe-but-backwards-compatible values. The TS gateway
 | `1TUBE_SHUTDOWN_GRACE_MS`                                   | `10000`                | Total wall-clock budget (ms) for shutdown, split between (1) draining gateway in-flight requests and (2) tearing down the workerd subprocess. See [Graceful shutdown](#graceful-shutdown) below.                                                                                                                                                                                                                                                                                                                                 |
 | `1TUBE_DEFAULT_RPM`                                         | `120`                  | Override the gateway-wide default rate limit (requests per minute, per IP, per function). Per-function `1tube.json#rpm` still wins.                                                                                                                                                                                                                                                                                                                                                                                              |
 | `1TUBE_DISABLE_RATE_LIMIT`                                  | unset                  | Set to `1` to bypass rate limiting entirely. **Load-test / dev only** — production deployments must keep the limiter on. The gateway prints a clear warning at boot when this is enabled.                                                                                                                                                                                                                                                                                                                                        |
+| `NPM_CONFIG_MIN_RELEASE_AGE`                               | `0` (set by launcher)  | Deno 2.9's minimum dependency age. The `1tube` launcher and .NET host export `0` for the Deno child unless you set it, cancelling only Deno's new 24h default. See [Minimum dependency age](#minimum-dependency-age). Must be set _before_ Deno starts — a gateway flag can't change it.                                                                                                                                                                                                                                            |
 
 ````
 ## Deferred boot & warm-up overlay

package/drizzle/20260610161429_init_logs/snapshot.json

@@ -302,4 +302,4 @@
     }
   ],
   "renames": []
-}
+}

package/drizzle/20260610161430_logs_fts/snapshot.json

@@ -302,4 +302,4 @@
     }
   ],
   "renames": []
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",

package/scripts/npm-cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
@@ -9,26 +10,134 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const denoConfig = resolve(packageRoot, "deno.json");
 const cliEntrypoint = resolve(packageRoot, "src", "cli.ts");
 const denoBin = process.env.DENO_BIN || "deno";
-const cliArgs = process.argv.slice(2);
-const forwardedArgs = cliArgs.length === 0 ? ["--help"] : cliArgs;
-
-const child = spawn(
-  denoBin,
-  [
-    "run",
-    "--quiet",
-    "-A",
-    "--config",
-    denoConfig,
-    cliEntrypoint,
-    ...forwardedArgs,
-  ],
-  {
+
+// Arg model
+// ---------
+// Everything BEFORE a standalone `--` is a 1tube CLI argument (forwarded
+// after the entrypoint). Everything AFTER `--` is a raw `deno run` flag,
+// inserted BEFORE the entrypoint — so this launcher can fully replace a
+// hand-rolled `deno run … src/server.ts` line:
+//
+//   1tube serve --functions ./supabase/functions --dev --hmr \
+//     -- --no-lock --env-file=.env --config ./supabase/functions/deno.json --node-modules-dir=false
+//
+// Projects that would rather not thread flags through the command line
+// can set `1TUBE_DENO_ARGS` instead (same flags, space-separated).
+const rawArgs = process.argv.slice(2);
+const sepIndex = rawArgs.indexOf("--");
+const tubeArgs = sepIndex === -1 ? rawArgs : rawArgs.slice(0, sepIndex);
+const cliDenoArgs = sepIndex === -1 ? [] : rawArgs.slice(sepIndex + 1);
+
+// CLI passthrough is appended last so it wins on any duplicate flag
+// (Deno applies last-one-wins for repeated flags).
+const denoPassthrough = [
+  ...tokenizeArgs(
+    process.env.ONETUBE_DENO_ARGS ?? process.env["1TUBE_DENO_ARGS"] ?? "",
+  ),
+  ...cliDenoArgs,
+];
+
+// Default to --help only when the user gave us nothing at all; if they
+// supplied deno flags but no 1tube subcommand, let cli.ts fall through to
+// its default `serve` path.
+const forwardedTubeArgs = tubeArgs.length === 0 && denoPassthrough.length === 0
+  ? ["--help"]
+  : tubeArgs;
+
+// 1tube ships its own deno.json (import map for the gateway's jsr:/npm:
+// dependencies). Only inject it when the project didn't supply its own
+// --config — a Supabase project points --config at
+// supabase/functions/deno.json so its function workers resolve the
+// project's bare specifiers. The gateway's own sources use fully
+// qualified npm:/jsr: specifiers, so they resolve without our config.
+const userSuppliedConfig = denoPassthrough.some((a) =>
+  a === "--config" || a === "-c" ||
+  a.startsWith("--config=") || a.startsWith("-c=")
+);
+
+// Managed lockfile
+// ----------------
+// A lockfile is what makes a big functions project boot fast: without one
+// (`--no-lock`) Deno re-solves the entire npm/jsr version graph from
+// scratch on every start, and a 100-function project pays that as a
+// multi-second floor every boot. People reach for `--no-lock` to dodge
+// "the lock went stale when I bumped a dep" pain — but in dev Deno's
+// lockfile is ADDITIVE and non-frozen: a changed dependency is appended
+// without error. So the right default is a lockfile we own, not none.
+//
+// We point `--lock` at `.1tube/deno.lock` — a gateway-owned scratch path
+// (already gitignored alongside `.1tube/logs.db`) so it never adds git
+// churn and never collides with a project's own committed `deno.lock`.
+// We never pass `--frozen`, so dep changes self-heal. `1TUBE_REFRESH_LOCK=1`
+// drops the managed lock for a clean rebuild. Any explicit `--lock`,
+// `--no-lock`, or `--frozen` the user passes wins — we don't second-guess.
+const managedLock = resolveManagedLock(denoPassthrough);
+
+const denoArgs = ["run", "--quiet", "-A"];
+if (!userSuppliedConfig) denoArgs.push("--config", denoConfig);
+if (managedLock) denoArgs.push("--lock", managedLock);
+denoArgs.push(...denoPassthrough, cliEntrypoint, ...forwardedTubeArgs);
+
+// Deno 2.9 enables a 24h "minimum dependency age" by default, which makes
+// a function that pins a freshly published npm version fail to resolve in
+// local dev ("…newer than the specified minimum dependency date"). This
+// setting cannot be changed from inside the process (Deno snapshots npm
+// config at startup), so the launcher is the place to neutralize it.
+//
+// NPM_CONFIG_MIN_RELEASE_AGE is the LOWEST explicit tier in Deno's
+// precedence chain (CLI flag > deno.json > .npmrc > this env var > the
+// 24h built-in default). Setting it to 0 cancels ONLY the built-in
+// default — any .npmrc `min-release-age`, deno.json `minimumDependencyAge`,
+// or `--minimum-dependency-age` the project sets still wins. We never
+// override a value the user already exported.
+const childEnv = { ...process.env };
+if (
+  childEnv.NPM_CONFIG_MIN_RELEASE_AGE === undefined &&
+  childEnv.npm_config_min_release_age === undefined
+) {
+  childEnv.NPM_CONFIG_MIN_RELEASE_AGE = "0";
+}
+// Let the gateway print which lockfile is in effect (it can't read its own
+// process's `--lock` flag back out of Deno).
+if (managedLock) childEnv.ONETUBE_LOCK = managedLock;
+
+// Resolve the real deno binary up front. Node ≥18.20 refuses to spawn a
+// `.cmd`/`.bat` shim without a shell, but spawning a real `.exe` (or a
+// bare binary on POSIX) with `shell:false` lets Node escape arguments
+// properly — important now that we forward arbitrary deno flags, some of
+// which carry paths with spaces (`--config "C:\My Project\deno.json"`).
+// We only fall back to a shell when we must (a `.cmd`/`.bat` shim, or we
+// couldn't locate the binary on a Windows PATH at all).
+const resolvedDeno = resolveExecutable(denoBin);
+const needsShell = resolvedDeno
+  ? /\.(cmd|bat)$/i.test(resolvedDeno)
+  : process.platform === "win32";
+const spawnBin = resolvedDeno ?? denoBin;
+
+let child;
+if (needsShell) {
+  // A `.cmd`/`.bat` shim (the npm-installed deno) — or an unresolved name
+  // on Windows — must go through a shell. We pass a single, manually
+  // quoted command string instead of an args array so that (a) paths
+  // with spaces survive and (b) we sidestep Node's DEP0190 "args are not
+  // escaped" deprecation, which fires only for the shell-plus-array form.
+  const command = [spawnBin, ...denoArgs].map(quoteForCmd).join(" ");
+  child = spawn(command, {
     stdio: "inherit",
-    shell: process.platform === "win32",
+    shell: true,
     windowsHide: false,
-  },
-);
+    env: childEnv,
+  });
+} else {
+  // Real executable (deno.exe / a POSIX binary): no shell, so Node
+  // escapes each argument for us.
+  child = spawn(spawnBin, denoArgs, {
+    stdio: "inherit",
+    shell: false,
+    windowsHide: false,
+    env: childEnv,
+  });
+}
 
 for (const signal of ["SIGINT", "SIGTERM"]) {
   process.on(signal, () => {
@@ -54,3 +163,116 @@ child.on("exit", (code, signal) => {
   }
   process.exit(code ?? 1);
 });
+
+/**
+ * Decide whether to inject a 1tube-managed lockfile, and where.
+ *
+ * Returns the absolute lock path to pass to `--lock`, or null when the
+ * caller already made an explicit locking choice (`--lock`, `--no-lock`,
+ * or `--frozen`) — in which case we stay out of the way entirely.
+ *
+ * The managed lock lives at `<cwd>/.1tube/deno.lock`: a scratch path that
+ * 1tube already owns and gitignores, so enabling it adds no git churn and
+ * never clashes with a project's own committed `deno.lock`.
+ *
+ * @param {string[]} passthrough  Raw deno flags being forwarded to `deno run`.
+ * @returns {string | null}
+ */
+function resolveManagedLock(passthrough) {
+  const explicit = passthrough.some((a) =>
+    a === "--lock" || a.startsWith("--lock=") ||
+    a === "--no-lock" || a.startsWith("--no-lock=") ||
+    a === "--frozen" || a.startsWith("--frozen=")
+  );
+  if (explicit) return null;
+
+  const dir = join(process.cwd(), ".1tube");
+  const lockPath = join(dir, "deno.lock");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    // If we can't create the scratch dir, fall back to no managed lock
+    // rather than crash the launcher.
+    return null;
+  }
+
+  // `1TUBE_REFRESH_LOCK=1` forces a clean rebuild by dropping the managed
+  // lock; Deno then re-derives it from the current deps on this boot.
+  if (truthy(process.env.ONETUBE_REFRESH_LOCK ?? process.env["1TUBE_REFRESH_LOCK"])) {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      // Best-effort.
+    }
+  }
+  return lockPath;
+}
+
+/**
+ * Loose truthiness for env-var flags: "1", "true", "yes", "on" (any case).
+ *
+ * @param {string | undefined} v
+ * @returns {boolean}
+ */
+function truthy(v) {
+  return v !== undefined && /^(1|true|yes|on)$/i.test(v.trim());
+}
+
+/**
+ * Split a flag string into argv tokens, honoring single/double quotes so
+ * values with spaces (`--env-file="my env.env"`) survive. Good enough for
+ * a dev-time convenience var — not a full shell parser.
+ *
+ * @param {string} s
+ * @returns {string[]}
+ */
+function tokenizeArgs(s) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    out.push(m[1] ?? m[2] ?? m[3]);
+  }
+  return out;
+}
+
+/**
+ * Locate an executable on PATH (honoring PATHEXT on Windows). Returns an
+ * absolute path, or null when the name can't be resolved — in which case
+ * the caller hands the bare name to spawn and lets the OS/shell try.
+ *
+ * @param {string} bin
+ * @returns {string | null}
+ */
+function resolveExecutable(bin) {
+  // An explicit path (absolute or containing a separator) is used as-is.
+  if (isAbsolute(bin) || bin.includes("/") || bin.includes("\\")) {
+    return existsSync(bin) ? bin : null;
+  }
+  const isWin = process.platform === "win32";
+  const exts = isWin
+    ? (process.env.PATHEXT?.split(";").map((e) => e.trim()).filter(Boolean) ??
+      [".EXE", ".CMD", ".BAT"])
+    : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join(dir, bin + ext);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Quote a single argument for cmd.exe. Leaves simple tokens untouched to
+ * avoid over-quoting; wraps anything with whitespace or shell
+ * metacharacters in double quotes, doubling any embedded quotes.
+ *
+ * @param {string} arg
+ * @returns {string}
+ */
+function quoteForCmd(arg) {
+  if (arg === "") return '""';
+  if (!/[\s"&|<>^()%!]/.test(arg)) return arg;
+  return '"' + arg.replace(/"/g, '""') + '"';
+}

package/src/backends/deno/hot-reloader.ts

@@ -398,7 +398,9 @@ export function createDenoHotReloader(
       }`;
       log(`[1tube] HMR ${reason}`);
       try {
-        const summary = await opts.host.reload(affected, reason);
+        const summary = await opts.host.reload(affected, reason, {
+          changedPaths: paths,
+        });
         const parts: string[] = [];
         if (summary.reloaded.length > 0) {
           parts.push(`reloaded=${summary.reloaded.join(",")}`);

package/src/backends/deno/shared-runtime.ts

@@ -59,7 +59,11 @@ export interface DenoSharedRuntime {
    * Invoke a function exported by a shared module. Throws if the
    * module or export is unknown, or if the export itself throws.
    */
-  call(moduleId: string, exportName: string, args: readonly unknown[]): Promise<unknown>;
+  call(
+    moduleId: string,
+    exportName: string,
+    args: readonly unknown[],
+  ): Promise<unknown>;
   /**
    * Re-import a shared module after its source file changed. Returns
    * the new record. If the export list changed, callers should