1tube 0.1.44 → 0.1.46

package/dist/edge.d.ts

@@ -117,6 +117,52 @@ export declare function internalServerError(message?: string, details?: unknown)
 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;
+/**
+ * How the rate limiter buckets requests for a function:
+ *   - "identity" (default): one bucket per authenticated user, falling back to
+ *     the client IP for unauthenticated/public functions.
+ *   - "ip": always bucket by client IP, even when a user is authenticated.
+ *   - "global": a single shared bucket for the whole function.
+ *
+ * Defined here (the self-contained `edge` surface) rather than in `manifest.ts`
+ * so the published `dist/edge.d.ts` has no dangling cross-module reference;
+ * `manifest.ts` re-exports it for the gateway side.
+ */
+export type RateLimitBy = "identity" | "ip" | "global";
+/** Full-control form of `serve({ rateLimit })`. */
+export interface RateLimitConfig {
+    /**
+     * Requests per minute. `0` = unlimited (the function is exempt). Omit to use
+     * the gateway default / any `1tube.json` value.
+     */
+    rpm?: number;
+    /**
+     * Bucket key strategy. Defaults to "identity" (per authenticated user,
+     * falling back to client IP). See {@link RateLimitBy}.
+     */
+    by?: RateLimitBy;
+}
+/**
+ * Per-function rate-limit declaration for `serve({ rateLimit })`:
+ *   - `false`  → exempt from rate limiting entirely (signed webhooks, trusted
+ *     server-to-server callers).
+ *   - `true`   → gateway default limit, keyed by identity (the implicit default
+ *     when `rateLimit` is omitted).
+ *   - `number` → requests-per-minute, keyed by identity.
+ *   - object   → full control over rpm + key strategy.
+ */
+export type RateLimitOption = boolean | number | RateLimitConfig;
+/** Normalized shape consumed by the registry / Worker `register()` contract. */
+export interface NormalizedRateLimit {
+    rpm?: number;
+    rateLimitBy?: RateLimitBy;
+}
+/**
+ * Collapse the friendly {@link RateLimitOption} into `{ rpm?, rateLimitBy? }`.
+ * `undefined`/`true` leave both unset (gateway default); `false` maps to the
+ * `rpm: 0` "unlimited" sentinel the gateway limiter understands.
+ */
+export declare function normalizeRateLimit(rl: RateLimitOption | undefined): NormalizedRateLimit;
 export interface ServeConfig<TContext = unknown> {
     name: string;
     require: unknown;
@@ -128,6 +174,13 @@ export interface ServeConfig<TContext = unknown> {
      * different prefix while keeping the same function modules.
      */
     pathPrefix?: string;
+    /**
+     * Per-function rate-limit declaration. Overrides any `1tube.json` `rpm`.
+     * Use `false` to exempt the function from rate limiting (e.g. a signed
+     * server-to-server webhook). Honoured by the 1tube gateway; standalone
+     * runtimes that front their own limiter ignore it.
+     */
+    rateLimit?: RateLimitOption;
 }
 export interface MatchedRoute {
     route: RouteDefinition<SchemaLike | undefined, SchemaLike | undefined, SchemaLike | undefined, RouteResponses, any>;

package/dist/edge.js

@@ -135,6 +135,20 @@ export function serviceUnavailable(message = "Service unavailable", details) {
 export function gatewayTimeout(message = "Gateway timeout", details) {
     return jsonError(HttpStatus.GATEWAY_TIMEOUT, message, details);
 }
+/**
+ * Collapse the friendly {@link RateLimitOption} into `{ rpm?, rateLimitBy? }`.
+ * `undefined`/`true` leave both unset (gateway default); `false` maps to the
+ * `rpm: 0` "unlimited" sentinel the gateway limiter understands.
+ */
+export function normalizeRateLimit(rl) {
+    if (rl === undefined || rl === true)
+        return {};
+    if (rl === false)
+        return { rpm: 0 };
+    if (typeof rl === "number")
+        return { rpm: rl };
+    return { rpm: rl.rpm, rateLimitBy: rl.by };
+}
 export function getStandaloneServe() {
     const runtime = globalThis;
     const standaloneServe = runtime.Deno?.serve;

package/package.json

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

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

@@ -95,7 +95,10 @@ export interface DenoReloadDebouncerOptions {
    * `debounceMs`. Unset = classic trailing-only behavior.
    */
   leadingMs?: number;
-  flushFn: (paths: readonly string[]) => Promise<void>;
+  // Awaited at the call site, so a synchronous callback is fine too (a test
+  // that just records the paths needn't be `async`, which would trip
+  // require-await). The real reloader flush is async.
+  flushFn: (paths: readonly string[]) => void | Promise<void>;
   setTimer?: (cb: () => void, ms: number) => number;
   clearTimer?: (id: number) => void;
 }

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

@@ -5,18 +5,18 @@
  * bootstrap hosts EVERY function in a single isolate. The point is
  * dependency sharing: a 100-function project where most functions import
  * the same heavy npm graph (`ai`, `@supabase/supabase-js`, `@google/genai`,
- * `zod`, �) pays to compile + evaluate that graph exactly once here,
+ * `zod`, ?) pays to compile + evaluate that graph exactly once here,
  * instead of once per function across 100 isolates. On a real project that
  * collapses warm-boot from ~per-function-sum/cores down to roughly the
  * one-time cost of the union graph (measured ~6s vs ~18s).
  *
  * Trade-off: functions share globals and a crash takes the whole isolate
- * down. That's why this mode is dev-only � production keeps isolate-per-
+ * down. That's why this mode is dev-only ? production keeps isolate-per-
  * function (or workerd) for real isolation.
  *
  * Lifecycle:
  *
- *   host ? init      : { functions: [{name, entryUrl, manifest}], � }
+ *   host ? init      : { functions: [{name, entryUrl, manifest}], ? }
  *                      Imported SERIALLY so each function's top-level
  *                      `serve()` registration can be attributed to the
  *                      right name (parallel imports would interleave the
@@ -26,7 +26,7 @@
  *                      Streams `fn_ready` / `fn_error` per function, then
  *                      `all_done`.
  *
- *   host ? dispatch  : { id, name, � } ? look up the captured handler by
+ *   host ? dispatch  : { id, name, ? } ? look up the captured handler by
  *                      name and run it (per-request AsyncLocalStorage so
  *                      concurrent invocations attribute console output).
  *
@@ -42,7 +42,11 @@
 /// <reference lib="deno.worker" />
 
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { FunctionManifest } from "../../manifest.ts";
+import {
+  type FunctionManifest,
+  mergeServeRateLimit,
+  type RateLimitBy,
+} from "../../manifest.ts";
 import type { AuthContext } from "../../registry.ts";
 
 interface FnSpec {
@@ -96,7 +100,12 @@ type Handler = (
 interface RegistryStub {
   register(
     handler: Handler,
-    opts: { public: boolean; timeoutMs?: number },
+    opts: {
+      public: boolean;
+      timeoutMs?: number;
+      rpm?: number;
+      rateLimitBy?: RateLimitBy;
+    },
   ): void;
 }
 
@@ -104,6 +113,8 @@ interface CapturedHandler {
   handler: Handler;
   isPublic: boolean;
   timeoutMs?: number;
+  rpm?: number;
+  rateLimitBy?: RateLimitBy;
   manifest: FunctionManifest;
 }
 
@@ -159,7 +170,7 @@ function installConsoleCapture(): void {
       try {
         let message = args.map(formatConsoleArg).join(" ");
         if (message.length > MAX_CONSOLE_MESSAGE) {
-          message = message.slice(0, MAX_CONSOLE_MESSAGE) + "�";
+          message = message.slice(0, MAX_CONSOLE_MESSAGE) + "?";
         }
         postMessage({
           type: "console",
@@ -184,7 +195,7 @@ function installConsoleCapture(): void {
 
 const stub: RegistryStub = {
   register(handler, opts) {
-    if (!importing) return; // serve() called outside an import window � ignore
+    if (!importing) return; // serve() called outside an import window ? ignore
     if (importing.captured) {
       console.warn(
         `[1tube] "${importing.name}" called serve() twice; using the last handler`,
@@ -194,6 +205,8 @@ const stub: RegistryStub = {
       handler,
       isPublic: opts.public,
       timeoutMs: opts.timeoutMs,
+      rpm: opts.rpm,
+      rateLimitBy: opts.rateLimitBy,
       manifest: { runtime: "deno" } as unknown as FunctionManifest,
     };
   },
@@ -282,7 +295,14 @@ async function loadFunction(
     });
     return;
   }
-  captured.manifest = fn.manifest;
+  // Fold any `serve({ rateLimit })` override into the manifest reported to the
+  // gateway so its rate-limiter (which reads `manifestFor()`) honours
+  // code-declared limits ? this isolate, not the gateway, ran the module.
+  const reportedManifest = mergeServeRateLimit(fn.manifest, {
+    rpm: captured.rpm,
+    rateLimitBy: captured.rateLimitBy,
+  });
+  captured.manifest = reportedManifest;
   handlers.set(fn.name, captured);
   postMessage({
     type: "fn_ready",
@@ -290,7 +310,7 @@ async function loadFunction(
     ms: performance.now() - t0,
     isPublic: captured.isPublic,
     timeoutMs: captured.timeoutMs,
-    manifest: fn.manifest,
+    manifest: reportedManifest,
   });
 }
 

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

@@ -27,7 +27,11 @@
 /// <reference lib="deno.worker" />
 
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { FunctionManifest } from "../../manifest.ts";
+import {
+  type FunctionManifest,
+  mergeServeRateLimit,
+  type RateLimitBy,
+} from "../../manifest.ts";
 import type { AuthContext } from "../../registry.ts";
 
 interface InitMessage {
@@ -70,7 +74,12 @@ type Handler = (
 interface RegistryStub {
   register(
     handler: Handler,
-    opts: { public: boolean; timeoutMs?: number },
+    opts: {
+      public: boolean;
+      timeoutMs?: number;
+      rpm?: number;
+      rateLimitBy?: RateLimitBy;
+    },
   ): void;
 }
 
@@ -78,6 +87,8 @@ interface CapturedHandler {
   handler: Handler;
   isPublic: boolean;
   timeoutMs?: number;
+  rpm?: number;
+  rateLimitBy?: RateLimitBy;
 }
 
 let captured: CapturedHandler | null = null;
@@ -202,6 +213,8 @@ const stub: RegistryStub = {
       handler,
       isPublic: opts.public,
       timeoutMs: opts.timeoutMs,
+      rpm: opts.rpm,
+      rateLimitBy: opts.rateLimitBy,
     };
   },
 };
@@ -322,12 +335,22 @@ self.onmessage = (ev: MessageEvent<HostMessage>) => {
         });
         return;
       }
+      // Fold any `serve({ rateLimit })` override into the manifest we report
+      // so the gateway's rate-limiter (which reads `manifestFor()`) honours
+      // code-declared limits — the function module runs in this Worker, not in
+      // the gateway process, so this `ready` handshake is the only channel.
+      const reportedManifest = manifest
+        ? mergeServeRateLimit(manifest, {
+          rpm: captured.rpm,
+          rateLimitBy: captured.rateLimitBy,
+        })
+        : manifest;
       postMessage({
         type: "ready",
         name: functionName,
         isPublic: captured.isPublic,
         timeoutMs: captured.timeoutMs,
-        manifest,
+        manifest: reportedManifest,
       });
     })();
     return;

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

@@ -1188,6 +1188,13 @@ export function createDenoWorkerHost(
    */
   let coloReloadChain: Promise<unknown> = Promise.resolve();
 
+  // In-flight worker-retirement drains. A retiring worker leaves `coloWorkers`
+  // immediately but lingers (its `kill` armed on a timer) so in-flight
+  // requests can finish. Tracked so `stop()` can both cancel the timer AND
+  // run the kill now — otherwise the timer (and the Worker) outlive the host
+  // and leak, which Deno's test sanitizer flags.
+  const coloDrains = new Set<{ timer: number; kill: () => void }>();
+
   interface ColoFnResult {
     name: string;
     ok: boolean;
@@ -1379,7 +1386,12 @@ export function createDenoWorkerHost(
    */
   function terminateColoWorker(w: Worker, drainMs: number): void {
     coloWorkers.delete(w);
+    let entry: { timer: number; kill: () => void } | null = null;
     const kill = () => {
+      if (entry) {
+        clearTimeout(entry.timer);
+        coloDrains.delete(entry);
+      }
       try {
         w.terminate();
       } catch { /* already gone */ }
@@ -1390,8 +1402,13 @@ export function createDenoWorkerHost(
         }
       }
     };
-    if (drainMs > 0) setTimeout(kill, drainMs);
-    else kill();
+    if (drainMs > 0) {
+      const timer = setTimeout(kill, drainMs) as unknown as number;
+      entry = { timer, kill };
+      coloDrains.add(entry);
+    } else {
+      kill();
+    }
   }
 
   /**
@@ -1768,6 +1785,11 @@ export function createDenoWorkerHost(
   }
 
   function stopColocated(): void {
+    // Cancel + finish any in-flight retirement drains first: this clears their
+    // timers and terminates the lingering workers (which already left
+    // `coloWorkers`), so nothing outlives the host.
+    for (const d of [...coloDrains]) d.kill();
+    coloDrains.clear();
     for (const p of coloPending.values()) {
       p.reject(new Error("gateway shutting down"));
     }

package/src/edge.ts

@@ -446,6 +446,64 @@ export function gatewayTimeout(
   return jsonError(HttpStatus.GATEWAY_TIMEOUT, message, details);
 }
 
+/**
+ * How the rate limiter buckets requests for a function:
+ *   - "identity" (default): one bucket per authenticated user, falling back to
+ *     the client IP for unauthenticated/public functions.
+ *   - "ip": always bucket by client IP, even when a user is authenticated.
+ *   - "global": a single shared bucket for the whole function.
+ *
+ * Defined here (the self-contained `edge` surface) rather than in `manifest.ts`
+ * so the published `dist/edge.d.ts` has no dangling cross-module reference;
+ * `manifest.ts` re-exports it for the gateway side.
+ */
+export type RateLimitBy = "identity" | "ip" | "global";
+
+/** Full-control form of `serve({ rateLimit })`. */
+export interface RateLimitConfig {
+  /**
+   * Requests per minute. `0` = unlimited (the function is exempt). Omit to use
+   * the gateway default / any `1tube.json` value.
+   */
+  rpm?: number;
+  /**
+   * Bucket key strategy. Defaults to "identity" (per authenticated user,
+   * falling back to client IP). See {@link RateLimitBy}.
+   */
+  by?: RateLimitBy;
+}
+
+/**
+ * Per-function rate-limit declaration for `serve({ rateLimit })`:
+ *   - `false`  → exempt from rate limiting entirely (signed webhooks, trusted
+ *     server-to-server callers).
+ *   - `true`   → gateway default limit, keyed by identity (the implicit default
+ *     when `rateLimit` is omitted).
+ *   - `number` → requests-per-minute, keyed by identity.
+ *   - object   → full control over rpm + key strategy.
+ */
+export type RateLimitOption = boolean | number | RateLimitConfig;
+
+/** Normalized shape consumed by the registry / Worker `register()` contract. */
+export interface NormalizedRateLimit {
+  rpm?: number;
+  rateLimitBy?: RateLimitBy;
+}
+
+/**
+ * Collapse the friendly {@link RateLimitOption} into `{ rpm?, rateLimitBy? }`.
+ * `undefined`/`true` leave both unset (gateway default); `false` maps to the
+ * `rpm: 0` "unlimited" sentinel the gateway limiter understands.
+ */
+export function normalizeRateLimit(
+  rl: RateLimitOption | undefined,
+): NormalizedRateLimit {
+  if (rl === undefined || rl === true) return {};
+  if (rl === false) return { rpm: 0 };
+  if (typeof rl === "number") return { rpm: rl };
+  return { rpm: rl.rpm, rateLimitBy: rl.by };
+}
+
 export interface ServeConfig<TContext = unknown> {
   name: string;
   require: unknown;
@@ -463,6 +521,13 @@ export interface ServeConfig<TContext = unknown> {
    * different prefix while keeping the same function modules.
    */
   pathPrefix?: string;
+  /**
+   * Per-function rate-limit declaration. Overrides any `1tube.json` `rpm`.
+   * Use `false` to exempt the function from rate limiting (e.g. a signed
+   * server-to-server webhook). Honoured by the 1tube gateway; standalone
+   * runtimes that front their own limiter ignore it.
+   */
+  rateLimit?: RateLimitOption;
 }
 
 export interface MatchedRoute {

package/src/gateway/rate-limit.ts

@@ -1,6 +1,13 @@
 /**
  * In-memory token bucket rate limiter.
- * Keyed by user ID (set by the auth middleware) or remote IP.
+ *
+ * Buckets are keyed by the per-function `rateLimitBy` strategy (manifest /
+ * `serve({ rateLimit })`), defaulting to "identity": user ID when the auth
+ * middleware set one, otherwise remote IP. `"ip"` forces IP keying even for
+ * authenticated callers; `"global"` shares one bucket across all callers.
+ *
+ * A resolved rpm of `0` (or less) exempts the function entirely — used for
+ * trusted, already-authenticated traffic like signed server-to-server webhooks.
  *
  * X-Forwarded-For is only honored when the immediate connection comes from a
  * trusted proxy (env `1TUBE_TRUSTED_PROXIES`, comma-separated CIDRs/IPs).
@@ -11,6 +18,7 @@
 import type { Context, Next } from "npm:hono@4";
 import { getConnInfo } from "npm:hono@4/deno";
 import type { FunctionRegistry } from "../registry.ts";
+import type { RateLimitBy } from "../manifest.ts";
 import { routeRemainder } from "./route-prefix.ts";
 
 interface Bucket {
@@ -81,9 +89,19 @@ function getOrCreateBucket(key: string, rpm: number): Bucket {
   return bucket;
 }
 
-function resolveKey(c: Context): string {
-  const userId = c.get("userId") as string | undefined;
-  if (userId) return `user:${userId}`;
+function resolveKey(c: Context, by: RateLimitBy): string {
+  // A single shared bucket for the whole function — every caller draws from
+  // the same tokens regardless of identity or IP.
+  if (by === "global") return "global";
+
+  // Identity-first (the default): one bucket per authenticated user so a
+  // noisy IP can't starve everyone behind a shared NAT, and a single user
+  // can't mint fresh buckets by hopping IPs. `by: "ip"` opts out and always
+  // keys by IP even for authenticated callers.
+  if (by !== "ip") {
+    const userId = c.get("userId") as string | undefined;
+    if (userId) return `user:${userId}`;
+  }
 
   const trusted = loadTrustedProxies();
   let socketAddr = "unknown";
@@ -138,12 +156,21 @@ export function createRateLimiter(config: Partial<RateLimitConfig> = {}) {
     // (configurable) prefix, before any nested route.
     const fnName = routeRemainder(c.req.path).split("/", 1)[0] || "";
 
-    const manifestRpm = fnName
-      ? cfg.registry?.manifestFor(fnName)?.rpm
-      : undefined;
-    const rpm = manifestRpm ??
+    const manifest = fnName ? cfg.registry?.manifestFor(fnName) : undefined;
+    // `??` (not `||`) so a manifest `rpm: 0` survives — it's the "unlimited"
+    // sentinel, distinct from "unset" (undefined → fall back to overrides).
+    const rpm = manifest?.rpm ??
       ((fnName && cfg.overrides[fnName]) || cfg.defaultRpm);
-    const key = `${resolveKey(c)}:${fnName || "global"}`;
+
+    // rpm <= 0 means the function is explicitly exempt (e.g. a signed
+    // server-to-server webhook). Skip the bucket entirely.
+    if (rpm <= 0) {
+      await next();
+      return;
+    }
+
+    const by: RateLimitBy = manifest?.rateLimitBy ?? "identity";
+    const key = `${resolveKey(c, by)}:${fnName || "global"}`;
     const bucket = getOrCreateBucket(key, rpm);
 
     if (bucket.tokens <= 0) {

package/src/manifest.ts

@@ -8,7 +8,8 @@
  *     metadata — the in-process TS gateway has no way to enforce them inside
  *     a single V8 isolate; treat them as documentation for now.
  *   - `timeoutMs` — wall-clock dispatch timeout (real today).
- *   - `rpm` — per-function rate-limit override (real today).
+ *   - `rpm` — per-function rate-limit override (real today). `0` = unlimited.
+ *   - `rateLimitBy` — rate-limit bucket key strategy (identity/ip/global).
  *   - `memoryMB` — recorded only; cannot be enforced from inside V8. Use the
  *     host process's cgroup / job-object cap instead (visible on /health as
  *     `memory.limit_mb`).
@@ -26,6 +27,13 @@
 // without depending on a shared import-map entry.
 import { join } from "node:path";
 
+// `RateLimitBy` is defined on the self-contained `edge` surface so the
+// published `dist/edge.d.ts` stays free of cross-module references. The gateway
+// side imports it from here; this re-export is type-only and erased at runtime,
+// so manifest.ts gains no runtime dependency on edge.ts.
+import type { RateLimitBy } from "./edge.ts";
+export type { RateLimitBy };
+
 export interface ManifestPermissions {
   /** Hostnames the function may reach (e.g. "api.example.com"). [] = none. */
   net: string[];
@@ -52,8 +60,17 @@ export interface FunctionManifest {
   permissions: ManifestPermissions;
   /** Per-function timeout in ms. Undefined = use gateway default. */
   timeoutMs?: number;
-  /** Per-function rate limit (requests per minute). Undefined = use gateway default. */
+  /**
+   * Per-function rate limit (requests per minute). Undefined = use gateway
+   * default. `0` = unlimited — the function is exempt from rate limiting (use
+   * for signed server-to-server webhooks and other trusted callers).
+   */
   rpm?: number;
+  /**
+   * Bucket key strategy for this function's rate limit. Undefined = "identity".
+   * See {@link RateLimitBy}.
+   */
+  rateLimitBy?: RateLimitBy;
   /** Memory cap (MB). Recorded only; not enforced by the TS runtime. */
   memoryMB?: number;
   /** Eagerly load + keep alive. Recorded only by the TS runtime. */
@@ -97,6 +114,21 @@ function asPositiveInt(v: unknown): number | undefined {
   return n > 0 ? n : undefined;
 }
 
+/**
+ * Like {@link asPositiveInt} but preserves `0`. Used for `rpm`, where `0` is a
+ * meaningful value ("unlimited") distinct from "unset". Negatives/NaN drop to
+ * undefined so a typo can't accidentally exempt a function.
+ */
+function asNonNegativeInt(v: unknown): number | undefined {
+  if (typeof v !== "number" || !Number.isFinite(v)) return undefined;
+  const n = Math.floor(v);
+  return n >= 0 ? n : undefined;
+}
+
+function asRateLimitBy(v: unknown): RateLimitBy | undefined {
+  return v === "identity" || v === "ip" || v === "global" ? v : undefined;
+}
+
 function asRatio(v: unknown, fallback: number): number {
   if (typeof v !== "number" || !Number.isFinite(v)) return fallback;
   if (v < 0) return 0;
@@ -123,7 +155,8 @@ export function parseManifest(raw: unknown, fromFile = true): FunctionManifest {
   };
 
   base.timeoutMs = asPositiveInt(obj.timeoutMs);
-  base.rpm = asPositiveInt(obj.rpm);
+  base.rpm = asNonNegativeInt(obj.rpm);
+  base.rateLimitBy = asRateLimitBy(obj.rateLimitBy);
   base.memoryMB = asPositiveInt(obj.memoryMB);
 
   if (typeof obj.warm === "boolean") base.warm = obj.warm;
@@ -142,6 +175,29 @@ export function parseManifest(raw: unknown, fromFile = true): FunctionManifest {
   return base;
 }
 
+/**
+ * Fold a code-declared `serve({ rateLimit })` override (already normalized to
+ * `{ rpm?, rateLimitBy? }`) into a manifest. Used by the in-process registry
+ * and the Worker entries so the gateway's rate-limiter — which only ever reads
+ * the manifest via `manifestFor()` — picks up values declared in the function
+ * module. Serve-config values win over `1tube.json`; absent ones are left as-is.
+ * Returns the original manifest unchanged when there is nothing to apply, so
+ * callers can keep object identity in the common case.
+ */
+export function mergeServeRateLimit(
+  manifest: FunctionManifest,
+  override: { rpm?: number; rateLimitBy?: RateLimitBy },
+): FunctionManifest {
+  if (override.rpm === undefined && override.rateLimitBy === undefined) {
+    return manifest;
+  }
+  return {
+    ...manifest,
+    rpm: override.rpm ?? manifest.rpm,
+    rateLimitBy: override.rateLimitBy ?? manifest.rateLimitBy,
+  };
+}
+
 /**
  * Read and parse `<functionsDir>/<name>/1tube.json`. Missing file =
  * defaultManifest(). Malformed JSON = defaultManifest() with a stderr warning.

package/src/registry.ts

@@ -7,7 +7,12 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
-import { defaultManifest, type FunctionManifest } from "./manifest.ts";
+import {
+  defaultManifest,
+  type FunctionManifest,
+  mergeServeRateLimit,
+  type RateLimitBy,
+} from "./manifest.ts";
 
 export interface AuthContext {
   userId: string;
@@ -169,7 +174,14 @@ export class FunctionRegistry {
    */
   register(
     handler: AuthenticatedHandler | PublicHandler,
-    opts: { public: boolean; timeoutMs?: number },
+    opts: {
+      public: boolean;
+      timeoutMs?: number;
+      /** `serve({ rateLimit })` override. `0` = unlimited. Wins over `1tube.json`. */
+      rpm?: number;
+      /** `serve({ rateLimit })` bucket key strategy. Wins over `1tube.json`. */
+      rateLimitBy?: RateLimitBy;
+    },
   ): void {
     const name = currentNameStorage.getStore();
     if (!name) {
@@ -178,7 +190,11 @@ export class FunctionRegistry {
           "This is a bug in the function loader — must be wrapped in runWithCurrentFunction().",
       );
     }
-    const manifest = this.pendingManifests.get(name) ?? defaultManifest();
+    const base = this.pendingManifests.get(name) ?? defaultManifest();
+    // Fold any `serve({ rateLimit })` override into the manifest so the
+    // gateway's rate-limiter (which only ever reads `manifestFor()`) sees the
+    // code-declared value without a separate lookup path.
+    const manifest = mergeServeRateLimit(base, opts);
     this.handlers.set(name, {
       handler,
       isPublic: opts.public,