@cratis/chronicle 6.50.0 → 6.51.0

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_a_later_event_sequence_fails.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { a_unit_of_work_with_a_recording_store, successfulAppendResult, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when committing events with append metadata and a later event sequence fails', () => {
+    let unitOfWork: UnitOfWork;
+    let appends: RecordedAppend[];
+    let error: unknown;
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store(async eventSequenceId => {
+            if (eventSequenceId === 'outbox') throw new Error('Kernel unavailable');
+            return [successfulAppendResult(0n)];
+        });
+        ({ unitOfWork, appends } = recording);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'first' });
+        unitOfWork.addEvent(new EventSequenceId('outbox'), 'a-1', { order: 1 }, { subject: 'second' });
+        error = await unitOfWork.commit().catch(caught => caught);
+    });
+
+    it('should reject the commit', () => (error as Error).message.should.equal('Kernel unavailable'));
+    it('should have written the earlier event sequence, since appends to separate sequences are not atomic', () => appends[0].events[0].subject!.should.equal('first'));
+    it('should not mark the unit of work completed', () => unitOfWork.isCompleted.should.be.false);
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_events_span_event_sequences.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import type { AppendResult } from '../../../eventSequences/AppendResult.js';
+import { a_unit_of_work_with_a_recording_store, successfulAppendResult, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+chai.should();
+
+describe('when committing events with append metadata and events span event sequences', () => {
+    const outbox = new EventSequenceId('outbox');
+    const scope = { sequenceNumber: 4n, eventSourceId: true };
+    let appends: RecordedAppend[];
+    let results: ReadonlyArray<AppendResult>;
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store(async (eventSequenceId, events) =>
+            events.map((_, index) => successfulAppendResult(BigInt(eventSequenceId === 'outbox' ? 100 + index : index))));
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'log-subject', concurrencyScope: scope });
+        recording.unitOfWork.addEvent(outbox, 'a-1', { order: 1 }, { subject: 'outbox-subject' });
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 2 });
+        await recording.unitOfWork.commit();
+        appends = recording.appends;
+        results = recording.unitOfWork.getAppendResults();
+    });
+
+    it('should append once per event sequence', () => appends.map(_ => _.eventSequenceId).should.deep.equal([EventSequenceId.eventLog.value, 'outbox']));
+    it('should keep the subject in the event log append', () => appends[0].events[0].subject!.should.equal('log-subject'));
+    it('should keep the subject in the outbox append', () => appends[1].events[0].subject!.should.equal('outbox-subject'));
+    it('should pass the scope to the event log append', () => appends[0].options.concurrencyScopes!.should.deep.equal({ 'a-1': scope }));
+    it('should not pass the scope to the outbox append', () => appends[1].options.should.not.have.property('concurrencyScopes'));
+    it('should report results in input order', () => results.map(_ => _.sequenceNumber.value).should.deep.equal([0n, 100n, 1n]));
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_options_differ_per_event.spec.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { Tag } from '../../../events/Tag.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import type { EventForEventSourceId } from '../../../eventSequences/EventForEventSourceId.js';
+import { a_unit_of_work_with_a_recording_store } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+const should = chai.should();
+
+describe('when committing events with append metadata and options differ per event', () => {
+    const occurred = new Date('2026-01-02T03:04:05.000Z');
+    const first = { name: 'first' };
+    const second = { name: 'second' };
+    const third = { name: 'third' };
+    let batch: EventForEventSourceId[];
+
+    beforeEach(async () => {
+        const { unitOfWork, appends } = a_unit_of_work_with_a_recording_store();
+        const tags = ['priority'];
+        const occurredInput = new Date(occurred.getTime());
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', first, {
+            eventStreamType: 'Orders', eventStreamId: 'order-1', eventSourceType: 'Customer',
+            subject: 'subject-1', occurred: occurredInput, tags
+        });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'b-1', second, { tags: [new Tag('audit')] });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', third);
+        tags.push('mutated-after-enrollment');
+        occurredInput.setUTCFullYear(1999);
+        await unitOfWork.commit();
+        batch = appends[0].events;
+    });
+
+    it('should append the events in input order', () => batch.map(_ => _.event).should.deep.equal([first, second, third]));
+    it('should keep the stream type of the first event', () => batch[0].eventStreamType!.should.equal('Orders'));
+    it('should keep the stream id of the first event', () => batch[0].eventStreamId!.should.equal('order-1'));
+    it('should keep the source type of the first event', () => batch[0].eventSourceType!.should.equal('Customer'));
+    it('should keep the subject of the first event', () => batch[0].subject!.should.equal('subject-1'));
+    it('should keep the occurrence time given at enrollment', () => batch[0].occurred!.toISOString().should.equal(occurred.toISOString()));
+    it('should keep the tags given at enrollment', () => batch[0].tags!.should.deep.equal(['priority']));
+    it('should keep the tags of the second event', () => batch[1].tags!.map(String).should.deep.equal(['audit']));
+    it('should not give the third event any metadata', () => Object.keys(batch[2]).sort().should.deep.equal(['event', 'eventSourceId']));
+    it('should not leak the subject of the first event to the second', () => should.not.exist(batch[1].subject));
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_the_append_is_rejected.spec.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { a_unit_of_work_with_a_recording_store, successfulAppendResult } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when committing events with append metadata and the append is rejected', () => {
+    const violation = { eventSourceId: 'a-1', expectedSequenceNumber: new EventSequenceNumber(1n), actualSequenceNumber: new EventSequenceNumber(5n) };
+    let unitOfWork: UnitOfWork;
+
+    beforeEach(async () => {
+        ({ unitOfWork } = a_unit_of_work_with_a_recording_store(async () => [
+            { ...successfulAppendResult(0n), isSuccess: false, concurrencyViolation: violation }
+        ]));
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { concurrencyScope: { sequenceNumber: 1n } });
+        await unitOfWork.commit();
+    });
+
+    it('should not report success', () => unitOfWork.isSuccess.should.be.false);
+    it('should surface the concurrency violation', () => unitOfWork.getConcurrencyViolations().should.deep.equal([violation]));
+});

