@beignet/provider-rate-limit-upstash

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

[!CAUTION] Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

Upstash-backed RateLimitPort provider for Beignet applications.

The provider installs ctx.ports.rateLimit using Upstash Redis and @upstash/ratelimit.

createUpstashRateLimitProvider(...) returns the stable UpstashRateLimitProvider type. UpstashRateLimitConfig describes its validated config; the Zod schema remains internal.

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.
• Supports fixed window and sliding window algorithms via UPSTASH_ALGORITHM.
• Bounds dependency decisions and fails closed after five seconds by default.
• Exposes a read-only readiness check through ctx.ports.upstash.
• Emits devtools events for allowed, blocked, and failed hits.

Install

bun add @beignet/provider-rate-limit-upstash @beignet/core @upstash/redis @upstash/ratelimit

Configuration

Set these environment variables:

Choosing an algorithm

• fixed-window (default) is the cheapest option: one counter per window. It can allow short bursts at window boundaries, since a client can spend a full limit at the end of one window and again at the start of the next.
• sliding-window smooths those boundary bursts by weighting the previous window into the current one, at the cost of slightly more Redis work per hit.

Switching algorithms changes how counters are keyed in Redis, so in-flight windows effectively reset when you change UPSTASH_ALGORITHM.

Getting Upstash credentials

1. Sign up at Upstash
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

In a Beignet starter app, install and wire the port with:

bun beignet provider add rate-limit-upstash
bun install

Set the Upstash environment variables above. The preset extends the existing provider registry and app port wiring. Add createRateLimitHooks<AppContext>() from @beignet/core/server to the existing hooks list in server/index.ts to enforce contract metadata. Preserve the starter's authentication, context, other hooks, and providers.

For manual provider registration, import createUpstashRateLimitProvider from this package and add createUpstashRateLimitProvider() to your provider list. Follow the rate limiting guide for the server patch and verification steps.

The bare createRateLimitHooks<AppContext>() call covers global and user scoped limits. Contracts that declare rateLimit: { scope: "ip" } require an explicit server-level trustedProxy.clientIp, hook-local trustedProxy.clientIp, ipSource, or earlyKey option — createServer(...) fails at startup otherwise instead of silently assigning all unidentified traffic to a contract-scoped bucket. Prefer a server-level trustedProxy: { clientIp: "x-forwarded-for-last" } behind a trusted reverse proxy or trustedProxy: { clientIp: "cf-connecting-ip" } for platform headers. Use a hook-local option only for an intentional override, or ipSource: "none" to opt in to one unknown-client bucket per contract.

Default keys include the contract name, so unrelated contracts do not consume one another's limits. User scope fails with AuthUnauthorizedError unless route hooks resolve a user actor. A custom key or earlyKey owns the complete bucket key and should include route identity unless cross-route aggregation is intentional.

beignet doctor --strict checks that installed Upstash rate-limit providers are registered in server/providers.ts and that UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN are present in app env examples or config.

Use createUpstashRateLimitProvider(...) when you want to pass config directly instead of reading UPSTASH_* env vars. Options override env-derived values:

import { createUpstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";

export const providers = [
  createUpstashRateLimitProvider({
    redisRestUrl: secrets.upstashRedisRestUrl,
    redisRestToken: secrets.upstashRedisRestToken,
    prefix: "myapp:ratelimit",
    algorithm: "sliding-window",
    timeoutMs: 2500,
    timeoutPolicy: "fail-closed",
  }),
];

Calling createUpstashRateLimitProvider() with no options uses the env-backed configuration.

Direct adapter

Use createUpstashRateLimit(...) when the app already owns an Upstash Redis client:

import { Redis } from "@upstash/redis";
import { createUpstashRateLimit } from "@beignet/provider-rate-limit-upstash";

const client = Redis.fromEnv();
const rateLimit = createUpstashRateLimit({
  client,
  prefix: "myapp:ratelimit",
  algorithm: "sliding-window",
  timeoutMs: 2500,
  timeoutPolicy: "fail-closed",
});

The direct factory defaults to the same beignet:ratelimit prefix and fixed-window algorithm as the provider. It reads no environment variables and does not own the client lifecycle. Pass instrumentation to retain provider events in direct wiring.

Direct use

Once the provider is registered, you can use the rate limit port in hooks, policies, or use cases:

// Example app-specific policy that rate limits by IP address
async function checkIpRateLimit(ctx: AppContext) {
  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:

// 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:

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:

type RateLimitMetadata = {
  rateLimit?: {
    max: number;
    windowSec: number;
    scope?: "global" | "ip" | "user";
  };
};

async function rateLimitFromMeta(ctx: AppContext, 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:

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 Ratelimit.fixedWindow() by default, or Ratelimit.slidingWindow() when UPSTASH_ALGORITHM=sliding-window
• Backend: Upstash Redis REST API (serverless-compatible)
• Per-request configuration: Caches one Ratelimit instance per (limit, windowSec, algorithm) combination to support dynamic limits without reconstructing limiters on every hit() call
• 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, algorithm, allowed/blocked result, remaining count, reset time, retry-after value, and duration. Provider failures are recorded as rateLimit.hit.failed. An intentional fail-open timeout is recorded as rateLimit.hit.degraded, not as an ordinary allowed decision.

Escape hatch

The provider contributes the standard rateLimit port plus ctx.ports.upstash with the raw Upstash Redis client for operations the stable rate limit port does not model:

// Access the Redis client for advanced operations.
await ctx.ports.upstash.client.get("some:key");
await ctx.ports.upstash.client.set("some:key", "value");

// Use the read-only PING check from readiness and connected preflight.
const health = await ctx.ports.upstash.checkHealth();

To get proper type inference for the contributed ports, extend your ports type with UpstashRateLimitProviderPorts:

import type { UpstashRateLimitProviderPorts } from "@beignet/provider-rate-limit-upstash";

type AppPorts = typeof basePorts & UpstashRateLimitProviderPorts;
// Adds rateLimit plus upstash.client and upstash.checkHealth() to AppPorts.

Use the stable RateLimitPort for normal application behavior. Use the raw client only when the Upstash-specific operation is intentional.

Failure behavior

The env-backed provider throws during startup when required Upstash env vars are missing. Network and Upstash errors are recorded and rethrown unchanged.

Upstash's SDK can return an allowed result when it cannot make a decision before its timeout. Beignet treats that condition as an error by default: after UPSTASH_TIMEOUT_MS (default 5000), fail-closed records rateLimit.hit.failed and throws so protected work does not continue without enforcement. Set UPSTASH_TIMEOUT_POLICY=fail-open only when availability is more important than enforcement during an Upstash outage. Fail-open timeouts return an allowed result with unknown remaining/reset values and emit rateLimit.hit.degraded.

Local and tests

Use a fake RateLimitPort in route and use-case tests. For local development, either point at an Upstash development database or wire an app-owned memory rate limiter before this provider is needed.

Deployment notes

Rate-limit keys are part of production behavior. Set UPSTASH_PREFIX per app and environment so deploy previews, staging, and production do not share counters accidentally.

The provider uses Upstash's REST client and starts no worker or persistent connection, so the same adapter works in serverless and long-lived HTTP runtimes. The configured request-scoped timeout bounds each rate-limit decision and readiness PING. Add ctx.ports.upstash.checkHealth() to an app-owned readiness route; beignet preflight --connect discovers the same check automatically.

Testing

The provider includes comprehensive tests. Run them with:

bun test

License

MIT