Rate limits and quotas

limits:
  driver: local
  single-instance: true
  policies:
    export: { max: 5, per: 1m }

import { limits } from "mainsdk";

const d = await limits.rate("u_1", { per: "1m", max: 5 });   // an inline policy needs no main.yaml entry
if (!d.ok) console.log(`try again in ${d.retryAfter}s`);       // { ok, limit, remaining, resetAt, retryAfter?, policy, window }

limits:
  driver: redis                    # local | redis; default: the runtime store's driver
  redis: { url: secret:REDIS_URL }
  timeout: 50ms                    # per store call; then on-store-down applies
  single-instance: false           # true says local is enough in production
  policies:
    login:  { max: 5, per: 15m, algorithm: token-bucket, on-store-down: closed }
    api:    { max: 600, per: 1m, algorithm: sliding-window, burst: 600 }
    export: { max: 5, per: 1m }
  quotas:
    exports-daily: { max: 50, per: day, on-store-down: open }
  concurrency:
    transcode: { max: 2, ttl: 10m }

import { limits } from "mainsdk";

export async function GET(req: Request) {
  const d = await limits.rate(req.headers.get("x-forwarded-for") ?? "anon", "api");
  const headers = limits.headers(d);   // RateLimit-Policy and RateLimit, plus Retry-After when refused
  if (!d.ok) return new Response("Too many requests", { status: 429, headers });
  return new Response("ok", { headers });
}

import { limits } from "mainsdk";

async function runExport(userId: string): Promise<string> {
  return `export-${userId}`;
}

export async function startExport(userId: string) {
  await limits.quota("exports-daily", { key: userId });
  try {
    return await runExport(userId);
  } catch (err) {
    await limits.release("exports-daily", { key: userId, add: 1 });   // never below 0
    throw err;
  }
}

import { limits } from "mainsdk";

export async function nightlyReport() {
  await limits.lock("reports.nightly", async (signal) => {
    // one worker at a time; `signal` aborts if the lease is lost
  }, { ttl: "10m", wait: "5s" });   // wait for the holder; without `wait`, the second caller throws MAIN-LIMIT-0004
}

import { limits } from "mainsdk";

export async function transcode(tenantId: string) {
  await limits.concurrency("transcode", async () => {
    // at most 2 at a time for this key; a third caller throws MAIN-LIMIT-0003
  }, { key: tenantId });
}

limits:
  driver: redis   # was local
  redis: { url: secret:REDIS_URL }

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { limits } from "mainsdk";

describe("export rate limit", () => {
  it("refuses the sixth export in a minute and allows it after", async () => {
    const app = createTestApp({ main: "./main.yaml" });   // export: { max: 5, per: 1m }
    for (let i = 0; i < 5; i++) assert.equal((await limits.rate("u1", "export")).ok, true);
    const refused = await limits.rate("u1", "export");
    assert.equal(refused.ok, false);
    assert.ok((refused.retryAfter ?? 0) > 0);
    app.clock.advance("1m");
    assert.equal((await limits.rate("u1", "export")).ok, true);
  });
});