serverless-event-orchestrator 1.0.1

package/src/http/response.ts

@@ -0,0 +1,194 @@
+/**
+ * Response utilities for consistent HTTP responses
+ * Agnostic to domain-specific error codes - allows injection of custom codes
+ */
+
+/**
+ * Standard HTTP status codes
+ */
+export enum HttpStatus {
+  OK = 200,
+  CREATED = 201,
+  NO_CONTENT = 204,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  CONFLICT = 409,
+  UNPROCESSABLE_ENTITY = 422,
+  INTERNAL_SERVER_ERROR = 500,
+  SERVICE_UNAVAILABLE = 503,
+}
+
+/**
+ * Standard response structure
+ */
+export interface StandardResponse<T = unknown, C = string> {
+  status: number;
+  code: C;
+  data?: T;
+  message?: string;
+}
+
+/**
+ * Lambda HTTP response format
+ */
+export interface HttpResponse {
+  statusCode: number;
+  body: string;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Default response codes for standard HTTP statuses
+ */
+export const DefaultResponseCode = {
+  SUCCESS: 'SUCCESS',
+  CREATED: 'CREATED',
+  BAD_REQUEST: 'BAD_REQUEST',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+/**
+ * Creates a standardized HTTP response
+ * @param statusCode - HTTP status code
+ * @param data - Response payload
+ * @param code - Custom response code
+ * @param message - Optional message
+ * @param headers - Optional headers
+ */
+export function createStandardResponse<T, C = string>(
+  statusCode: number,
+  data?: T,
+  code?: C,
+  message?: string,
+  headers?: Record<string, string>
+): HttpResponse {
+  const responseCode = code ?? getDefaultCodeForStatus(statusCode);
+  
+  const body: StandardResponse<T, C | string> = {
+    status: statusCode,
+    code: responseCode,
+    ...(data !== undefined && { data }),
+    ...(message && { message }),
+  };
+
+  return {
+    statusCode,
+    body: JSON.stringify(body, null, 2),
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+  };
+}
+
+/**
+ * Gets default response code for a status
+ */
+function getDefaultCodeForStatus(status: number): string {
+  switch (status) {
+    case HttpStatus.OK:
+      return DefaultResponseCode.SUCCESS;
+    case HttpStatus.CREATED:
+      return DefaultResponseCode.CREATED;
+    case HttpStatus.BAD_REQUEST:
+      return DefaultResponseCode.BAD_REQUEST;
+    case HttpStatus.UNAUTHORIZED:
+      return DefaultResponseCode.UNAUTHORIZED;
+    case HttpStatus.FORBIDDEN:
+      return DefaultResponseCode.FORBIDDEN;
+    case HttpStatus.NOT_FOUND:
+      return DefaultResponseCode.NOT_FOUND;
+    case HttpStatus.CONFLICT:
+      return DefaultResponseCode.CONFLICT;
+    case HttpStatus.UNPROCESSABLE_ENTITY:
+      return DefaultResponseCode.VALIDATION_ERROR;
+    default:
+      return DefaultResponseCode.INTERNAL_ERROR;
+  }
+}
+
+/**
+ * Success response (200 OK)
+ */
+export function successResponse<T>(data?: T, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.OK, data, code ?? DefaultResponseCode.SUCCESS, undefined, headers);
+}
+
+/**
+ * Created response (201 Created)
+ */
+export function createdResponse<T>(data?: T, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.CREATED, data, code ?? DefaultResponseCode.CREATED, undefined, headers);
+}
+
+/**
+ * Bad request response (400)
+ */
+export function badRequestResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.BAD_REQUEST, undefined, code ?? DefaultResponseCode.BAD_REQUEST, message, headers);
+}
+
+/**
+ * Unauthorized response (401)
+ */
+export function unauthorizedResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.UNAUTHORIZED, undefined, code ?? DefaultResponseCode.UNAUTHORIZED, message, headers);
+}
+
+/**
+ * Forbidden response (403)
+ */
+export function forbiddenResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.FORBIDDEN, undefined, code ?? DefaultResponseCode.FORBIDDEN, message, headers);
+}
+
+/**
+ * Not found response (404)
+ */
+export function notFoundResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.NOT_FOUND, undefined, code ?? DefaultResponseCode.NOT_FOUND, message, headers);
+}
+
+/**
+ * Conflict response (409)
+ */
+export function conflictResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.CONFLICT, undefined, code ?? DefaultResponseCode.CONFLICT, message, headers);
+}
+
+/**
+ * Validation error response (422)
+ */
+export function validationErrorResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.UNPROCESSABLE_ENTITY, undefined, code ?? DefaultResponseCode.VALIDATION_ERROR, message, headers);
+}
+
+/**
+ * Internal server error response (500)
+ */
+export function internalErrorResponse(message?: string, code?: string, headers?: Record<string, string>): HttpResponse {
+  return createStandardResponse(HttpStatus.INTERNAL_SERVER_ERROR, undefined, code ?? DefaultResponseCode.INTERNAL_ERROR, message, headers);
+}
+
+/**
+ * Custom error response with automatic status resolution
+ * @param customCode - Your domain-specific error code
+ * @param message - Error message
+ * @param codeToStatusMap - Mapping of custom codes to HTTP statuses
+ */
+export function customErrorResponse<C extends string>(
+  customCode: C,
+  message?: string,
+  codeToStatusMap?: Record<C, HttpStatus>,
+  headers?: Record<string, string>
+): HttpResponse {
+  const status = codeToStatusMap?.[customCode] ?? HttpStatus.INTERNAL_SERVER_ERROR;
+  return createStandardResponse(status, undefined, customCode, message, headers);
+}

