eventsourcingdb 1.9.1 → 1.10.0

package/dist/Client.js

@@ -1,8 +1,14 @@
 import { convertCloudEventToEvent } from './convertCloudEventToEvent.js';
-import { heartbeatTimeout } from './heartbeatTimeout.js';
+import { HeartbeatTimeoutError } from './HeartbeatTimeoutError.js';
 import { isCloudEvent } from './isCloudEvent.js';
 import { isValidServerHeader } from './isValidServerHeader.js';
+import { getRawJsonElements } from './json/getRawJsonElements.js';
+import { getRawJsonMember } from './json/getRawJsonMember.js';
 import { readNdJsonStream } from './ndjson/readNdJsonStream.js';
+import { defaultStallTimeout, maximumStallTimeout } from './stall/defaultStallTimeout.js';
+import { readResponseText } from './stall/readResponseText.js';
+import { runWithStallGuard } from './stall/runWithStallGuard.js';
+import { StallGuard } from './stall/StallGuard.js';
 import { isStreamCloudEvent } from './stream/isStreamCloudEvent.js';
 import { isStreamError } from './stream/isStreamError.js';
 import { isStreamEventType } from './stream/isStreamEventType.js';
@@ -15,107 +21,118 @@ import { isString } from './types/isString.js';
 class Client {
     #url;
     #apiToken;
+    #stallTimeout;
     #getUrl(path) {
         return new URL(path, this.#url).toString();
     }
-    constructor(url, apiToken) {
+    constructor(url, apiToken, options = {}) {
+        const stallTimeout = options.stallTimeout ?? defaultStallTimeout;
+        if (!(stallTimeout >= 1 && stallTimeout <= maximumStallTimeout)) {
+            throw new Error(`Stall timeout must be between 1 and ${maximumStallTimeout} milliseconds, got '${stallTimeout}'.`);
+        }
         this.#url = url;
         this.#apiToken = apiToken;
+        this.#stallTimeout = stallTimeout;
     }
-    async ping() {
+    async ping(signal) {
         const url = this.#getUrl('/api/v1/ping');
-        const response = await fetch(url, {
-            method: 'get',
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'get',
+            });
+            if (!isValidServerHeader(response)) {
+                throw new Error('Server must be EventSourcingDB.');
+            }
+            if (response.status !== 200) {
+                throw new Error(`Failed to ping, got HTTP status code '${response.status}', expected '200'.`);
+            }
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            if (!hasShapeOf(responseBody, {
+                type: isString,
+            })) {
+                throw new Error('Failed to parse response.');
+            }
+            const eventType = 'io.eventsourcingdb.api.ping-received';
+            if (responseBody.type !== eventType) {
+                throw new Error('Failed to ping.');
+            }
         });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to ping, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            type: isString,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        const eventType = 'io.eventsourcingdb.api.ping-received';
-        if (responseBody.type !== eventType) {
-            throw new Error('Failed to ping.');
-        }
     }
-    async verifyApiToken() {
+    async verifyApiToken(signal) {
         const url = this.#getUrl('/api/v1/verify-api-token');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-            },
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'post',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                },
+            });
+            if (!isValidServerHeader(response)) {
+                throw new Error('Server must be EventSourcingDB.');
+            }
+            if (response.status !== 200) {
+                throw new Error(`Failed to verify API token, got HTTP status code '${response.status}', expected '200'.`);
+            }
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            if (!hasShapeOf(responseBody, {
+                type: isString,
+            })) {
+                throw new Error('Failed to parse response.');
+            }
+            const eventType = 'io.eventsourcingdb.api.api-token-verified';
+            if (responseBody.type !== eventType) {
+                throw new Error('Failed to verify API token.');
+            }
         });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to verify API token, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            type: isString,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        const eventType = 'io.eventsourcingdb.api.api-token-verified';
-        if (responseBody.type !== eventType) {
-            throw new Error('Failed to verify API token.');
-        }
     }
-    async writeEvents(events, preconditions = []) {
+    async writeEvents(events, preconditions = [], signal) {
         const url = this.#getUrl('/api/v1/write-events');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                events,
-                preconditions,
-            }),
-        });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to write events, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!Array.isArray(responseBody)) {
-            throw new Error('Failed to parse response.');
-        }
-        const writtenEvents = responseBody.map(item => {
-            if (!isCloudEvent(item)) {
-                throw new Error('Failed to parse response item.');
+        const stallTimeout = this.#stallTimeout;
+        return await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'post',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    events,
+                    preconditions,
+                }),
+            });
+            if (!isValidServerHeader(response)) {
+                throw new Error('Server must be EventSourcingDB.');
             }
