@crossdelta/cloudevents 0.5.6 → 0.6.0

package/dist/infrastructure/errors.js

@@ -1,54 +0,0 @@
-// HTTP Response Functions
-/**
- * Handles errors with full context logging
- */
-export const handleErrorWithContext = (error, context, additionalInfo) => {
-    const errorInfo = {
-        message: error.message,
-        stack: error.stack,
-        url: context.req.url,
-        method: context.req.method,
-        headers: Object.fromEntries(context.req.raw.headers.entries()),
-        ...additionalInfo,
-    };
-    console.error('[Error Handler]', JSON.stringify(errorInfo, null, 2));
-    return errorInfo;
-};
-/**
- * Converts an error to a standardized response format
- */
-export const errorToResponse = (error, type = 'InternalError') => ({
-    error: {
-        type,
-        message: error.message,
-        timestamp: new Date().toISOString(),
-    },
-});
-/**
- * Creates a standardized error response
- */
-export const createErrorResponse = (type, message, details) => ({
-    error: {
-        type,
-        message,
-        timestamp: new Date().toISOString(),
-        details,
-    },
-});
-// Application Error Factory Functions
-export const createValidationError = (eventType, details) => ({
-    type: 'ValidationError',
-    eventType,
-    message: `Validation failed for event type: ${eventType}`,
-    details,
-});
-export const createNoHandlerFoundError = (eventType) => ({
-    type: 'NoHandlerFoundError',
-    eventType,
-    message: `No handler found for event type: ${eventType}`,
-});
-export const createCloudEventParseError = (message, cause) => ({
-    type: 'CloudEventParseError',
-    message,
-    cause,
-});

package/dist/infrastructure/index.d.ts

@@ -1,4 +0,0 @@
-export type { CloudEventParseError, ErrorResponse, NoHandlerFoundError, SuccessResponse, ValidationError, } from './errors';
-export { createCloudEventParseError, createErrorResponse, createNoHandlerFoundError, createValidationError, errorToResponse, handleErrorWithContext, } from './errors';
-export type { Logger } from './logging';
-export { createLogger, logger } from './logging';

package/dist/infrastructure/index.js

@@ -1,2 +0,0 @@
-export { createCloudEventParseError, createErrorResponse, createNoHandlerFoundError, createValidationError, errorToResponse, handleErrorWithContext, } from './errors';
-export { createLogger, logger } from './logging';

package/dist/infrastructure/logging.d.ts

@@ -1,18 +0,0 @@
-/**
- * Logger interface for structured logging
- */
-export interface Logger {
-    log: (message: string, args?: unknown) => void;
-    info: (message: string, args?: unknown) => void;
-    warn: (message: string, error?: unknown) => void;
-    error: (message: string, error?: unknown) => void;
-    debug: (message: string, args?: unknown) => void;
-}
-/**
- * Creates a logger with configurable output based on enabled flag
- */
-export declare const createLogger: (enabled: boolean) => Logger;
-/**
- * Default logger instance (enabled by default)
- */
-export declare const logger: Logger;

package/dist/infrastructure/logging.js

@@ -1,27 +0,0 @@
-/**
- * Logging Infrastructure
- *
- * Provides structured logging with configurable output levels
- * and CloudEvents-specific logging utilities
- */
-const LOG_PREFIX = 'cloudevents';
-/**
- * Creates a logger with configurable output based on enabled flag
- */
-export const createLogger = (enabled) => {
-    const logWithArgs = (consoleFn, message, args) => {
-        const formattedMessage = `[${LOG_PREFIX}] ${message}`;
-        args !== undefined ? consoleFn(formattedMessage, args) : consoleFn(formattedMessage);
-    };
-    return {
-        log: (message, args) => enabled && logWithArgs(console.log, message, args),
-        info: (message, args) => enabled && logWithArgs(console.info, message, args),
-        warn: (message, error) => enabled && logWithArgs(console.warn, message, error),
-        error: (message, error) => logWithArgs(console.error, message, error),
-        debug: (message, args) => logWithArgs(console.debug, message, args),
-    };
-};
-/**
- * Default logger instance (enabled by default)
- */
-export const logger = createLogger(true);

