Architecture: Deepen Router to own middleware and eliminate route-matching leaks across middleware

[jonbaldie]

Candidate Summary

• Recommendation Strength: Worth exploring
• Modules Involved: src/router.ts, src/middleware.ts, src/handler.ts
• Domain Context: HTTP transport layer for Queue and Item Lifecycle
• Architecture Vocabulary: module, interface, depth, seam, adapter, leverage, locality

Problem & Evidence

Currently, Router in src/router.ts is a shallow module that only registers paths and methods, and executes them against a request URL.

Because Router does not own middleware or route execution pipelines, src/handler.ts wraps the entire router.handle method in a global chain:

const handlerWithAuth = withAuth(apiToken)(router.handle);
const handlerWithRateLimit = withRateLimit(rateLimiter)(handlerWithAuth);

Because the middleware wraps the entire router externally, any unauthenticated or un-rate-limited route (specifically /health) must be known and checked by EVERY middleware independently.

In src/middleware.ts:

const HEALTH_PATTERN = new URLPattern({ pathname: "/health{/}?" });

export function withAuth(apiToken: string): Middleware {
...
    if (HEALTH_PATTERN.exec(request.url)) {
        return next(request, info);
    }
...
export function withRateLimit(limiter: RateLimiter): Middleware {
...
    if (HEALTH_PATTERN.exec(request.url)) {
        return next(request, info);
    }

And in src/handler.ts:

router.get("/health{/}?", () => { ... });

Friction points:

1. Duplicated route pattern knowledge: Both withAuth and withRateLimit independently parse the URL and duplicate the /health{/}? pattern. In issue Health endpoint returns 401 for trailing-slash variant /health/ (public probe marked unhealthy) #67, fixing trailing slash support required editing both src/middleware.ts and src/handler.ts.
2. Violation of middleware single responsibility: Middleware modules designed to validate Bearer tokens or calculate IP rate limits are tightly coupled to the application's URL routing table. Adding any future public endpoint (e.g. /metrics) requires modifying all middleware files.
3. Inverted dispatch on 404: Unauthenticated requests to non-existent paths return 401 Unauthorized before the router ever runs, hiding 404 Not Found behind authentication.

Test Evidence (/deintrovert-tests)

In tests/handler_test.ts, middleware tests must construct full HTTP request URLs that include /health or non-health endpoints to verify bypass behavior, coupling middleware tests to specific route paths rather than testing auth or rate-limiting invariants directly.

The Deletion Test

Deleting HEALTH_PATTERN from src/middleware.ts removes path-matching complexity from middleware entirely. Middlewares become pure transforms: withAuth only inspects headers; withRateLimit only inspects IP and request timestamps.

Proposed Change

Deepen Router so that routes or route groups can declare middleware:

router.get("/health{/}?", healthHandler); // unauthenticated, unthrottled
router.group([withRateLimit(limiter), withAuth(apiToken)], (r) => {
    r.get("/queues", listQueuesHandler);
    r.post("/enqueue/:queue", enqueueHandler);
    r.get("/dequeue/:queue", dequeueHandler);
    r.get("/peek/:queue", peekHandler);
    r.get("/length/:queue", lengthHandler);
});

Alternatively, have Router match the route first, returning the handler and its associated middleware pipeline.

Benefits

• Leverage: New endpoints declare their security policy in one place (at route registration) rather than requiring edits across multiple middleware files.
• Locality: Routing rules and path matching concentrate entirely in src/router.ts and src/handler.ts. Middleware concentrates strictly on auth or rate limiting.
• Testability: Middleware can be tested in isolation using dummy requests without needing to construct specific URL pathnames matching /health.

[jonbaldie]

This was generated by AI during triage.

Verification: Confirmed in src/router.ts, src/middleware.ts, and src/handler.ts. Currently, Router does not support middleware or route pipelines. src/handler.ts wraps router.handle globally with withRateLimit and withAuth. Consequently, withAuth and withRateLimit duplicate the /health{/}? URLPattern check to bypass health probes. In addition, unauthenticated requests to non-existent routes return 401 Unauthorized before route matching occurs.

Redundancy check: Searched Router, withAuth, withRateLimit, createHandler, and tests/router_test.ts. Middleware remains external to Router, and path-matching bypass logic exists in src/middleware.ts. No matching .out-of-scope/ record exists.

Agent Brief

Category: enhancement
Summary: Deepen Router to support route-level or group middleware pipelines and eliminate route pattern matching from withAuth and withRateLimit.

Current behavior:
src/handler.ts wraps the entire router.handle function in withRateLimit(limiter)(withAuth(apiToken)(router.handle)). Because middleware wraps the router globally, withAuth and withRateLimit in src/middleware.ts each define and execute HEALTH_PATTERN = new URLPattern({ pathname: "/health{/}?" }) to exempt /health from auth and rate limits. Unauthenticated requests to undefined paths receive 401 instead of 404.

Desired behavior:
Router owns route registration and middleware execution. Endpoints or route groups declare their middleware requirements (e.g. rate limiting, auth) upon registration. withAuth and withRateLimit become focused HTTP middleware without any URL pattern matching or route knowledge. Unauthenticated requests to unregistered routes return 404 Not Found rather than 401 Unauthorized.

Key interfaces:

• Router in src/router.ts: supports attaching middleware to routes or route groups (e.g. router.use(), router.group(), or route-level middleware options), executing middleware in sequence before invoking the route handler.
• withAuth in src/middleware.ts: inspects Authorization header and validates Bearer token without checking request URLs or HEALTH_PATTERN.
• withRateLimit in src/middleware.ts: enforces rate limits per client identity without checking request URLs or HEALTH_PATTERN.
• registerRoutes / createHandler in src/handler.ts: configures /health as an unauthenticated/unthrottled route, while queue endpoints are registered with rate limiting and authentication middleware.

Acceptance criteria:
[ ] HEALTH_PATTERN is removed from src/middleware.ts.
[ ] withAuth and withRateLimit contain no URL matching or route-exemption logic.
[ ] Router allows routes or route groups to specify middleware pipelines that execute prior to route handlers.
[ ] /health and /health/ respond 200 without requiring an Authorization header or consuming rate limit tokens.
[ ] Queue endpoints (/queues, /enqueue/:queue, /dequeue/:queue, /peek/:queue, /length/:queue) enforce rate limiting and bearer token authentication.
[ ] Requests to unregistered routes return 404 Not Found without requiring authentication.
[ ] All router, handler, and e2e test suites pass.

Out of scope:

• Changing rate limiter sliding window algorithms or eviction rules.
• Modifying Bearer token validation logic or supported token character sets.
• Changing Queue Manager or persistence operations.