1tube 0.1.31 → 0.1.33

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/edge-caller.d.ts

@@ -0,0 +1,30 @@
+export type CallEdgeAuth = "service" | "user" | {
+    bearer: string;
+};
+export interface CallEdgeFunctionOptions {
+    /** HTTP method. Defaults to `"POST"`. */
+    method?: string;
+    /** Optional route path inside the target function, e.g. `/sync`. */
+    path?: string;
+    /** Query parameters appended to the function URL. */
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    auth?: CallEdgeAuth;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface EdgeCallerRuntime {
+    getBaseUrl(): string;
+    /** Public prefix in front of the function name. Defaults to `/functions/v1`. */
+    pathPrefix?: string;
+    getServiceRoleToken(): string | null | undefined;
+    getAnonKey?(): string | null | undefined;
+    getUserToken(): string | null | undefined;
+    fetch?: typeof fetch;
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+export interface EdgeCaller {
+    callEdgeFunction(name: string, options?: CallEdgeFunctionOptions): Promise<Response>;
+    callEdgeFunctionInBackground(name: string, options?: CallEdgeFunctionOptions): void;
+}
+export declare function createEdgeCaller(runtime: EdgeCallerRuntime): EdgeCaller;

package/dist/edge-caller.js

@@ -0,0 +1,77 @@
+function resolveBearerToken(runtime, auth) {
+    if (typeof auth === "object" && auth !== null && "bearer" in auth) {
+        return auth.bearer;
+    }
+    if (auth === "user") {
+        const token = runtime.getUserToken();
+        if (!token) {
+            throw new Error("[callEdgeFunction] auth: 'user' requires an authenticated caller " +
+                "(no user token available).");
+        }
+        return token;
+    }
+    const serviceToken = runtime.getServiceRoleToken();
+    if (!serviceToken) {
+        throw new Error("[callEdgeFunction] service auth requires a service role token.");
+    }
+    return serviceToken;
+}
+function serializeBody(body) {
+    if (body === undefined || body === null)
+        return { body: undefined };
+    if (typeof body === "string") {
+        return { body, contentType: "text/plain;charset=UTF-8" };
+    }
+    if (body instanceof Uint8Array ||
+        body instanceof ArrayBuffer ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof ReadableStream) {
+        return { body: body };
+    }
+    return { body: JSON.stringify(body), contentType: "application/json" };
+}
+function buildRequest(runtime, name, opts) {
+    const pathPrefix = runtime.pathPrefix ?? "/functions/v1";
+    const routePath = opts.path ? `/${opts.path.replace(/^\/+/, "")}` : "";
+    const url = new URL(`${runtime.getBaseUrl().replace(/\/+$/, "")}/${pathPrefix.replace(/^\/+|\/+$/g, "")}/${name}${routePath}`);
+    for (const [key, value] of Object.entries(opts.query ?? {})) {
+        if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    const token = resolveBearerToken(runtime, opts.auth ?? "service");
+    const { body, contentType } = serializeBody(opts.body);
+    const anonKey = runtime.getAnonKey?.();
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        ...(contentType ? { "Content-Type": contentType } : {}),
+        ...(anonKey ? { apikey: anonKey } : {}),
+        ...opts.headers,
+    };
+    return {
+        url: url.toString(),
+        init: {
+            method: opts.method ?? "POST",
+            headers,
+            body: body ?? null,
+            signal: opts.signal,
+        },
+    };
+}
+export function createEdgeCaller(runtime) {
+    const fetchImpl = runtime.fetch ?? fetch;
+    return {
+        async callEdgeFunction(name, options = {}) {
+            const { url, init } = buildRequest(runtime, name, options);
+            return await fetchImpl(url, init);
+        },
+        callEdgeFunctionInBackground(name, options = {}) {
+            const { url, init } = buildRequest(runtime, name, options);
+            const promise = fetchImpl(url, init).catch((err) => {
+                console.error(`[callEdgeFunctionInBackground] ${name} failed:`, err);
+            });
+            runtime.waitUntil?.(promise);
+        },
+    };
+}

package/dist/edge.d.ts

@@ -0,0 +1,176 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface SchemaLike<T = unknown> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+export interface JsonSchemaAdapter {
+    toJsonSchema(schema: SchemaLike): unknown;
+}
+type SchemaOutput<TSchema> = TSchema extends SchemaLike<infer T> ? T : undefined;
+type ParamsOutput<TSchema> = TSchema extends SchemaLike<infer T> ? T : Record<string, string>;
+type QueryOutput<TSchema> = TSchema extends SchemaLike<infer T> ? T : Record<string, string>;
+export declare enum HttpStatus {
+    OK = 200,
+    CREATED = 201,
+    ACCEPTED = 202,
+    NO_CONTENT = 204,
+    RESET_CONTENT = 205,
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    METHOD_NOT_ALLOWED = 405,
+    REQUEST_TIMEOUT = 408,
+    CONFLICT = 409,
+    GONE = 410,
+    PRECONDITION_FAILED = 412,
+    PAYLOAD_TOO_LARGE = 413,
+    UNSUPPORTED_MEDIA_TYPE = 415,
+    UNPROCESSABLE_CONTENT = 422,
+    LOCKED = 423,
+    PRECONDITION_REQUIRED = 428,
+    TOO_MANY_REQUESTS = 429,
+    INTERNAL_SERVER_ERROR = 500,
+    NOT_IMPLEMENTED = 501,
+    BAD_GATEWAY = 502,
+    SERVICE_UNAVAILABLE = 503,
+    GATEWAY_TIMEOUT = 504
+}
+export type ErrorHttpStatus = HttpStatus.BAD_REQUEST | HttpStatus.UNAUTHORIZED | HttpStatus.FORBIDDEN | HttpStatus.NOT_FOUND | HttpStatus.METHOD_NOT_ALLOWED | HttpStatus.REQUEST_TIMEOUT | HttpStatus.CONFLICT | HttpStatus.GONE | HttpStatus.PRECONDITION_FAILED | HttpStatus.PAYLOAD_TOO_LARGE | HttpStatus.UNSUPPORTED_MEDIA_TYPE | HttpStatus.UNPROCESSABLE_CONTENT | HttpStatus.LOCKED | HttpStatus.PRECONDITION_REQUIRED | HttpStatus.TOO_MANY_REQUESTS | HttpStatus.INTERNAL_SERVER_ERROR | HttpStatus.NOT_IMPLEMENTED | HttpStatus.BAD_GATEWAY | HttpStatus.SERVICE_UNAVAILABLE | HttpStatus.GATEWAY_TIMEOUT;
+export type RouteResponses = Partial<Record<HttpStatus, SchemaLike>>;
+export interface RouteRequest<TParams extends SchemaLike | undefined, TQuery extends SchemaLike | undefined, TBody extends SchemaLike | undefined, TContext> {
+    req: Request;
+    ctx: TContext;
+    params: ParamsOutput<TParams>;
+    query: QueryOutput<TQuery>;
+    body: SchemaOutput<TBody>;
+}
+export type RouteHandler<TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TContext = unknown> = (input: RouteRequest<TParams, TQuery, TBody, TContext>) => Response | Promise<Response>;
+export interface RouteOptions<TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = RouteResponses, TContext = unknown> {
+    params?: TParams;
+    query?: TQuery;
+    body?: TBody;
+    responses: TResponses;
+    summary?: string;
+    description?: string;
+    handler: RouteHandler<TParams, TQuery, TBody, TContext>;
+}
+export interface RouteDefinition<TParams extends SchemaLike | undefined = SchemaLike | undefined, TQuery extends SchemaLike | undefined = SchemaLike | undefined, TBody extends SchemaLike | undefined = SchemaLike | undefined, TResponses extends RouteResponses = RouteResponses, TContext = unknown> extends RouteOptions<TParams, TQuery, TBody, TResponses, TContext> {
+    method: HttpMethod;
+    path: string;
+    operationId: string;
+}
+export interface JsonRouteOptions<TBody extends SchemaLike, TResponses extends RouteResponses, TContext> {
+    body: TBody;
+    responses: TResponses;
+    summary?: string;
+    description?: string;
+    handler: RouteHandler<undefined, undefined, TBody, TContext>;
+}
+export declare function createRouteBuilder<TDefaultContext = unknown>(): {
+    get: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, undefined, TResponses, TDefaultContext>) => RouteDefinition<TParams, TQuery, undefined, TResponses, TDefaultContext>;
+    post: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, TDefaultContext>) => RouteDefinition<TParams, TQuery, TBody, TResponses, TDefaultContext>;
+    put: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, TDefaultContext>) => RouteDefinition<TParams, TQuery, TBody, TResponses, TDefaultContext>;
+    patch: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, TDefaultContext>) => RouteDefinition<TParams, TQuery, TBody, TResponses, TDefaultContext>;
+    delete: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TResponses extends RouteResponses = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, undefined, TResponses, TDefaultContext>) => RouteDefinition<TParams, TQuery, undefined, TResponses, TDefaultContext>;
+    postJson: <TBody extends SchemaLike, TResponses extends RouteResponses>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, TDefaultContext>) => RouteDefinition<undefined, undefined, TBody, TResponses, TDefaultContext>;
+    putJson: <TBody extends SchemaLike, TResponses extends RouteResponses>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, TDefaultContext>) => RouteDefinition<undefined, undefined, TBody, TResponses, TDefaultContext>;
+    patchJson: <TBody extends SchemaLike, TResponses extends RouteResponses>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, TDefaultContext>) => RouteDefinition<undefined, undefined, TBody, TResponses, TDefaultContext>;
+};
+export declare const route: {
+    get: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>> = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, undefined, TResponses, unknown>) => RouteDefinition<TParams, TQuery, undefined, TResponses, unknown>;
+    post: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>> = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, unknown>) => RouteDefinition<TParams, TQuery, TBody, TResponses, unknown>;
+    put: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>> = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, unknown>) => RouteDefinition<TParams, TQuery, TBody, TResponses, unknown>;
+    patch: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TBody extends SchemaLike | undefined = undefined, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>> = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, TBody, TResponses, unknown>) => RouteDefinition<TParams, TQuery, TBody, TResponses, unknown>;
+    delete: <TParams extends SchemaLike | undefined = undefined, TQuery extends SchemaLike | undefined = undefined, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>> = Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: RouteOptions<TParams, TQuery, undefined, TResponses, unknown>) => RouteDefinition<TParams, TQuery, undefined, TResponses, unknown>;
+    postJson: <TBody extends SchemaLike, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, unknown>) => RouteDefinition<undefined, undefined, TBody, TResponses, unknown>;
+    putJson: <TBody extends SchemaLike, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, unknown>) => RouteDefinition<undefined, undefined, TBody, TResponses, unknown>;
+    patchJson: <TBody extends SchemaLike, TResponses extends Partial<Record<HttpStatus, SchemaLike<unknown>>>>(path: string, operationId: string, options: JsonRouteOptions<TBody, TResponses, unknown>) => RouteDefinition<undefined, undefined, TBody, TResponses, unknown>;
+};
+export declare function json(body: unknown, init?: number | ResponseInit): Response;
+export declare function jsonError(status: ErrorHttpStatus, message: string, details?: unknown, init?: Omit<ResponseInit, "status">): Response;
+export declare function empty(status?: HttpStatus, init?: Omit<ResponseInit, "status">): Response;
+export declare function text(body: string, init?: number | ResponseInit): Response;
+export declare function created(body: unknown, init?: Omit<ResponseInit, "status">): Response;
+export declare function accepted(body: unknown, init?: Omit<ResponseInit, "status">): Response;
+export declare function noContent(init?: Omit<ResponseInit, "status">): Response;
+export declare function badRequest(message?: string, details?: unknown): Response;
+export declare function unauthorized(message?: string, details?: unknown): Response;
+export declare function forbidden(message?: string, details?: unknown): Response;
+export declare function notFound(message?: string, details?: unknown): Response;
+export declare function methodNotAllowed(allowedMethods: readonly string[], message?: string): Response;
+export declare function conflict(message?: string, details?: unknown): Response;
+export declare function gone(message?: string, details?: unknown): Response;
+export declare function payloadTooLarge(message?: string, details?: unknown): Response;
+export declare function unsupportedMediaType(message?: string, details?: unknown): Response;
+export declare function unprocessableContent(message?: string, details?: unknown): Response;
+export declare function tooManyRequests(input?: {
+    message?: string;
+    retryAfterSeconds?: number;
+}): Response;
+export declare function internalServerError(message?: string, details?: unknown): Response;
+export declare function badGateway(message?: string, details?: unknown): Response;
+export declare function serviceUnavailable(message?: string, details?: unknown): Response;
+export declare function gatewayTimeout(message?: string, details?: unknown): Response;
+export interface ServeConfig<TContext = unknown> {
+    name: string;
+    require: unknown;
+    timeoutMs?: number;
+    routes: RouteDefinition<SchemaLike | undefined, SchemaLike | undefined, SchemaLike | undefined, RouteResponses, TContext>[];
+    /**
+     * Public prefix in front of the function name. Supabase-compatible hosts use
+     * `/functions/v1`; ASP.NET Core or other reverse proxies may expose a
+     * different prefix while keeping the same function modules.
+     */
+    pathPrefix?: string;
+}
+export interface MatchedRoute {
+    route: RouteDefinition<SchemaLike | undefined, SchemaLike | undefined, SchemaLike | undefined, RouteResponses, any>;
+    params: Record<string, string>;
+}
+export interface RouteDispatcherContext<TContext> {
+    req: Request;
+    ctx: TContext;
+    matched: MatchedRoute;
+    getCorsHeaders?: (req: Request) => HeadersInit;
+}
+export type RouteDispatcher<TContext> = (input: RouteDispatcherContext<TContext>) => Promise<Response>;
+export interface FetchHandlerOptions<TContext> {
+    getContext(req: Request): TContext | Response | Promise<TContext | Response>;
+    getCorsHeaders?: (req: Request) => HeadersInit;
+    onError?: (error: unknown, req: Request) => Response | Promise<Response>;
+    afterResponse?: (response: Response, req: Request) => Response | Promise<Response>;
+}
+export interface StandaloneServe {
+    (handler: (req: Request) => Response | Promise<Response>): void;
+}
+export declare function getStandaloneServe(): StandaloneServe | null;
+export declare function normalizeRoutePath(path: string): string;
+export declare function splitPath(path: string): string[];
+export declare function getRelativePath(req: Request, functionName: string): string;
+export declare function getRelativePathFromParts(pathnameParts: string[], functionName: string, pathPrefix?: string): string;
+export declare function matchRoutePath(routePath: string, requestPath: string): Record<string, string> | null;
+export declare function findRoute<TContext>(config: ServeConfig<TContext>, req: Request): MatchedRoute | Response;
+export declare function queryObject(req: Request): Record<string, string>;
+export declare function parseJsonBody(req: Request): Promise<unknown>;
+export declare function flattenSchemaError(error: unknown): unknown;
+export declare function validateSchema<TSchema extends SchemaLike | undefined>(schema: TSchema, value: unknown, label: "params" | "query" | "body"): SchemaOutput<TSchema> | Response;
+export declare function withCors(req: Request, response: Response, getCorsHeaders?: (req: Request) => HeadersInit): Response;
+export declare function dispatchRoute<TContext>(input: RouteDispatcherContext<TContext>): Promise<Response>;
+export declare function createFetchHandler<TContext>(config: ServeConfig<TContext>, options: FetchHandlerOptions<TContext>): (req: Request) => Promise<Response>;
+export interface OpenApiDocumentOptions {
+    title: string;
+    version: string;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    schemaAdapter?: JsonSchemaAdapter;
+}
+export declare function createOpenApiDocument(config: ServeConfig<any>, options: OpenApiDocumentOptions): Record<string, unknown>;
+export {};