serverless-event-orchestrator 2.0.1 → 2.3.0

package/src/types/routes.ts

@@ -1,211 +1,218 @@
-import { RouteSegment } from './event-type.enum.js';
-import type { TenantInfo } from '../tenant/types.js';
-
-/**
- * HTTP methods supported by the router
- */
-export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
-
-/**
- * Middleware function signature
- * Returns the modified event or throws an error to halt execution
- */
-export type MiddlewareFn = (event: NormalizedEvent) => Promise<NormalizedEvent | void>;
-
-/**
- * Route configuration for a single endpoint
- */
-export interface RouteConfig {
-  handler: (event: NormalizedEvent) => Promise<any>;
-  middleware?: MiddlewareFn[];
-  cors?: boolean | CorsConfig;
-  rateLimit?: RateLimitConfig;
-}
-
-/**
- * CORS configuration options
- */
-export interface CorsConfig {
-  origins: string[] | '*';
-  methods?: string[];
-  headers?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-  exposedHeaders?: string[];
-}
-
-/**
- * Rate limit configuration
- */
-export interface RateLimitConfig {
-  burstLimit: number;
-  rateLimit: number;
-}
-
-/**
- * Standard HTTP router structure
- * Maps HTTP methods to path-handler pairs
- */
-export type HttpRouter = {
-  [K in HttpMethod]?: {
-    [path: string]: RouteConfig;
-  };
-};
-
-/**
- * Segmented HTTP router for access control categorization
- * Allows organizing routes by security context
- */
-export interface SegmentedHttpRouter {
-  public?: HttpRouter;
-  private?: HttpRouter;
-  backoffice?: HttpRouter;
-  internal?: HttpRouter;
-}
-
-/**
- * Segment configuration with optional middleware
- */
-export interface SegmentConfig {
-  routes: HttpRouter;
-  middleware?: MiddlewareFn[];
-}
-
-/**
- * Advanced segmented router with per-segment middleware
- */
-export interface AdvancedSegmentedRouter {
-  public?: SegmentConfig | HttpRouter;
-  private?: SegmentConfig | HttpRouter;
-  backoffice?: SegmentConfig | HttpRouter;
-  internal?: SegmentConfig | HttpRouter;
-}
-
-/**
- * EventBridge routes configuration
- * Maps operation names to handlers
- */
-export type EventBridgeRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
-
-/**
- * Lambda invocation routes
- */
-export type LambdaRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
-
-/**
- * SQS queue routes
- * Maps queue names to handlers
- */
-export type SqsRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
-
-/**
- * Complete dispatch routes configuration
- */
-export interface DispatchRoutes {
-  apigateway?: HttpRouter | SegmentedHttpRouter | AdvancedSegmentedRouter;
-  eventbridge?: EventBridgeRoutes;
-  lambda?: LambdaRoutes;
-  sqs?: SqsRoutes;
-}
-
-/**
- * Identity context extracted from the event
- */
-export interface IdentityContext {
-  userId?: string;
-  email?: string;
-  groups?: string[];
-  issuer?: string;
-  claims?: Record<string, any>;
-}
-
-/**
- * Route match result with extracted parameters
- */
-export interface RouteMatch {
-  handler: (event: NormalizedEvent) => Promise<any>;
-  params: Record<string, string>;
-  segment: RouteSegment;
-  middleware?: MiddlewareFn[];
-  config: RouteConfig;
-}
-
-/**
- * Normalized event structure passed to handlers
- */
-export interface NormalizedEvent {
-  eventRaw: any;
-  eventType: string;
-  payload: {
-    body?: Record<string, any>;
-    pathParameters?: Record<string, string>;
-    queryStringParameters?: Record<string, string>;
-    headers?: Record<string, string>;
-  };
-  params: Record<string, string>;
-  context: {
-    segment: RouteSegment;
-    identity?: IdentityContext;
-    requestId?: string;
-    tenantInfo?: TenantInfo;
-  };
-}
-
-/**
- * JWT verification configuration for a Cognito User Pool
- */
-export interface JwtVerificationPoolConfig {
-  /** Cognito User Pool ID (e.g., "us-east-1_ABC123") */
-  userPoolId: string;
-  /** App Client ID(s). Pass null to skip client ID verification. */
-  clientId?: string | string[] | null;
-  /** Expected token use. Pass null to accept either. Defaults to null. */
-  tokenUse?: 'id' | 'access' | null;
-}
-
-/**
- * Orchestrator configuration options
- */
-export interface OrchestratorConfig {
-  /**
-   * Enable verbose logging for debugging
-   */
-  debug?: boolean;
-
-  /**
-   * User Pool ID mappings for segment-based validation (issuer string only).
-   * @deprecated Use jwtVerification instead for cryptographic signature verification.
-   */
-  userPools?: {
-    [K in RouteSegment]?: string;
-  };
-
-  /**
-   * Global middleware applied to all routes
-   */
-  globalMiddleware?: MiddlewareFn[];
-
-  /**
-   * Custom response handlers
-   */
-  responses?: {
-    notFound?: () => any;
-    forbidden?: () => any;
-    badRequest?: (message?: string) => any;
-    internalError?: (message?: string) => any;
-  };
-
-  /**
-   * Automatically extract identity from Authorization header if no authorizer is present
-   */
-  autoExtractIdentity?: boolean;
-
-  /**
-   * JWT signature verification configuration.
-   * When provided for a segment, JWTs from the Authorization header
-   * are cryptographically verified against the Cognito JWKS endpoint.
-   */
-  jwtVerification?: {
-    [K in RouteSegment]?: JwtVerificationPoolConfig;
-  };
-}
+import { RouteSegment } from './event-type.enum.js';
+import type { TenantInfo } from '../tenant/types.js';
+
+/**
+ * HTTP methods supported by the router
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
+
+/**
+ * Middleware function signature
+ * Returns the modified event or throws an error to halt execution
+ */
+export type MiddlewareFn = (event: NormalizedEvent) => Promise<NormalizedEvent | void>;
+
+/**
+ * Route configuration for a single endpoint
+ */
+export interface RouteConfig {
+  handler: (event: NormalizedEvent) => Promise<any>;
+  middleware?: MiddlewareFn[];
+  cors?: boolean | CorsConfig;
+  rateLimit?: RateLimitConfig;
+}
+
+/**
+ * CORS configuration options
+ */
+export interface CorsConfig {
+  origins: string[] | '*';
+  methods?: string[];
+  headers?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+  exposedHeaders?: string[];
+}
+
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+  burstLimit: number;
+  rateLimit: number;
+}
+
+/**
+ * Standard HTTP router structure
+ * Maps HTTP methods to path-handler pairs
+ */
+export type HttpRouter = {
+  [K in HttpMethod]?: {
+    [path: string]: RouteConfig;
+  };
+};
+
+/**
+ * Segmented HTTP router for access control categorization
+ * Allows organizing routes by security context
+ */
+export interface SegmentedHttpRouter {
+  public?: HttpRouter;
+  private?: HttpRouter;
+  backoffice?: HttpRouter;
+  internal?: HttpRouter;
+}
+
+/**
+ * Segment configuration with optional middleware
+ */
+export interface SegmentConfig {
+  routes: HttpRouter;
+  middleware?: MiddlewareFn[];
+}
+
+/**
+ * Advanced segmented router with per-segment middleware
+ */
+export interface AdvancedSegmentedRouter {
+  public?: SegmentConfig | HttpRouter;
+  private?: SegmentConfig | HttpRouter;
+  backoffice?: SegmentConfig | HttpRouter;
+  internal?: SegmentConfig | HttpRouter;
+}
+
+/**
+ * EventBridge routes configuration
+ * Maps operation names to handlers
+ */
+export type EventBridgeRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
+
+/**
+ * Lambda invocation routes
+ */
+export type LambdaRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
+
+/**
+ * SQS queue routes
+ * Maps queue names to handlers
+ */
+export type SqsRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
+
+/**
+ * Scheduled event routes (EventBridge Scheduler / CloudWatch Events rules)
+ * Maps rule names to handlers. Use 'default' as fallback.
+ */
+export type ScheduledRoutes = Record<string, (event: NormalizedEvent) => Promise<any>>;
+
+/**
+ * Complete dispatch routes configuration
+ */
+export interface DispatchRoutes {
+  apigateway?: HttpRouter | SegmentedHttpRouter | AdvancedSegmentedRouter;
+  eventbridge?: EventBridgeRoutes;
+  lambda?: LambdaRoutes;
+  sqs?: SqsRoutes;
+  scheduled?: ScheduledRoutes;
+}
+
+/**
+ * Identity context extracted from the event
+ */
+export interface IdentityContext {
+  userId?: string;
+  email?: string;
+  groups?: string[];
+  issuer?: string;
+  claims?: Record<string, any>;
+}
+
+/**
+ * Route match result with extracted parameters
+ */
+export interface RouteMatch {
+  handler: (event: NormalizedEvent) => Promise<any>;
+  params: Record<string, string>;
+  segment: RouteSegment;
+  middleware?: MiddlewareFn[];
+  config: RouteConfig;
+}
+
+/**
+ * Normalized event structure passed to handlers
+ */
+export interface NormalizedEvent {
+  eventRaw: any;
+  eventType: string;
+  payload: {
+    body?: Record<string, any>;
+    pathParameters?: Record<string, string>;
+    queryStringParameters?: Record<string, string>;
+    headers?: Record<string, string>;
+  };
+  params: Record<string, string>;
+  context: {
+    segment: RouteSegment;
+    identity?: IdentityContext;
+    requestId?: string;
+    tenantInfo?: TenantInfo;
+  };
+}
+
+/**
+ * JWT verification configuration for a Cognito User Pool
+ */
+export interface JwtVerificationPoolConfig {
+  /** Cognito User Pool ID (e.g., "us-east-1_ABC123") */
+  userPoolId: string;
+  /** App Client ID(s). Pass null to skip client ID verification. */
+  clientId?: string | string[] | null;
+  /** Expected token use. Pass null to accept either. Defaults to null. */
+  tokenUse?: 'id' | 'access' | null;
+}
+
+/**
+ * Orchestrator configuration options
+ */
+export interface OrchestratorConfig {
+  /**
+   * Enable verbose logging for debugging
+   */
+  debug?: boolean;
+
+  /**
+   * User Pool ID mappings for segment-based validation (issuer string only).
+   * @deprecated Use jwtVerification instead for cryptographic signature verification.
+   */
+  userPools?: {
+    [K in RouteSegment]?: string;
+  };
+
+  /**
+   * Global middleware applied to all routes
+   */
+  globalMiddleware?: MiddlewareFn[];
+
+  /**
+   * Custom response handlers
+   */
+  responses?: {
+    notFound?: () => any;
+    forbidden?: () => any;
+    badRequest?: (message?: string) => any;
+    internalError?: (message?: string) => any;
+  };
+
+  /**
+   * Automatically extract identity from Authorization header if no authorizer is present
+   */
+  autoExtractIdentity?: boolean;
+
+  /**
+   * JWT signature verification configuration.
+   * When provided for a segment, JWTs from the Authorization header
+   * are cryptographically verified against the Cognito JWKS endpoint.
+   */
+  jwtVerification?: {
+    [K in RouteSegment]?: JwtVerificationPoolConfig;
+  };
+}

