eventsourcingdb 1.10.0 → 2.0.0

package/dist/Client.js

@@ -1,470 +1,110 @@
-import { convertCloudEventToEvent } from './convertCloudEventToEvent.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 { detectApiVersion } from './detectApiVersion.js';
+import { isAbortError } from './http/isAbortError.js';
+import { waitUnlessAborted } from './http/waitUnlessAborted.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';
-import { isStreamHeartbeat } from './stream/isStreamHeartbeat.js';
-import { isStreamRow } from './stream/isStreamRow.js';
-import { isStreamSubject } from './stream/isStreamSubject.js';
 import { hasShapeOf } from './types/hasShapeOf.js';
 import { isBoolean } from './types/isBoolean.js';
-import { isString } from './types/isString.js';
-class Client {
-    #url;
-    #apiToken;
-    #stallTimeout;
-    #getUrl(path) {
-        return new URL(path, this.#url).toString();
+import { V1Transport } from './v1/V1Transport.js';
+import { V2Transport } from './v2/V2Transport.js';
+// Reads a stream through the transport, unless the caller aborts while the
+// client finds out which one to use, which ends the stream, as aborting it
+// does at any other time.
+const streamThrough = async function* (getTransport, stream) {
+    let transport;
+    try {
+        transport = await getTransport();
+    }
+    catch (error) {
+        if (isAbortError(error)) {
+            return;
+        }
+        throw error;
     }
+    yield* stream(transport);
+};
+class Client {
+    #transportOptions;
+    #transport;
+    #detection;
     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;
+        this.#transportOptions = { url, apiToken, stallTimeout };
     }
-    async ping(signal) {
-        const url = this.#getUrl('/api/v1/ping');
-        const stallTimeout = this.#stallTimeout;
-        await runWithStallGuard({ stallTimeout, signal }, async (stallGuard) => {
-            const response = await stallGuard.send(url, {
-                method: 'get',
+    // This is the one place that chooses between the APIs. The first request of
+    // a client finds out which API the server offers, and the client keeps the
+    // answer. Requests that start meanwhile wait for the same answer. If the
+    // client fails to find out, the request fails, and the next one tries again.
+    async #getTransport(signal) {
+        if (this.#transport !== undefined) {
+            return this.#transport;
+        }
+        signal?.throwIfAborted();
+        if (this.#detection === undefined) {
+            const detection = detectApiVersion(this.#transportOptions).then(apiVersion => {
+                this.#transport =
+                    apiVersion === 'v2'
+                        ? new V2Transport(this.#transportOptions)
+                        : new V1Transport(this.#transportOptions);
+                return this.#transport;
             });
-            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.');
-            }
-        });
+            const forget = () => {
+                if (this.#detection === detection) {
+                    this.#detection = undefined;
+                }
+            };
+            detection.then(forget, forget);
+            this.#detection = detection;
+        }
+        return await waitUnlessAborted(this.#detection, signal);
+    }
+    async ping(signal) {
+        const transport = await this.#getTransport(signal);
+        await transport.ping(signal);
     }
     async verifyApiToken(signal) {
-        const url = this.#getUrl('/api/v1/verify-api-token');
-        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.');
-            }
-        });
+        const transport = await this.#getTransport(signal);
+        await transport.verifyApiToken(signal);
     }
+    // A write that fails once it may have reached the server fails with an
+    // OutcomeUnknownError, since it may have been stored nonetheless. This
+    // includes aborting the signal once the write has been sent.
     async writeEvents(events, preconditions = [], signal) {
-        const url = this.#getUrl('/api/v1/write-events');
-        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.');
-            }
-            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;
-        });
+        const transport = await this.#getTransport(signal);
+        return await transport.writeEvents(events, preconditions, signal);
     }
     readEvents(subject, options, signal) {
-        const url = this.#getUrl('/api/v1/read-events');
-        const apiToken = this.#apiToken;
-        const stallTimeout = this.#stallTimeout;
-        return (async function* () {
-            const stallGuard = new StallGuard(stallTimeout, signal);
-            try {
-                stallGuard.restart();
-                const response = await stallGuard.send(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        subject,
-                        options,
-                    }),
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read events, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read events.');
-                }
-                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, 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 {
-                stallGuard.dispose({ abortRequest: true });
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readEvents(subject, options, signal));
     }
     runEventQlQuery(query, signal) {
-        const url = this.#getUrl('/api/v1/run-eventql-query');
-        const apiToken = this.#apiToken;
-        const stallTimeout = this.#stallTimeout;
-        return (async function* () {
-            const stallGuard = new StallGuard(stallTimeout, signal);
-            try {
-                stallGuard.restart();
-                const response = await stallGuard.send(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({ query }),
-                });
-                // 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) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to run EventQL query, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to run EventQL query.');
-                }
-                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamRow(line)) {
-                        const row = line.payload;
-                        yield row;
-                        continue;
-                    }
-                    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 {
-                stallGuard.dispose({ abortRequest: true });
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.runEventQlQuery(query, signal));
     }
     observeEvents(subject, options, signal) {
-        const url = this.#getUrl('/api/v1/observe-events');
-        const apiToken = this.#apiToken;
-        const stallTimeout = this.#stallTimeout;
-        return (async function* () {
-            const stallGuard = new StallGuard(stallTimeout, signal);
-            try {
-                stallGuard.restart();
-                const response = await stallGuard.send(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        subject,
-                        options,
-                    }),
-                });
-                // 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) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to observe events, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to observe events.');
-                }
-                for await (const { value: line, text } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamCloudEvent(line)) {
-                        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 {
-                stallGuard.dispose({ abortRequest: true });
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.observeEvents(subject, options, signal));
     }
+    // Registering an event schema is a write, so it fails like writeEvents does.
     async registerEventSchema(eventType, schema, signal) {
-        const url = this.#getUrl('/api/v1/register-event-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'.`);
-            }
-        });
+        const transport = await this.#getTransport(signal);
+        await transport.registerEventSchema(eventType, schema, signal);
     }
