@fluojs/http 1.0.0-beta.1

package/dist/middleware/cors.js

@@ -0,0 +1,57 @@
+function resolveOrigin(options, requestOrigin) {
+  if (typeof options.allowOrigin === 'function') {
+    return options.allowOrigin(requestOrigin);
+  }
+  if (Array.isArray(options.allowOrigin)) {
+    if (!requestOrigin) {
+      return undefined;
+    }
+    return options.allowOrigin.includes(requestOrigin) ? requestOrigin : undefined;
+  }
+  return options.allowOrigin ?? '*';
+}
+function setHeaderIfValue(response, name, value) {
+  if (value) {
+    response.setHeader(name, value);
+  }
+}
+export function createCorsMiddleware(options = {}) {
+  if (options.allowCredentials === true) {
+    if (options.allowOrigin === '*' || options.allowOrigin === undefined) {
+      throw new Error('CORS misconfiguration: allowCredentials cannot be true when allowOrigin is "*" or unset (defaults to "*"). Specify explicit origins instead.');
+    }
+  }
+  const allowMethods = options.allowMethods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+  return {
+    async handle(context, next) {
+      const requestOriginHeader = context.request.headers.origin;
+      const requestOrigin = Array.isArray(requestOriginHeader) ? requestOriginHeader[0] : requestOriginHeader;
+      const origin = resolveOrigin(options, requestOrigin);
+      if (origin) {
+        if (options.allowCredentials === true && origin === '*') {
+          throw new Error('CORS misconfiguration: allowCredentials cannot be true when allowOrigin function returns "*". Specify explicit origins instead.');
+        }
+        context.response.setHeader('Access-Control-Allow-Origin', origin);
+      }
+      setHeaderIfValue(context.response, 'Access-Control-Allow-Methods', allowMethods.join(', '));
+      setHeaderIfValue(context.response, 'Access-Control-Allow-Headers', options.allowHeaders?.join(', '));
+      setHeaderIfValue(context.response, 'Access-Control-Expose-Headers', options.exposeHeaders?.join(', '));
+      setHeaderIfValue(context.response, 'Access-Control-Allow-Credentials', options.allowCredentials ? 'true' : undefined);
+      setHeaderIfValue(context.response, 'Access-Control-Max-Age', options.maxAge !== undefined ? String(options.maxAge) : undefined);
+      if (origin && origin !== '*') {
+        const existingVary = context.response.headers['vary'] ?? context.response.headers['Vary'];
+        const varyValues = existingVary ? Array.isArray(existingVary) ? existingVary : String(existingVary).split(',').map(v => v.trim()) : [];
+        if (!varyValues.some(v => v.toLowerCase() === 'origin')) {
+          varyValues.push('Origin');
+        }
+        context.response.setHeader('Vary', varyValues.join(', '));
+      }
+      if (context.request.method === 'OPTIONS') {
+        context.response.setStatus(204);
+        await context.response.send(undefined);
+        return;
+      }
+      await next();
+    }
+  };
+}

package/dist/middleware/middleware.d.ts

@@ -0,0 +1,8 @@
+import type { Constructor } from '@fluojs/core';
+import type { Middleware, MiddlewareContext, MiddlewareLike, MiddlewareRouteConfig, Next } from '../types.js';
+export declare function isMiddlewareRouteConfig(value: MiddlewareLike): value is MiddlewareRouteConfig;
+export declare function normalizeRoutePattern(path: string): string;
+export declare function matchRoutePattern(pattern: string, path: string): boolean;
+export declare function forRoutes<T extends Constructor<Middleware>>(middlewareClass: T, ...routes: string[]): MiddlewareRouteConfig;
+export declare function runMiddlewareChain(definitions: MiddlewareLike[], context: MiddlewareContext, terminal: Next): Promise<void>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,cAAc,CAAC;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AAM9H,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,qBAAqB,CAE7F;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAUxE;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,WAAW,CAAC,UAAU,CAAC,EACzD,eAAe,EAAE,CAAC,EAClB,GAAG,MAAM,EAAE,MAAM,EAAE,GAClB,qBAAqB,CAEvB;AA2CD,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,cAAc,EAAE,EAC7B,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,EAAE,IAAI,GACb,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/middleware/middleware.js