-            const event = convertCloudEventToEvent(item);
-            return event;
+            if (response.status !== 200) {
+                throw new Error(`Failed to write events, got HTTP status code '${response.status}', expected '200'.`);
+            }
+            const responseText = await readResponseText(response, stallGuard);
+            const responseBody = JSON.parse(responseText);
+            if (!Array.isArray(responseBody)) {
+                throw new Error('Failed to parse response.');
+            }
+            const responseItemTexts = getRawJsonElements(responseText);
+            const writtenEvents = responseBody.map((item, index) => {
+                if (!isCloudEvent(item)) {
+                    throw new Error('Failed to parse response item.');
+                }
+                const event = convertCloudEventToEvent(item, responseItemTexts[index]);
+                return event;
+            });
+            return writtenEvents;
         });
-        return writtenEvents;
     }
     readEvents(subject, options, signal) {
         const url = this.#getUrl('/api/v1/read-events');
         const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
         return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
+            const stallGuard = new StallGuard(stallTimeout, signal);
             try {
-                const response = await fetch(url, {
+                stallGuard.restart();
+                const response = await stallGuard.send(url, {
                     method: 'post',
                     headers: {
                         authorization: `Bearer ${apiToken}`,
@@ -125,7 +142,6 @@ class Client {
                         subject,
                         options,
                     }),
-                    signal: combinedSignal,
                 });
                 if (!isValidServerHeader(response)) {
                     const serverHeader = response.headers.get('Server');
@@ -140,57 +156,50 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to read events.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
+                for await (const { value: line, text } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
                     if (isStreamError(line)) {
                         throw new Error(`${line.payload.error}.`);
                     }
                     if (isStreamCloudEvent(line)) {
-                        const event = convertCloudEventToEvent(line.payload);
+                        const event = convertCloudEventToEvent(line.payload, getRawJsonMember(text, 'payload'));
                         yield event;
                         continue;
                     }
                     throw new Error('Failed to read events.');
                 }
+                stallGuard.throwIfStalled();
             }
             catch (error) {
+                stallGuard.throwIfStalled();
                 if (error instanceof DOMException && error.name === 'AbortError') {
                     return;
                 }
                 throw error;
             }
             finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
+                stallGuard.dispose({ abortRequest: true });
             }
         })();
     }
     runEventQlQuery(query, signal) {
         const url = this.#getUrl('/api/v1/run-eventql-query');
         const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
         return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
+            const stallGuard = new StallGuard(stallTimeout, signal);
             try {
-                const response = await fetch(url, {
+                stallGuard.restart();
+                const response = await stallGuard.send(url, {
                     method: 'post',
                     headers: {
                         authorization: `Bearer ${apiToken}`,
                         'content-type': 'application/json',
                     },
                     body: JSON.stringify({ query }),
-                    signal: combinedSignal,
                 });
+                // Once the headers have arrived, the server sends a heartbeat every
+                // second, so from now on a stall means that heartbeats are missing.
+                stallGuard.onStall(() => new HeartbeatTimeoutError(stallTimeout));
                 if (!isValidServerHeader(response)) {
                     const serverHeader = response.headers.get('Server');
                     if (!serverHeader) {
@@ -204,7 +213,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to run EventQL query.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
+                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
                     if (isStreamHeartbeat(line)) {
                         continue;
                     }
@@ -218,38 +227,29 @@ class Client {
                     }
                     throw new Error('Failed to run EventQL query.');
                 }
+                stallGuard.throwIfStalled();
             }
             catch (error) {
+                stallGuard.throwIfStalled();
                 if (error instanceof DOMException && error.name === 'AbortError') {
                     return;
                 }
                 throw error;
             }
             finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
+                stallGuard.dispose({ abortRequest: true });
             }
         })();
     }
     observeEvents(subject, options, signal) {
         const url = this.#getUrl('/api/v1/observe-events');
         const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
         return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
+            const stallGuard = new StallGuard(stallTimeout, signal);
             try {
-                const response = await fetch(url, {
+                stallGuard.restart();
+                const response = await stallGuard.send(url, {
                     method: 'post',
                     headers: {
                         authorization: `Bearer ${apiToken}`,
@@ -259,8 +259,10 @@ class Client {
                         subject,
                         options,
                     }),
-                    signal: combinedSignal,
                 });
+                // Once the headers have arrived, the server sends a heartbeat every
+                // second, so from now on a stall means that heartbeats are missing.
+                stallGuard.onStall(() => new HeartbeatTimeoutError(stallTimeout));
                 if (!isValidServerHeader(response)) {
                     const serverHeader = response.headers.get('Server');
                     if (!serverHeader) {
@@ -274,7 +276,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to observe events.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
+                for await (const { value: line, text } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
                     if (isStreamHeartbeat(line)) {
                         continue;
                     }
@@ -282,64 +284,58 @@ class Client {
                         throw new Error(`${line.payload.error}.`);
                     }
                     if (isStreamCloudEvent(line)) {
-                        const event = convertCloudEventToEvent(line.payload);
+                        const event = convertCloudEventToEvent(line.payload, getRawJsonMember(text, 'payload'));
                         yield event;
                         continue;
                     }
                     throw new Error('Failed to observe events.');
                 }
+                stallGuard.throwIfStalled();
             }
             catch (error) {
+                stallGuard.throwIfStalled();
                 if (error instanceof DOMException && error.name === 'AbortError') {
                     return;
                 }
                 throw error;
             }
             finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
+                stallGuard.dispose({ abortRequest: true });
             }
         })();
     }
-    async registerEventSchema(eventType, schema) {
+    async registerEventSchema(eventType, schema, signal) {
         const url = this.#getUrl('/api/v1/register-event-schema');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                eventType,
-                schema,
-            }),
+        const stallTimeout = this.#stallTimeout;
+        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'post',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    eventType,
+                    schema,
+                }),
+            });
+            if (!isValidServerHeader(response)) {
+                throw new Error('Server must be EventSourcingDB.');
+            }
+            if (response.status !== 200) {
+                throw new Error(`Failed to register event schema, got HTTP status code '${response.status}', expected '200'.`);
+            }
         });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to register event schema, got HTTP status code '${response.status}', expected '200'.`);
-        }
     }
     readSubjects(baseSubject, signal) {
         const url = this.#getUrl('/api/v1/read-subjects');
         const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
         return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
+            const stallGuard = new StallGuard(stallTimeout, signal);
             try {
-                const response = await fetch(url, {
+                stallGuard.restart();
+                const response = await stallGuard.send(url, {
                     method: 'post',
                     headers: {
                         authorization: `Bearer ${apiToken}`,
@@ -348,7 +344,6 @@ class Client {
                     body: JSON.stringify({
                         baseSubject,
                     }),
-                    signal: combinedSignal,
                 });
                 if (!isValidServerHeader(response)) {
                     const serverHeader = response.headers.get('Server');
@@ -363,7 +358,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to read subjects.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
+                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
                     if (isStreamError(line)) {
                         throw new Error(`${line.payload.error}.`);
                     }
@@ -373,70 +368,63 @@ class Client {
                     }
                     throw new Error('Failed to read subjects.');
                 }
+                stallGuard.throwIfStalled();
             }
             catch (error) {
+                stallGuard.throwIfStalled();
                 if (error instanceof DOMException && error.name === 'AbortError') {
                     return;
                 }
                 throw error;
             }
             finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
+                stallGuard.dispose({ abortRequest: true });
             }
         })();
     }
-    async readEventType(eventType) {
+    async readEventType(eventType, signal) {
         const url = this.#getUrl('/api/v1/read-event-type');
-        const response = await fetch(url, {
-            method: 'post',
-            headers: {
-                authorization: `Bearer ${this.#apiToken}`,
-                'content-type': 'application/json',
-            },
-            body: JSON.stringify({
-                eventType,
-            }),
+        const stallTimeout = this.#stallTimeout;
+        return await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
+            const response = await stallGuard.send(url, {
+                method: 'post',
+                headers: {
+                    authorization: `Bearer ${this.#apiToken}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    eventType,
+                }),
+            });
+            if (!isValidServerHeader(response)) {
+                throw new Error('Server must be EventSourcingDB.');
+            }
+            if (response.status !== 200) {
+                throw new Error(`Failed to read event type, got HTTP status code '${response.status}', expected '200'.`);
+            }
+            const responseBody = JSON.parse(await readResponseText(response, stallGuard));
+            if (!hasShapeOf(responseBody, {
+                eventType: isString,
+                isPhantom: isBoolean,
+            })) {
+                throw new Error('Failed to parse response.');
+            }
+            return responseBody;
         });
-        if (!isValidServerHeader(response)) {
-            throw new Error('Server must be EventSourcingDB.');
-        }
-        if (response.status !== 200) {
-            throw new Error(`Failed to read event type, got HTTP status code '${response.status}', expected '200'.`);
-        }
-        const responseBody = await response.json();
-        if (!hasShapeOf(responseBody, {
-            eventType: isString,
-            isPhantom: isBoolean,
-        })) {
-            throw new Error('Failed to parse response.');
-        }
-        return responseBody;
     }
     readEventTypes(signal) {
         const url = this.#getUrl('/api/v1/read-event-types');
         const apiToken = this.#apiToken;
+        const stallTimeout = this.#stallTimeout;
         return (async function* () {
-            const internalAbortController = new AbortController();
-            const combinedSignal = signal ?? internalAbortController.signal;
-            const shouldAbortInternally = !signal;
-            let removeAbortListener;
-            if (signal && !signal.aborted) {
-                const onAbort = () => internalAbortController.abort();
-                signal.addEventListener('abort', onAbort, { once: true });
-                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
-            }
+            const stallGuard = new StallGuard(stallTimeout, signal);
             try {
-                const response = await fetch(url, {
+                stallGuard.restart();
+                const response = await stallGuard.send(url, {
                     method: 'post',
                     headers: {
                         authorization: `Bearer ${apiToken}`,
                     },
-                    signal: combinedSignal,
                 });
                 if (!isValidServerHeader(response)) {
                     const serverHeader = response.headers.get('Server');
@@ -451,7 +439,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to read event types.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
+                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
                     if (isStreamHeartbeat(line)) {
                         continue;
                     }
@@ -464,20 +452,17 @@ class Client {
                     }
                     throw new Error('Failed to read event types.');
                 }
+                stallGuard.throwIfStalled();
             }
             catch (error) {
+                stallGuard.throwIfStalled();
                 if (error instanceof DOMException && error.name === 'AbortError') {
                     return;
                 }
                 throw error;
             }
             finally {
-                if (removeAbortListener) {
-                    removeAbortListener();
-                }
-                if (shouldAbortInternally) {
-                    internalAbortController.abort();
-                }
+                stallGuard.dispose({ abortRequest: true });
             }
         })();
     }

package/dist/ClientOptions.d.ts

@@ -0,0 +1,4 @@
+interface ClientOptions {
+    stallTimeout?: number;
+}
+export type { ClientOptions };

package/dist/ClientOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/ConnectionStalledError.d.ts

@@ -0,0 +1,4 @@
+declare class ConnectionStalledError extends TypeError {
+    constructor(stallTimeout?: number, options?: ErrorOptions);
+}
+export { ConnectionStalledError };

package/dist/ConnectionStalledError.js

@@ -0,0 +1,13 @@
+import { defaultStallTimeout } from './stall/defaultStallTimeout.js';
+import { formatDuration } from './stall/formatDuration.js';
+// Extends TypeError, since fetch fails with a TypeError if a request stalls
+// for longer than its own timeouts allow, so code that catches that keeps
+// working. For the same reason, its cause carries the code of the timeout
+// error of fetch for the same situation.
+class ConnectionStalledError extends TypeError {
+    constructor(stallTimeout = defaultStallTimeout, options) {
+        super(`Nothing arrived from the server for ${formatDuration(stallTimeout)}.`, options);
+        this.name = 'ConnectionStalledError';
+    }
+}
+export { ConnectionStalledError };

package/dist/Event.d.ts

@@ -14,7 +14,7 @@ declare class Event {
     traceparent?: string;
     tracestate?: string;
     signature: string | null;
-    constructor({ specversion, id, time, timeFromServer, source, subject, type, datacontenttype, data, hash, predecessorhash, traceparent, tracestate, signature, }: {
+    constructor({ specversion, id, time, timeFromServer, source, subject, type, datacontenttype, data, dataFromServer, hash, predecessorhash, traceparent, tracestate, signature, }: {
         specversion: string;
         id: string;
         time: Date;
@@ -24,6 +24,7 @@ declare class Event {
         type: string;
         datacontenttype: string;
         data: Record<string, unknown>;
+        dataFromServer: string;
         hash: string;
         predecessorhash: string;
         traceparent?: string;