package/src/utils/headers.ts

@@ -1,72 +1,72 @@
-/**
- * Header normalization utilities
- * HTTP headers are case-insensitive, this ensures consistent access
- */
-
-/**
- * Normalizes headers to lowercase keys for consistent access
- * @param headers - Original headers object
- * @returns Headers with lowercase keys
- */
-export function normalizeHeaders(headers: Record<string, string> | undefined): Record<string, string> {
-  if (!headers) return {};
-  
-  const normalized: Record<string, string> = {};
-  
-  for (const [key, value] of Object.entries(headers)) {
-    normalized[key.toLowerCase()] = value;
-  }
-  
-  return normalized;
-}
-
-/**
- * Gets a header value case-insensitively
- * @param headers - Headers object
- * @param name - Header name to find
- * @returns Header value or undefined
- */
-export function getHeader(headers: Record<string, string> | undefined, name: string): string | undefined {
-  if (!headers) return undefined;
-  
-  const normalizedName = name.toLowerCase();
-  
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === normalizedName) {
-      return value;
-    }
-  }
-  
-  return undefined;
-}
-
-/**
- * Standard CORS headers for preflight responses
- */
-export function getCorsHeaders(config?: {
-  origins?: string[] | '*';
-  methods?: string[];
-  headers?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-}): Record<string, string> {
-  const origin = config?.origins === '*' ? '*' : (config?.origins?.join(', ') || '*');
-  const methods = config?.methods?.join(', ') || 'GET,POST,PUT,DELETE,PATCH,OPTIONS';
-  const headers = config?.headers?.join(', ') || 'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token';
-  
-  const corsHeaders: Record<string, string> = {
-    'Access-Control-Allow-Origin': origin,
-    'Access-Control-Allow-Methods': methods,
-    'Access-Control-Allow-Headers': headers,
-  };
-  
-  if (config?.credentials) {
-    corsHeaders['Access-Control-Allow-Credentials'] = 'true';
-  }
-  
-  if (config?.maxAge) {
-    corsHeaders['Access-Control-Max-Age'] = String(config.maxAge);
-  }
-  
-  return corsHeaders;
-}
+/**
+ * Header normalization utilities
+ * HTTP headers are case-insensitive, this ensures consistent access
+ */
+
+/**
+ * Normalizes headers to lowercase keys for consistent access
+ * @param headers - Original headers object
+ * @returns Headers with lowercase keys
+ */
+export function normalizeHeaders(headers: Record<string, string> | undefined): Record<string, string> {
+  if (!headers) return {};
+  
+  const normalized: Record<string, string> = {};
+  
+  for (const [key, value] of Object.entries(headers)) {
+    normalized[key.toLowerCase()] = value;
+  }
+  
+  return normalized;
+}
+
+/**
+ * Gets a header value case-insensitively
+ * @param headers - Headers object
+ * @param name - Header name to find
+ * @returns Header value or undefined
+ */
+export function getHeader(headers: Record<string, string> | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  
+  const normalizedName = name.toLowerCase();
+  
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  
+  return undefined;
+}
+
+/**
+ * Standard CORS headers for preflight responses
+ */
+export function getCorsHeaders(config?: {
+  origins?: string[] | '*';
+  methods?: string[];
+  headers?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}): Record<string, string> {
+  const origin = config?.origins === '*' ? '*' : (config?.origins?.join(', ') || '*');
+  const methods = config?.methods?.join(', ') || 'GET,POST,PUT,DELETE,PATCH,OPTIONS';
+  const headers = config?.headers?.join(', ') || 'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token';
+  
+  const corsHeaders: Record<string, string> = {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Methods': methods,
+    'Access-Control-Allow-Headers': headers,
+  };
+  
+  if (config?.credentials) {
+    corsHeaders['Access-Control-Allow-Credentials'] = 'true';
+  }
+  
+  if (config?.maxAge) {
+    corsHeaders['Access-Control-Max-Age'] = String(config.maxAge);
+  }
+  
+  return corsHeaders;
+}

package/src/utils/index.ts

@@ -1,2 +1,2 @@
-export * from './path-matcher.js';
-export * from './headers.js';
+export * from './path-matcher.js';
+export * from './headers.js';