package/src/identity/extractor.ts

@@ -0,0 +1,89 @@
+import { IdentityContext } from '../types/routes.js';
+
+/**
+ * Extracts identity context from API Gateway authorizer claims
+ * Supports Cognito User Pools and custom authorizers
+ */
+
+/**
+ * Extracts identity information from the event's authorizer context
+ * @param event - Raw API Gateway event
+ * @returns Identity context or undefined if not authenticated
+ */
+export function extractIdentity(event: any): IdentityContext | undefined {
+  const claims = event?.requestContext?.authorizer?.claims;
+  
+  if (!claims) {
+    return undefined;
+  }
+  
+  return {
+    userId: claims.sub || claims['cognito:username'],
+    email: claims.email,
+    groups: parseGroups(claims['cognito:groups']),
+    issuer: claims.iss,
+    claims,
+  };
+}
+
+/**
+ * Parses Cognito groups from claims
+ * Groups can come as a string or array depending on configuration
+ */
+function parseGroups(groups: string | string[] | undefined): string[] {
+  if (!groups) return [];
+  if (Array.isArray(groups)) return groups;
+  
+  // Cognito sometimes sends groups as a comma-separated string
+  return groups.split(',').map(g => g.trim()).filter(Boolean);
+}
+
+/**
+ * Extracts the User Pool ID from the issuer URL
+ * @param issuer - Cognito issuer URL (e.g., https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx)
+ * @returns User Pool ID or undefined
+ */
+export function extractUserPoolId(issuer: string | undefined): string | undefined {
+  if (!issuer) return undefined;
+  
+  // Extract the last segment of the issuer URL
+  const parts = issuer.split('/');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Validates that the token issuer matches the expected User Pool
+ * @param identity - Extracted identity context
+ * @param expectedUserPoolId - Expected User Pool ID
+ * @returns True if issuer matches
+ */
+export function validateIssuer(identity: IdentityContext | undefined, expectedUserPoolId: string): boolean {
+  if (!identity?.issuer) return false;
+  
+  const actualUserPoolId = extractUserPoolId(identity.issuer);
+  return actualUserPoolId === expectedUserPoolId;
+}
+
+/**
+ * Checks if the user belongs to any of the specified groups
+ * @param identity - Extracted identity context
+ * @param allowedGroups - Groups that grant access
+ * @returns True if user is in at least one allowed group
+ */
+export function hasAnyGroup(identity: IdentityContext | undefined, allowedGroups: string[]): boolean {
+  if (!identity?.groups || identity.groups.length === 0) return false;
+  
+  return allowedGroups.some(group => identity.groups?.includes(group));
+}
+
+/**
+ * Checks if the user belongs to all specified groups
+ * @param identity - Extracted identity context
+ * @param requiredGroups - Groups required for access
+ * @returns True if user is in all required groups
+ */
+export function hasAllGroups(identity: IdentityContext | undefined, requiredGroups: string[]): boolean {
+  if (!identity?.groups || identity.groups.length === 0) return false;
+  
+  return requiredGroups.every(group => identity.groups?.includes(group));
+}

package/src/identity/index.ts

@@ -0,0 +1 @@
+export * from './extractor.js';

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * serverless-event-orchestrator
+ * 
+ * A lightweight, type-safe event dispatcher and middleware orchestrator for AWS Lambda.
+ * Designed for hexagonal architectures with support for segmented routing,
+ * Cognito User Pool validation, and built-in infrastructure middlewares.
+ */
+
+// Core dispatcher
+export { dispatchEvent, detectEventType, createOrchestrator } from './dispatcher.js';
+
+// Types
+export {
+  EventType,
+  RouteSegment,
+} from './types/event-type.enum.js';
+
+export {
+  HttpMethod,
+  MiddlewareFn,
+  RouteConfig,
+  CorsConfig,
+  RateLimitConfig,
+  HttpRouter,
+  SegmentedHttpRouter,
+  SegmentConfig,
+  AdvancedSegmentedRouter,
+  EventBridgeRoutes,
+  LambdaRoutes,
+  SqsRoutes,
+  DispatchRoutes,
+  IdentityContext,
+  RouteMatch,
+  NormalizedEvent,
+  OrchestratorConfig,
+} from './types/routes.js';
+
+// HTTP utilities
+export {
+  HttpStatus,
+  StandardResponse,
+  HttpResponse,
+  DefaultResponseCode,
+  createStandardResponse,
+  successResponse,
+  createdResponse,
+  badRequestResponse,
+  unauthorizedResponse,
+  forbiddenResponse,
+  notFoundResponse,
+  conflictResponse,
+  validationErrorResponse,
+  internalErrorResponse,
+  customErrorResponse,
+} from './http/response.js';
+
+export {
+  parseJsonBody,
+  parseQueryParams,
+  withJsonBodyParser,
+} from './http/body-parser.js';
+
+export {
+  isPreflightRequest,
+  createPreflightResponse,
+  applyCorsHeaders,
+  withCors,
+} from './http/cors.js';
+
+// Identity utilities
+export {
+  extractIdentity,
+  extractUserPoolId,
+  validateIssuer,
+  hasAnyGroup,
+  hasAllGroups,
+} from './identity/extractor.js';
+
+// Path utilities
+export {
+  matchPath,
+  patternToRegex,
+  hasPathParameters,
+  normalizePath,
+} from './utils/path-matcher.js';
+
+// Header utilities
+export {
+  normalizeHeaders,
+  getHeader,
+  getCorsHeaders,
+} from './utils/headers.js';

package/src/types/event-type.enum.ts

@@ -0,0 +1,20 @@
+/**
+ * Supported AWS event types for dispatching
+ */
+export enum EventType {
+  EventBridge = 'eventbridge',
+  ApiGateway = 'apigateway',
+  Lambda = 'lambda',
+  Sqs = 'sqs',
+  Unknown = 'unknown',
+}
+
+/**
+ * Route segments for access control categorization
+ */
+export enum RouteSegment {
+  Public = 'public',
+  Private = 'private',
+  Backoffice = 'backoffice',
+  Internal = 'internal',
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './event-type.enum.js';
+export * from './routes.js';

package/src/types/routes.ts

@@ -0,0 +1,182 @@
+import { RouteSegment } from './event-type.enum.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;
+  };
+}
+
+/**
+ * Orchestrator configuration options
+ */
+export interface OrchestratorConfig {
+  /**
+   * Enable verbose logging for debugging
+   */
+  debug?: boolean;
+
+  /**
+   * User Pool ID mappings for segment-based validation
+   */
+  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;
+  };
+}

package/src/utils/headers.ts

@@ -0,0 +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;
+}

package/src/utils/index.ts

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