feat(extensibility): FUNC-577 - Gates provide composable handlers

[johnstonmatt]

// example-function.ts
import { withSupabase } from "@supabase/server";
import { withFeatureFlag } from "@supabase/server/gates/feature-flag";
import { withRateLimit } from "@supabase/server/gates/rate-limit";

export default {
  fetch: withSupabase(
    { allow: "user" }, // ctx.supabase, ctx.userClaims
    withFeatureFlag(
      {
        name: "beta-search",
        evaluate: (req) => req.headers.get("x-beta") === "1",
      },
      withRateLimit(
        {
          limit: 60,
          windowMs: 60_000,
          key: (req) => req.headers.get("cf-connecting-ip") ?? "anon",
        },
        async (_req, ctx) => {
          // ctx.userClaims  ← withSupabase
          // ctx.supabase    ← withSupabase  (user-scoped, RLS applies)
          // ctx.featureFlag ← withFeatureFlag
          // ctx.rateLimit   ← withRateLimit
          const { data } = await ctx.supabase.from("reports").select();
          return Response.json({
            user: ctx.userClaims!.id,
            variant: ctx.featureFlag.variant,
            remaining: ctx.rateLimit.remaining,
            data,
          });
        },
      ),
    ),
  ),
};

This pull request introduces a new extensibility system called gates to the @supabase/server package, enabling users and third-party authors to add reusable middleware-like wrappers (such as feature flags, rate limiting, etc.) to fetch handlers. The PR also adds documentation and updates package exports to support this new system, including a built-in feature flag gate as an example. Below are the most important changes:

Gates System Introduction & Documentation

• Added a comprehensive section to the README.md explaining gates: what they are, how to use them, and where to find documentation and examples. This includes usage patterns, TypeScript inference details, and links to authoring guides.
• Added a new src/core/gates/README.md with detailed documentation for gate authors and consumers, including type safety guarantees, composition rules, and authoring patterns using the new defineGate primitive.

Exports and Packaging

• Updated package.json and jsr.json to export the new @supabase/server/core/gates (gate authoring primitives) and @supabase/server/gates/feature-flag (the worked example gate), making them available for import in user projects. [1] [2] [3]

Documentation and Discoverability

• Expanded the exports and documentation tables in README.md to list the new gate-related exports and provide direct links to documentation for extending handlers, writing custom gates, and using the feature flag gate. [1] [2]

Changelog

• Minor formatting fix in CHANGELOG.md for consistency.

Notes

• there are many other Gates that have been developed internally which we may choose to provide here later

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@65

commit: cbffc47