package/dist/middlewares/cloudevents-middleware.d.ts

@@ -1,171 +0,0 @@
-/**
- * CloudEvents Middleware for Hono - Simplified Core
- *
- * Supports automatic handler discovery and manual registration.
- * Handles event validation, routing, and safeParse mode for graceful degradation.
- * Includes optional DLQ-Safe mode for Pub/Sub Push endpoints.
- */
-import type { Context } from 'hono';
-import type { HandlerConstructor } from '../domain';
-import { clearHandlerCache } from '../processing';
-/**
- * Configuration options for CloudEvents middleware
- *
- * @interface CloudEventsOptions
- */
-export interface CloudEventsOptions {
-    /**
-     * Directory path for automatic handler discovery
-     *
-     * @example './src/events' or './handlers'
-     * @default undefined
-     */
-    discover?: string;
-    /**
-     * Array of handler constructors for manual registration
-     *
-     * @example [CustomerCreatedHandler, OrderProcessedHandler]
-     * @default []
-     */
-    handlers?: HandlerConstructor[];
-    /**
-     * Logging configuration
-     *
-     * - `false`: No logging (production default)
-     * - `true`: Basic structured logging
-     * - `'pretty'`: Human-readable format (development)
-     * - `'structured'`: JSON format (production)
-     *
-     * @default false
-     */
-    log?: boolean | 'pretty' | 'structured';
-    /**
-     * Google Cloud Pub/Sub topic for quarantining invalid messages
-     *
-     * When specified, enables DLQ-Safe mode:
-     * - Always returns HTTP 204 to prevent redelivery
-     * - Quarantines validation errors and malformed events
-     * - Non-blocking background processing
-     *
-     * @example 'projects/my-project/topics/quarantine-topic'
-     * @default undefined
-     */
-    quarantineTopic?: string;
-    /**
-     * Google Cloud Pub/Sub topic for publishing recoverable handler errors
-     *
-     * Used in DLQ-Safe mode to publish errors that can be retried later:
-     * - Handler execution failures
-     * - Temporary processing errors
-     * - Network timeouts
-     *
-     * @example 'projects/my-project/topics/error-topic'
-     * @default undefined
-     */
-    errorTopic?: string;
-    /**
-     * Google Cloud Project ID
-     *
-     * @example 'my-production-project'
-     * @default Detected from environment (GOOGLE_CLOUD_PROJECT, etc.)
-     */
-    projectId?: string;
-    /**
-     * CloudEvent source identifier
-     *
-     * @example 'my-service' or 'https://my-domain.com/service'
-     * @default Auto-detected from environment
-     */
-    source?: string;
-    /**
-     * Set for message deduplication based on CloudEvent ID
-     *
-     * Automatically managed by the middleware to prevent duplicate processing.
-     * Can be provided for custom deduplication logic.
-     *
-     * @default new Set<string>()
-     */
-    processedMessageIds?: Set<string>;
-}
-export { clearHandlerCache };
-/**
- * CloudEvents middleware for Hono applications
- *
- * Provides automatic CloudEvent processing with handler discovery, validation,
- * and optional DLQ-Safe mode for Google Cloud Pub/Sub Push endpoints.
- *
- * @example
- * ```typescript
- * import { Hono } from 'hono'
- * import { cloudEvents } from '@orderboss/cloudevents'
- *
- * const app = new Hono()
- *
- * // Basic usage with handler discovery
- * app.use('*', cloudEvents({
- *   discover: './src/events/*.event.{ts,js}',
- *   log: true
- * }))
- *
- * // Manual handler registration
- * app.use('*', cloudEvents({
- *   handlers: [CustomerCreatedHandler, OrderProcessedHandler],
- *   log: 'pretty'
- * }))
- *
- * // DLQ-Safe mode for Pub/Sub Push
- * app.use('*', cloudEvents({
- *   discover: './src/events/*.event.{ts,js}',
- *   quarantineTopic: 'quarantine-topic',
- *   errorTopic: 'error-topic',
- *   projectId: 'my-project',
- *   log: 'structured'
- * }))
- * ```
- *
- * @param options - Configuration options for the middleware
- * @param options.discover - Directory path for automatic handler discovery (e.g., './src/events')
- * @param options.handlers - Array of handler constructors for manual registration
- * @param options.log - Enable logging: false (default), true, 'pretty' (dev), or 'structured' (prod)
- * @param options.quarantineTopic - Pub/Sub topic for quarantining invalid messages (enables DLQ-Safe mode)
- * @param options.errorTopic - Pub/Sub topic for publishing recoverable handler errors
- * @param options.projectId - Google Cloud Project ID (defaults to environment detection)
- * @param options.source - CloudEvent source identifier (defaults to auto-detection)
- * @param options.processedMessageIds - Set for message deduplication (automatically managed)
- *
- * @returns Hono middleware function that processes CloudEvents
- *
- * @remarks
- * **Handler Discovery:**
- * - Automatically discovers handlers in the specified directory
- * - Handlers must export a class that extends the base handler pattern
- * - Supports nested directories and TypeScript files
- *
- * **Event Format Support:**
- * - CloudEvents Structured mode (JSON with specversion)
- * - CloudEvents Binary mode (headers + data)
- * - Google Pub/Sub Push format
- * - Raw event data (wrapped in CloudEvent)
- *
- * **DLQ-Safe Mode:**
- * - Activated when `quarantineTopic` is specified
- * - Always returns HTTP 204 to prevent Pub/Sub redelivery
- * - Quarantines invalid messages to specified topic
- * - Publishes handler errors to error topic
- * - All DLQ operations are non-blocking for optimal performance
- *
- * **Standard Mode:**
- * - Returns HTTP 200 for successful processing
- * - Returns HTTP 422 for validation errors
- * - Returns HTTP 500 for handler errors
- * - Allows Pub/Sub DLQ behavior for unhandled errors
- *
- * **Performance Features:**
- * - Handler caching for improved startup time
- * - Dynamic parser loading for optimal bundle size
- * - Message deduplication based on CloudEvent ID
- * - Background processing for DLQ operations
- *
- * @since 1.0.0
- */
-export declare function cloudEvents(options?: CloudEventsOptions): (ctx: Context, next: () => Promise<void>) => Promise<void | Response>;

