1tube 0.1.32 → 0.1.34

package/README.md

@@ -73,6 +73,7 @@ dependency install — **1tube’s runtime graph is just Hono + JSR std**.
 | `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
 
@@ -87,6 +88,9 @@ All knobs default to safe-but-backwards-compatible values. The TS gateway
 | `--timeout` / `FUNCTION_TIMEOUT_MS`                         | `150000`               | Per-request wall-clock cap (also overridable per function)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `--dev` / `1TUBE_DEV`                                       | off                    | Applies the well-known local Supabase JWT/secrets. **Refuses to start in prod when JWT_SECRET / SUPABASE_SERVICE_ROLE_KEY are missing or are the public dev defaults.**                                                                                                                                                                                                                                                                                                                                                          |
 | `--hmr` / `1TUBE_HMR`                                       | off                    | File-watch + per-function reload (dev only).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--defer-boot` / `1TUBE_DEFER_BOOT`                         | on in dev/HMR          | Deferred boot (Deno backend only): the gateway accepts requests immediately while function Workers spawn in the background. Requests for cold functions jump the boot queue and get `503` + `X-1tube-Warming: 1` until ready. Disable with `--no-defer-boot` / `1TUBE_DEFER_BOOT=0`. See [Deferred boot & warm-up overlay](#deferred-boot--warm-up-overlay).                                                                                                                                                                     |
+| `--warmup-grace-ms` / `1TUBE_WARMUP_GRACE_MS`               | `250`                  | How long the dispatcher waits for a warming function before answering with the warming 503. Keeps fast-loading functions from flashing the frontend overlay.                                                                                                                                                                                                                                                                                                                                                                     |
+| `1TUBE_HMR_FRESH_WAIT_MS`                                   | `2500`                 | How long a request waits for an in-flight HMR respawn of its function before falling back to the previous (stale) worker. Fresh code wins by default (Vite-style "request stalls until the rebuild lands"). Stale fallbacks carry `X-1tube-Stale: 1`. `0` = never wait.                                                                                                                                                                                                                                                          |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -103,6 +107,99 @@ All knobs default to safe-but-backwards-compatible values. The TS gateway
 | `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.                                                                                                                                                                                                                                                                                                                                        |
 
 ````
+## Deferred boot & warm-up overlay
+
+On the Deno backend, eager boot pays the full cost of spawning one Worker per
+function (each transpiling + evaluating its whole import graph) **before** the
+gateway accepts a single request. With dozens of functions importing heavy
+deps, that's tens of seconds of staring at a boot log.
+
+Deferred boot (default whenever `--dev` or `--hmr` is on) flips the order:
+
+1. Functions are **discovered instantly** and registered as known-but-queued —
+   the gateway starts serving right away. Time-to-first-request drops from
+   "sum of all worker spawns" to effectively zero.
+2. Workers spawn in the background with the usual bounded concurrency
+   (`--deno-worker-concurrency`, default 8).
+3. A request for a function whose Worker isn't ready yet **bumps it to the
+   front of the queue** and spawns it immediately, out-of-band. If it becomes
+   ready within the grace window (`--warmup-grace-ms`, default 250 ms) the
+   request is served normally and the client never notices. Otherwise the
+   gateway answers with the **warming contract** below, and the rest of the
+   queue keeps loading in the background.
+
+### The warming contract
+
+```http
+HTTP/1.1 503 Service Unavailable
+X-1tube-Warming: 1
+Retry-After: 1
+
+{"error":"Backend is warming up","reason":"function_warming","function":"hello",
+ "state":"loading","warmup":{"total":53,"ready":12,"loading":8,"queued":33,"failed":0}}
+```
+
+`X-1tube-Warming: 1` is the discriminator — a plain 503 (circuit breaker,
+overload) never carries it. It's in `Access-Control-Expose-Headers`, so browser
+JS can read it cross-origin. This is what lets a frontend distinguish "the
+backend is still warming up" from real latency or a real outage and show an
+honest overlay instead of a spinner.
+
+`GET /1tube/warmup` reports overall progress (also CORS-enabled), e.g. for a
+progress bar inside the overlay.
+
+### Frontend helper
+
+The npm package ships a tiny client (`1tube/warmup-client`, no dependencies):
+
+```ts
+import { createWarmupFetch } from "1tube/warmup-client";
+
+const warmFetch = createWarmupFetch({
+  onWarmingChange: (warming) => setShowWarmupOverlay(warming), // drive the overlay
+  retryDelayMs: 400,
+  maxWaitMs: 120_000,
+});
+
+// Drop-in fetch replacement: retries through warm-up transparently.
+const resp = await warmFetch(`${GATEWAY}/functions/v1/hello`, { method: "POST" });
+```
+
+`isWarmingResponse(resp)` and `fetchWarmupStatus(baseUrl)` are exported for
+hand-rolled integrations.
+
+### Smart HMR reloads
+
+The same queue machinery powers HMR on the Deno backend, so a save costs as
+little as possible:
+
+- **No-op saves are dropped.** Changed files are content-hashed; a re-save
+  with identical bytes (format-on-save no-ops, `touch`, agent tooling
+  re-writing the same file) never respawns a Worker.
+- **Leading-edge debounce.** The first fs event of a quiet period flushes
+  after ~40 ms instead of the full 200 ms trailing window — a single editor
+  save starts reloading almost immediately. Stragglers still coalesce.
+- **MRU-first respawns.** When one edit affects more functions than there are
+  spawn lanes (shared-module edits), the functions you've hit most recently
+  respawn first; idle ones go last.
+- **Request-driven priority + freshness.** A request for a function whose
+  respawn is still queued/in-flight bumps it to the front (out-of-band, above
+  the concurrency bound) and waits up to `1TUBE_HMR_FRESH_WAIT_MS` (default
+  2500 ms) so save → refresh returns the **new** code, like Vite. If the
+  respawn takes longer, the previous worker answers and the response is marked
+  `X-1tube-Stale: 1` (CORS-exposed) so tooling can tell the difference.
+- **Targeted re-discovery.** Reloading one function stats only that function's
+  dir instead of re-scanning the whole functions root.
+
+Notes:
+
+- Deferred boot is **off by default in prod** (eager boot keeps the "everything
+  is ready before traffic" contract); opt in with `--defer-boot`.
+- Functions that fail to boot answer `503 {"reason":"function_boot_failed"}`
+  (not a warming response — retrying won't help).
+- Workerd backend is unaffected: it boots all functions as a single bundle
+  generation.
+
 ## Workerd backend
 
 1tube can optionally run each function inside a [workerd](https://github.com/cloudflare/workerd) subprocess instead of importing it directly into the gateway. This gives:

package/deno.json

@@ -15,6 +15,8 @@
     "@std/path": "jsr:@std/path@^1",
     "@std/assert": "jsr:@std/assert@^1",
     "hono": "npm:hono@4",
+    "drizzle-orm": "npm:drizzle-orm@1.0.0-rc.3",
+    "drizzle-orm/": "npm:/drizzle-orm@1.0.0-rc.3/",
     "esbuild": "npm:esbuild@^0.28",
     "es-module-lexer": "npm:es-module-lexer@^2",
     "@deno/esbuild-plugin": "jsr:@deno/esbuild-plugin@^1.2",

package/deno.lock

@@ -11,12 +11,19 @@
     "jsr:@std/path@^1.1.1": "1.1.4",
     "jsr:@std/path@^1.1.4": "1.1.4",
     "jsr:@zip-js/zip-js@^2.8.0": "2.8.26",
+    "npm:@ai-sdk/anthropic@2": "2.0.80_zod@3.25.76",
+    "npm:@ai-sdk/google@2": "2.0.74_zod@3.25.76",
+    "npm:@ai-sdk/openai@2": "2.0.106_zod@3.25.76",
+    "npm:ai@6": "6.0.193_zod@3.25.76",
+    "npm:drizzle-kit@1.0.0-rc.3": "1.0.0-rc.3",
+    "npm:drizzle-orm@1.0.0-rc.3": "1.0.0-rc.3_zod@3.25.76",
     "npm:es-module-lexer@2": "2.1.0",
     "npm:esbuild@0.28": "0.28.0",
     "npm:esbuild@~0.25.5": "0.25.12",
-    "npm:hono@4": "4.12.18",
-    "npm:hono@^4.12.18": "4.12.18",
-    "npm:typescript@latest": "6.0.3"
+    "npm:hono@4": "4.12.25",
+    "npm:hono@^4.12.25": "4.12.25",
+    "npm:typescript@latest": "6.0.3",
+    "npm:zod@^3.23.0": "3.25.76"
   },
   "jsr": {
     "@deno/esbuild-plugin@1.2.1": {
@@ -59,6 +66,72 @@
     }
   },
   "npm": {
+    "@ai-sdk/anthropic@2.0.80_zod@3.25.76": {
+      "integrity": "sha512-7HPgFv91YFFYyZapM/Vy3tRbBq/hL44omh0vz/WikiU7fJFxdOjCeg6Nb089lxM7+qBe7blZsoSRJ7gfAkEo1w==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.3",
+        "@ai-sdk/provider-utils@3.0.25_zod@3.25.76",
+        "zod"
+      ]
+    },
+    "@ai-sdk/gateway@3.0.121_zod@3.25.76": {
+      "integrity": "sha512-uY248djJRxa5W68MHiyqO8WLdOeKQoRClGg7PVX/VPhVW8SJNM7/l5DcrA5WAM3YfQrLyNkgZa2VOu8T0t8LUw==",
+      "dependencies": [
+        "@ai-sdk/provider@3.0.10",
+        "@ai-sdk/provider-utils@4.0.27_zod@3.25.76",
+        "@vercel/oidc",
+        "zod"
+      ]
+    },
+    "@ai-sdk/google@2.0.74_zod@3.25.76": {
+      "integrity": "sha512-Lhw1742RXc+4pRIvqVXa0jdl5+qdpmw8lj0lm6OchUg9rVGHzymlaxe7CDiYX5U2af4jbjKeTY22LDi3bIycgQ==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.3",
+        "@ai-sdk/provider-utils@3.0.25_zod@3.25.76",
+        "zod"
+      ]
+    },
+    "@ai-sdk/openai@2.0.106_zod@3.25.76": {
+      "integrity": "sha512-EFC0rpo1wfe4HIz5KZCE72edP2J7fOeR7wPXzjCDljaTRB1wectKDIKRLowpU4F0mbcJ+XScAsoYNPK/Z20aVQ==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.3",
+        "@ai-sdk/provider-utils@3.0.25_zod@3.25.76",
+        "zod"
+      ]
+    },
+    "@ai-sdk/provider-utils@3.0.25_zod@3.25.76": {
+      "integrity": "sha512-CvsRu+32Y8a167s+lrIBtsybvgTHp8j9y+6BeTvLeoW3Q+okw/b4CnNUFOLIXsRaKHQKAH+IHNJPYWywfpw0LA==",
+      "dependencies": [
+        "@ai-sdk/provider@2.0.3",
+        "@standard-schema/spec",
+        "eventsource-parser",
+        "zod"
+      ]
+    },
+    "@ai-sdk/provider-utils@4.0.27_zod@3.25.76": {
+      "integrity": "sha512-ubkAJ+xODouwtmN1tYlvTPphH1hPOBfZaEQe8U7skGvFAnIRs9PPpsq57bC2+Ky/MB4yzhd6YOsxTAx9sGpazw==",
+      "dependencies": [
+        "@ai-sdk/provider@3.0.10",
+        "@standard-schema/spec",
+        "eventsource-parser",
+        "zod"
+      ]
+    },
+    "@ai-sdk/provider@2.0.3": {
+      "integrity": "sha512-h88OPkavHTiN9tMn2l5awAznGB0lXzjcLhgR1/rvjB2zlLprsNxbM2tt6OJsHUxduLC3klq0/eqaSf6fX5XVww==",
+      "dependencies": [
+        "json-schema"
+      ]
+    },
+    "@ai-sdk/provider@3.0.10": {
+      "integrity": "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw==",
+      "dependencies": [
+        "json-schema"
+      ]
+    },
+    "@drizzle-team/brocli@0.11.0": {
+      "integrity": "sha512-hD3pekGiPg0WPCCGAZmusBBJsDqGUR66Y452YgQsZOnkdQ7ViEPKuyP4huUGEZQefp8g34RRodXYmJ2TbCH+tg=="
+    },
     "@esbuild/aix-ppc64@0.25.12": {
       "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
       "os": ["aix"],
@@ -319,6 +392,51 @@
       "os": ["win32"],
       "cpu": ["x64"]
     },
+    "@js-temporal/polyfill@0.5.1": {
+      "integrity": "sha512-hloP58zRVCRSpgDxmqCWJNlizAlUgJFqG2ypq79DCvyv9tHjRYMDOcPFjzfl/A1/YxDvRCZz8wvZvmapQnKwFQ==",
+      "dependencies": [
+        "jsbi"
+      ]
+    },
+    "@opentelemetry/api@1.9.1": {
+      "integrity": "sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q=="
+    },
+    "@standard-schema/spec@1.1.0": {
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="
+    },
+    "@vercel/oidc@3.2.0": {
+      "integrity": "sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug=="
+    },
+    "ai@6.0.193_zod@3.25.76": {
+      "integrity": "sha512-VQOTOse8+X8kMtg61DNSXlYJzwOW4NjMLDJNk/qxClWsFe4oiyFJDHGGG1oezfGcFzuYuQe/8Z7r4kwiZWh2YQ==",
+      "dependencies": [
+        "@ai-sdk/gateway",
+        "@ai-sdk/provider@3.0.10",
+        "@ai-sdk/provider-utils@4.0.27_zod@3.25.76",
+        "@opentelemetry/api",
+        "zod"
+      ]
+    },
+    "drizzle-kit@1.0.0-rc.3": {
+      "integrity": "sha512-lwGIi6GTlEYzrtac1Szecns+zrAxjaOoNysfBCKRQOXQE7nMJ8IU2I2S6ek3FHEm1N30dQb5YrTdqV7zNH6n7A==",
+      "dependencies": [
+        "@drizzle-team/brocli",
+        "@js-temporal/polyfill",
+        "esbuild@0.25.12",
+        "get-tsconfig",
+        "jiti"
+      ],
+      "bin": true
+    },
+    "drizzle-orm@1.0.0-rc.3_zod@3.25.76": {
+      "integrity": "sha512-akZOa5UxapFbdBG8IDkfBRpSZJpMHaOJtGgp7oi1oHaiU8S3KN92waHo2l5aRuv1D9tMGYpv3BQFOsiGcNjLTQ==",
+      "dependencies": [
+        "zod"
+      ],
+      "optionalPeers": [
+        "zod"
+      ]
+    },
     "es-module-lexer@2.1.0": {
       "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ=="
     },
@@ -388,12 +506,37 @@
       "scripts": true,
       "bin": true
     },
-    "hono@4.12.18": {
-      "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ=="
+    "eventsource-parser@3.1.0": {
+      "integrity": "sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg=="
+    },
+    "get-tsconfig@4.14.0": {
+      "integrity": "sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==",
+      "dependencies": [
+        "resolve-pkg-maps"
+      ]
+    },
+    "hono@4.12.25": {
+      "integrity": "sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ=="
+    },
+    "jiti@2.6.1": {
+      "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==",
+      "bin": true
+    },
+    "jsbi@4.3.2": {
+      "integrity": "sha512-9fqMSQbhJykSeii05nxKl4m6Eqn2P6rOlYiS+C5Dr/HPIU/7yZxu5qzbs40tgaFORiw2Amd0mirjxatXYMkIew=="
+    },
+    "json-schema@0.4.0": {
+      "integrity": "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA=="
+    },
+    "resolve-pkg-maps@1.0.0": {
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="
     },
     "typescript@6.0.3": {
       "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
       "bin": true
+    },
+    "zod@3.25.76": {
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="
     }
   },
   "workspace": {
@@ -403,13 +546,16 @@
       "jsr:@std/assert@1",
       "jsr:@std/path@1",
       "jsr:@zip-js/zip-js@^2.8.0",
+      "npm:drizzle-orm@1.0.0-rc.3",
       "npm:es-module-lexer@2",
       "npm:esbuild@0.28",
       "npm:hono@4"
     ],
     "packageJson": {
       "dependencies": [
-        "npm:hono@^4.12.18"
+        "npm:drizzle-kit@1.0.0-rc.3",
+        "npm:drizzle-orm@1.0.0-rc.3",
+        "npm:hono@^4.12.25"
       ]
     }
   }

package/dist/warmup-client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Frontend helper for 1tube's deferred-boot warming contract.
+ *
+ * When the gateway boots with `--defer-boot` (default in dev/HMR mode),
+ * a request for a function whose Worker isn't ready yet returns:
+ *
+ *     503 Service Unavailable
+ *     X-1tube-Warming: 1
+ *     Retry-After: 1
+ *     { "error": "Backend is warming up", "reason": "function_warming", ... }
+ *
+ * The gateway simultaneously bumps that function to the front of its
+ * boot queue, so retrying soon usually succeeds. This module wraps
+ * `fetch` so the warming state is surfaced to the UI (show a
+ * "Backend is warming up" overlay) instead of looking like real latency.
+ *
+ * Usage:
+ *
+ *     import { createWarmupFetch } from "1tube/warmup-client";
+ *
+ *     const warmFetch = createWarmupFetch({
+ *       onWarmingChange: (warming) => overlay.toggle(warming),
+ *     });
+ *     const resp = await warmFetch("/functions/v1/hello", { method: "POST" });
+ */
+/** Response header the gateway sets on warming 503s. */
+export declare const WARMING_HEADER = "x-1tube-warming";
+/** True when `resp` is the gateway's "function is warming up" response. */
+export declare function isWarmingResponse(resp: Response): boolean;
+export interface WarmupInfo {
+    /** 1-based count of attempts made so far (including the initial one). */
+    attempt: number;
+    /** Milliseconds elapsed since the first attempt. */
+    elapsedMs: number;
+}
+export interface WarmupFetchOptions {
+    /** Underlying fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Give up after this long and return the last warming response as-is.
+     * Defaults to 120 000 ms. Set 0 to disable retrying entirely (the
+     * warming response is returned immediately; `onWarmingChange` still
+     * fires so the overlay can be driven manually).
+     */
+    maxWaitMs?: number;
+    /**
+     * Delay between retries, in ms. Defaults to 400. The warming 503's
+     * `Retry-After` header is deliberately ignored here — it has seconds
+     * granularity, far too coarse for warm-up polling (functions usually
+     * become ready within a few hundred ms of being prioritized).
+     */
+    retryDelayMs?: number;
+    /**
+     * Fired with `true` when the first warming response is seen and with
+     * `false` once a non-warming response arrives (or retrying stops).
+     * Wire this to your "Backend is warming up" overlay.
+     */
+    onWarmingChange?: (warming: boolean, info: WarmupInfo) => void;
+}
+/**
+ * Wrap `fetch` so warming 503s are retried transparently while the UI is
+ * informed via `onWarmingChange`. The returned function is a drop-in
+ * `fetch` replacement for calls into the 1tube gateway.
+ *
+ * Note on request bodies: retrying re-sends `init.body`. Strings, Blobs,
+ * ArrayBuffers, FormData and URLSearchParams are safely re-sendable; a
+ * `ReadableStream` body is consumed by the first attempt, so streaming
+ * requests are returned without retrying (the overlay callback still
+ * fires).
+ */
+export declare function createWarmupFetch(options?: WarmupFetchOptions): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface WarmupStatus {
+    backend: string;
+    /** True once every discovered function finished booting. */
+    ready: boolean;
+    total: number;
+    loaded: number;
+    loading: string[];
+    queued: string[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * Fetch the gateway's boot status from `GET /1tube/warmup`. Useful for a
+ * progress bar inside the overlay ("12/53 functions ready").
+ *
+ * @param baseUrl Gateway origin, e.g. `http://localhost:3100`.
+ */
+export declare function fetchWarmupStatus(baseUrl: string, init?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<WarmupStatus>;

package/dist/warmup-client.js

@@ -0,0 +1,100 @@
+/**
+ * Frontend helper for 1tube's deferred-boot warming contract.
+ *
+ * When the gateway boots with `--defer-boot` (default in dev/HMR mode),
+ * a request for a function whose Worker isn't ready yet returns:
+ *
+ *     503 Service Unavailable
+ *     X-1tube-Warming: 1
+ *     Retry-After: 1
+ *     { "error": "Backend is warming up", "reason": "function_warming", ... }
+ *
+ * The gateway simultaneously bumps that function to the front of its
+ * boot queue, so retrying soon usually succeeds. This module wraps
+ * `fetch` so the warming state is surfaced to the UI (show a
+ * "Backend is warming up" overlay) instead of looking like real latency.
+ *
+ * Usage:
+ *
+ *     import { createWarmupFetch } from "1tube/warmup-client";
+ *
+ *     const warmFetch = createWarmupFetch({
+ *       onWarmingChange: (warming) => overlay.toggle(warming),
+ *     });
+ *     const resp = await warmFetch("/functions/v1/hello", { method: "POST" });
+ */
+/** Response header the gateway sets on warming 503s. */
+export const WARMING_HEADER = "x-1tube-warming";
+/** True when `resp` is the gateway's "function is warming up" response. */
+export function isWarmingResponse(resp) {
+    return resp.status === 503 && resp.headers.get(WARMING_HEADER) === "1";
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Wrap `fetch` so warming 503s are retried transparently while the UI is
+ * informed via `onWarmingChange`. The returned function is a drop-in
+ * `fetch` replacement for calls into the 1tube gateway.
+ *
+ * Note on request bodies: retrying re-sends `init.body`. Strings, Blobs,
+ * ArrayBuffers, FormData and URLSearchParams are safely re-sendable; a
+ * `ReadableStream` body is consumed by the first attempt, so streaming
+ * requests are returned without retrying (the overlay callback still
+ * fires).
+ */
+export function createWarmupFetch(options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const maxWaitMs = options.maxWaitMs ?? 120_000;
+    const retryDelayMs = options.retryDelayMs ?? 400;
+    return async (input, init) => {
+        const startedAt = Date.now();
+        let attempt = 0;
+        let warming = false;
+        const info = () => ({
+            attempt,
+            elapsedMs: Date.now() - startedAt,
+        });
+        const setWarming = (next) => {
+            if (warming === next)
+                return;
+            warming = next;
+            options.onWarmingChange?.(next, info());
+        };
+        try {
+            while (true) {
+                attempt++;
+                const resp = await fetchImpl(input, init);
+                if (!isWarmingResponse(resp)) {
+                    setWarming(false);
+                    return resp;
+                }
+                setWarming(true);
+                const bodyNotReplayable = typeof ReadableStream !== "undefined" &&
+                    init?.body instanceof ReadableStream;
+                const elapsed = Date.now() - startedAt;
+                if (bodyNotReplayable || elapsed + retryDelayMs > maxWaitMs) {
+                    return resp;
+                }
+                await sleep(retryDelayMs);
+            }
+        }
+        finally {
+            // Covers thrown fetch errors and the give-up paths above: never
+            // leave the overlay stuck on.
+            setWarming(false);
+        }
+    };
+}
+/**
+ * Fetch the gateway's boot status from `GET /1tube/warmup`. Useful for a
+ * progress bar inside the overlay ("12/53 functions ready").
+ *
+ * @param baseUrl Gateway origin, e.g. `http://localhost:3100`.
+ */
+export async function fetchWarmupStatus(baseUrl, init) {
+    const fetchImpl = init?.fetch ?? fetch;
+    const resp = await fetchImpl(`${baseUrl.replace(/\/+$/, "")}/1tube/warmup`, init?.signal ? { signal: init.signal } : undefined);
+    if (!resp.ok) {
+        throw new Error(`warmup status request failed: HTTP ${resp.status}`);
+    }
+    return await resp.json();
+}

package/drizzle/20260610161429_init_logs/migration.sql

@@ -0,0 +1,30 @@
+CREATE TABLE `invocations` (
+	`id` text PRIMARY KEY,
+	`ts_ms` integer NOT NULL,
+	`function_name` text NOT NULL,
+	`method` text NOT NULL,
+	`path` text NOT NULL,
+	`status` integer NOT NULL,
+	`duration_ms` integer NOT NULL,
+	`user_id` text,
+	`backend` text NOT NULL,
+	`error_kind` text,
+	`error_message` text,
+	`error_stack` text
+);
+--> statement-breakpoint
+CREATE TABLE `logs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT,
+	`invocation_id` text,
+	`ts_ms` integer NOT NULL,
+	`level` text NOT NULL,
+	`function_name` text,
+	`source` text DEFAULT 'function' NOT NULL,
+	`message` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_invocations_ts` ON `invocations` (`ts_ms`);--> statement-breakpoint
+CREATE INDEX `idx_invocations_fn_ts` ON `invocations` (`function_name`,`ts_ms`);--> statement-breakpoint
+CREATE INDEX `idx_invocations_status_ts` ON `invocations` (`status`,`ts_ms`);--> statement-breakpoint
+CREATE INDEX `idx_logs_invocation` ON `logs` (`invocation_id`);--> statement-breakpoint
+CREATE INDEX `idx_logs_ts` ON `logs` (`ts_ms`);