@zdavison/matador 2.0.1

package/dist/codec/rabbitmq-codec.js

@@ -0,0 +1,242 @@
+import { CodecDecodeError } from './codec.js';
+/**
+ * Header names used by Matador in RabbitMQ messages.
+ */
+const HEADERS = {
+    // Routing
+    EVENT_KEY: 'x-matador-event-key',
+    TARGET_SUBSCRIBER: 'x-matador-subscriber',
+    SCHEDULED_FOR: 'x-matador-scheduled-for',
+    ORIGINAL_QUEUE: 'x-matador-original-queue',
+    // Processing state
+    ATTEMPTS: 'x-matador-attempts',
+    CREATED_AT: 'x-matador-created-at',
+    FIRST_ERROR: 'x-matador-first-error',
+    LAST_ERROR: 'x-matador-last-error',
+    // Observability
+    IMPORTANCE: 'x-matador-importance',
+    CORRELATION_ID: 'x-matador-correlation-id',
+    // v1 compatibility headers
+    V1_EVENT_ID: 'x-event-id',
+    V1_CORRELATION_ID: 'x-correlation-id',
+    V1_USER_ID: 'x-user-id',
+};
+/**
+ * RabbitMQ-specific codec that stores routing/metadata in headers.
+ *
+ * Benefits:
+ * - No duplication between body and headers
+ * - RabbitMQ can route/filter based on headers
+ * - Smaller message body
+ * - v1 message format compatibility built-in
+ */
+export class RabbitMQCodec {
+    contentType = 'application/json';
+    encode(envelope) {
+        const { docket } = envelope;
+        // Body only contains id, data, and metadata (since metadata can be large)
+        const body = {
+            id: envelope.id,
+            data: envelope.data,
+            ...(docket.metadata !== undefined && { metadata: docket.metadata }),
+        };
+        // All docket fields go in headers
+        const headers = {
+            // Routing
+            [HEADERS.EVENT_KEY]: docket.eventKey,
+            [HEADERS.TARGET_SUBSCRIBER]: docket.targetSubscriber,
+            // Processing state
+            [HEADERS.ATTEMPTS]: docket.attempts,
+            [HEADERS.CREATED_AT]: docket.createdAt,
+            // Observability
+            [HEADERS.IMPORTANCE]: docket.importance,
+        };
+        // Optional fields
+        if (docket.scheduledFor !== undefined) {
+            headers[HEADERS.SCHEDULED_FOR] = docket.scheduledFor;
+        }
+        if (docket.originalQueue !== undefined) {
+            headers[HEADERS.ORIGINAL_QUEUE] = docket.originalQueue;
+        }
+        if (docket.firstError !== undefined) {
+            headers[HEADERS.FIRST_ERROR] = docket.firstError;
+        }
+        if (docket.lastError !== undefined) {
+            headers[HEADERS.LAST_ERROR] = docket.lastError;
+        }
+        if (docket.correlationId !== undefined) {
+            headers[HEADERS.CORRELATION_ID] = docket.correlationId;
+        }
+        return {
+            body: new TextEncoder().encode(JSON.stringify(body)),
+            headers,
+            contentType: this.contentType,
+        };
+    }
+    decode(body, headers) {
+        if (body.length === 0) {
+            throw new CodecDecodeError('Cannot decode empty buffer');
+        }
+        let json;
+        try {
+            json = new TextDecoder('utf-8').decode(body);
+        }
+        catch (error) {
+            throw new CodecDecodeError('Invalid UTF-8 encoding', error);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
+        }
+        catch (error) {
+            throw new CodecDecodeError('Invalid JSON', error);
+        }
+        // Detect format: v1 has 'key' and 'targetSubscriber' at top level
+        if (this.isV1Body(parsed)) {
+            return this.decodeV1(parsed, headers);
+        }
+        // v2 format
+        if (!this.isV2Body(parsed)) {
+            throw new CodecDecodeError('Invalid message body structure');
+        }
+        return this.decodeV2(parsed, headers);
+    }
+    isV1Body(value) {
+        if (typeof value !== 'object' || value === null)
+            return false;
+        const obj = value;
+        return (typeof obj['key'] === 'string' &&
+            typeof obj['targetSubscriber'] === 'string' &&
+            'data' in obj &&
+            !('payload' in obj));
+    }
+    isV2Body(value) {
+        if (typeof value !== 'object' || value === null)
+            return false;
+        const obj = value;
+        return (typeof obj['id'] === 'string' && 'data' in obj && !('key' in obj) // Distinguish from v1 which also has 'data'
+        );
+    }
+    decodeV2(body, headers) {
+        // Required headers
+        const eventKey = this.requireStringHeader(headers, HEADERS.EVENT_KEY);
+        const targetSubscriber = this.requireStringHeader(headers, HEADERS.TARGET_SUBSCRIBER);
+        const attempts = this.requireNumberHeader(headers, HEADERS.ATTEMPTS);
+        const createdAt = this.requireStringHeader(headers, HEADERS.CREATED_AT);
+        const importance = this.requireStringHeader(headers, HEADERS.IMPORTANCE);
+        // Optional headers
+        const scheduledFor = this.optionalStringHeader(headers, HEADERS.SCHEDULED_FOR);
+        const originalQueue = this.optionalStringHeader(headers, HEADERS.ORIGINAL_QUEUE);
+        const firstError = this.optionalStringHeader(headers, HEADERS.FIRST_ERROR);
+        const lastError = this.optionalStringHeader(headers, HEADERS.LAST_ERROR);
+        const correlationId = this.optionalStringHeader(headers, HEADERS.CORRELATION_ID);
+        const docket = {
+            // Routing
+            eventKey,
+            targetSubscriber,
+            ...(scheduledFor !== undefined && { scheduledFor }),
+            ...(originalQueue !== undefined && { originalQueue }),
+            // Processing state
+            attempts,
+            createdAt,
+            ...(firstError !== undefined && { firstError }),
+            ...(lastError !== undefined && { lastError }),
+            // Observability
+            importance: importance,
+            ...(correlationId !== undefined && { correlationId }),
+            ...(body.metadata !== undefined && { metadata: body.metadata }),
+        };
+        return {
+            id: body.id,
+            data: body.data,
+            docket,
+        };
+    }
+    /**
+     * Decodes a v1 format message for backwards compatibility.
+     * v1 format: { key, data, metadata, universal, targetSubscriber, ... }
+     */
+    decodeV1(body, headers) {
+        const { event_id, user_id, correlation_id, ...otherUniversal } = body.universal ?? {};
+        // Merge metadata: event metadata + remaining universal fields
+        const mergedMetadata = {};
+        if (body.metadata && typeof body.metadata === 'object') {
+            Object.assign(mergedMetadata, body.metadata);
+        }
+        if (user_id !== undefined && user_id !== null) {
+            mergedMetadata['user_id'] = user_id;
+        }
+        Object.assign(mergedMetadata, otherUniversal);
+        // Try to get attempts from header (v1 also uses x-matador-attempts)
+        const attempts = typeof headers[HEADERS.ATTEMPTS] === 'number'
+            ? headers[HEADERS.ATTEMPTS]
+            : 1;
+        // Try to get importance from header
+        const importance = typeof headers[HEADERS.IMPORTANCE] === 'string'
+            ? headers[HEADERS.IMPORTANCE]
+            : 'should-investigate';
+        // Get correlation ID from either v1 or v2 header
+        const correlationId = headers[HEADERS.CORRELATION_ID] ??
+            headers[HEADERS.V1_CORRELATION_ID] ??
+            correlation_id ??
+            undefined;
+        // Get event ID from v1 header or body
+        const eventId = headers[HEADERS.V1_EVENT_ID] ??
+            event_id ??
+            crypto.randomUUID();
+        const now = new Date().toISOString();
+        // Calculate scheduledFor if delayMs was specified (though it's likely already passed)
+        let scheduledFor;
+        if (body.options?.delayMs) {
+            scheduledFor = new Date(Date.now() + body.options.delayMs).toISOString();
+        }
+        const docket = {
+            // Routing
+            eventKey: body.key,
+            targetSubscriber: body.targetSubscriber,
+            ...(scheduledFor !== undefined && { scheduledFor }),
+            // Processing state
+            attempts,
+            createdAt: now,
+            // Observability
+            importance: importance,
+            ...(correlationId !== undefined && { correlationId }),
+            ...(Object.keys(mergedMetadata).length > 0 && {
+                metadata: mergedMetadata,
+            }),
+        };
+        return {
+            id: eventId,
+            data: body.data,
+            docket,
+        };
+    }
+    requireStringHeader(headers, name) {
+        const value = headers[name];
+        if (value === undefined) {
+            throw new CodecDecodeError(`Missing required header: ${name}`);
+        }
+        if (typeof value !== 'string') {
+            throw new CodecDecodeError(`Header ${name} must be string, got ${typeof value}`);
+        }
+        return value;
+    }
+    requireNumberHeader(headers, name) {
+        const value = headers[name];
+        if (value === undefined) {
+            throw new CodecDecodeError(`Missing required header: ${name}`);
+        }
+        if (typeof value !== 'number') {
+            throw new CodecDecodeError(`Header ${name} must be number, got ${typeof value}`);
+        }
+        return value;
+    }
+    optionalStringHeader(headers, name) {
+        const value = headers[name];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'string')
+            return undefined;
+        return value;
+    }
+}

