@cratis/chronicle 6.49.0 → 6.51.0

package/webhooks/for_Webhooks/against_a_kernel/given/WebhookReceiver.fixture.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { ReceivedWebhookRequest } from './ReceivedWebhookRequest.fixture.js';
+
+/**
+ * The host name the kernel container uses to reach this process. Docker Desktop resolves
+ * host.docker.internal natively; on Linux (CI) the kernel container maps it to the host gateway
+ * (--add-host=host.docker.internal:host-gateway, see .github/workflows/build.yml).
+ * Override with CHRONICLE_INTEGRATION_WEBHOOK_HOST when the kernel reaches this process differently.
+ */
+const receiverHost = process.env.CHRONICLE_INTEGRATION_WEBHOOK_HOST ?? 'host.docker.internal';
+
+/**
+ * A local HTTP endpoint the kernel delivers webhook requests to. It records every request and
+ * answers each with a fixed status code.
+ */
+export class WebhookReceiver {
+    private readonly _requests: ReceivedWebhookRequest[] = [];
+    private _server: Server | undefined;
+    private _port = 0;
+
+    /**
+     * Initializes a new instance of the {@link WebhookReceiver} class.
+     * @param _statusCode - The status code to answer every request with.
+     */
+    constructor(private readonly _statusCode: number) {}
+
+    /** Gets the requests received so far, in arrival order. */
+    get requests(): ReadonlyArray<ReceivedWebhookRequest> {
+        return this._requests;
+    }
+
+    /**
+     * Starts listening on all interfaces on a free port, so a kernel container can reach it.
+     */
+    async start(): Promise<void> {
+        const server = createServer((request, response) => {
+            const chunks: Buffer[] = [];
+            request.on('data', (chunk: Buffer) => chunks.push(chunk));
+            request.on('end', () => {
+                this._requests.push({
+                    method: request.method ?? '',
+                    path: request.url ?? '',
+                    headers: request.headers,
+                    body: Buffer.concat(chunks).toString('utf8')
+                });
+                response.statusCode = this._statusCode;
+                response.end();
+            });
+        });
+        await new Promise<void>((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '0.0.0.0', () => resolve());
+        });
+        this._server = server;
+        this._port = (server.address() as AddressInfo).port;
+    }
+
+    /**
+     * Gets the URL the kernel should deliver to for the given path.
+     * @param path - The path, starting with a slash.
+     * @returns The URL as seen from the kernel.
+     */
+    urlFor(path: string): string {
+        return `http://${receiverHost}:${this._port}${path}`;
+    }
+
+    /**
+     * Waits until at least the given number of requests have arrived.
+     * @param count - The number of requests to wait for.
+     * @param timeoutMs - How long to wait before failing.
+     * @returns The requests received.
+     */
+    async waitForRequests(count: number, timeoutMs = 30_000): Promise<ReadonlyArray<ReceivedWebhookRequest>> {
+        const deadline = Date.now() + timeoutMs;
+        while (this._requests.length < count) {
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for ${count} webhook request(s); received ${this._requests.length}. ` +
+                    `Is ${receiverHost} reachable from the kernel?`);
+            }
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        return this._requests;
+    }
+
+    /**
+     * Stops listening.
+     */
+    async stop(): Promise<void> {
+        const server = this._server;
+        if (!server) return;
+        this._server = undefined;
+        server.closeAllConnections();
+        await new Promise<void>(resolve => server.close(() => resolve()));
+    }
+}

package/webhooks/for_Webhooks/against_a_kernel/when_delivering_events_to_a_failing_webhook.integration.spec.ts

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import type { FailedPartition, ObserverInformation } from '../../../observation/index.js';
+import { WebhookReceiver } from './given/WebhookReceiver.fixture.js';
+
+chai.should();
+
+// Runs against a real Chronicle kernel; skipped locally unless the connection string is set (see vitest.integration.config.ts).
+// In CI it never skips, so a missing connection string or unreachable kernel fails instead of passing vacuously.
+// The kernel must reach this process over HTTP; see WebhookReceiver for the address it uses.
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class ParcelLost {
+    @field(String) parcelId = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ParcelLost],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 30_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when delivering events to a failing webhook against a kernel', () => {
+    const webhookId = randomUUID();
+    const eventSourceId = randomUUID();
+    const receiver = new WebhookReceiver(500);
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let appendedSequenceNumber: bigint;
+    let failedPartition: FailedPartition;
+    let observer: ObserverInformation | undefined;
+
+    beforeAll(async () => {
+        await receiver.start();
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(`Webhooks${randomUUID().replaceAll('-', '').slice(0, 12)}`);
+
+        await store.webhooks.register(webhookId, receiver.urlFor('/parcels'), _ => _.withEventType(ParcelLost));
+
+        const parcel = new ParcelLost();
+        parcel.parcelId = randomUUID();
+        appendedSequenceNumber = (await store.eventLog.append(eventSourceId, parcel)).sequenceNumber.value;
+
+        await receiver.waitForRequests(1);
+        const failed = await eventually(
+            () => store.failedPartitions.getFailedPartitionsFor(webhookId),
+            _ => _.some(partition => partition.partition === eventSourceId));
+        failedPartition = failed.find(_ => _.partition === eventSourceId)!;
+        observer = (await store.observers.getAll()).find(_ => _.id === webhookId);
+    });
+
+    afterAll(async () => {
+        try {
+            await store?.webhooks.remove(webhookId);
+        } finally {
+            try {
+                await receiver.stop();
+            } finally {
+                client?.dispose();
+            }
+        }
+    });
+
+    it('should have attempted the delivery', () => receiver.requests.length.should.be.greaterThan(0));
+    it('should record the attempt for the appended event', () => failedPartition.attempts[0].sequenceNumber.value.should.equal(appendedSequenceNumber));
+    // The kernel retries the failing status with backoff inside the delivery, so the recorded reason is usually the
+    // subscriber timeout rather than the status code; either way it must carry a reason.
+    it('should record why the attempt failed', () => failedPartition.attempts[0].messages.should.not.be.empty);
+    it('should not record the event as handled', () => observer!.lastHandledEventSequenceNumber.value.should.not.equal(appendedSequenceNumber));
+});

package/webhooks/for_Webhooks/against_a_kernel/when_delivering_events_to_a_webhook.integration.spec.ts

@@ -0,0 +1,130 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import type { FailedPartition } from '../../../observation/index.js';
+import type { ReceivedWebhookRequest } from './given/ReceivedWebhookRequest.fixture.js';
+import { WebhookReceiver } from './given/WebhookReceiver.fixture.js';
+
+chai.should();
+
+// Runs against a real Chronicle kernel; skipped locally unless the connection string is set (see vitest.integration.config.ts).
+// In CI it never skips, so a missing connection string or unreachable kernel fails instead of passing vacuously.
+// The kernel must reach this process over HTTP; see WebhookReceiver for the address it uses.
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class ParcelDelivered {
+    @field(String) parcelId = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ParcelDelivered],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+interface DeliveredEvent {
+    readonly context: {
+        readonly eventType: { readonly id: string; readonly generation: number };
+        readonly eventSourceId: string;
+        readonly sequenceNumber: number;
+    };
+    readonly content: { readonly parcelId: string };
+}
+
+interface DeliveredBody {
+    readonly partition: string;
+    readonly events: ReadonlyArray<DeliveredEvent>;
+}
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 30_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when delivering events to a webhook against a kernel', () => {
+    const webhookId = randomUUID();
+    const eventSourceId = randomUUID();
+    const parcelId = randomUUID();
+    const receiver = new WebhookReceiver(200);
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let appendedSequenceNumber: bigint;
+    let request: ReceivedWebhookRequest;
+    let body: DeliveredBody;
+    let failedPartitions: FailedPartition[];
+
+    beforeAll(async () => {
+        await receiver.start();
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(`Webhooks${randomUUID().replaceAll('-', '').slice(0, 12)}`);
+
+        await store.webhooks.register(webhookId, receiver.urlFor('/parcels'), _ => _
+            .withEventType(ParcelDelivered)
+            .withHeader('X-Source', 'specs'));
+
+        const parcel = new ParcelDelivered();
+        parcel.parcelId = parcelId;
+        const result = await store.eventLog.append(eventSourceId, parcel);
+        appendedSequenceNumber = result.sequenceNumber.value;
+
+        request = (await receiver.waitForRequests(1))[0];
+        body = JSON.parse(request.body) as DeliveredBody;
+
+        // Once the kernel records the event as handled it has acted on the receiver's answer.
+        await eventually(
+            () => store.observers.getAll(),
+            _ => _.some(observer => observer.id === webhookId && observer.lastHandledEventSequenceNumber.value === appendedSequenceNumber));
+        failedPartitions = await store.failedPartitions.getFailedPartitionsFor(webhookId);
+    });
+
+    afterAll(async () => {
+        try {
+            await store?.webhooks.remove(webhookId);
+        } finally {
+            try {
+                await receiver.stop();
+            } finally {
+                client?.dispose();
+            }
+        }
+    });
+
+    it('should post to the target path', () => `${request.method} ${request.path}`.should.equal('POST /parcels'));
+    it('should send json', () => request.headers['content-type']!.should.match(/^application\/json/));
+    // Kernels up to at least 19.30.0 drop basic, bearer and OAuth authorization for webhooks outside the System event store
+    // while reporting the registration as successful, so no Authorization header is ever sent (Cratis/Chronicle#4567).
+    it.todo('should authorize with the configured credentials once Cratis/Chronicle#4567 is fixed');
+    it('should send the configured header', () => request.headers['x-source']!.should.equal('specs'));
+    it('should deliver the event source as the partition', () => body.partition.should.equal(eventSourceId));
+    it('should deliver the appended event only', () => body.events.length.should.equal(1));
+    it('should deliver the event content', () => body.events[0].content.parcelId.should.equal(parcelId));
+    it('should deliver the event type', () => body.events[0].context.eventType.id.should.equal('ParcelDelivered'));
+    it('should deliver the event source id', () => body.events[0].context.eventSourceId.should.equal(eventSourceId));
+    it('should deliver the sequence number', () => BigInt(body.events[0].context.sequenceNumber).should.equal(appendedSequenceNumber));
+    it('should not report the webhook as failed', () => failedPartitions.should.be.empty);
+});

package/webhooks/for_Webhooks/against_a_kernel/when_registering_a_webhook_that_is_not_replayable_and_not_active.integration.spec.ts

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import type { WebhookDefinition } from '@cratis/chronicle.contracts';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import type { IEventStore } from '../../../IEventStore.js';
+
+chai.should();
+
+// Runs against a real Chronicle kernel; skipped locally unless the connection string is set (see vitest.integration.config.ts).
+// In CI it never skips, so a missing connection string or unreachable kernel fails instead of passing vacuously.
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class ParcelReturned {
+    @field(String) parcelId = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ParcelReturned],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 20_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when registering a webhook that is not replayable and not active against a kernel', () => {
+    const defaultWebhookId = randomUUID();
+    const restrictedWebhookId = randomUUID();
+    const targetUrl = 'http://localhost:9/parcels';
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let defaultWebhook: WebhookDefinition;
+    let restrictedWebhook: WebhookDefinition;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(`Webhooks${randomUUID().replaceAll('-', '').slice(0, 12)}`);
+
+        // A webhook with the defaults proves the read-back distinguishes true from false, so a false
+        // below cannot be an artifact of how an absent field decodes.
+        await store.webhooks.register(defaultWebhookId, targetUrl, _ => _.withEventType(ParcelReturned));
+        await store.webhooks.register(restrictedWebhookId, targetUrl, _ => _
+            .withEventType(ParcelReturned)
+            .notReplayable()
+            .notActive());
+
+        const webhooks = await eventually(
+            () => store.webhooks.getWebhooks(),
+            _ => [defaultWebhookId, restrictedWebhookId].every(id => _.some(webhook => webhook.Identifier === id)));
+        defaultWebhook = webhooks.find(_ => _.Identifier === defaultWebhookId)!;
+        restrictedWebhook = webhooks.find(_ => _.Identifier === restrictedWebhookId)!;
+    });
+
+    afterAll(async () => {
+        const failures: unknown[] = [];
+        for (const id of [defaultWebhookId, restrictedWebhookId]) {
+            try {
+                await store?.webhooks.remove(id);
+            } catch (error) {
+                failures.push(error);
+            }
+        }
+        client?.dispose();
+        if (failures.length > 0) throw failures[0];
+    });
+
+    it('should keep a default webhook replayable', () => defaultWebhook.IsReplayable.should.be.true);
+    it('should keep a default webhook active', () => defaultWebhook.IsActive.should.be.true);
+    it('should keep the webhook not replayable', () => restrictedWebhook.IsReplayable.should.be.false);
+    // The kernel records IsActive=false in WebhookAdded, but its MongoDB storage converter drops IsActive when reading
+    // definitions back (Storage.MongoDB/Observation/Webhooks/WebhookDefinitionConverters.cs, ToKernel), so every
+    // kernel up to at least 19.30.0 lists the webhook as active (Cratis/Chronicle#4581). The client sending
+    // IsActive=false is covered by the unit spec when_registering_a_webhook_that_is_not_replayable_and_not_active.spec.ts.
+    it.todo('should keep the webhook not active once the kernel reads IsActive back from storage');
+});

package/webhooks/for_Webhooks/when_registering_a_webhook_that_is_not_replayable_and_not_active.spec.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { AddWebhooks } from '@cratis/chronicle.contracts';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { eventType } from '../../events/index.js';
+import type { IEventTypes } from '../../events/IEventTypes.js';
+import { Webhooks } from '../Webhooks.js';
+
+chai.should();
+
+@eventType()
+class ParcelReturned {
+    @field(String) parcelId = '';
+}
+
+describe('when registering a webhook that is not replayable and not active', () => {
+    let sent: AddWebhooks | undefined;
+
+    beforeEach(async () => {
+        sent = undefined;
+        const connection = {
+            webhooks: {
+                addWebhooks: async (request: AddWebhooks) => {
+                    sent = request;
+                    return { IsAuthorized: true, ValidationResults: [], ExceptionMessages: [] };
+                }
+            }
+        } as unknown as ChronicleConnection;
+        const webhooks = new Webhooks('store', connection, { all: [] } as unknown as IEventTypes, {} as IClientArtifactsProvider);
+
+        await webhooks.register('parcels', 'http://localhost:9/parcels', _ => _
+            .withEventType(ParcelReturned)
+            .notReplayable()
+            .notActive());
+    });
+
+    it('should send the webhook as not active', () => sent!.Webhooks[0].IsActive.should.be.false);
+    it('should send the webhook as not replayable', () => sent!.Webhooks[0].IsReplayable.should.be.false);
+});