@beignet/provider-rate-limit-upstash

[!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.
• 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:

| 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: beignet:ratelimit) | myapp:ratelimit | | UPSTASH_ALGORITHM | No | Rate limit algorithm, fixed-window or sliding-window (default: fixed-window) | sliding-window |

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

import { createNextServer, createNextServerLoader } from "@beignet/next";
import { createUpstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";
import { createRateLimitHooks } from "@beignet/core/server";
import type { AppContext } from "@/app-context";
import { initialPorts } from "@/infra/port-wiring";
import { routes } from "@/server/routes";

export const getServer = createNextServerLoader(() =>
  createNextServer({
    ports: initialPorts,
    providers: [createUpstashRateLimitProvider()],
    trustedProxy: { clientIp: "x-forwarded-for-last" },
    hooks: [createRateLimitHooks<AppContext>()],
    context: ({ ports }) => ({ ports }),
    routes,
  }),
);

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 sharing one ip:unknown bucket across all clients. 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 the shared bucket.

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",
  }),
];

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",
});

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.

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");

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;
// { rateLimit: RateLimitPort; upstash: { client: Redis } }

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. A failed hit(...) call records a failed rate-limit event and throws the underlying Upstash error; hooks should decide whether that is fail-open or fail-closed for the route.

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.

Testing

The provider includes comprehensive tests. Run them with:

bun test

License

MIT