1tube 0.1.41 → 0.1.43

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/deno.lock

@@ -20,8 +20,8 @@
     "npm:es-module-lexer@2": "2.1.0",
     "npm:esbuild@~0.25.5": "0.25.12",
     "npm:esbuild@~0.28.1": "0.28.1",
-    "npm:hono@4": "4.12.25",
-    "npm:hono@^4.12.25": "4.12.25",
+    "npm:hono@4": "4.12.27",
+    "npm:hono@^4.12.27": "4.12.27",
     "npm:typescript@latest": "6.0.3",
     "npm:zod@^3.23.0": "3.25.76"
   },
@@ -515,8 +515,8 @@
         "resolve-pkg-maps"
       ]
     },
-    "hono@4.12.25": {
-      "integrity": "sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ=="
+    "hono@4.12.27": {
+      "integrity": "sha512-1yrb/+w6HWQJrUCLkJ2IF5jNIPvvFkblV5RNOYl6bV+OA6p9GLcMpHFFGTosSvHvcAUibuUukRqhlYI4z32C7Q=="
     },
     "jiti@2.6.1": {
       "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==",
@@ -555,7 +555,7 @@
       "dependencies": [
         "npm:drizzle-kit@1.0.0-rc.3",
         "npm:drizzle-orm@1.0.0-rc.3",
-        "npm:hono@^4.12.25"
+        "npm:hono@^4.12.27"
       ]
     }
   }

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.41",
+  "version": "0.1.43",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
-    "hono": "^4.12.25"
+    "hono": "^4.12.27"
   },
   "devDependencies": {
     "drizzle-kit": "1.0.0-rc.3"

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 } 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,112 @@ 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=")
+);
+
+const denoArgs = ["run", "--quiet", "-A"];
+if (!userSuppliedConfig) denoArgs.push("--config", denoConfig);
+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";
+}
+
+// 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 +141,62 @@ child.on("exit", (code, signal) => {
   }
   process.exit(code ?? 1);
 });
+
+/**
+ * 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/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

package/src/backends/deno/worker-entry.ts

@@ -62,10 +62,16 @@ interface SharedCallResultMessage {
 
 type HostMessage = InitMessage | DispatchMessage | SharedCallResultMessage;
 
-type Handler = (req: Request, auth?: AuthContext) => Response | Promise<Response>;
+type Handler = (
+  req: Request,
+  auth?: AuthContext,
+) => Response | Promise<Response>;
 
 interface RegistryStub {
-  register(handler: Handler, opts: { public: boolean; timeoutMs?: number }): void;
+  register(
+    handler: Handler,
+    opts: { public: boolean; timeoutMs?: number },
+  ): void;
 }
 
 interface CapturedHandler {
@@ -93,13 +99,23 @@ let initDone = false;
 const invocationContext = new AsyncLocalStorage<{ invocationId?: string }>();
 
 type ConsoleLevel = "debug" | "log" | "info" | "warn" | "error";
-const CONSOLE_LEVELS: ConsoleLevel[] = ["debug", "log", "info", "warn", "error"];
+const CONSOLE_LEVELS: ConsoleLevel[] = [
+  "debug",
+  "log",
+  "info",
+  "warn",
+  "error",
+];
 const MAX_CONSOLE_MESSAGE = 8 * 1024;
 
 function formatConsoleArg(arg: unknown): string {
   if (typeof arg === "string") return arg;
   try {
-    return Deno.inspect(arg, { depth: 4, colors: false, strAbbreviateSize: 4096 });
+    return Deno.inspect(arg, {
+      depth: 4,
+      colors: false,
+      strAbbreviateSize: 4096,
+    });
   } catch {
     try {
       return String(arg);
@@ -178,7 +194,9 @@ const stub: RegistryStub = {
       // The function called serve() twice. Last write wins, matching the
       // in-process registry's behaviour. Surface a warning so authors notice
       // the bug.
-      console.warn(`[1tube] "${functionName}" called serve() twice; using the last handler`);
+      console.warn(
+        `[1tube] "${functionName}" called serve() twice; using the last handler`,
+      );
     }
     captured = {
       handler,
@@ -188,8 +206,8 @@ const stub: RegistryStub = {
   },
 };
 
-(globalThis as { __edgeFunctionRegistry?: RegistryStub }).__edgeFunctionRegistry =
-  stub;
+(globalThis as { __edgeFunctionRegistry?: RegistryStub })
+  .__edgeFunctionRegistry = stub;
 
 self.addEventListener("unhandledrejection", (e) => {
   e.preventDefault();
@@ -221,7 +239,8 @@ async function runDispatch(msg: DispatchMessage): Promise<void> {
     postMessage({
       type: "response_error",
       id: msg.id,
-      message: `Function "${functionName}" did not call serve() before dispatch`,
+      message:
+        `Function "${functionName}" did not call serve() before dispatch`,
     });
     return;
   }