suaveplan/packages/api-stack/api/api-plugin-site/docs/middleware-integration.md

Middleware composition — site + rate-limit + audit

@suaveplan/api-plugin-site ships zero runtime dependencies on @suaveplan/api-plugin-rate-limit and @suaveplan/api-plugin-audit. This is deliberate. The composition knob lives in the host application: callers wire the middleware via Hono's app.use(prefix, middleware) pattern so they can swap or skip implementations as their deployment requires.

This guide documents the canonical pattern, the recommended layering order, and a copy-pasteable end-to-end example. A runnable verification of every assertion lives in src/integration/middleware-composition.integration.test.ts.

Layering order

                ┌────────────────────────────────────────┐
   inbound      │  audit middleware (OUTERMOST)          │
   request  ──▶ │  ──▶ rate-limit middleware             │
                │      ──▶ site routes (INNERMOST)       │
                └────────────────────────────────────────┘

The order matters and is not interchangeable:

1. Audit OUTERMOST. The audit middleware records one event per inbound request — including requests that are rejected by rate-limit with 429. Putting audit inside rate-limit would silently drop the audit record on every throttled call, defeating the purpose of an immutable trail. The audit middleware is also a no-throw boundary by contract, so it adds no failure modes.
2. Rate-limit MIDDLE. The rate-limit middleware is mounted on the site prefix (/sites/*) so it does not consume budget for unrelated routes mounted on the same host (health checks, OpenAPI documents, etc). Putting rate-limit inside the site routes would force every site route to opt in by hand and would miss requests that hit 404 route stubs.
3. Site routes INNERMOST. The site plugin's createPrivateSiteRoutes and createPublicSiteRoutes factories return OpenAPIHono instances that are mounted via app.route(prefix, routes). They make zero assumptions about the surrounding middleware stack.

Canonical example

import {
    AuditLogger,
    MemoryAuditAdapter,
} from "@suaveplan/audit-logging";
import { createAuditMiddleware } from "@suaveplan/api-plugin-audit";
import {
    createDefaultStorage,
    createRateLimitService,
    rateLimit,
    RateLimitPluginOptionsSchema,
} from "@suaveplan/api-plugin-rate-limit";
import {
    createPrivateSiteRoutes,
    createPublicSiteRoutes,
    MIDDLEWARE_RECOMMENDATIONS,
    SiteService,
} from "@suaveplan/api-plugin-site";
import { Hono } from "hono";

// ── 1. Site service + routes ────────────────────────────────────────
const siteService = new SiteService(db, mergeConfig());
const privateRoutes = createPrivateSiteRoutes({ siteService });
const publicRoutes = createPublicSiteRoutes({ domainResolver });

// ── 2. Rate-limit service driven by the recommendations bundle ─────
const clock = () => Date.now();
const rateLimitConfig = RateLimitPluginOptionsSchema.parse({
    defaultLimit: 100,
    defaultWindowMs: 60_000,
    routes: MIDDLEWARE_RECOMMENDATIONS.map((r) => ({
        id: r.routeGroup,
        path: r.rateLimit.pathPattern,
        limit: r.rateLimit.limit,
        windowMs: r.rateLimit.windowMs,
    })),
});
const rateLimitService = createRateLimitService({
    config: rateLimitConfig,
    storage: createDefaultStorage({ clock }),
    clock,
    logger: hostLogger,
});

// ── 3. Audit logger backed by your AuditStorageAdapter ─────────────
const auditSink = new MemoryAuditAdapter();
const auditLogger = new AuditLogger({
    storage: auditSink,
    secretKey: process.env.AUDIT_SECRET ?? "x".repeat(32),
    enableChainIntegrity: true,
});
const auditMiddleware = createAuditMiddleware({
    logger: auditLogger,
    config: {
        sink: auditSink,
        secretKey: process.env.AUDIT_SECRET ?? "x".repeat(32),
        samplingRate: 1,
        excludePaths: ["/health"],
        redactQueryParams: ["token"],
        redactHeaders: ["authorization", "cookie"],
        redactBodyFields: ["password", "secret"],
        recordResponseSize: true,
        recordRequestBody: false,
        enableChainIntegrity: true,
        rng: Math.random,
    },
    hostLogger,
});

// ── 4. Compose: audit outermost → rate-limit → site routes ────────
const app = new Hono();
app.use("*", auditMiddleware);
app.use("/sites/*", rateLimit({ service: rateLimitService }));
app.route("/", publicRoutes);
app.route("/", privateRoutes);

Recommendations

The MIDDLEWARE_RECOMMENDATIONS constant exported from this package describes the recommended rate-limit ceilings and audit categories per documented route group (public:resolve, public:read, private:write). See src/integration/middleware-recommendations.md for the per-field rationale and an advanced consumption example.

Verification

The integration test at src/integration/middleware-composition.integration.test.ts boots a real Hono app composed exactly as documented above, exercises POST /sites, and asserts:

• The response status is 201 and the site row is persisted (site behaviour preserved).
• X-RateLimit-Limit is present on the response (rate-limit observed the request).
• The audit sink contains exactly one AuditEvent with details.method === "POST" and details.path === "/sites".