@@ -0,0 +1,64 @@
+import { normalizeRoutePath } from '../route-path.js';
+function isMiddleware(value) {
+  return typeof value === 'object' && value !== null && 'handle' in value;
+}
+export function isMiddlewareRouteConfig(value) {
+  return typeof value === 'object' && value !== null && 'middleware' in value && 'routes' in value;
+}
+export function normalizeRoutePattern(path) {
+  if (path.endsWith('/*')) {
+    return `${normalizeRoutePattern(path.slice(0, -2))}/*`;
+  }
+  return normalizeRoutePath(path);
+}
+export function matchRoutePattern(pattern, path) {
+  const normalizedPath = normalizeRoutePattern(path);
+  const normalizedPattern = normalizeRoutePattern(pattern);
+  if (normalizedPattern.endsWith('/*')) {
+    const prefix = normalizedPattern.slice(0, -2);
+    return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+  }
+  return normalizedPath === normalizedPattern;
+}
+export function forRoutes(middlewareClass, ...routes) {
+  return {
+    middleware: middlewareClass,
+    routes
+  };
+}
+async function resolveMiddleware(definition, requestContext) {
+  if (isMiddleware(definition)) {
+    return definition;
+  }
+  return requestContext.container.resolve(definition);
+}
+async function resolveActiveMiddlewareDefinitions(definitions, context) {
+  const requestPath = context.request.path;
+  const middlewareChain = [];
+  for (const definition of definitions) {
+    if (isMiddlewareRouteConfig(definition)) {
+      const matches = definition.routes.length === 0 || definition.routes.some(route => matchRoutePattern(route, requestPath));
+      if (!matches) {
+        continue;
+      }
+      const middleware = await context.requestContext.container.resolve(definition.middleware);
+      middlewareChain.push(middleware);
+      continue;
+    }
+    middlewareChain.push(await resolveMiddleware(definition, context.requestContext));
+  }
+  return middlewareChain;
+}
+function deferNext(next) {
+  return async () => {
+    await Promise.resolve();
+    await next();
+  };
+}
+export async function runMiddlewareChain(definitions, context, terminal) {
+  const middlewareChain = await resolveActiveMiddlewareDefinitions(definitions, context);
+  const composed = middlewareChain.reduceRight((next, middleware) => deferNext(async () => {
+    await middleware.handle(context, next);
+  }), deferNext(terminal));
+  await composed();
+}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,39 @@
+import type { MiddlewareContext, Middleware } from '../types.js';
+/** Snapshot of one key's current rate-limit window state. */
+export interface RateLimitStoreEntry {
+    count: number;
+    resetAt: number;
+}
+/** Store contract used by `createRateLimitMiddleware(...)` request windows. */
+export interface RateLimitStore {
+    get(key: string): RateLimitStoreEntry | undefined | Promise<RateLimitStoreEntry | undefined>;
+    set(key: string, entry: RateLimitStoreEntry): void | Promise<void>;
+    increment(key: string): number | Promise<number>;
+    evict(now: number): void | Promise<void>;
+}
+/** Public configuration contract for `createRateLimitMiddleware(...)`. */
+export interface RateLimitOptions {
+    limit: number;
+    windowMs: number;
+    keyResolver?: (ctx: MiddlewareContext) => string;
+    store?: RateLimitStore;
+    /**
+     * Trust `Forwarded`, `X-Forwarded-For`, and `X-Real-IP` before the raw socket address.
+     * Enable this only when the adapter sits behind a trusted proxy that overwrites spoofable headers.
+     */
+    trustProxyHeaders?: boolean;
+}
+/**
+ * Create the built-in in-memory store for request rate-limit windows.
+ *
+ * @returns Store instance that tracks request counts in process memory.
+ */
+export declare function createMemoryRateLimitStore(): RateLimitStore;
+/**
+ * Create middleware that rejects requests once a per-key window exceeds its limit.
+ *
+ * @param options Limit, window, trust, and storage settings for one middleware instance.
+ * @returns Middleware that enforces the configured request budget.
+ */
+export declare function createRateLimitMiddleware(options: RateLimitOptions): Middleware;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIjE,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IAC7F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,CAAC;IACjD,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAQD;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,cAAc,CAwC3D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAkD/E"}

package/dist/middleware/rate-limit.js

