@run402/functions 1.60.3 → 1.62.0

package/README.md

@@ -145,6 +145,75 @@ const items = await adminDb().from("items").select("title, slug").order("created
 
 Use `adminDb()` (not `db(req)`) here — there's no incoming request to forward.
 
+## Routed HTTP functions
+
+Deploy-v2 web routes can map public same-origin browser paths to functions, for example `routes: { "replace": [{ "pattern": "/api/*", "target": { "type": "function", "name": "api" } }] }`. A browser request to a routed path does **not** need a Run402 API key at the public edge. Direct `/functions/v1/:name` invocation is unchanged: it remains API-key protected and API-shaped.
+
+Routed browser traffic invokes your function with the `run402.routed_http.v1` envelope. The gateway preserves the public URL, path, raw query, duplicate-safe lower-case headers, raw cookie header, optional base64 body, and route context. The matched prefix is not stripped from `path`.
+
+Request fields:
+- `version`, `method`, `url`, `path`, `rawPath`, `rawQuery`
+- `headers: Array<[string, string]>`
+- `cookies.raw`
+- `body: null | { encoding: "base64"; data; size }`
+- `context.source`, `projectId`, `releaseId`, `deploymentId`, `host`, `proto`, `routePattern`, `routeKind`, `routeTarget`, `requestId`, plus optional `clientIp` and `userAgent`
+
+Response fields:
+- `status` from 200 through 599
+- optional duplicate-safe `headers`
+- optional `cookies: string[]`, preserved as separate `Set-Cookie` headers
+- optional base64 `body`
+
+Helpers:
+
+```ts
+import {
+  routedHttp,
+  type RoutedHttpRequestV1,
+  type RoutedHttpResponseV1,
+} from "@run402/functions";
+
+export default async function handler(
+  event: RoutedHttpRequestV1,
+): Promise<RoutedHttpResponseV1> {
+  if (!routedHttp.isRequest(event)) {
+    return routedHttp.json({ error: "unsupported_event" }, { status: 400 });
+  }
+
+  if (event.method === "OPTIONS") {
+    return routedHttp.text("", {
+      status: 204,
+      headers: [
+        ["access-control-allow-origin", "https://app.example.com"],
+        ["access-control-allow-methods", "GET, POST, OPTIONS"],
+        ["access-control-allow-headers", "content-type, authorization"],
+      ],
+    });
+  }
+
+  if (event.method === "POST" && !event.headers.some(([k]) => k === "x-csrf-token")) {
+    return routedHttp.json({ error: "csrf_required" }, { status: 403 });
+  }
+
+  return routedHttp.json(
+    { ok: true, path: event.path, query: event.rawQuery },
+    {
+      headers: [["cache-control", "private, no-store"]],
+      cookies: [
+        "sid=abc; HttpOnly; Secure; SameSite=Lax; Path=/",
+        "theme=dark; Secure; SameSite=Lax; Path=/",
+      ],
+    },
+  );
+}
+```
+
+`routedHttp.text`, `routedHttp.json`, and `routedHttp.bytes` return `RoutedHttpResponseV1`. Named `text`, `json`, `bytes`, and `isRequest` exports are also available. Redirects are ordinary 3xx responses with a `Location` header. `HEAD` responses send headers without body bytes. WebSockets, `101 Switching Protocols`, streaming, and SSE are not supported in Phase 1.
+
+Limits and defaults: request and response bodies are capped at 6 MiB. Run402 does not add wildcard CORS. Run402 does not store routed dynamic responses in a shared cache; if your function sets no `Cache-Control`, the gateway adds `Cache-Control: private, no-store` and `x-run402-cache: dynamic-bypass`.
+
+Security notes: application auth, authorization, sessions, OAuth callbacks, CORS, and CSRF belong in your function code. For cookie-authenticated `POST`, `PUT`, `PATCH`, or `DELETE`, validate a CSRF token or an equivalent same-site defense. Do not trust spoofable forwarding headers for authorization; prefer the typed `event.context` metadata when it is present.
+
 ## Imports auto-resolved
 
 Inside a deployed function you can `import { ... } from "@run402/functions"` directly — the gateway bundles this library plus any `--deps` you declared at deploy time. **Do not list `@run402/functions` in your `--deps`** — it's rejected. Native binary modules (`sharp`, `canvas`, native `bcrypt`, etc.) are also rejected.

package/dist/index.d.ts

@@ -5,4 +5,6 @@ export { email } from "./email.js";
 export type { EmailSendOptions, EmailRawOptions, EmailTemplateOptions, EmailSendResult } from "./email.js";
 export { ai } from "./ai.js";
 export type { TranslateOptions, TranslateResult, ModerateResult } from "./ai.js";
+export { bytes, isRequest, json, routedHttp, text } from "./routed-http.js";
+export type { RoutedHttpHeaderList, RoutedHttpRequestV1, RoutedHttpResponseInit, RoutedHttpResponseV1, } from "./routed-http.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export { db, adminDb, QueryBuilder } from "./db.js";
 export { getUser } from "./auth.js";
 export { email } from "./email.js";
 export { ai } from "./ai.js";
+export { bytes, isRequest, json, routedHttp, text } from "./routed-http.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/routed-http.d.ts

@@ -0,0 +1,61 @@
+export type RoutedHttpHeaderList = Array<[string, string]>;
+export interface RoutedHttpRequestV1 {
+    version: "run402.routed_http.v1";
+    method: string;
+    url: string;
+    path: string;
+    rawPath: string;
+    rawQuery: string;
+    headers: RoutedHttpHeaderList;
+    cookies: {
+        raw: string | null;
+    };
+    body: null | {
+        encoding: "base64";
+        data: string;
+        size: number;
+    };
+    context: {
+        source: "route";
+        projectId: string;
+        releaseId: string | null;
+        deploymentId: string | null;
+        host: string;
+        proto: "https" | "http";
+        routePattern: string;
+        routeKind: "exact" | "prefix";
+        routeTarget: {
+            type: "function";
+            name: string;
+        };
+        requestId: string;
+        clientIp?: string;
+        userAgent?: string;
+    };
+}
+export interface RoutedHttpResponseV1 {
+    status: number;
+    headers?: RoutedHttpHeaderList;
+    cookies?: string[];
+    body?: null | {
+        encoding: "base64";
+        data: string;
+        size: number;
+    };
+}
+export interface RoutedHttpResponseInit {
+    status?: number;
+    headers?: RoutedHttpHeaderList;
+    cookies?: string[];
+}
+export declare function text(body: string, init?: RoutedHttpResponseInit): RoutedHttpResponseV1;
+export declare function json(value: unknown, init?: RoutedHttpResponseInit): RoutedHttpResponseV1;
+export declare function bytes(value: Uint8Array, init?: RoutedHttpResponseInit): RoutedHttpResponseV1;
+export declare function isRequest(event: unknown): event is RoutedHttpRequestV1;
+export declare const routedHttp: {
+    text: typeof text;
+    json: typeof json;
+    bytes: typeof bytes;
+    isRequest: typeof isRequest;
+};
+//# sourceMappingURL=routed-http.d.ts.map

package/dist/routed-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routed-http.d.ts","sourceRoot":"","sources":["../src/routed-http.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAChC,IAAI,EAAE,IAAI,GAAG;QACX,QAAQ,EAAE,QAAQ,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE;QACP,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;QAC9B,WAAW,EAAE;YAAE,IAAI,EAAE,UAAU,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAChD,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,IAAI,GAAG;QACZ,QAAQ,EAAE,QAAQ,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,IAAI,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,sBAA2B,GAChC,oBAAoB,CAMtB;AAED,wBAAgB,IAAI,CAClB,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,sBAA2B,GAChC,oBAAoB,CAMtB;AAED,wBAAgB,KAAK,CACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE,sBAA2B,GAChC,oBAAoB,CAEtB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAEtE;AAED,eAAO,MAAM,UAAU;;;;;CAKtB,CAAC"}

package/dist/routed-http.js

@@ -0,0 +1,54 @@
+import { Buffer } from "node:buffer";
+export function text(body, init = {}) {
+    return withBody(Buffer.from(body, "utf8"), {
+        status: init.status,
+        headers: withDefaultContentType(init.headers, "text/plain; charset=utf-8"),
+        cookies: init.cookies,
+    });
+}
+export function json(value, init = {}) {
+    return withBody(Buffer.from(JSON.stringify(value), "utf8"), {
+        status: init.status,
+        headers: withDefaultContentType(init.headers, "application/json; charset=utf-8"),
+        cookies: init.cookies,
+    });
+}
+export function bytes(value, init = {}) {
+    return withBody(value, init);
+}
+export function isRequest(event) {
+    return isRecord(event) && event.version === "run402.routed_http.v1";
+}
+export const routedHttp = {
+    text,
+    json,
+    bytes,
+    isRequest,
+};
+function withBody(value, init) {
+    const bodyBytes = value instanceof Buffer ? value : Buffer.from(value);
+    const response = {
+        status: init.status ?? 200,
+        body: {
+            encoding: "base64",
+            data: bodyBytes.toString("base64"),
+            size: bodyBytes.byteLength,
+        },
+    };
+    if (init.headers !== undefined)
+        response.headers = init.headers;
+    if (init.cookies !== undefined)
+        response.cookies = init.cookies;
+    return response;
+}
+function withDefaultContentType(headers, contentType) {
+    const out = headers ? [...headers] : [];
+    const hasContentType = out.some(([name]) => name.toLowerCase() === "content-type");
+    if (!hasContentType)
+        out.unshift(["content-type", contentType]);
+    return out;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+//# sourceMappingURL=routed-http.js.map

package/dist/routed-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routed-http.js","sourceRoot":"","sources":["../src/routed-http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAmDrC,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAA+B,EAAE;IAEjC,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;QACzC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC,OAAO,EAAE,2BAA2B,CAAC;QAC1E,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,IAAI,CAClB,KAAc,EACd,OAA+B,EAAE;IAEjC,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,EAAE;QAC1D,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC,OAAO,EAAE,iCAAiC,CAAC;QAChF,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,KAAK,CACnB,KAAiB,EACjB,OAA+B,EAAE;IAEjC,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,uBAAuB,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,SAAS;CACV,CAAC;AAEF,SAAS,QAAQ,CACf,KAAiB,EACjB,IAA4B;IAE5B,MAAM,SAAS,GAAG,KAAK,YAAY,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAyB;QACrC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG;QAC1B,IAAI,EAAE;YACJ,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAClC,IAAI,EAAE,SAAS,CAAC,UAAU;SAC3B;KACF,CAAC;IACF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAChE,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAChE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,sBAAsB,CAC7B,OAAyC,EACzC,WAAmB;IAEnB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,MAAM,cAAc,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,cAAc,CAAC,CAAC;IACnF,IAAI,CAAC,cAAc;QAAE,GAAG,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@run402/functions",
-  "version": "1.60.3",
+  "version": "1.62.0",
   "description": "In-function helper library for Run402 serverless functions — db, adminDb, getUser, email, ai. Auto-bundled into deployed functions; also installable for local TypeScript autocomplete.",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "node --experimental-test-module-mocks --test --import tsx src/db.test.ts src/auth.test.ts"
+    "test": "node --experimental-test-module-mocks --test --import tsx src/db.test.ts src/auth.test.ts src/routed-http.test.ts"
   },
   "engines": {
     "node": ">=18"