package/dist/codec/rabbitmq-codec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rabbitmq-codec.test.d.ts.map

package/dist/codec/rabbitmq-codec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rabbitmq-codec.test.d.ts","sourceRoot":"","sources":["../../src/codec/rabbitmq-codec.test.ts"],"names":[],"mappings":""}

package/dist/codec/rabbitmq-codec.test.js

@@ -0,0 +1,433 @@
+import { describe, expect, it } from 'bun:test';
+import { RabbitMQCodec } from './rabbitmq-codec.js';
+/**
+ * Add your v1 message examples here.
+ * Each fixture describes:
+ * - name: A descriptive name for the test case
+ * - body: The v1 message body (what goes in the RabbitMQ message content)
+ * - headers: Optional RabbitMQ headers that accompany the message
+ * - expected: The expected v2 envelope fields after translation
+ */
+const V1_MESSAGE_FIXTURES = [
+    // === BASIC EXAMPLES ===
+    {
+        name: 'minimal v1 message with only required fields',
+        body: {
+            key: 'user.created',
+            data: { userId: '123' },
+            targetSubscriber: 'email-service',
+        },
+        expected: {
+            eventKey: 'user.created',
+            targetSubscriber: 'email-service',
+            data: { userId: '123' },
+            attempts: 1,
+            importance: 'should-investigate',
+        },
+    },
+    {
+        name: 'v1 message with metadata',
+        body: {
+            key: 'order.placed',
+            data: { orderId: 'ORD-456', amount: 99.99 },
+            metadata: { source: 'web', region: 'us-east' },
+            targetSubscriber: 'fulfillment-service',
+        },
+        expected: {
+            eventKey: 'order.placed',
+            targetSubscriber: 'fulfillment-service',
+            data: { orderId: 'ORD-456', amount: 99.99 },
+            metadata: { source: 'web', region: 'us-east' },
+        },
+    },
+    // === UNIVERSAL METADATA EXAMPLES ===
+    {
+        name: 'v1 message with universal.event_id',
+        body: {
+            key: 'payment.processed',
+            data: { paymentId: 'PAY-789' },
+            universal: {
+                event_id: 'evt-abc-123',
+            },
+            targetSubscriber: 'notification-service',
+        },
+        expected: {
+            id: 'evt-abc-123',
+            eventKey: 'payment.processed',
+            targetSubscriber: 'notification-service',
+            data: { paymentId: 'PAY-789' },
+        },
+    },
+    {
+        name: 'v1 message with universal.user_id (merged into metadata)',
+        body: {
+            key: 'profile.updated',
+            data: { field: 'email' },
+            universal: {
+                user_id: 'user-456',
+            },
+            targetSubscriber: 'audit-service',
+        },
+        expected: {
+            eventKey: 'profile.updated',
+            targetSubscriber: 'audit-service',
+            data: { field: 'email' },
+            metadata: { user_id: 'user-456' },
+        },
+    },
+    {
+        name: 'v1 message with universal.correlation_id',
+        body: {
+            key: 'request.received',
+            data: { requestId: 'req-001' },
+            universal: {
+                correlation_id: 'corr-xyz-789',
+            },
+            targetSubscriber: 'logger-service',
+        },
+        expected: {
+            eventKey: 'request.received',
+            targetSubscriber: 'logger-service',
+            data: { requestId: 'req-001' },
+            correlationId: 'corr-xyz-789',
+        },
+    },
+    {
+        name: 'v1 message with all universal fields',
+        body: {
+            key: 'checkout.completed',
+            data: { cartId: 'cart-999' },
+            universal: {
+                event_id: 'evt-full-123',
+                user_id: 'user-777',
+                correlation_id: 'corr-full-456',
+                custom_field: 'custom_value',
+            },
+            targetSubscriber: 'analytics-service',
+        },
+        expected: {
+            id: 'evt-full-123',
+            eventKey: 'checkout.completed',
+            targetSubscriber: 'analytics-service',
+            data: { cartId: 'cart-999' },
+            correlationId: 'corr-full-456',
+            metadata: {
+                user_id: 'user-777',
+                custom_field: 'custom_value',
+            },
+        },
+    },
+    // === METADATA MERGING EXAMPLES ===
+    {
+        name: 'v1 message with both metadata and universal (merged)',
+        body: {
+            key: 'item.added',
+            data: { itemId: 'item-123' },
+            metadata: { category: 'electronics', priority: 'high' },
+            universal: {
+                user_id: 'user-888',
+                tenant_id: 'tenant-001',
+            },
+            targetSubscriber: 'inventory-service',
+        },
+        expected: {
+            eventKey: 'item.added',
+            targetSubscriber: 'inventory-service',
+            data: { itemId: 'item-123' },
+            metadata: {
+                category: 'electronics',
+                priority: 'high',
+                user_id: 'user-888',
+                tenant_id: 'tenant-001',
+            },
+        },
+    },
+    // === HEADER-BASED EXAMPLES ===
+    {
+        name: 'v1 message with attempt count from header',
+        body: {
+            key: 'task.retry',
+            data: { taskId: 'task-555' },
+            targetSubscriber: 'worker-service',
+        },
+        headers: {
+            'x-matador-attempts': 3,
+        },
+        expected: {
+            eventKey: 'task.retry',
+            targetSubscriber: 'worker-service',
+            data: { taskId: 'task-555' },
+            attempts: 3,
+        },
+    },
+    {
+        name: 'v1 message with importance from header',
+        body: {
+            key: 'alert.triggered',
+            data: { alertId: 'alert-111' },
+            targetSubscriber: 'pager-service',
+        },
+        headers: {
+            'x-matador-importance': 'must-investigate',
+        },
+        expected: {
+            eventKey: 'alert.triggered',
+            targetSubscriber: 'pager-service',
+            data: { alertId: 'alert-111' },
+            importance: 'must-investigate',
+        },
+    },
+    {
+        name: 'v1 message with correlation_id from v1 header',
+        body: {
+            key: 'trace.event',
+            data: { traceId: 'trace-222' },
+            targetSubscriber: 'tracing-service',
+        },
+        headers: {
+            'x-correlation-id': 'header-corr-id',
+        },
+        expected: {
+            eventKey: 'trace.event',
+            targetSubscriber: 'tracing-service',
+            data: { traceId: 'trace-222' },
+            correlationId: 'header-corr-id',
+        },
+    },
+    {
+        name: 'v1 message with event_id from v1 header',
+        body: {
+            key: 'legacy.event',
+            data: { legacyId: 'leg-333' },
+            targetSubscriber: 'legacy-handler',
+        },
+        headers: {
+            'x-event-id': 'header-event-id-456',
+        },
+        expected: {
+            id: 'header-event-id-456',
+            eventKey: 'legacy.event',
+            targetSubscriber: 'legacy-handler',
+            data: { legacyId: 'leg-333' },
+        },
+    },
+    // === EDGE CASES ===
+    {
+        name: 'v1 message with null universal fields (ignored)',
+        body: {
+            key: 'null.test',
+            data: { test: true },
+            universal: {
+                event_id: null,
+                user_id: null,
+                correlation_id: null,
+            },
+            targetSubscriber: 'null-handler',
+        },
+        expected: {
+            eventKey: 'null.test',
+            targetSubscriber: 'null-handler',
+            data: { test: true },
+        },
+    },
+    {
+        name: 'v1 message with empty metadata object',
+        body: {
+            key: 'empty.metadata',
+            data: { value: 42 },
+            metadata: {},
+            targetSubscriber: 'empty-handler',
+        },
+        expected: {
+            eventKey: 'empty.metadata',
+            targetSubscriber: 'empty-handler',
+            data: { value: 42 },
+        },
+    },
+    {
+        name: 'v1 message with complex nested data',
+        body: {
+            key: 'complex.event',
+            data: {
+                nested: {
+                    deeply: {
+                        value: [1, 2, { three: 'four' }],
+                    },
+                },
+                array: ['a', 'b', 'c'],
+            },
+            targetSubscriber: 'complex-handler',
+        },
+        expected: {
+            eventKey: 'complex.event',
+            targetSubscriber: 'complex-handler',
+            data: {
+                nested: {
+                    deeply: {
+                        value: [1, 2, { three: 'four' }],
+                    },
+                },
+                array: ['a', 'b', 'c'],
+            },
+        },
+    },
+    {
+        name: 'v1 message with before field (ignored in v2)',
+        body: {
+            key: 'update.event',
+            data: { newValue: 'after' },
+            before: { oldValue: 'before' },
+            targetSubscriber: 'update-handler',
+        },
+        expected: {
+            eventKey: 'update.event',
+            targetSubscriber: 'update-handler',
+            data: { newValue: 'after' },
+        },
+    },
+    // === ADD YOUR EXAMPLES BELOW ===
+    // Copy this template and fill in your v1 message data:
+    //
+    // {
+    //   name: 'descriptive name for your test case',
+    //   body: {
+    //     key: 'your.event.key',
+    //     data: { /* your event data */ },
+    //     metadata: { /* optional metadata */ },
+    //     universal: {
+    //       event_id: 'optional-event-id',
+    //       user_id: 'optional-user-id',
+    //       correlation_id: 'optional-correlation-id',
+    //       // any other custom fields
+    //     },
+    //     before: { /* optional, will be ignored */ },
+    //     options: { delayMs: 1000 }, // optional
+    //     targetSubscriber: 'your-subscriber-name',
+    //   },
+    //   headers: {
+    //     // optional headers
+    //     'x-matador-attempts': 1,
+    //     'x-matador-importance': 'should-investigate',
+    //     'x-event-id': 'header-event-id',
+    //     'x-correlation-id': 'header-correlation-id',
+    //   },
+    //   expected: {
+    //     id: 'expected-id', // optional, will be generated if not in body/headers
+    //     eventKey: 'your.event.key',
+    //     targetSubscriber: 'your-subscriber-name',
+    //     data: { /* expected data */ },
+    //     metadata: { /* expected merged metadata */ },
+    //     correlationId: 'expected-correlation-id',
+    //     attempts: 1,
+    //     importance: 'should-investigate',
+    //   },
+    // },
+];
+describe('RabbitMQCodec', () => {
+    const codec = new RabbitMQCodec();
+    describe('v1 to v2 translation', () => {
+        for (const fixture of V1_MESSAGE_FIXTURES) {
+            it(`should translate: ${fixture.name}`, () => {
+                const body = new TextEncoder().encode(JSON.stringify(fixture.body));
+                const headers = fixture.headers ?? {};
+                const envelope = codec.decode(body, headers);
+                // Check required fields
+                expect(envelope.docket.eventKey).toBe(fixture.expected.eventKey);
+                expect(envelope.docket.targetSubscriber).toBe(fixture.expected.targetSubscriber);
+                expect(envelope.data).toEqual(fixture.expected.data);
+                // Check optional ID (may be generated if not specified)
+                if (fixture.expected.id !== undefined) {
+                    expect(envelope.id).toBe(fixture.expected.id);
+                }
+                else {
+                    expect(envelope.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+                }
+                // Check metadata
+                if (fixture.expected.metadata !== undefined) {
+                    expect(envelope.docket.metadata).toEqual(fixture.expected.metadata);
+                }
+                else {
+                    expect(envelope.docket.metadata === undefined ||
+                        Object.keys(envelope.docket.metadata).length === 0).toBe(true);
+                }
+                // Check correlation ID
+                if (fixture.expected.correlationId !== undefined) {
+                    expect(envelope.docket.correlationId).toBe(fixture.expected.correlationId);
+                }
+                // Check attempts (defaults to 1)
+                if (fixture.expected.attempts !== undefined) {
+                    expect(envelope.docket.attempts).toBe(fixture.expected.attempts);
+                }
+                else {
+                    expect(envelope.docket.attempts).toBe(1);
+                }
+                // Check importance (defaults to 'should-investigate')
+                if (fixture.expected.importance !== undefined) {
+                    expect(envelope.docket.importance).toBe(fixture.expected.importance);
+                }
+                else {
+                    expect(envelope.docket.importance).toBe('should-investigate');
+                }
+                // Check createdAt is a valid ISO string
+                expect(envelope.docket.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/);
+            });
+        }
+    });
+    describe('v1 edge cases', () => {
+        it('should handle options.delayMs by setting scheduledFor', () => {
+            const body = {
+                key: 'delayed.event',
+                data: { test: true },
+                options: { delayMs: 5000 },
+                targetSubscriber: 'delay-handler',
+            };
+            const encoded = new TextEncoder().encode(JSON.stringify(body));
+            const before = Date.now();
+            const envelope = codec.decode(encoded, {});
+            const after = Date.now();
+            expect(envelope.docket.scheduledFor).toBeDefined();
+            const scheduledTime = new Date(envelope.docket.scheduledFor).getTime();
+            expect(scheduledTime).toBeGreaterThanOrEqual(before + 5000);
+            expect(scheduledTime).toBeLessThanOrEqual(after + 5000);
+        });
+        it('should prefer header event_id over body universal.event_id', () => {
+            const body = {
+                key: 'priority.test',
+                data: {},
+                universal: { event_id: 'body-event-id' },
+                targetSubscriber: 'test-handler',
+            };
+            const encoded = new TextEncoder().encode(JSON.stringify(body));
+            const envelope = codec.decode(encoded, {
+                'x-event-id': 'header-event-id',
+            });
+            expect(envelope.id).toBe('header-event-id');
+        });
+        it('should prefer v2 correlation header over v1 header', () => {
+            const body = {
+                key: 'corr.priority',
+                data: {},
+                targetSubscriber: 'test-handler',
+            };
+            const encoded = new TextEncoder().encode(JSON.stringify(body));
+            const envelope = codec.decode(encoded, {
+                'x-matador-correlation-id': 'v2-corr-id',
+                'x-correlation-id': 'v1-corr-id',
+            });
+            expect(envelope.docket.correlationId).toBe('v2-corr-id');
+        });
+        it('should prefer header correlation_id over body universal.correlation_id', () => {
+            const body = {
+                key: 'corr.priority',
+                data: {},
+                universal: { correlation_id: 'body-corr-id' },
+                targetSubscriber: 'test-handler',
+            };
+            const encoded = new TextEncoder().encode(JSON.stringify(body));
+            const envelope = codec.decode(encoded, {
+                'x-correlation-id': 'header-corr-id',
+            });
+            expect(envelope.docket.correlationId).toBe('header-corr-id');
+        });
+    });
+});