sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ RateLimit.ts

import type * as cf from "@cloudflare/workers-types";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Data from "effect/Data";
import type * as Effect from "effect/Effect";
import * as Binding from "./Binding.ts";
import type { RateLimitBinding } from "./RateLimitBinding.ts";

const TypeId = "Cloudflare.RateLimit" as const;
type TypeId = typeof TypeId;

export type RateLimitPeriod = 10 | 60;

export class RateLimitError extends Data.TaggedError("RateLimitError")<{
  message: string;
  cause: unknown;
}> {}

/**
 * Effect-native client for a Cloudflare Rate Limit binding. Wraps the runtime
 * `cf.RateLimit` so `limit` returns an `Effect` tagged with {@link RateLimitError}.
 */
export interface RateLimitClient {
  /** Effect resolving to the raw Cloudflare runtime binding. */
  raw: Effect.Effect<cf.RateLimit, never, RuntimeContext>;
  limit(
    options: Parameters<cf.RateLimit["limit"]>[0],
  ): Effect.Effect<Awaited<ReturnType<cf.RateLimit["limit"]>>, RateLimitError, RuntimeContext>;
}

export type RateLimitProps = {
  /**
   * Positive integer or string that uniquely identifies this rate limit
   * configuration.
   */
  namespaceId: number | string;
  /** Simple rate limiting configuration. */
  simple: {
    /** The number of requests allowed within the period. */
    limit: number;
    /** The period, in seconds, over which requests are counted. */
    period: RateLimitPeriod;
  };
};

/**
 * A Cloudflare Rate Limit binding for counting arbitrary keys inside Workers — a
 * Worker-only binding with no backing cloud resource.
 *
 * `RateLimit` is a single value that is at once the `Binding.Service` tag, the
 * callable that produces a {@link RateLimitBinding}, and the type. Declare it on
 * a Worker's `env` (it flows through `InferEnv` → the native `cf.RateLimit`) or
 * `yield*` it inside an Effect-native Worker to attach the binding and obtain
 * the {@link RateLimitClient}.
 *
 * ### Declaring on a Worker's env
 * **Example:** Async (non-Effect) Worker
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     THROTTLE: Cloudflare.RateLimit("THROTTLE", {
 *       namespaceId: 1001,
 *       simple: { limit: 10, period: 60 },
 *     }),
 *   },
 * });
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 * //   { THROTTLE: RateLimit } — the native Cloudflare binding
 *
 * // worker.ts
 * export default {
 *   fetch: async (req: Request, env: WorkerEnv) => {
 *     const { success } = await env.THROTTLE.limit({ key: "ip" });
 *     return new Response(success ? "ok" : "rate limited");
 *   },
 * };
 * ```
 *
 * ### Binding inside an Effect-native Worker
 * **Example:** yield* RateLimit does the binding
 * ```typescript
 * Cloudflare.Worker("Worker", { main: "./src/worker.ts" },
 *   Effect.gen(function* () {
 *     // Attaches the binding to this Worker AND returns the runtime client.
 *     const throttle = yield* Cloudflare.RateLimit("THROTTLE", {
 *       namespaceId: 1001,
 *       simple: { limit: 10, period: 60 },
 *     });
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const { success } = yield* throttle.limit({ key: "ip" });
 *         return HttpServerResponse.text(success ? "ok" : "rate limited");
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Workers.RateLimitBinding)),
 * );
 * ```
 *
 * @see https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/
 *
 * @binding
 * @product Rate Limiting
 * @category Application Security
 */
export interface RateLimit extends Binding.Service<RateLimit, TypeId, RateLimitClient> {
  /**
   * @param name Binding name (logical id) — the `env` key it resolves to.
   * @param props Rate limit namespace + simple config.
   */
  (name: string, props: RateLimitProps): RateLimitBinding;
}

export const RateLimit = Binding.Service<
  RateLimit,
  { namespaceId: string; simple: { limit: number; period: RateLimitPeriod } }
>({
  id: TypeId,
  defaultName: "RATE_LIMIT",
  parse: (name: string, props: RateLimitProps) => ({
    name,
    namespaceId: String(props.namespaceId),
    simple: props.simple,
  }),
  toWorkerBinding: (binding) => ({
    type: "ratelimit",
    name: binding.name,
    namespaceId: binding.namespaceId,
    simple: binding.simple,
  }),
});

export const isRateLimit = (value: unknown): value is RateLimitBinding =>
  Binding.isBinding(value) && value.kind === TypeId;