@@ -0,0 +1,106 @@
+import { TooManyRequestsException, createErrorResponse } from '../exceptions.js';
+import { resolveClientIdentity } from '../client-identity.js';
+
+/** Snapshot of one key's current rate-limit window state. */
+
+/** Store contract used by `createRateLimitMiddleware(...)` request windows. */
+
+/** Public configuration contract for `createRateLimitMiddleware(...)`. */
+
+function defaultKeyResolver(ctx, options) {
+  return resolveClientIdentity(ctx.request, {
+    trustProxyHeaders: options.trustProxyHeaders ?? false
+  });
+}
+
+/**
+ * Create the built-in in-memory store for request rate-limit windows.
+ *
+ * @returns Store instance that tracks request counts in process memory.
+ */
+export function createMemoryRateLimitStore() {
+  const map = new Map();
+  let nextSweepAt = 0;
+  return {
+    get(key) {
+      return map.get(key);
+    },
+    set(key, entry) {
+      map.set(key, entry);
+    },
+    increment(key) {
+      const entry = map.get(key);
+      if (!entry) {
+        return 0;
+      }
+      entry.count++;
+      return entry.count;
+    },
+    evict(now) {
+      if (now < nextSweepAt) {
+        return;
+      }
+      let next = Number.POSITIVE_INFINITY;
+      for (const [key, entry] of map) {
+        if (now >= entry.resetAt) {
+          map.delete(key);
+          continue;
+        }
+        next = Math.min(next, entry.resetAt);
+      }
+      nextSweepAt = Number.isFinite(next) ? next : 0;
+    }
+  };
+}
+
+/**
+ * Create middleware that rejects requests once a per-key window exceeds its limit.
+ *
+ * @param options Limit, window, trust, and storage settings for one middleware instance.
+ * @returns Middleware that enforces the configured request budget.
+ */
+export function createRateLimitMiddleware(options) {
+  const store = options.store ?? createMemoryRateLimitStore();
+  return {
+    async handle(context, next) {
+      const key = options.keyResolver ? options.keyResolver(context) : defaultKeyResolver(context, options);
+      const now = Date.now();
+      await store.evict(now);
+      const entry = await store.get(key);
+      if (!entry || now >= entry.resetAt) {
+        const resetAt = now + options.windowMs;
+        await store.set(key, {
+          count: 1,
+          resetAt
+        });
+        if (1 > options.limit) {
+          const retryAfter = Math.ceil(options.windowMs / 1000);
+          const error = new TooManyRequestsException('Too Many Requests', {
+            meta: {
+              retryAfter
+            }
+          });
+          context.response.setHeader('Retry-After', String(retryAfter));
+          context.response.setStatus(429);
+          await context.response.send(createErrorResponse(error, context.requestContext.requestId));
+          return;
+        }
+        return next();
+      }
+      const count = await store.increment(key);
+      if (count > options.limit) {
+        const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+        const error = new TooManyRequestsException('Too Many Requests', {
+          meta: {
+            retryAfter
+          }
+        });
+        context.response.setHeader('Retry-After', String(retryAfter));
+        context.response.setStatus(429);
+        await context.response.send(createErrorResponse(error, context.requestContext.requestId));
+        return;
+      }
+      return next();
+    }
+  };
+}

package/dist/middleware/security-headers.d.ts

@@ -0,0 +1,12 @@
+import type { Middleware } from '../types.js';
+export interface SecurityHeadersOptions {
+    contentSecurityPolicy?: string | false;
+    crossOriginOpenerPolicy?: string | false;
+    referrerPolicy?: string | false;
+    strictTransportSecurity?: string | false;
+    xContentTypeOptions?: false;
+    xFrameOptions?: string | false;
+    xXssProtection?: string | false;
+}
+export declare function createSecurityHeadersMiddleware(options?: SecurityHeadersOptions): Middleware;
+//# sourceMappingURL=security-headers.d.ts.map

package/dist/middleware/security-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/middleware/security-headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC,qBAAqB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvC,uBAAuB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC,uBAAuB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,mBAAmB,CAAC,EAAE,KAAK,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACjC;AAYD,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU,CA6ChG"}

package/dist/middleware/security-headers.js

@@ -0,0 +1,47 @@
+const DEFAULTS = {
+  contentSecurityPolicy: "default-src 'self'",
+  crossOriginOpenerPolicy: 'same-origin',
+  referrerPolicy: 'strict-origin-when-cross-origin',
+  strictTransportSecurity: 'max-age=15552000; includeSubDomains',
+  xContentTypeOptions: 'nosniff',
+  xFrameOptions: 'SAMEORIGIN',
+  xXssProtection: '0'
+};
+export function createSecurityHeadersMiddleware(options = {}) {
+  const csp = 'contentSecurityPolicy' in options ? options.contentSecurityPolicy : DEFAULTS.contentSecurityPolicy;
+  const coop = 'crossOriginOpenerPolicy' in options ? options.crossOriginOpenerPolicy : DEFAULTS.crossOriginOpenerPolicy;
+  const referrer = 'referrerPolicy' in options ? options.referrerPolicy : DEFAULTS.referrerPolicy;
+  const hsts = 'strictTransportSecurity' in options ? options.strictTransportSecurity : DEFAULTS.strictTransportSecurity;
+  const xcto = 'xContentTypeOptions' in options ? options.xContentTypeOptions : DEFAULTS.xContentTypeOptions;
+  const xfo = 'xFrameOptions' in options ? options.xFrameOptions : DEFAULTS.xFrameOptions;
+  const xxp = 'xXssProtection' in options ? options.xXssProtection : DEFAULTS.xXssProtection;
+  const applyHeaders = response => {
+    if (csp) {
+      response.setHeader('Content-Security-Policy', csp);
+    }
+    if (coop) {
+      response.setHeader('Cross-Origin-Opener-Policy', coop);
+    }
+    if (referrer) {
+      response.setHeader('Referrer-Policy', referrer);
+    }
+    if (hsts) {
+      response.setHeader('Strict-Transport-Security', hsts);
+    }
+    if (xcto) {
+      response.setHeader('X-Content-Type-Options', xcto);
+    }
+    if (xfo) {
+      response.setHeader('X-Frame-Options', xfo);
+    }
+    if (xxp) {
+      response.setHeader('X-XSS-Protection', xxp);
+    }
+  };
+  return {
+    async handle(context, next) {
+      applyHeaders(context.response);
+      await next();
+    }
+  };
+}