package/transactions/for_UnitOfWork/when_rolling_back_events_with_append_metadata.spec.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, type Mock } from 'vitest';
+import { EventSequenceId } from '../../eventSequences/EventSequenceId.js';
+import { a_unit_of_work_with_a_recording_store } from './given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../UnitOfWork.js';
+
+chai.should();
+
+describe('when rolling back events with append metadata', () => {
+    let unitOfWork: UnitOfWork;
+    let record: Mock;
+
+    beforeEach(async () => {
+        ({ unitOfWork, record } = a_unit_of_work_with_a_recording_store());
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'subject-1', concurrencyScope: { sequenceNumber: 1n } });
+        await unitOfWork.rollback();
+    });
+
+    it('should drop the buffered events', () => unitOfWork.getEvents().should.be.empty);
+    it('should not append anything', () => record.mock.calls.should.be.empty);
+    it('should reject a later commit', async () => (await unitOfWork.commit().catch(caught => caught)).should.be.instanceOf(Error));
+});

package/transactions/index.ts

@@ -8,3 +8,4 @@ export { UnitOfWork } from './UnitOfWork.js';
 export { UnitOfWorkManager } from './UnitOfWorkManager.js';
 export type { TransactionalEventRouting } from './TransactionalEventRouting.js';
 export type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+export { ConflictingConcurrencyScopesInUnitOfWork } from './ConflictingConcurrencyScopesInUnitOfWork.js';

package/transactions/toEventForEventSourceId.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
+
+/**
+ * Captures an event and its transactional append metadata as the batch entry appended on commit.
+ * Only supplied values become keys, and tags and occurrence time are copied so later caller mutations do not leak in.
+ * The concurrency scope is not part of the entry; the unit of work passes it per event source identifier.
+ * @param eventSourceId - The event source identifier.
+ * @param event - The event payload.
+ * @param options - Optional transactional append metadata.
+ * @returns The batch entry.
+ */
+export function toEventForEventSourceId(eventSourceId: string, event: object, options?: TransactionalAppendOptions): EventForEventSourceId {
+    const namedTags = mergeNamedTags(options?.namedTags);
+    return {
+        eventSourceId,
+        event,
+        ...(options?.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
+        ...(options?.eventStream !== undefined ? { eventStream: options.eventStream } : {}),
+        ...(options?.eventStreamType !== undefined ? { eventStreamType: options.eventStreamType } : {}),
+        ...(options?.eventStreamId !== undefined ? { eventStreamId: options.eventStreamId } : {}),
+        ...(options?.eventSourceType !== undefined ? { eventSourceType: options.eventSourceType } : {}),
+        ...(options?.occurred !== undefined ? { occurred: new Date(options.occurred.getTime()) } : {}),
+        ...(options?.subject !== undefined ? { subject: options.subject } : {}),
+        ...(options?.tags !== undefined ? { tags: [...options.tags] } : {}),
+        ...(namedTags.length > 0 ? { namedTags } : {})
+    };
+}

package/vitest.integration.config.ts

@@ -7,6 +7,8 @@ import baseConfig from './vitest.config.js';
 // Kernel-backed specifications. They need a running Chronicle kernel and are skipped unless
 // CHRONICLE_INTEGRATION_CONNECTION_STRING points at one, for example
 // chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000
+// The webhook delivery specifications also need the kernel to reach this process over HTTP, as
+// host.docker.internal by default; set CHRONICLE_INTEGRATION_WEBHOOK_HOST when it reaches it differently.
 export default defineConfig({
     ...baseConfig,
     test: {

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

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { IncomingHttpHeaders } from 'node:http';
+
+/**
+ * A request the kernel delivered to a {@link WebhookReceiver}.
+ */
+export interface ReceivedWebhookRequest {
+    /** The HTTP method. */
+    readonly method: string;
+
+    /** The request path, including any query string. */
+    readonly path: string;
+
+    /** The request headers, with lowercase names. */
+    readonly headers: IncomingHttpHeaders;
+
+    /** The raw request body. */
+    readonly body: string;
+}

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);
+});