-    readSubjects(baseSubject, signal) {
-        const url = this.#getUrl('/api/v1/read-subjects');
-        const apiToken = this.#apiToken;
-        const stallTimeout = this.#stallTimeout;
-        return (async function* () {
-            const stallGuard = new StallGuard(stallTimeout, signal);
-            try {
-                stallGuard.restart();
-                const response = await stallGuard.send(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                        'content-type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        baseSubject,
-                    }),
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read subjects, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read subjects.');
-                }
-                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamSubject(line)) {
-                        yield line.payload.subject;
-                        continue;
-                    }
-                    throw new Error('Failed to read subjects.');
-                }
-                stallGuard.throwIfStalled();
-            }
-            catch (error) {
-                stallGuard.throwIfStalled();
-                if (error instanceof DOMException && error.name === 'AbortError') {
-                    return;
-                }
-                throw error;
-            }
-            finally {
-                stallGuard.dispose({ abortRequest: true });
-            }
-        })();
+    readSubjects(subject, options, signal) {
+        // The option decides whether to read the subject alone or with all the
+        // subjects below it, so it has no default, and a caller without types has
+        // to set it as well.
+        if (!hasShapeOf(options, { recursive: isBoolean })) {
+            throw new Error("Option 'recursive' must be set to true or false.");
+        }
+        const { recursive } = options;
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readSubjects(subject, { recursive }, signal));
     }
     async readEventType(eventType, signal) {
-        const url = this.#getUrl('/api/v1/read-event-type');
-        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;
-        });
+        const transport = await this.#getTransport(signal);
+        return await transport.readEventType(eventType, signal);
     }
     readEventTypes(signal) {
-        const url = this.#getUrl('/api/v1/read-event-types');
-        const apiToken = this.#apiToken;
-        const stallTimeout = this.#stallTimeout;
-        return (async function* () {
-            const stallGuard = new StallGuard(stallTimeout, signal);
-            try {
-                stallGuard.restart();
-                const response = await stallGuard.send(url, {
-                    method: 'post',
-                    headers: {
-                        authorization: `Bearer ${apiToken}`,
-                    },
-                });
-                if (!isValidServerHeader(response)) {
-                    const serverHeader = response.headers.get('Server');
-                    if (!serverHeader) {
-                        throw new Error('Server must be EventSourcingDB, but Server header is missing.');
-                    }
-                    throw new Error(`Server must be EventSourcingDB, got Server header: '${serverHeader}'.`);
-                }
-                if (response.status !== 200) {
-                    throw new Error(`Failed to read event types, got HTTP status code '${response.status}', expected '200'.`);
-                }
-                if (!response.body) {
-                    throw new Error('Failed to read event types.');
-                }
-                for await (const { value: line } of readNdJsonStream(response.body, stallGuard.signal, stallGuard)) {
-                    if (isStreamHeartbeat(line)) {
-                        continue;
-                    }
-                    if (isStreamError(line)) {
-                        throw new Error(`${line.payload.error}.`);
-                    }
-                    if (isStreamEventType(line)) {
-                        yield line.payload;
-                        continue;
-                    }
-                    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 {
-                stallGuard.dispose({ abortRequest: true });
-            }
-        })();
+        return streamThrough(async () => await this.#getTransport(signal), transport => transport.readEventTypes(signal));
     }
 }
 export { Client };

package/dist/DbApiError.d.ts

@@ -0,0 +1,17 @@
+interface DbApiErrorOptions {
+    status: number;
+    description: string;
+    code?: string;
+    details?: Record<string, unknown>;
+    retryAfter?: number;
+}
+declare class DbApiError extends Error {
+    readonly code: string | undefined;
+    readonly description: string;
+    readonly details: Record<string, unknown>;
+    readonly status: number;
+    readonly retryAfter: number | undefined;
+    constructor({ status, description, code, details, retryAfter }: DbApiErrorOptions);
+}
+export type { DbApiErrorOptions };
+export { DbApiError };

package/dist/DbApiError.js

@@ -0,0 +1,24 @@
+// An error that the server reports, whether as an error item of the v2 API, as
+// a status other than 200 with a text, or as an error of the v1 API.
+class DbApiError extends Error {
+    // The URL that names the error, exactly as the server sends it, which the
+    // constants of ErrorCode hold. It is undefined for an error without a code.
+    code;
+    description;
+    details;
+    // The HTTP status of the response, which is 200 for an error item.
+    status;
+    // The seconds after which the server accepts requests again, which only a
+    // response with the status 429 may name.
+    retryAfter;
+    constructor({ status, description, code, details = {}, retryAfter }) {
+        super(description === '' ? `The server answered with HTTP status code '${status}'.` : description);
+        this.name = 'DbApiError';
+        this.code = code;
+        this.description = description;
+        this.details = details;
+        this.status = status;
+        this.retryAfter = retryAfter;
+    }
+}
+export { DbApiError };