package/dist/route-path.d.ts

@@ -0,0 +1,15 @@
+export interface RoutePathLiteralSegment {
+    kind: 'literal';
+    value: string;
+}
+export interface RoutePathParamSegment {
+    kind: 'param';
+    name: string;
+}
+export type RoutePathSegment = RoutePathLiteralSegment | RoutePathParamSegment;
+export declare function normalizeRoutePath(path: string): string;
+export declare function parseRoutePath(path: string, label?: string): RoutePathSegment[];
+export declare function validateRoutePath(path: string, label?: string): void;
+export declare function extractRoutePathParams(path: string): string[];
+export declare function matchRoutePath(registeredSegments: readonly RoutePathSegment[], incomingSegments: readonly string[]): Readonly<Record<string, string>> | undefined;
+//# sourceMappingURL=route-path.d.ts.map

package/dist/route-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-path.d.ts","sourceRoot":"","sources":["../src/route-path.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,qBAAqB,CAAC;AAsD/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAK/E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAEpE;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D;AAED,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,SAAS,gBAAgB,EAAE,EAC/C,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAqB9C"}

package/dist/route-path.js

@@ -0,0 +1,69 @@
+import { InvalidRoutePathError } from './errors.js';
+const routeParamNamePattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const unsupportedLiteralTokenPattern = /[*?+()[\]{}\\]/;
+const supportedRouteSyntaxDescription = 'Only literal segments and full-segment ":param" placeholders are supported.';
+function normalizeLabel(label) {
+  const value = label?.trim();
+  return value && value.length > 0 ? value : 'Route path';
+}
+function describeSegment(segment) {
+  return `"${segment}"`;
+}
+function throwInvalidRoutePath(label, path, segment, reason) {
+  throw new InvalidRoutePathError(`${normalizeLabel(label)} "${path}" is invalid at segment ${describeSegment(segment)}: ${reason}. ${supportedRouteSyntaxDescription}`);
+}
+function parseRoutePathSegment(segment, path, label) {
+  if (segment.startsWith(':')) {
+    const paramName = segment.slice(1);
+    if (!routeParamNamePattern.test(paramName)) {
+      throwInvalidRoutePath(label, path, segment, 'Parameter names must match /[a-zA-Z_][a-zA-Z0-9_]*/');
+    }
+    return {
+      kind: 'param',
+      name: paramName
+    };
+  }
+  if (segment.includes(':')) {
+    throwInvalidRoutePath(label, path, segment, 'Parameters must occupy the entire segment');
+  }
+  if (unsupportedLiteralTokenPattern.test(segment)) {
+    throwInvalidRoutePath(label, path, segment, 'Wildcards, regex-like tokens, and inline modifiers are not supported');
+  }
+  return {
+    kind: 'literal',
+    value: segment
+  };
+}
+export function normalizeRoutePath(path) {
+  const segments = path.split('/').filter(Boolean);
+  const normalized = `/${segments.join('/')}`;
+  return normalized === '' ? '/' : normalized;
+}
+export function parseRoutePath(path, label) {
+  const normalizedPath = normalizeRoutePath(path);
+  const segments = normalizedPath.split('/').filter(Boolean);
+  return segments.map(segment => parseRoutePathSegment(segment, path, label));
+}
+export function validateRoutePath(path, label) {
+  void parseRoutePath(path, label);
+}
+export function extractRoutePathParams(path) {
+  return parseRoutePath(path).flatMap(segment => segment.kind === 'param' ? [segment.name] : []);
+}
+export function matchRoutePath(registeredSegments, incomingSegments) {
+  if (registeredSegments.length !== incomingSegments.length) {
+    return undefined;
+  }
+  const params = {};
+  for (const [index, segment] of registeredSegments.entries()) {
+    const incoming = incomingSegments[index];
+    if (segment.kind === 'param') {
+      params[segment.name] = incoming;
+      continue;
+    }
+    if (segment.value !== incoming) {
+      return undefined;
+    }
+  }
+  return params;
+}