@spine-event-engine/client-web 2.0.0-snapshot.2

package/dist/client/client.js

@@ -0,0 +1,1049 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { clone, create, toBinary } from "@bufbuild/protobuf";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport, createGrpcWebTransport } from "@connectrpc/connect-web";
+import { SignalEnvelopes, AnyMessages } from "@spine-event-engine/core";
+import { ActorContextSchema, CommandContextSchema, CommandIdSchema, TenantIdSchema, UserIdSchema, ZoneIdSchema, } from "@spine-event-engine/proto";
+import { CommandService, QuerySchema, QueryResponseSchema, QueryService, SubscriptionService, SubscriptionUpdateSchema, TargetSchema, TopicSchema, } from "@spine-event-engine/proto/client";
+/**
+ * Thrown for a service response that violates the frozen wire contract.
+ */
+export class ClientProtocolError extends Error {
+    // prettier-ignore
+    /**
+     * Creates an error for an invalid wire response.
+     * @param message Explains the protocol violation.
+     */
+    constructor(message) {
+        super(`Client protocol error: ${message}`);
+        this.name = "ClientProtocolError";
+    }
+}
+/**
+ * Internal marker selecting the terminal overflow path without inspecting error text.
+ */
+class SubscriptionBufferOverflowError extends ClientProtocolError {
+}
+/**
+ * Internal marker for a transport stream that ended without terminal cancellation.
+ */
+class SubscriptionStreamEndedError extends ClientProtocolError {
+}
+/**
+ * Browser-safe Spine client whose transport and ID source are supplied by the caller.
+ */
+export class Client {
+    #owner;
+    #tenant;
+    #zoneId;
+    #subscriptions;
+    /**
+     * Creates a browser client from a supplied transport and immutable options.
+     *
+     * @param source Supplies the browser-safe transport and request-ID source.
+     * @param options Supplies optional tenant, zone, reconnect, and subscription settings.
+     */
+    constructor(source, options) {
+        this.#owner = new ClientOwner(source, options.onReauthenticateBeforeReconnect);
+        this.#tenant = BrowserClientValues.tenant(options.tenant);
+        this.#zoneId = BrowserClientValues.zoneId(options.zoneId);
+        this.#subscriptions = BrowserClientValues.subscriptionRuntimeOptions(options.subscriptions);
+    }
+    /**
+     * Creates a client from an injected transport and request-ID source.
+     * @param source Supplies the transport and request-ID source.
+     * @param options Supplies immutable client options.
+     * @returns Returns the created client.
+     */
+    static usingTransport(source, options = {}) {
+        return new Client(source, options);
+    }
+    /**
+     * Creates a browser client that always uses the gRPC-Web protocol.
+     * @param baseUrl Supplies the gateway base URL.
+     * @param options Supplies browser client options.
+     * @returns Returns the created client.
+     */
+    static forGrpcWeb(baseUrl, options = {}) {
+        return new Client(BrowserClientValues.browserSource(createGrpcWebTransport(BrowserClientValues.browserTransportOptions(baseUrl, options))), options);
+    }
+    /**
+     * Creates a browser client that always uses binary Connect (`application/proto`).
+     *
+     * The selected gateway must permit binary Connect, including packed `Any` command
+     * and query values. Selection is explicit: this method never probes or falls back.
+     * @param baseUrl Supplies the gateway base URL.
+     * @param options Supplies browser client options.
+     * @returns Returns the created client.
+     */
+    static forConnect(baseUrl, options = {}) {
+        return new Client(BrowserClientValues.browserSource(createConnectTransport({
+            ...BrowserClientValues.browserTransportOptions(baseUrl, options),
+            useBinaryFormat: true,
+        })), options);
+    }
+    /**
+     * Creates an immutable request scope for the guest actor.
+     * @returns Returns the guest request scope.
+     */
+    asGuest() {
+        return new Request(this.#owner, this.#tenant, this.#zoneId, this.#subscriptions, "guest");
+    }
+    /**
+     * Creates an immutable request scope for one actor.
+     * @param user Identifies the actor for requests in the scope.
+     * @returns Returns the actor request scope.
+     */
+    onBehalfOf(user) {
+        if (user.length === 0)
+            throw new TypeError("Client actor must not be empty.");
+        return new Request(this.#owner, this.#tenant, this.#zoneId, this.#subscriptions, user);
+    }
+    /**
+     * Closes the client by requesting open-work cancellation, awaiting subscription cleanup, and closing its transport.
+     * @returns Completes after subscription cleanup and transport closure.
+     */
+    close() {
+        return this.#owner.close();
+    }
+}
+class Request {
+    #owner;
+    #tenant;
+    #zoneId;
+    #subscriptions;
+    #actor;
+    constructor(owner, selectedTenant, selectedZoneId, subscriptions, actor) {
+        this.#owner = owner;
+        this.#tenant = selectedTenant;
+        this.#zoneId = selectedZoneId;
+        this.#subscriptions = subscriptions;
+        this.#actor = actor;
+    }
+    async post(schema, message, options = {}) {
+        return this.#owner.run(options.signal, async (signal) => {
+            const id = this.#owner.createRequestId();
+            if (id.length === 0)
+                throw new ClientProtocolError("request ID is missing or invalid.");
+            const command = SignalEnvelopes.command({
+                id: create(CommandIdSchema, { uuid: id }),
+                context: create(CommandContextSchema, { actorContext: this.#context() }),
+                schema,
+                message,
+                validate: false,
+            });
+            const ack = await createClient(CommandService, this.#owner.transport).post(command, {
+                signal,
+            });
+            BrowserClientValues.validateAckId(ack.messageId, id);
+            return BrowserClientValues.outcome(ack.status?.status);
+        });
+    }
+    async send(queryOrBuilder, options = {}) {
+        return this.#owner.run(options.signal, async (signal) => {
+            const source = "build" in queryOrBuilder ? queryOrBuilder.build() : queryOrBuilder;
+            const query = clone(QuerySchema, source);
+            query.context = this.#context();
+            return createClient(QueryService, this.#owner.transport).read(query, { signal });
+        });
+    }
+    async createSubscription(topic, options) {
+        const validatedOptions = BrowserClientValues.validateSubscriptionOptions(options);
+        return this.#owner.run(validatedOptions.signal, (signal) => Promise.resolve(new TopicSubscription(this.#owner, BrowserClientValues.cloneTopic(topic, this.#context()), signal, validatedOptions, this.#subscriptions)));
+    }
+    #context() {
+        return create(ActorContextSchema, {
+            ...(this.#tenant === undefined ? {} : { tenantId: clone(TenantIdSchema, this.#tenant) }),
+            zoneId: clone(ZoneIdSchema, this.#zoneId),
+            actor: create(UserIdSchema, { value: this.#actor }),
+            timestamp: create(TimestampSchema, { seconds: BigInt(Math.floor(Date.now() / 1_000)) }),
+        });
+    }
+}
+class ClientOwner {
+    transport;
+    #source;
+    #onReauthenticateBeforeReconnect;
+    #controllers = new Set();
+    #subscriptions = new Set();
+    #closed = false;
+    #close;
+    constructor(source, onReauthenticateBeforeReconnect) {
+        this.#source = source;
+        this.#onReauthenticateBeforeReconnect = onReauthenticateBeforeReconnect;
+        this.transport = source.transport;
+    }
+    createRequestId() {
+        return this.#source.createRequestId();
+    }
+    async onReauthenticateBeforeReconnect(signal, remainingMs) {
+        this.assertOpen();
+        const callback = this.#onReauthenticateBeforeReconnect;
+        if (callback === undefined)
+            return;
+        if (!Number.isSafeInteger(remainingMs) || remainingMs <= 0)
+            throw new ClientProtocolError("subscription reauthentication retry deadline is exhausted.");
+        const controller = new AbortController();
+        const abort = () => {
+            controller.abort(signal.reason);
+        };
+        const timeout = setTimeout(() => {
+            controller.abort(new ClientProtocolError("subscription reauthentication timed out."));
+        }, remainingMs);
+        signal.addEventListener("abort", abort, { once: true });
+        const pending = Promise.resolve().then(() => callback(controller.signal));
+        const terminal = Promise.withResolvers();
+        const rejectTerminal = () => {
+            terminal.reject(controller.signal.reason ??
+                new ClientProtocolError("subscription reauthentication aborted."));
+        };
+        controller.signal.addEventListener("abort", rejectTerminal, { once: true });
+        try {
+            await Promise.race([pending, terminal.promise]);
+            this.assertOpen();
+        }
+        finally {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            controller.signal.removeEventListener("abort", rejectTerminal);
+            void pending.catch(() => undefined);
+        }
+    }
+    async run(signal, work) {
+        this.assertOpen();
+        if (signal?.aborted)
+            throw signal.reason;
+        const controller = new AbortController();
+        const abort = () => {
+            controller.abort(signal?.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        this.#controllers.add(controller);
+        try {
+            const result = await work(controller.signal);
+            this.assertOpen();
+            return result;
+        }
+        finally {
+            this.#controllers.delete(controller);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async close() {
+        return (this.#close ??= this.closeOwned());
+    }
+    add(subscription) {
+        this.assertOpen();
+        this.#subscriptions.add(subscription);
+    }
+    remove(subscription) {
+        this.#subscriptions.delete(subscription);
+    }
+    assertOpen() {
+        if (this.#closed)
+            throw new ClientProtocolError("client is closing.");
+    }
+    async closeOwned() {
+        this.#closed = true;
+        for (const controller of this.#controllers)
+            controller.abort();
+        const failures = [];
+        try {
+            const settled = await Promise.allSettled([...this.#subscriptions].map((subscription) => subscription.cancel()));
+            for (const result of settled)
+                if (result.status === "rejected")
+                    failures.push(result.reason);
+        }
+        finally {
+            try {
+                this.#source.close?.();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, `Client close cleanup failed: ${failures.map((failure) => String(failure)).join("; ")}`);
+    }
+}
+class TopicSubscription {
+    #owner;
+    #topic;
+    #signal;
+    /**
+     * Subscription kind and optional authoritative Entity recovery query.
+     */
+    #options;
+    /**
+     * Validated bounded-queue, retry, and scheduler settings.
+     */
+    #runtime;
+    #updates;
+    #lifecycle;
+    #controller = new AbortController();
+    #wire;
+    #cancelled = false;
+    #generation = 0;
+    #terminal = false;
+    #wireCleanup;
+    #activation;
+    #cancellation;
+    #streamIterator;
+    #retryAttempt = 0;
+    #retryStartedAt;
+    #connectedAt;
+    constructor(owner, topic, signal, options, runtime) {
+        this.#owner = owner;
+        this.#topic = topic;
+        this.#signal = signal;
+        this.#options = options;
+        this.#runtime = runtime;
+        this.#updates = new BrowserClientValues.BoundedChannel("subscription update", runtime.updateCapacity, runtime.updateByteCapacity);
+        this.#lifecycle = new BrowserClientValues.BoundedChannel("subscription lifecycle", runtime.lifecycleCapacity);
+        owner.add(this);
+    }
+    get updates() {
+        return this.#updates;
+    }
+    get lifecycle() {
+        return this.#lifecycle;
+    }
+    async activate(options = {}) {
+        this.#owner.assertOpen();
+        if (this.#cancelled)
+            throw new ClientProtocolError("subscription is cancelled.");
+        await (this.#activation ??= this.#activateOwned(options.signal));
+    }
+    cancel() {
+        return (this.#cancellation ??= this.#cancelOwned());
+    }
+    async #activateOwned(signal) {
+        if (signal?.aborted)
+            throw signal.reason;
+        if (this.#signal.aborted)
+            throw this.#signal.reason;
+        const generation = ++this.#generation;
+        const abort = () => {
+            this.#controller.abort(signal?.reason ?? this.#signal.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        this.#signal.addEventListener("abort", abort, { once: true });
+        try {
+            this.#pushLifecycle({ state: "connecting", generation, attempt: 0 });
+            const pendingSubscription = createClient(SubscriptionService, this.#owner.transport).subscribe(this.#topic, { signal: this.#controller.signal });
+            const subscription = await ClientTerminalValues.raceTerminal(pendingSubscription, this.#controller.signal, () => {
+                ClientTerminalValues.cancelLateSubscription(pendingSubscription, this.#owner.transport);
+            });
+            this.#wire = subscription;
+            BrowserClientValues.validateSubscription(subscription, this.#topic, true);
+            if (generation !== this.#generation) {
+                await this.#cancelWireOnce(subscription);
+                throw new ClientProtocolError("subscription is cancelled.");
+            }
+            const updates = createClient(SubscriptionService, this.#owner.transport).activate(subscription, {
+                signal: this.#controller.signal,
+            });
+            const iterator = updates[Symbol.asyncIterator]();
+            this.#streamIterator = iterator;
+            void this.consumeUpdates(iterator, subscription, generation).catch(() => undefined);
+            if (this.#cancelled || generation !== this.#generation) {
+                await this.#cancelWireOnce(subscription);
+                throw new ClientProtocolError("subscription is cancelled.");
+            }
+            this.#pushLifecycle({ state: "connected", generation });
+            this.#connectedAt = this.#runtime.scheduler.now();
+        }
+        catch (error) {
+            if (this.#cancelled)
+                throw error;
+            if (this.#retryable(error) && this.#canRetry()) {
+                await this.#recover(error, this.#wire);
+                return;
+            }
+            this.#failStreams(error, generation);
+            let cleanupFailure;
+            try {
+                if (this.#wire !== undefined)
+                    await this.#cancelWireOnce(this.#wire);
+            }
+            catch (cleanupError) {
+                cleanupFailure = cleanupError;
+            }
+            finally {
+                this.#cancelled = true;
+                this.#owner.remove(this);
+            }
+            if (cleanupFailure !== undefined)
+                throw new AggregateError([error, cleanupFailure], "Subscription activation cleanup failed.");
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+            this.#signal.removeEventListener("abort", abort);
+        }
+    }
+    async #cancelOwned() {
+        this.#cancelled = true;
+        this.#generation++;
+        this.#updates.discard();
+        this.#finishLifecycle({ state: "closed", generation: this.#generation - 1 });
+        this.#controller.abort();
+        await this.#disposeLateIterator();
+        try {
+            if (this.#wire !== undefined)
+                await this.#cancelWireOnce(this.#wire);
+        }
+        finally {
+            this.#owner.remove(this);
+        }
+    }
+    async consumeUpdates(updates, subscription, generation) {
+        let recovering = false;
+        try {
+            for (;;) {
+                const next = await ClientTerminalValues.raceTerminal(updates.next(), this.#controller.signal);
+                if (next.done)
+                    throw new SubscriptionStreamEndedError("subscription stream ended unexpectedly.");
+                if (this.#cancelled || generation !== this.#generation)
+                    return;
+                const update = next.value;
+                const topic = subscription.topic;
+                if (topic === undefined)
+                    throw new ClientProtocolError("accepted subscription topic is missing.");
+                BrowserClientValues.validateSubscription(update.subscription, topic, true);
+                if (update.subscription?.id?.value !== subscription.id?.value)
+                    throw new ClientProtocolError("subscription update ID does not match the accepted subscription.");
+                if (update.response?.status?.status.case === "error" &&
+                    update.response.status.status.value.type === "backend-unavailable" &&
+                    update.update.case === undefined) {
+                    this.#pushLifecycle({ state: "gapPossible", generation });
+                    continue;
+                }
+                const delivery = BrowserClientValues.freezeDelivery({
+                    kind: "update",
+                    update: clone(SubscriptionUpdateSchema, update),
+                });
+                const bytes = toBinary(SubscriptionUpdateSchema, update).byteLength;
+                this.#pushUpdate(delivery, bytes);
+            }
+        }
+        catch (error) {
+            if (this.#cancelled)
+                return;
+            if (this.#retryable(error) && this.#canRetry()) {
+                recovering = true;
+                void this.#recover(error, subscription).catch(() => undefined);
+                return;
+            }
+            this.#failStreams(error, generation);
+            try {
+                await this.#cancelAfterFailure();
+            }
+            catch {
+                // The stream's original terminal error remains observable; cleanup is best effort.
+            }
+        }
+        finally {
+            if (!recovering) {
+                this.#updates.close();
+                this.#lifecycle.close();
+                this.#owner.remove(this);
+                if (this.#streamIterator === updates)
+                    this.#streamIterator = undefined;
+            }
+        }
+    }
+    #retryable(error) {
+        return (error instanceof SubscriptionStreamEndedError ||
+            (error instanceof Error && !(error instanceof ClientProtocolError)));
+    }
+    #canRetry() {
+        const now = this.#runtime.scheduler.now();
+        const connectedAt = this.#connectedAt;
+        this.#connectedAt = undefined;
+        if (connectedAt !== undefined && now - connectedAt >= this.#runtime.retryPolicy.maxElapsedMs) {
+            this.#retryAttempt = 0;
+            this.#retryStartedAt = undefined;
+        }
+        this.#retryStartedAt ??= now;
+        return this.#retryAttempt < this.#runtime.retryPolicy.maxAttempts && !this.#elapsed();
+    }
+    #elapsed() {
+        return (this.#runtime.scheduler.now() - (this.#retryStartedAt ?? 0) >=
+            this.#runtime.retryPolicy.maxElapsedMs);
+    }
+    async #recover(error, previousWire) {
+        let failure = error;
+        let wire = previousWire;
+        let generation = this.#generation;
+        try {
+            while (this.#retryable(failure) && this.#canRetry()) {
+                const attempt = ++this.#retryAttempt;
+                generation = ++this.#generation;
+                await this.#disposeLateIterator();
+                if (wire !== undefined)
+                    await this.#cancelWireOnce(wire);
+                const delay = this.#runtime.retryPolicy.delayMs(attempt);
+                if (!Number.isSafeInteger(delay) || delay <= 0)
+                    throw new ClientProtocolError("subscription retry delay must be a positive safe integer.");
+                await ClientTerminalValues.raceTerminal(this.#runtime.scheduler.wait(delay, this.#controller.signal), this.#controller.signal);
+                if (this.#controller.signal.aborted)
+                    throw this.#controller.signal.reason;
+                if (this.#elapsed())
+                    throw failure;
+                await ClientTerminalValues.raceTerminal(this.#owner.onReauthenticateBeforeReconnect(this.#controller.signal, this.#remainingRetryMs()), this.#controller.signal);
+                if (this.#elapsed())
+                    throw failure;
+                this.#pushLifecycle({ state: "connecting", generation, attempt });
+                try {
+                    const pending = createClient(SubscriptionService, this.#owner.transport).subscribe(this.#topic, { signal: this.#controller.signal });
+                    const subscription = await ClientTerminalValues.raceTerminal(pending, this.#controller.signal, () => {
+                        ClientTerminalValues.cancelLateSubscription(pending, this.#owner.transport);
+                    });
+                    this.#wire = subscription;
+                    BrowserClientValues.validateSubscription(subscription, this.#topic, true);
+                    const updates = createClient(SubscriptionService, this.#owner.transport).activate(subscription, { signal: this.#controller.signal });
+                    const iterator = updates[Symbol.asyncIterator]();
+                    this.#streamIterator = iterator;
+                    if (this.#options.kind === "entity")
+                        await this.#resynchronize(generation);
+                    void this.consumeUpdates(iterator, subscription, generation).catch(() => undefined);
+                    if (this.#options.kind === "event")
+                        this.#pushLifecycle({ state: "gapPossible", generation });
+                    this.#pushLifecycle({ state: "connected", generation });
+                    this.#connectedAt = this.#runtime.scheduler.now();
+                    return;
+                }
+                catch (retryFailure) {
+                    failure = retryFailure;
+                    wire = this.#wire;
+                }
+            }
+            throw failure;
+        }
+        catch (recoveryError) {
+            if (this.#cancelled)
+                throw recoveryError;
+            const terminalError = recoveryError instanceof Error ? recoveryError : error;
+            await this.#disposeLateIterator();
+            this.#failStreams(terminalError, generation);
+            try {
+                await this.#cancelAfterFailure();
+            }
+            catch {
+                // The terminal failure remains observable when cleanup fails.
+            }
+            finally {
+                this.#updates.close();
+                this.#lifecycle.close();
+                this.#owner.remove(this);
+            }
+            throw terminalError;
+        }
+    }
+    #remainingRetryMs() {
+        const elapsed = this.#runtime.scheduler.now() - (this.#retryStartedAt ?? 0);
+        const remaining = this.#runtime.retryPolicy.maxElapsedMs - elapsed;
+        if (!Number.isSafeInteger(remaining) || remaining <= 0)
+            throw new ClientProtocolError("subscription reauthentication retry deadline is exhausted.");
+        return remaining;
+    }
+    async #resynchronize(generation) {
+        let query;
+        try {
+            const source = this.#options.kind === "entity" ? this.#options.authoritativeQuery() : undefined;
+            if (source === undefined)
+                throw new Error("entity recovery query is missing.");
+            query = clone(QuerySchema, "build" in source ? source.build() : source);
+        }
+        catch (error) {
+            throw new ClientProtocolError(`authoritative query could not be prepared: ${String(error)}`);
+        }
+        if (!BrowserClientValues.sameTarget(query.target, this.#topic.target))
+            throw new ClientProtocolError("authoritative query target does not match the subscription topic.");
+        const topicContext = this.#topic.context;
+        if (topicContext === undefined)
+            throw new ClientProtocolError("subscription topic context is missing.");
+        query.context = clone(ActorContextSchema, topicContext);
+        this.#pushLifecycle({ state: "resynchronizing", generation });
+        const pending = createClient(QueryService, this.#owner.transport).read(query, {
+            signal: this.#controller.signal,
+        });
+        const response = await ClientTerminalValues.raceTerminal(pending, this.#controller.signal);
+        if (response.response?.status?.status.case !== "ok")
+            throw new ClientProtocolError("authoritative query response is not OK.");
+        if (this.#cancelled || generation !== this.#generation)
+            return;
+        this.#pushUpdate(BrowserClientValues.freezeResynchronization({
+            kind: "resynchronization",
+            response: clone(QueryResponseSchema, response),
+        }), toBinary(QueryResponseSchema, response).byteLength);
+    }
+    async #cancelAfterFailure() {
+        this.#cancelled = true;
+        try {
+            if (this.#wire !== undefined)
+                await this.#cancelWireOnce(this.#wire);
+        }
+        finally {
+            this.#owner.remove(this);
+        }
+    }
+    #pushUpdate(value, bytes) {
+        const error = this.#updates.push(value, bytes);
+        if (error !== undefined)
+            throw error;
+    }
+    #pushLifecycle(value) {
+        const error = this.#lifecycle.push(value);
+        if (error !== undefined)
+            throw error;
+    }
+    #failStreams(error, generation) {
+        const terminalError = error instanceof Error ? error : new Error(String(error));
+        this.#updates.fail(terminalError);
+        if (terminalError instanceof SubscriptionBufferOverflowError) {
+            this.#terminal = true;
+            this.#lifecycle.fail(terminalError);
+            return;
+        }
+        if (this.#terminal)
+            return;
+        this.#terminal = true;
+        this.#finishLifecycle({
+            state: "failed",
+            generation,
+            error: terminalError,
+        });
+    }
+    #finishLifecycle(value) {
+        if (this.#terminal && value.state === "closed")
+            return;
+        this.#terminal = true;
+        this.#lifecycle.finish(value);
+    }
+    #cancelWireOnce(subscription) {
+        if (this.#wireCleanup?.wire === subscription)
+            return this.#wireCleanup.promise;
+        const promise = ClientTerminalValues.cancelWire(this.#owner.transport, subscription);
+        this.#wireCleanup = { wire: subscription, promise };
+        return promise;
+    }
+    async #disposeLateIterator() {
+        const iterator = this.#streamIterator;
+        if (iterator === undefined)
+            return;
+        this.#streamIterator = undefined;
+        try {
+            let timeout;
+            try {
+                await Promise.race([
+                    Promise.resolve(iterator.return?.()).catch(() => undefined),
+                    new Promise((resolve) => {
+                        timeout = setTimeout(resolve, CLEANUP_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+            }
+        }
+        catch {
+            // Local terminal state must not depend on a non-cooperative iterator.
+        }
+    }
+}
+const CLEANUP_TIMEOUT_MS = 1_000;
+const ClientTerminalValues = Object.freeze({
+    raceTerminal(pending, signal, onTerminal) {
+        if (signal.aborted) {
+            void pending.catch(() => undefined);
+            onTerminal?.();
+            return Promise.reject(ClientTerminalValues.abortError(signal));
+        }
+        const terminal = Promise.withResolvers();
+        const abort = () => {
+            terminal.reject(ClientTerminalValues.abortError(signal));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        return Promise.race([pending, terminal.promise])
+            .catch((error) => {
+            if (signal.aborted)
+                onTerminal?.();
+            throw error;
+        })
+            .finally(() => {
+            signal.removeEventListener("abort", abort);
+        });
+    },
+    abortError(signal) {
+        const reason = signal.reason;
+        if (reason instanceof Error)
+            return reason;
+        if (typeof reason === "string")
+            return new Error(reason);
+        if (typeof reason === "number" || typeof reason === "boolean" || typeof reason === "bigint")
+            return new Error(String(reason));
+        return new Error("operation aborted.");
+    },
+    /**
+     * Cancels a wire accepted after its local subscription has already terminated.
+     */
+    cancelLateSubscription(pending, transport) {
+        void pending
+            .then((subscription) => ClientTerminalValues.cancelWire(transport, subscription))
+            .catch(() => undefined);
+    },
+    async cancelWire(transport, subscription) {
+        const controller = new AbortController();
+        let timeout;
+        const timedOut = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                reject(new ClientProtocolError("subscription cleanup timed out."));
+            }, CLEANUP_TIMEOUT_MS);
+        });
+        const remote = createClient(SubscriptionService, transport).cancel(subscription, {
+            signal: controller.signal,
+        });
+        void remote.catch(() => undefined);
+        try {
+            await Promise.race([remote, timedOut]);
+        }
+        finally {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+        }
+    },
+});
+/**
+ * Builds browser-client request, subscription, and immutable wire values.
+ */
+const BrowserClientValues = Object.freeze({
+    subscriptionRuntimeOptions(options) {
+        return {
+            updateCapacity: BrowserClientValues.positiveSubscriptionOption(options?.updateBufferCapacity, 64, "update buffer capacity"),
+            updateByteCapacity: BrowserClientValues.positiveSubscriptionOption(options?.updateBufferByteCapacity, 1_048_576, "update buffer byte capacity"),
+            lifecycleCapacity: BrowserClientValues.positiveSubscriptionOption(options?.lifecycleBufferCapacity, 32, "lifecycle buffer capacity"),
+            retryPolicy: BrowserClientValues.retryPolicy(options?.retryPolicy),
+            scheduler: BrowserClientValues.scheduler(options?.scheduler),
+        };
+    },
+    DEFAULT_RETRY_POLICY: {
+        maxAttempts: 5,
+        maxElapsedMs: 30_000,
+        delayMs(attempt) {
+            const bounded = Math.min(5_000, 250 * 2 ** Math.max(0, attempt - 1));
+            return Math.min(5_000, Math.max(1, Math.round(bounded * (0.8 + Math.random() * 0.4))));
+        },
+    },
+    DEFAULT_SUBSCRIPTION_SCHEDULER: {
+        now: () => Date.now(),
+        wait: (delayMs, signal) => new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(ClientTerminalValues.abortError(signal));
+                return;
+            }
+            const timeout = setTimeout(resolve, delayMs);
+            signal.addEventListener("abort", () => {
+                clearTimeout(timeout);
+                reject(ClientTerminalValues.abortError(signal));
+            }, { once: true });
+        }),
+    },
+    retryPolicy(policy) {
+        const resolved = policy ?? BrowserClientValues.DEFAULT_RETRY_POLICY;
+        if (!Number.isSafeInteger(resolved.maxAttempts) || resolved.maxAttempts <= 0)
+            throw new TypeError("Client subscription retry max attempts must be a positive safe integer.");
+        if (!Number.isSafeInteger(resolved.maxElapsedMs) || resolved.maxElapsedMs <= 0)
+            throw new TypeError("Client subscription retry max elapsed time must be a positive safe integer.");
+        if (typeof resolved.delayMs !== "function")
+            throw new TypeError("Client subscription retry delay must be a function.");
+        for (let attempt = 1; attempt <= resolved.maxAttempts; attempt++) {
+            const delay = resolved.delayMs(attempt);
+            if (!Number.isSafeInteger(delay) || delay <= 0)
+                throw new TypeError("Client subscription retry delay must be a positive safe integer.");
+        }
+        return resolved;
+    },
+    scheduler(scheduler) {
+        const resolved = scheduler ?? BrowserClientValues.DEFAULT_SUBSCRIPTION_SCHEDULER;
+        if (typeof resolved.now !== "function" || typeof resolved.wait !== "function")
+            throw new TypeError("Client subscription scheduler must provide now() and wait().");
+        const now = resolved.now();
+        if (!Number.isSafeInteger(now) || now < 0)
+            throw new TypeError("Client subscription scheduler time must be a non-negative safe integer.");
+        return resolved;
+    },
+    positiveSubscriptionOption(value, fallback, name) {
+        const resolved = value ?? fallback;
+        if (!Number.isSafeInteger(resolved) || resolved <= 0)
+            throw new TypeError(`Client subscription ${name} must be a positive safe integer.`);
+        return resolved;
+    },
+    validateSubscriptionOptions(options) {
+        if (options === null ||
+            typeof options !== "object" ||
+            !("kind" in options) ||
+            (options.kind !== "event" && options.kind !== "entity"))
+            throw new TypeError("Subscription kind must be 'event' or 'entity'.");
+        if (options.kind === "event") {
+            if ("authoritativeQuery" in options)
+                throw new TypeError("Event subscriptions must not provide an authoritative query.");
+            return options;
+        }
+        if (!("authoritativeQuery" in options) || typeof options.authoritativeQuery !== "function")
+            throw new TypeError("Entity subscriptions require an authoritative query.");
+        return options;
+    },
+    BoundedChannel: class BoundedChannel {
+        #name;
+        #capacity;
+        #byteCapacity;
+        #values = [];
+        #bytes = 0;
+        #consumer = false;
+        #closed = false;
+        #error;
+        #pending;
+        constructor(name, capacity, byteCapacity) {
+            this.#name = name;
+            this.#capacity = capacity;
+            this.#byteCapacity = byteCapacity;
+        }
+        push(value, bytes = 0) {
+            if (this.#closed || this.#error !== undefined)
+                return new ClientProtocolError(`${this.#name} stream is closed.`);
+            if (this.#values.length >= this.#capacity ||
+                this.#bytes + bytes > (this.#byteCapacity ?? Infinity)) {
+                return new SubscriptionBufferOverflowError(`${this.#name} buffer overflow.`);
+            }
+            if (this.#pending !== undefined) {
+                this.#pending.resolve({ done: false, value });
+                this.#pending = undefined;
+                return undefined;
+            }
+            this.#values.push({ value, bytes });
+            this.#bytes += bytes;
+            return undefined;
+        }
+        /**
+         * Ends after already accepted values have been consumed.
+         */
+        close() {
+            this.#closed = true;
+            if (this.#values.length === 0 && this.#error === undefined) {
+                this.#pending?.resolve({ done: true, value: undefined });
+                this.#pending = undefined;
+            }
+        }
+        /**
+         * Discards buffered values for explicit local cancellation.
+         */
+        discard() {
+            this.#closed = true;
+            this.#values.length = 0;
+            this.#bytes = 0;
+            if (this.#error === undefined) {
+                this.#pending?.resolve({ done: true, value: undefined });
+                this.#pending = undefined;
+            }
+        }
+        /**
+         * Appends one terminal notice after the configured non-terminal capacity, then ends.
+         * The terminal slot is bounded and never displaces an admitted lifecycle notice.
+         */
+        finish(value) {
+            if (this.#error !== undefined)
+                return;
+            this.#closed = true;
+            if (this.#pending !== undefined) {
+                this.#pending.resolve({ done: false, value });
+                this.#pending = undefined;
+                return;
+            }
+            this.#values.push({ value, bytes: 0 });
+        }
+        fail(error) {
+            if (this.#error !== undefined)
+                return;
+            this.#error = error;
+            this.#values.length = 0;
+            this.#pending?.reject(error);
+            this.#pending = undefined;
+        }
+        [Symbol.asyncIterator]() {
+            if (this.#consumer)
+                throw new ClientProtocolError(`${this.#name} stream has a single consumer.`);
+            this.#consumer = true;
+            return { next: () => this.next() };
+        }
+        next() {
+            if (this.#error !== undefined)
+                return Promise.reject(this.#error);
+            const entry = this.#values.shift();
+            if (entry !== undefined) {
+                this.#bytes -= entry.bytes;
+                return Promise.resolve({ done: false, value: entry.value });
+            }
+            if (this.#closed)
+                return Promise.resolve({ done: true, value: undefined });
+            if (this.#pending !== undefined)
+                return Promise.reject(new ClientProtocolError(`${this.#name} stream allows only one pending next() call.`));
+            this.#pending = Promise.withResolvers();
+            return this.#pending.promise;
+        }
+    },
+    freezeDelivery(delivery) {
+        return Object.freeze({ ...delivery, update: BrowserClientValues.deepFreeze(delivery.update) });
+    },
+    freezeResynchronization(delivery) {
+        return Object.freeze({
+            ...delivery,
+            response: BrowserClientValues.deepFreeze(delivery.response),
+        });
+    },
+    deepFreeze(value) {
+        if (value === null || typeof value !== "object" || ArrayBuffer.isView(value))
+            return value;
+        for (const child of Object.values(value))
+            BrowserClientValues.deepFreeze(child);
+        return Object.freeze(value);
+    },
+    browserSource(transport) {
+        return { transport, createRequestId: BrowserClientValues.browserRequestId };
+    },
+    browserTransportOptions(baseUrl, options) {
+        return {
+            baseUrl,
+            interceptors: options.onRequestMetadata === undefined
+                ? []
+                : [BrowserClientValues.requestMetadata(options.onRequestMetadata)],
+            ...(options.credentials === undefined
+                ? {}
+                : { fetch: BrowserClientValues.credentialedFetch(options.credentials) }),
+        };
+    },
+    credentialedFetch(credentials) {
+        if (credentials !== "omit" && credentials !== "same-origin" && credentials !== "include")
+            throw new TypeError("Browser Fetch credentials must be omit, same-origin, or include.");
+        return (input, init) => globalThis.fetch(input, { ...init, credentials });
+    },
+    requestMetadata(onRequestMetadata) {
+        return (next) => async (request) => {
+            const metadata = new Headers(onRequestMetadata());
+            for (const [name, value] of metadata)
+                request.header.set(name, value);
+            return next(request);
+        };
+    },
+    browserRequestId() {
+        const crypto = globalThis.crypto;
+        if (!BrowserClientValues.isBrowserCrypto(crypto))
+            throw new ClientProtocolError("secure random browser API is unavailable for request IDs.");
+        if (typeof crypto.randomUUID === "function")
+            return crypto.randomUUID();
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+        bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+        const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    },
+    isBrowserCrypto(value) {
+        return (value !== null &&
+            typeof value === "object" &&
+            "getRandomValues" in value &&
+            typeof value.getRandomValues === "function");
+    },
+    cloneTopic(topic, context) {
+        const prepared = structuredClone(topic);
+        prepared.context = context;
+        return prepared;
+    },
+    validateSubscription(subscription, expectedTopic, allowRewrittenContext = false) {
+        if (subscription === undefined || subscription.id?.value.length === 0)
+            throw new ClientProtocolError("subscription ID is missing or invalid.");
+        if (subscription.topic === undefined ||
+            !BrowserClientValues.sameTopic(subscription.topic, expectedTopic, allowRewrittenContext))
+            throw new ClientProtocolError("subscription topic does not match the requested topic.");
+    },
+    sameTopic(left, right, ignoreContext = false) {
+        if (ignoreContext) {
+            left = { ...left, context: undefined };
+            right = { ...right, context: undefined };
+        }
+        const a = toBinary(TopicSchema, left);
+        const b = toBinary(TopicSchema, right);
+        return a.length === b.length && a.every((value, index) => value === b[index]);
+    },
+    sameTarget(left, right) {
+        if (left === undefined || right === undefined)
+            return left === right;
+        const a = toBinary(TargetSchema, left);
+        const b = toBinary(TargetSchema, right);
+        return a.length === b.length && a.every((value, index) => value === b[index]);
+    },
+    tenant(value) {
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string") {
+            if (value.kind.case !== "value" || value.kind.value.length === 0)
+                throw new TypeError("Client tenant must not be empty.");
+            return clone(TenantIdSchema, value);
+        }
+        if (value.length === 0)
+            throw new TypeError("Client tenant must not be empty.");
+        return create(TenantIdSchema, { kind: { case: "value", value } });
+    },
+    zoneId(value) {
+        if (typeof value !== "string" && value !== undefined) {
+            if (value.value.length === 0)
+                throw new TypeError("Client zoneId must not be empty.");
+            return clone(ZoneIdSchema, value);
+        }
+        const zone = value ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (zone.length === 0)
+            throw new TypeError("Client zoneId must not be empty.");
+        return create(ZoneIdSchema, { value: zone });
+    },
+    outcome(status) {
+        if (status?.case === "ok")
+            return Object.freeze({ kind: "ok" });
+        if (status?.case === "error")
+            return Object.freeze({
+                kind: "error",
+                error: BrowserClientValues.cloneMessage(status.value),
+            });
+        if (status?.case === "rejection")
+            return Object.freeze({
+                kind: "rejection",
+                rejection: BrowserClientValues.cloneMessage(status.value),
+            });
+        throw new ClientProtocolError("response status is missing or invalid.");
+    },
+    validateAckId(packed, id) {
+        const commandId = packed === undefined ? undefined : AnyMessages.unpack(packed, CommandIdSchema);
+        if (commandId?.uuid !== id)
+            throw new ClientProtocolError("acknowledgement command ID does not match the posted command.");
+    },
+    cloneMessage(message) {
+        return structuredClone(message);
+    },
+});
+//# sourceMappingURL=client.js.map