package/dist/middlewares/cloudevents-middleware.js

@@ -1,276 +0,0 @@
-import { parseEventFromContext } from '../adapters/cloudevents';
-import { handleErrorWithContext, logger } from '../infrastructure';
-import { addProcessedMessage, clearHandlerCache, createCacheKey, createProcessingContext, getCachedHandlers, isDlqSafeMode, isHandlerMatching, publishRecoverableError, quarantineMessage, setupHandlers, throwValidationError, validateEventData, } from '../processing';
-// Export clearHandlerCache for testing
-export { clearHandlerCache };
-/**
- * Logs middleware initialization status
- */
-const logInitialization = (options, log) => {
-    if (isDlqSafeMode(options)) {
-        const quarantine = options.quarantineTopic || 'not configured';
-        const errorTopic = options.errorTopic || 'not configured';
-        const projectId = options.projectId || 'default';
-        const source = options.source || 'auto-detected';
-        if (log === 'pretty') {
-            logger.info('DLQ-Safe mode enabled');
-            logger.info(`  • Quarantine topic: ${quarantine}`);
-            logger.info(`  • Error topic: ${errorTopic}`);
-            logger.info(`  • Project ID: ${projectId}`);
-            logger.info(`  • Source: ${source}`);
-        }
-        else {
-            logger.info('CloudEvents middleware initialized', {
-                mode: 'DLQ-Safe',
-                quarantineTopic: quarantine,
-                errorTopic: errorTopic,
-                projectId: projectId,
-                source: source,
-            });
-        }
-    }
-    else {
-        if (log === 'pretty') {
-            logger.info('DLQ-Safe mode disabled - using standard error handling');
-        }
-        else {
-            logger.info('CloudEvents middleware initialized', {
-                mode: 'Standard',
-                note: 'Using standard error handling',
-            });
-        }
-    }
-};
-/**
- * Executes a single handler with error handling
- */
-const executeHandler = async (handler, eventData, context) => {
-    try {
-        await handler.handle(eventData, context);
-    }
-    catch (error) {
-        logger.error(`Handler execution failed for ${handler.name}:`, error);
-        throw error;
-    }
-};
-/**
- * Processes handlers in DLQ-safe or standard mode
- */
-const processHandlerSafely = async (handler, eventData, ctx, processingContext, options) => {
-    const validationResult = validateEventData(handler, eventData);
-    if ('error' in validationResult) {
-        if (validationResult.shouldSkip) {
-            return; // Skip this handler in safeParse mode
-        }
-        if (isDlqSafeMode(options)) {
-            // Non-blocking quarantine - don't wait for DLQ publishing
-            queueMicrotask(() => {
-                quarantineMessage(processingContext, 'validation_error', options, validationResult.error).catch((error) => {
-                    logger.error('Failed to quarantine validation error:', error);
-                });
-            });
-            return;
-        }
-        throwValidationError(handler.name, validationResult.error);
-    }
-    // Execute handler
-    try {
-        await executeHandler(handler, eventData, ctx);
-    }
-    catch (error) {
-        if (isDlqSafeMode(options)) {
-            // Non-blocking error publishing - don't wait for DLQ publishing
-            queueMicrotask(() => {
-                publishRecoverableError(processingContext, error, options).catch((publishError) => {
-                    logger.error('Failed to publish recoverable error:', publishError);
-                });
-            });
-            return;
-        }
-        throw error;
-    }
-};
-/**
- * Executes all matching handlers for an event
- */
-const executeMatchingHandlers = async (handlers, eventType, eventData, ctx, processingContext, options) => {
-    const matchingHandlers = handlers.filter(isHandlerMatching(eventType, eventData, ctx));
-    if (matchingHandlers.length === 0) {
-        const errorMessage = `No handlers found for event type: ${eventType}`;
-        if (isDlqSafeMode(options)) {
-            // Non-blocking quarantine - don't wait for DLQ publishing
-            queueMicrotask(() => {
-                quarantineMessage(processingContext, 'no_handler', options, new Error(errorMessage)).catch((error) => {
-                    logger.error('Failed to quarantine no_handler error:', error);
-                });
-            });
-            return;
-        }
-        throw new Error(errorMessage);
-    }
-    // Process all matching handlers
-    await Promise.all(matchingHandlers.map((handler) => processHandlerSafely(handler, eventData, ctx, processingContext, options)));
-};
-/**
- * Main CloudEvent processing function
- */
-const processCloudEvent = async (ctx, options) => {
-    const cacheKey = createCacheKey(options.discover, options.handlers);
-    const handlers = getCachedHandlers(cacheKey);
-    try {
-        const { event, cloudEventData } = await parseEventFromContext(ctx);
-        // Use cloudEventData as primary source, fallback to event
-        const eventData = cloudEventData || event;
-        if (!eventData) {
-            throw new Error('Failed to parse CloudEvent from request');
-        }
-        const eventType = eventData.type;
-        const eventPayload = eventData.data;
-        const context = cloudEventData || {};
-        const messageId = eventData.id || 'unknown';
-        // Deduplication check
-        const dedupeSet = options.processedMessageIds || new Set();
-        if (dedupeSet.has(messageId)) {
-            logger.info(`Duplicate message ${messageId} detected, skipping processing`);
-            return ctx.json({ status: 'duplicate', messageId }, 200);
-        }
-        addProcessedMessage(messageId);
-        dedupeSet.add(messageId);
-        const processingContext = createProcessingContext(eventType, eventPayload, context, event || eventData);
-        if (options.log) {
-            logger.info(`Processing event type: ${eventType}`);
-        }
-        // Execute handlers
-        await executeMatchingHandlers(handlers, eventType, eventPayload, context, processingContext, options);
-        // Return success response
-        return isDlqSafeMode(options)
-            ? ctx.body(null, 204) // Always 204 in DLQ-safe mode
-            : ctx.json({ status: 'processed', eventType, messageId }, 200);
-    }
-    catch (error) {
-        // Handle ValidationError specifically
-        if (error && typeof error === 'object' && 'type' in error && error.type === 'ValidationError') {
-            return ctx.json({ error }, 422);
-        }
-        handleErrorWithContext(error, ctx, { isDlqSafe: isDlqSafeMode(options) });
-        return ctx.json({ error: 'Internal Server Error' }, 500);
-    }
-};
-/**
- * CloudEvents middleware for Hono applications
- *
- * Provides automatic CloudEvent processing with handler discovery, validation,
- * and optional DLQ-Safe mode for Google Cloud Pub/Sub Push endpoints.
- *
- * @example
- * ```typescript
- * import { Hono } from 'hono'
- * import { cloudEvents } from '@orderboss/cloudevents'
- *
- * const app = new Hono()
- *
- * // Basic usage with handler discovery
- * app.use('*', cloudEvents({
- *   discover: './src/events/*.event.{ts,js}',
- *   log: true
- * }))
- *
- * // Manual handler registration
- * app.use('*', cloudEvents({
- *   handlers: [CustomerCreatedHandler, OrderProcessedHandler],
- *   log: 'pretty'
- * }))
- *
- * // DLQ-Safe mode for Pub/Sub Push
- * app.use('*', cloudEvents({
- *   discover: './src/events/*.event.{ts,js}',
- *   quarantineTopic: 'quarantine-topic',
- *   errorTopic: 'error-topic',
- *   projectId: 'my-project',
- *   log: 'structured'
- * }))
- * ```
- *
- * @param options - Configuration options for the middleware
- * @param options.discover - Directory path for automatic handler discovery (e.g., './src/events')
- * @param options.handlers - Array of handler constructors for manual registration
- * @param options.log - Enable logging: false (default), true, 'pretty' (dev), or 'structured' (prod)
- * @param options.quarantineTopic - Pub/Sub topic for quarantining invalid messages (enables DLQ-Safe mode)
- * @param options.errorTopic - Pub/Sub topic for publishing recoverable handler errors
- * @param options.projectId - Google Cloud Project ID (defaults to environment detection)
- * @param options.source - CloudEvent source identifier (defaults to auto-detection)
- * @param options.processedMessageIds - Set for message deduplication (automatically managed)
- *
- * @returns Hono middleware function that processes CloudEvents
- *
- * @remarks
- * **Handler Discovery:**
- * - Automatically discovers handlers in the specified directory
- * - Handlers must export a class that extends the base handler pattern
- * - Supports nested directories and TypeScript files
- *
- * **Event Format Support:**
- * - CloudEvents Structured mode (JSON with specversion)
- * - CloudEvents Binary mode (headers + data)
- * - Google Pub/Sub Push format
- * - Raw event data (wrapped in CloudEvent)
- *
- * **DLQ-Safe Mode:**
- * - Activated when `quarantineTopic` is specified
- * - Always returns HTTP 204 to prevent Pub/Sub redelivery
- * - Quarantines invalid messages to specified topic
- * - Publishes handler errors to error topic
- * - All DLQ operations are non-blocking for optimal performance
- *
- * **Standard Mode:**
- * - Returns HTTP 200 for successful processing
- * - Returns HTTP 422 for validation errors
- * - Returns HTTP 500 for handler errors
- * - Allows Pub/Sub DLQ behavior for unhandled errors
- *
- * **Performance Features:**
- * - Handler caching for improved startup time
- * - Dynamic parser loading for optimal bundle size
- * - Message deduplication based on CloudEvent ID
- * - Background processing for DLQ operations
- *
- * @since 1.0.0
- */
-export function cloudEvents(options = {}) {
-    const { discover, handlers = [], log = false } = options;
-    const cacheKey = createCacheKey(discover, handlers);
-    // Setup handlers immediately when middleware is created
-    if (log) {
-        setupHandlers(cacheKey, discover, handlers, log)
-            // Log configuration status based on log format preference
-            .then(() => logInitialization(options, log))
-            .catch((error) => logger.error('Failed to setup handlers during initialization:', error));
-    }
-    return async (ctx, next) => {
-        if (ctx.req.method !== 'POST') {
-            return next();
-        }
-        await setupHandlers(cacheKey, discover, handlers, log);
-        try {
-            return await processCloudEvent(ctx, options);
-        }
-        catch (error) {
-            // In DLQ-safe mode, always return 204 to prevent DLQ
-            if (isDlqSafeMode(options)) {
-                logger.error('Error during request processing (DLQ-safe mode):', error);
-                queueMicrotask(async () => {
-                    try {
-                        const processingContext = createProcessingContext('unknown', null, null, null);
-                        await quarantineMessage(processingContext, 'processing_error', options, error);
-                    }
-                    catch (quarantineError) {
-                        const errorMessage = quarantineError instanceof Error ? quarantineError.message : 'Unknown error';
-                        logger.error(`Failed to quarantine error: ${errorMessage}`);
-                    }
-                });
-                return ctx.body(null, 204);
-            }
-            throw error;
-        }
-    };
-}

