@beignet/provider-rate-limit-upstash 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-rate-limit-upstash
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,220 @@
+# @beignet/provider-rate-limit-upstash
+
+Upstash-backed `RateLimitPort` provider for Beignet applications.
+
+The provider installs `ctx.ports.rateLimit` using
+[Upstash Redis](https://upstash.com/) and
+[@upstash/ratelimit](https://github.com/upstash/ratelimit).
+
+## Features
+
+- Implements the standard `RateLimitPort` interface.
+- Uses the Upstash Redis REST API, so it is serverless-friendly.
+- Supports dynamic limits per request with a configurable key prefix.
+- Emits devtools events for allowed, blocked, and failed hits.
+
+## Install
+
+```bash
+bun add @beignet/provider-rate-limit-upstash @upstash/redis @upstash/ratelimit
+```
+
+## Configuration
+
+Set these environment variables:
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `UPSTASH_REDIS_REST_URL` | Yes | Your Upstash Redis REST URL | `https://us1-properly-ancient-12345.upstash.io` |
+| `UPSTASH_REDIS_REST_TOKEN` | Yes | Your Upstash Redis REST token | `AXXXeyJpZCI6IjEy...` |
+| `UPSTASH_PREFIX` | No | Key prefix for rate limit keys (default: `ck:ratelimit`) | `myapp:ratelimit` |
+
+### Getting Upstash credentials
+
+1. Sign up at [Upstash](https://upstash.com/)
+2. Create a new Redis database
+3. Navigate to the database details page
+4. Copy the REST URL and REST token from the "REST API" section
+
+## Setup
+
+```ts
+import { createNextServer } from "@beignet/next";
+import { upstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";
+import { createRateLimitHooks } from "@beignet/core/server";
+import type { AppContext } from "@/app-context";
+import { appPorts } from "@/infra/app-ports";
+import { routes } from "@/server/routes";
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [upstashRateLimitProvider],
+  hooks: [createRateLimitHooks<AppContext>()],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+## Direct use
+
+Once the provider is registered, you can use the rate limit port in hooks,
+policies, or use cases:
+
+```ts
+// Example app-specific policy that rate limits by IP address
+async function checkIpRateLimit(ctx: AppCtx) {
+  const result = await ctx.ports.rateLimit.hit({
+    key: `ip:${ctx.ip}`,
+    limit: 100,
+    windowSec: 60, // 100 requests per 60 seconds
+  });
+
+  if (!result.allowed) {
+    return {
+      status: 429,
+      headers: {
+        "X-RateLimit-Limit": "100",
+        "X-RateLimit-Remaining": String(result.remaining ?? 0),
+        "X-RateLimit-Reset": result.resetAt?.toISOString() ?? "",
+        "Retry-After": String(result.retryAfterSeconds ?? 0),
+      },
+      body: {
+        code: "TOO_MANY_REQUESTS",
+        message: "Rate limit exceeded. Please try again later.",
+      },
+    };
+  }
+
+  // Request is allowed
+  return undefined;
+}
+```
+
+### Different rate limits for different endpoints
+
+You can apply different rate limits for different operations:
+
+```ts
+// Strict rate limit for auth endpoints
+const loginResult = await ctx.ports.rateLimit.hit({
+  key: `login:${ctx.ip}`,
+  limit: 5,
+  windowSec: 300, // 5 attempts per 5 minutes
+});
+
+// More relaxed rate limit for API endpoints
+const apiResult = await ctx.ports.rateLimit.hit({
+  key: `api:user:${userId}`,
+  limit: 1000,
+  windowSec: 3600, // 1000 requests per hour
+});
+```
+
+### Using with contract metadata
+
+You can define rate limit metadata on your contracts:
+
+```ts
+const getTodos = api.get("/todos")
+  .meta({
+    rateLimit: { max: 60, windowSec: 60, scope: "user" },
+  });
+```
+
+The built-in `createRateLimitHooks(...)` helper reads this metadata and applies
+the limit through `ctx.ports.rateLimit`. If your app needs custom behavior, keep
+the same metadata shape and call the port directly:
+
+```ts
+type RateLimitMetadata = {
+  rateLimit?: {
+    max: number;
+    windowSec: number;
+    scope?: "global" | "ip" | "user";
+  };
+};
+
+async function rateLimitFromMeta(ctx: AppCtx, meta?: RateLimitMetadata) {
+  if (!meta?.rateLimit) return;
+
+  const { max, windowSec, scope = "global" } = meta.rateLimit;
+  const actorId =
+    ctx.actor?.type === "user" && ctx.actor.id ? ctx.actor.id : undefined;
+  const result = await ctx.ports.rateLimit.hit({
+    key:
+      scope === "user"
+        ? `user:${actorId ?? "anonymous"}`
+        : `${scope}:${ctx.ip ?? "global"}`,
+    limit: max,
+    windowSec,
+  });
+
+  if (!result.allowed) {
+    return {
+      status: 429,
+      body: {
+        code: "TOO_MANY_REQUESTS",
+        message: "Too many requests",
+      },
+    };
+  }
+}
+```
+
+## Rate limit result
+
+The `hit` method returns a `RateLimitResult` with:
+
+```ts
+interface RateLimitResult {
+  allowed: boolean;                 // true if the hit is within the limit
+  remaining: number | null;         // requests remaining in the window
+  resetAt: Date | null;             // when the window resets
+  retryAfterSeconds: number | null; // retry delay when the hit is rejected
+}
+```
+
+## Implementation details
+
+- **Algorithm**: Uses fixed window rate limiting via `Ratelimit.fixedWindow()`
+- **Backend**: Upstash Redis REST API (serverless-compatible)
+- **Per-request configuration**: Creates a new `Ratelimit` instance for each `hit()` call to support dynamic limits
+- **Key prefix**: Configurable prefix to avoid key collisions
+
+## Devtools
+
+When `@beignet/devtools` is installed before this provider, rate limit
+checks appear under the dashboard's Rate limits watcher.
+
+The provider records `rateLimit.hit` events with the key, limit, window,
+configured prefix, allowed/blocked result, remaining count, reset time,
+retry-after value, and duration. Provider failures are recorded as
+`rateLimit.hit.failed`.
+
+## Advanced usage
+
+### Access the underlying Redis client
+
+The provider extends the standard `RateLimitPort` with access to the underlying Upstash Redis client:
+
+```ts
+import type { UpstashRateLimitPort } from "@beignet/provider-rate-limit-upstash";
+
+const rateLimit = ctx.ports.rateLimit as UpstashRateLimitPort;
+
+// Access the Redis client for advanced operations
+await rateLimit.client.get("some:key");
+await rateLimit.client.set("some:key", "value");
+```
+
+## Testing
+
+The provider includes comprehensive tests. Run them with:
+
+```bash
+bun test
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @beignet/provider-rate-limit-upstash
+ *
+ * Upstash-based rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { upstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ *
+ * // In your middleware/policies:
+ * const result = await ctx.ports.rateLimit.hit({
+ *   key: `ip:${ctx.ip}`,
+ *   limit: 100,
+ *   windowSec: 60,
+ * });
+ *
+ * if (!result.allowed) {
+ *   return { status: 429, body: { message: "Too Many Requests" } };
+ * }
+ * ```
+ */
+import type { RateLimitPort } from "@beignet/core/ports";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { Redis } from "@upstash/redis";
+import { z } from "zod";
+/**
+ * Configuration schema for the Upstash Rate Limit provider.
+ * Validates environment variables with UPSTASH_ prefix.
+ */
+declare const UpstashRateLimitConfigSchema: z.ZodObject<{
+    REDIS_REST_URL: z.ZodString;
+    REDIS_REST_TOKEN: z.ZodString;
+    PREFIX: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Inferred configuration type for Upstash Rate Limit provider.
+ */
+export type UpstashRateLimitConfig = z.infer<typeof UpstashRateLimitConfigSchema>;
+/**
+ * Extended rate limit port interface that includes the Upstash Redis client.
+ * The Upstash provider adds the underlying client for advanced operations.
+ */
+export interface UpstashRateLimitPort extends RateLimitPort {
+    /**
+     * The underlying Upstash Redis client instance.
+     * Use this for advanced operations not covered by the rate limit interface.
+     */
+    client: Redis;
+}
+export interface CreateUpstashRateLimitPortOptions {
+    instrumentation?: ProviderInstrumentationTarget;
+}
+/**
+ * Upstash rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration via environment variables:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export declare const upstashRateLimitProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    REDIS_REST_URL: z.ZodString;
+    REDIS_REST_TOKEN: z.ZodString;
+    PREFIX: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, {
+    rateLimit: UpstashRateLimitPort;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,QAAA,MAAM,4BAA4B;;;;iBAkBhC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD;;;OAGG;IACH,MAAM,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAiHD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB;;;;;;EAyBnC,CAAC"}

package/dist/index.js

@@ -0,0 +1,186 @@
+/**
+ * @beignet/provider-rate-limit-upstash
+ *
+ * Upstash-based rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { upstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ *
+ * // In your middleware/policies:
+ * const result = await ctx.ports.rateLimit.hit({
+ *   key: `ip:${ctx.ip}`,
+ *   limit: 100,
+ *   windowSec: 60,
+ * });
+ *
+ * if (!result.allowed) {
+ *   return { status: 429, body: { message: "Too Many Requests" } };
+ * }
+ * ```
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+import { z } from "zod";
+/**
+ * Configuration schema for the Upstash Rate Limit provider.
+ * Validates environment variables with UPSTASH_ prefix.
+ */
+const UpstashRateLimitConfigSchema = z.object({
+    /**
+     * Upstash Redis REST URL.
+     * Example: "https://us1-properly-ancient-12345.upstash.io"
+     */
+    REDIS_REST_URL: z.string().url(),
+    /**
+     * Upstash Redis REST token.
+     */
+    REDIS_REST_TOKEN: z.string(),
+    /**
+     * Optional prefix for keys used by this rate limiter.
+     * Helps avoid collisions if you reuse the same Redis for multiple things.
+     * Defaults to "ck:ratelimit".
+     */
+    PREFIX: z.string().default("ck:ratelimit"),
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Creates an Upstash-backed RateLimitPort implementation.
+ *
+ * @param config - Validated Upstash configuration
+ * @returns A RateLimitPort implementation using Upstash
+ */
+function createUpstashRateLimitPort(config, options = {}) {
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "rate-limit-upstash",
+        watcher: "rateLimit",
+    });
+    const redis = new Redis({
+        url: config.REDIS_REST_URL,
+        token: config.REDIS_REST_TOKEN,
+    });
+    const prefix = config.PREFIX;
+    const port = {
+        async hit({ key, limit, windowSec }) {
+            const startedAt = Date.now();
+            try {
+                // Create a new Ratelimit instance for each call with the specified limit and window.
+                // This is necessary because Upstash's Ratelimit is configured with a specific
+                // limit/window at construction time, and we need dynamic limits per call.
+                // Performance note: Creating instances is lightweight as Upstash uses HTTP-based
+                // REST API calls, not persistent connections. The actual rate limiting logic
+                // happens server-side at Upstash.
+                const ratelimit = new Ratelimit({
+                    redis,
+                    // Use fixed window algorithm - simple and effective
+                    // Alternative: Ratelimit.slidingWindow(limit, `${windowSec} s`)
+                    limiter: Ratelimit.fixedWindow(limit, `${windowSec} s`),
+                    prefix,
+                });
+                const result = await ratelimit.limit(key);
+                const allowed = result.success;
+                // result.remaining is the number of remaining requests in the window
+                const remaining = typeof result.remaining === "number" ? result.remaining : null;
+                // Upstash returns a JavaScript timestamp in milliseconds.
+                const resetAt = typeof result.reset === "number" ? new Date(result.reset) : null;
+                const rateLimitResult = {
+                    allowed,
+                    remaining,
+                    resetAt,
+                    retryAfterSeconds: allowed || resetAt == null
+                        ? null
+                        : Math.max(0, Math.ceil((resetAt.getTime() - Date.now()) / 1000)),
+                };
+                instrumentation.custom({
+                    name: "rateLimit.hit",
+                    label: "Rate limit hit",
+                    summary: allowed ? "Request allowed" : "Request blocked",
+                    details: {
+                        key,
+                        limit,
+                        windowSec,
+                        prefix,
+                        allowed,
+                        remaining,
+                        resetAt: resetAt?.toISOString() ?? null,
+                        retryAfterSeconds: rateLimitResult.retryAfterSeconds,
+                        durationMs: Date.now() - startedAt,
+                    },
+                });
+                return rateLimitResult;
+            }
+            catch (error) {
+                instrumentation.custom({
+                    name: "rateLimit.hit.failed",
+                    label: "Rate limit failed",
+                    summary: "Rate limit hit failed",
+                    details: {
+                        key,
+                        limit,
+                        windowSec,
+                        prefix,
+                        durationMs: Date.now() - startedAt,
+                        error: errorMessage(error),
+                    },
+                });
+                throw error;
+            }
+        },
+        client: redis,
+    };
+    return port;
+}
+/**
+ * Upstash rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration via environment variables:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const upstashRateLimitProvider = createProvider({
+    name: "rate-limit-upstash",
+    config: {
+        schema: UpstashRateLimitConfigSchema,
+        envPrefix: "UPSTASH_",
+    },
+    async setup({ ports, config }) {
+        if (!config) {
+            throw new Error("[upstashRateLimitProvider] Missing config. " +
+                "Please set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables.");
+        }
+        const instrumentation = createProviderInstrumentation(ports, {
+            providerName: "rate-limit-upstash",
+            watcher: "rateLimit",
+        });
+        const rateLimitPort = createUpstashRateLimitPort(config, {
+            instrumentation,
+        });
+        return { ports: { rateLimit: rateLimitPort } };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@beignet/provider-rate-limit-upstash",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Upstash-based rate limit provider for Beignet - adds rate limit port using Upstash Redis",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "upstash",
+    "rate-limit",
+    "provider",
+    "redis",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-rate-limit-upstash"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@upstash/ratelimit": "^2.0.0",
+    "@upstash/redis": "^1.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@upstash/ratelimit": "^2.0.7",
+    "@upstash/redis": "^1.35.7",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,245 @@
+/**
+ * @beignet/provider-rate-limit-upstash
+ *
+ * Upstash-based rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { upstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ *
+ * // In your middleware/policies:
+ * const result = await ctx.ports.rateLimit.hit({
+ *   key: `ip:${ctx.ip}`,
+ *   limit: 100,
+ *   windowSec: 60,
+ * });
+ *
+ * if (!result.allowed) {
+ *   return { status: 429, body: { message: "Too Many Requests" } };
+ * }
+ * ```
+ */
+
+import type { RateLimitPort, RateLimitResult } from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+import { z } from "zod";
+
+/**
+ * Configuration schema for the Upstash Rate Limit provider.
+ * Validates environment variables with UPSTASH_ prefix.
+ */
+const UpstashRateLimitConfigSchema = z.object({
+  /**
+   * Upstash Redis REST URL.
+   * Example: "https://us1-properly-ancient-12345.upstash.io"
+   */
+  REDIS_REST_URL: z.string().url(),
+
+  /**
+   * Upstash Redis REST token.
+   */
+  REDIS_REST_TOKEN: z.string(),
+
+  /**
+   * Optional prefix for keys used by this rate limiter.
+   * Helps avoid collisions if you reuse the same Redis for multiple things.
+   * Defaults to "ck:ratelimit".
+   */
+  PREFIX: z.string().default("ck:ratelimit"),
+});
+
+/**
+ * Inferred configuration type for Upstash Rate Limit provider.
+ */
+export type UpstashRateLimitConfig = z.infer<
+  typeof UpstashRateLimitConfigSchema
+>;
+
+/**
+ * Extended rate limit port interface that includes the Upstash Redis client.
+ * The Upstash provider adds the underlying client for advanced operations.
+ */
+export interface UpstashRateLimitPort extends RateLimitPort {
+  /**
+   * The underlying Upstash Redis client instance.
+   * Use this for advanced operations not covered by the rate limit interface.
+   */
+  client: Redis;
+}
+
+export interface CreateUpstashRateLimitPortOptions {
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Creates an Upstash-backed RateLimitPort implementation.
+ *
+ * @param config - Validated Upstash configuration
+ * @returns A RateLimitPort implementation using Upstash
+ */
+function createUpstashRateLimitPort(
+  config: UpstashRateLimitConfig,
+  options: CreateUpstashRateLimitPortOptions = {},
+): UpstashRateLimitPort {
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "rate-limit-upstash",
+      watcher: "rateLimit",
+    },
+  );
+  const redis = new Redis({
+    url: config.REDIS_REST_URL,
+    token: config.REDIS_REST_TOKEN,
+  });
+
+  const prefix = config.PREFIX;
+
+  const port: UpstashRateLimitPort = {
+    async hit({ key, limit, windowSec }): Promise<RateLimitResult> {
+      const startedAt = Date.now();
+
+      try {
+        // Create a new Ratelimit instance for each call with the specified limit and window.
+        // This is necessary because Upstash's Ratelimit is configured with a specific
+        // limit/window at construction time, and we need dynamic limits per call.
+        // Performance note: Creating instances is lightweight as Upstash uses HTTP-based
+        // REST API calls, not persistent connections. The actual rate limiting logic
+        // happens server-side at Upstash.
+        const ratelimit = new Ratelimit({
+          redis,
+          // Use fixed window algorithm - simple and effective
+          // Alternative: Ratelimit.slidingWindow(limit, `${windowSec} s`)
+          limiter: Ratelimit.fixedWindow(limit, `${windowSec} s`),
+          prefix,
+        });
+
+        const result = await ratelimit.limit(key);
+
+        const allowed = result.success;
+
+        // result.remaining is the number of remaining requests in the window
+        const remaining =
+          typeof result.remaining === "number" ? result.remaining : null;
+
+        // Upstash returns a JavaScript timestamp in milliseconds.
+        const resetAt =
+          typeof result.reset === "number" ? new Date(result.reset) : null;
+
+        const rateLimitResult = {
+          allowed,
+          remaining,
+          resetAt,
+          retryAfterSeconds:
+            allowed || resetAt == null
+              ? null
+              : Math.max(0, Math.ceil((resetAt.getTime() - Date.now()) / 1000)),
+        };
+
+        instrumentation.custom({
+          name: "rateLimit.hit",
+          label: "Rate limit hit",
+          summary: allowed ? "Request allowed" : "Request blocked",
+          details: {
+            key,
+            limit,
+            windowSec,
+            prefix,
+            allowed,
+            remaining,
+            resetAt: resetAt?.toISOString() ?? null,
+            retryAfterSeconds: rateLimitResult.retryAfterSeconds,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return rateLimitResult;
+      } catch (error) {
+        instrumentation.custom({
+          name: "rateLimit.hit.failed",
+          label: "Rate limit failed",
+          summary: "Rate limit hit failed",
+          details: {
+            key,
+            limit,
+            windowSec,
+            prefix,
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    client: redis,
+  };
+
+  return port;
+}
+
+/**
+ * Upstash rate limit provider that extends ports with rate limiting capabilities.
+ *
+ * Configuration via environment variables:
+ * - UPSTASH_REDIS_REST_URL: Upstash Redis REST URL (required)
+ * - UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST token (required)
+ * - UPSTASH_PREFIX: Optional prefix for rate limit keys (default: "ck:ratelimit")
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [upstashRateLimitProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const upstashRateLimitProvider = createProvider({
+  name: "rate-limit-upstash",
+
+  config: {
+    schema: UpstashRateLimitConfigSchema,
+    envPrefix: "UPSTASH_",
+  },
+
+  async setup({ ports, config }) {
+    if (!config) {
+      throw new Error(
+        "[upstashRateLimitProvider] Missing config. " +
+          "Please set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables.",
+      );
+    }
+
+    const instrumentation = createProviderInstrumentation(ports, {
+      providerName: "rate-limit-upstash",
+      watcher: "rateLimit",
+    });
+    const rateLimitPort = createUpstashRateLimitPort(config, {
+      instrumentation,
+    });
+    return { ports: { rateLimit: rateLimitPort } };
+  },
+});