package/dist/middlewares/index.d.ts

@@ -1 +0,0 @@
-export { clearHandlerCache, cloudEvents } from './cloudevents-middleware';

package/dist/middlewares/index.js

@@ -1 +0,0 @@
-export { clearHandlerCache, cloudEvents } from './cloudevents-middleware';

package/dist/processing/dlq-safe.d.ts

@@ -1,82 +0,0 @@
-/**
- * DLQ-Safe mode utilities
- * Handles quarantine and error publishing for CloudEvents processing
- */
-/**
- * Reason codes for quarantined messages
- */
-export type QuarantineReason = 'parse_error' | 'no_handler' | 'validation_error' | 'unhandled_error' | 'processing_error';
-/**
- * Structure of messages published to the quarantine topic
- */
-export interface QuarantineMessage {
-    /** Original CloudEvent ID */
-    originalMessageId: string;
-    /** Original CloudEvent type */
-    originalEventType: string;
-    /** Original event data payload */
-    originalEventData: unknown;
-    /** Original event context/metadata */
-    originalEventContext: unknown;
-    /** Full original CloudEvent if available */
-    originalCloudEvent: unknown;
-    /** ISO timestamp when message was quarantined */
-    quarantinedAt: string;
-    /** Reason for quarantine */
-    quarantineReason: QuarantineReason;
-    /** Error message if applicable */
-    error?: string;
-}
-/**
- * Structure of messages published to the error topic (recoverable errors)
- */
-export interface ErrorMessage {
-    /** Original CloudEvent ID */
-    originalMessageId: string;
-    /** Original CloudEvent type */
-    originalEventType: string;
-    /** Original event data payload */
-    originalEventData: unknown;
-    /** Original event context/metadata */
-    originalEventContext: unknown;
-    /** Full original CloudEvent if available */
-    originalCloudEvent: unknown;
-    /** ISO timestamp when error occurred */
-    errorTimestamp: string;
-    /** Error details */
-    error: {
-        message: string;
-        stack?: string;
-        type: string;
-    };
-}
-export interface ProcessingContext {
-    messageId: string;
-    eventType: string;
-    eventData: unknown;
-    eventContext: unknown;
-    timestamp: string;
-    originalCloudEvent: unknown;
-}
-export interface DlqOptions {
-    quarantineTopic?: string;
-    errorTopic?: string;
-    projectId?: string;
-    source?: string;
-}
-/**
- * Checks if DLQ-Safe mode is enabled
- */
-export declare const isDlqSafeMode: (options: DlqOptions) => boolean;
-/**
- * Publishes a message to the quarantine topic for "poison messages" that can't be processed
- */
-export declare const quarantineMessage: (processingContext: ProcessingContext, reason: QuarantineReason, options: DlqOptions, error?: unknown) => Promise<void>;
-/**
- * Publishes recoverable processing errors to the error topic
- */
-export declare const publishRecoverableError: (processingContext: ProcessingContext, error: unknown, options: DlqOptions) => Promise<void>;
-/**
- * Creates processing context from event data
- */
-export declare const createProcessingContext: (eventType: string, eventData: unknown, context: unknown, originalCloudEvent: unknown) => ProcessingContext;