@my-swu/simulator-client 0.1.0

package/dist/match-session/controller.js

@@ -0,0 +1,513 @@
+import { MatchConnection } from '../connection.js';
+import { TypedEmitter } from '../internal/emitter.js';
+import { DEFAULT_ERROR_HISTORY_LIMIT, DEFAULT_MATCH_HISTORY_LIMIT } from '../internal/limits.js';
+import { nonNegativeNumber, normalizeReconnectBackoff, reconnectDelayMs, } from '../internal/reconnect-backoff.js';
+import { hasAccessSnapshot, matchReferenceFrom } from './access.js';
+import { errorPayloadFromUnknown } from './errors.js';
+const DEFAULT_EVENT_HISTORY_LIMIT = 50;
+const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 5_000;
+const DEFAULT_RECONNECT_MAX_RETRIES = 5;
+const DEFAULT_RECONNECT_BACKOFF_FACTOR = 2;
+/** SDK-owned live match session implementation. */
+export class MatchSessionController {
+    /**
+     * Vue reactivity opt-out. The controller relies on `#private` class fields
+     * which are unreachable through a `Proxy`, so Vue must not wrap it. This
+     * is Vue's documented escape hatch (`ReactiveFlags.SKIP`) and is a no-op
+     * in non-Vue runtimes.
+     */
+    __v_skip = true;
+    #defaultConnectOptions;
+    #emitter = new TypedEmitter();
+    #maxErrorHistory;
+    #maxEventHistory;
+    #matches;
+    #openConnection;
+    #autoReconnect;
+    #access;
+    #connection;
+    #connectionState = 'idle';
+    #aiStatus;
+    #detachConnection = [];
+    #errors = [];
+    #events = [];
+    #history = [];
+    #matchId;
+    #snapshot;
+    #seat;
+    #welcome;
+    #manualClose = false;
+    #reconnectGeneration = 0;
+    #reconnectState = { phase: 'idle' };
+    #reconnectTimer;
+    /** Creates one match session controller. */
+    constructor(options) {
+        this.#matches = options.matches;
+        this.#openConnection = options.openConnection;
+        this.#defaultConnectOptions = {
+            ...(options.options?.handshakeTimeoutMs == null ? {} : { handshakeTimeoutMs: options.options.handshakeTimeoutMs }),
+        };
+        this.#autoReconnect = normalizeAutoReconnect(options.options?.autoReconnect);
+        this.#maxEventHistory = options.options?.maxEventHistory ?? DEFAULT_EVENT_HISTORY_LIMIT;
+        this.#maxErrorHistory = options.options?.maxErrorHistory ?? DEFAULT_ERROR_HISTORY_LIMIT;
+        if (options.access != null) {
+            this.#storeAccess(options.access);
+        }
+    }
+    get connectionState() {
+        return this.#connectionState;
+    }
+    get aiStatus() {
+        return this.#aiStatus;
+    }
+    get errors() {
+        return [...this.#errors];
+    }
+    get events() {
+        return [...this.#events];
+    }
+    get history() {
+        return [...this.#history];
+    }
+    get errorMessages() {
+        return this.#errors.map(error => `${error.code} - ${error.message}`);
+    }
+    get matchId() {
+        return this.#matchId;
+    }
+    get reconnectState() {
+        return this.#reconnectState;
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    get seat() {
+        return this.#seat;
+    }
+    get state() {
+        return {
+            ...(this.#aiStatus == null ? {} : { aiStatus: this.#aiStatus }),
+            connectionState: this.#connectionState,
+            errors: this.errors,
+            errorMessages: this.errorMessages,
+            events: this.events,
+            history: this.history,
+            ...(this.#matchId == null ? {} : { matchId: this.#matchId }),
+            reconnectState: this.#reconnectState,
+            ...(this.#snapshot == null ? {} : { snapshot: this.#snapshot }),
+            ...(this.#seat == null ? {} : { seat: this.#seat }),
+            ...(this.#welcome == null ? {} : { welcome: this.#welcome }),
+        };
+    }
+    get welcome() {
+        return this.#welcome;
+    }
+    async connect(access, options = {}) {
+        this.#cancelAutoReconnect();
+        this.#manualClose = false;
+        const connectOptions = { ...this.#defaultConnectOptions, ...options };
+        if (access != null) {
+            this.#resetMatchState();
+            this.#storeAccess(access);
+        }
+        if (this.#access == null) {
+            const error = new Error('match session has no access');
+            this.#recordError(errorPayloadFromUnknown(error));
+            throw error;
+        }
+        // Keep an already-open socket alive through the replacement handshake.
+        // The server sees the new lease before this one drops, so a manual sync
+        // replacement remains one logical presence instead of disconnect/reconnect.
+        const previousConnection = this.#connection;
+        const previousDetachers = this.#detachConnection;
+        this.#setConnectionState('connecting');
+        try {
+            const connection = await this.#openConnection(this.#access, connectOptions);
+            if (previousConnection != null) {
+                for (const detach of previousDetachers) {
+                    detach();
+                }
+                this.#detachConnection = [];
+                previousConnection.close();
+            }
+            this.#connection = connection;
+            this.#attachConnection(connection);
+            this.#setConnectionState(connection.connectionState);
+            this.#seedFromConnection(connection);
+            return this;
+        }
+        catch (error) {
+            // A failed replacement leaves the old live connection usable.
+            this.#setConnectionState(previousConnection?.connectionState ?? 'closed');
+            this.#recordError(errorPayloadFromUnknown(error));
+            throw error;
+        }
+    }
+    async createMatch(request, options = {}) {
+        this.#resetMatchState();
+        let access;
+        try {
+            access = await this.#matches.create(request);
+        }
+        catch (error) {
+            this.#recordError(errorPayloadFromUnknown(error));
+            throw error;
+        }
+        this.#storeAccess(access);
+        await this.connect(undefined, options);
+        return access;
+    }
+    async joinMatch(match, request, options = {}) {
+        this.#resetMatchState();
+        let access;
+        try {
+            access = await this.#matches.join(matchReferenceFrom(match), request);
+        }
+        catch (error) {
+            this.#recordError(errorPayloadFromUnknown(error));
+            throw error;
+        }
+        this.#storeAccess(access);
+        await this.connect(undefined, options);
+        return access;
+    }
+    async spectateMatch(match, request, options = {}) {
+        this.#resetMatchState();
+        let access;
+        try {
+            access = await this.#matches.spectate(matchReferenceFrom(match), request);
+        }
+        catch (error) {
+            this.#recordError(errorPayloadFromUnknown(error));
+            throw error;
+        }
+        this.#storeAccess(access);
+        await this.connect(undefined, options);
+        return access;
+    }
+    close() {
+        this.#manualClose = true;
+        this.#cancelAutoReconnect();
+        this.#closeActiveConnection();
+        this.#setConnectionState('closed');
+    }
+    reconnect(options = {}) {
+        return this.connect(undefined, options);
+    }
+    ready() {
+        this.#activeConnection().ready();
+    }
+    undo() {
+        this.#activeConnection().undo();
+    }
+    respondUndo(approve) {
+        this.#activeConnection().respondUndo(approve);
+    }
+    setAiPaused(paused) {
+        this.#activeConnection().setAiPaused(paused);
+    }
+    sync() {
+        this.#activeConnection().sync();
+    }
+    ping(nonce) {
+        this.#activeConnection().ping(nonce);
+    }
+    sendCommand(command) {
+        this.#activeConnection().sendCommand(command);
+    }
+    sendFormatEvent(command) {
+        this.#activeConnection().sendFormatEvent(command);
+    }
+    sendAiFormatEvent(command) {
+        this.#activeConnection().sendAiFormatEvent(command);
+    }
+    sendChat(message) {
+        this.#activeConnection().sendChat(message);
+    }
+    sendInteractionCue(cue) {
+        this.#activeConnection().sendInteractionCue(cue);
+    }
+    on(event, listener) {
+        return this.#emitter.on(event, listener);
+    }
+    waitForSnapshot(predicate, options = {}) {
+        return this.#activeConnection().waitForSnapshot(predicate, options.timeoutMs == null ? {} : { timeoutMs: options.timeoutMs });
+    }
+    #activeConnection() {
+        if (this.#connection == null) {
+            throw new Error('match session is not connected');
+        }
+        return this.#connection;
+    }
+    #attachConnection(connection) {
+        this.#detachConnection = [
+            connection.on('connectionState', state => {
+                this.#setConnectionState(state);
+                if (state === 'closed') {
+                    this.#handleAbnormalClose(connection);
+                }
+            }),
+            connection.on('welcome', welcome => this.#setWelcome(welcome)),
+            connection.on('snapshot', snapshot => this.#setSnapshot(snapshot)),
+            connection.on('event', event => this.#recordEvent(event)),
+            connection.on('historySnapshot', snapshot => this.#setHistorySnapshot(snapshot)),
+            connection.on('historyEntry', entry => this.#recordHistoryEntry(entry)),
+            connection.on('interactionCue', cue => this.#emitInteractionCue(cue)),
+            connection.on('aiStatus', status => this.#setAiStatus(status)),
+            connection.on('error', error => this.#recordError(error)),
+            connection.on('message', message => this.#emitter.emit('message', message)),
+            connection.on('pong', pong => this.#emitter.emit('pong', pong)),
+        ];
+    }
+    #detachActiveConnection() {
+        for (const detach of this.#detachConnection) {
+            detach();
+        }
+        this.#detachConnection = [];
+    }
+    #closeActiveConnection() {
+        const activeConnection = this.#connection;
+        this.#detachActiveConnection();
+        this.#connection = undefined;
+        activeConnection?.close();
+    }
+    #cancelAutoReconnect() {
+        this.#reconnectGeneration += 1;
+        if (this.#reconnectTimer != null) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+        this.#setReconnectState({ phase: 'idle' });
+    }
+    #emitChange() {
+        this.#emitter.emit('change', this.state);
+    }
+    #recordError(error) {
+        // Bounded like the event feed: a flapping socket records one error per
+        // failed reconnect, so an uncapped buffer would grow for the whole session.
+        const errors = [...this.#errors, error];
+        this.#errors = this.#maxErrorHistory <= 0 ? [] : errors.slice(-this.#maxErrorHistory);
+        this.#emitter.emit('error', error);
+        this.#emitChange();
+    }
+    #recordEvent(event) {
+        const events = [...this.#events, event];
+        this.#events = this.#maxEventHistory <= 0 ? [] : events.slice(-this.#maxEventHistory);
+        this.#emitter.emit('event', event);
+        this.#emitChange();
+    }
+    #setHistorySnapshot(snapshot) {
+        this.#history = [...snapshot.entries];
+        this.#emitter.emit('historySnapshot', snapshot);
+        this.#emitChange();
+    }
+    #recordHistoryEntry(entry) {
+        const withoutDuplicate = this.#history.filter(existing => existing.id !== entry.id);
+        this.#history = [...withoutDuplicate, entry].slice(-DEFAULT_MATCH_HISTORY_LIMIT);
+        this.#emitter.emit('historyEntry', entry);
+        this.#emitChange();
+    }
+    #emitInteractionCue(cue) {
+        this.#emitter.emit('interactionCue', cue);
+    }
+    #resetMatchState() {
+        this.close();
+        this.#access = undefined;
+        this.#aiStatus = undefined;
+        this.#errors = [];
+        this.#events = [];
+        this.#history = [];
+        this.#matchId = undefined;
+        this.#snapshot = undefined;
+        this.#seat = undefined;
+        this.#welcome = undefined;
+        this.#setConnectionState('idle');
+        this.#emitChange();
+    }
+    #handleAbnormalClose(connection) {
+        if (this.#connection !== connection) {
+            return;
+        }
+        this.#detachActiveConnection();
+        this.#connection = undefined;
+        if (this.#manualClose || !this.#autoReconnect.enabled || this.#access == null) {
+            return;
+        }
+        this.#scheduleAutoReconnect(1, this.#reconnectGeneration);
+    }
+    #scheduleAutoReconnect(attempt, generation) {
+        if (attempt > this.#autoReconnect.maxRetries) {
+            this.#setReconnectState({
+                phase: 'exhausted',
+                attempts: this.#autoReconnect.maxRetries,
+                maxAttempts: this.#autoReconnect.maxRetries,
+            });
+            this.#recordError({
+                code: 'sdk_session_error',
+                message: 'automatic reconnect exhausted',
+            });
+            return;
+        }
+        const delayMs = reconnectDelayMs(this.#autoReconnect, attempt);
+        this.#setReconnectState({
+            phase: 'waiting',
+            attempt,
+            maxAttempts: this.#autoReconnect.maxRetries,
+            delayMs,
+        });
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            void this.#runAutoReconnectAttempt(attempt, generation);
+        }, delayMs);
+    }
+    async #runAutoReconnectAttempt(attempt, generation) {
+        if (generation !== this.#reconnectGeneration || this.#manualClose || this.#access == null) {
+            return;
+        }
+        this.#setReconnectState({
+            phase: 'connecting',
+            attempt,
+            maxAttempts: this.#autoReconnect.maxRetries,
+        });
+        this.#setConnectionState('connecting');
+        try {
+            const connection = await this.#openConnection(this.#access, this.#defaultConnectOptions);
+            if (generation !== this.#reconnectGeneration || this.#manualClose) {
+                connection.close();
+                return;
+            }
+            this.#connection = connection;
+            this.#attachConnection(connection);
+            this.#setConnectionState(connection.connectionState);
+            this.#seedFromConnection(connection);
+            this.#setReconnectState({ phase: 'idle' });
+            connection.sync();
+        }
+        catch (error) {
+            if (generation !== this.#reconnectGeneration || this.#manualClose) {
+                return;
+            }
+            if (attempt >= this.#autoReconnect.maxRetries) {
+                this.#recordError(errorPayloadFromUnknown(error));
+                this.#recordError({
+                    code: 'sdk_session_error',
+                    message: 'automatic reconnect exhausted',
+                });
+                this.#setReconnectState({
+                    phase: 'exhausted',
+                    attempts: attempt,
+                    maxAttempts: this.#autoReconnect.maxRetries,
+                });
+                this.#setConnectionState('closed');
+                return;
+            }
+            this.#setConnectionState('closed');
+            this.#scheduleAutoReconnect(attempt + 1, generation);
+        }
+    }
+    #seedFromConnection(connection) {
+        if (connection.aiStatus != null) {
+            this.#setAiStatus(connection.aiStatus);
+        }
+        if (connection.welcome != null) {
+            this.#setWelcome(connection.welcome);
+        }
+        if (connection.snapshot != null) {
+            this.#setSnapshot(connection.snapshot);
+        }
+        if (connection.historySnapshotReceived) {
+            // Empty recovery history is meaningful: consumers use this notification
+            // to baseline presence toasts before later live entries arrive.
+            this.#setHistorySnapshot({
+                snapshotRevision: connection.snapshotRevision,
+                entries: [...connection.history],
+            });
+        }
+    }
+    #setConnectionState(state) {
+        if (this.#connectionState === state) {
+            return;
+        }
+        this.#connectionState = state;
+        this.#emitter.emit('connectionState', state);
+        this.#emitChange();
+    }
+    #setReconnectState(state) {
+        if (sameReconnectState(this.#reconnectState, state)) {
+            return;
+        }
+        this.#reconnectState = state;
+        this.#emitter.emit('reconnectState', state);
+        this.#emitChange();
+    }
+    #setAiStatus(status) {
+        this.#aiStatus = status;
+        this.#emitter.emit('aiStatus', status);
+        this.#emitChange();
+    }
+    #setSnapshot(snapshot) {
+        this.#snapshot = snapshot;
+        this.#matchId = snapshot.matchId;
+        this.#emitter.emit('snapshot', snapshot);
+        this.#emitChange();
+    }
+    #setWelcome(welcome) {
+        this.#welcome = welcome;
+        this.#matchId = welcome.matchId;
+        this.#seat = welcome.seat ?? undefined;
+        this.#emitter.emit('welcome', welcome);
+        this.#emitChange();
+    }
+    #storeAccess(access) {
+        this.#access = 'spectatorToken' in access
+            ? {
+                matchId: access.matchId,
+                spectatorToken: access.spectatorToken,
+            }
+            : {
+                matchId: access.matchId,
+                seatToken: access.seatToken,
+            };
+        this.#matchId = access.matchId;
+        if (hasAccessSnapshot(access)) {
+            this.#seat = 'seat' in access ? access.seat : undefined;
+            this.#snapshot = access.snapshot;
+        }
+    }
+}
+function normalizeAutoReconnect(options) {
+    const policy = normalizeReconnectBackoff(options, {
+        enabled: false,
+        backoffFactor: DEFAULT_RECONNECT_BACKOFF_FACTOR,
+        initialDelayMs: DEFAULT_RECONNECT_INITIAL_DELAY_MS,
+        maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS,
+    });
+    const optionPolicy = options === true || options === false || options == null ? {} : options;
+    return {
+        ...policy,
+        maxRetries: Math.max(0, Math.floor(nonNegativeNumber(optionPolicy.maxRetries, DEFAULT_RECONNECT_MAX_RETRIES))),
+    };
+}
+function sameReconnectState(left, right) {
+    if (left.phase !== right.phase) {
+        return false;
+    }
+    switch (left.phase) {
+        case 'idle':
+            return true;
+        case 'waiting':
+            return right.phase === 'waiting'
+                && left.attempt === right.attempt
+                && left.maxAttempts === right.maxAttempts
+                && left.delayMs === right.delayMs;
+        case 'connecting':
+            return right.phase === 'connecting'
+                && left.attempt === right.attempt
+                && left.maxAttempts === right.maxAttempts;
+        case 'exhausted':
+            return right.phase === 'exhausted'
+                && left.attempts === right.attempts
+                && left.maxAttempts === right.maxAttempts;
+    }
+}

package/dist/match-session/errors.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorPayload } from '../generated/index.js';
+/** Converts arbitrary thrown values into renderable SDK error payloads. */
+export declare function errorPayloadFromUnknown(error: unknown): ErrorPayload;

package/dist/match-session/errors.js

@@ -0,0 +1,34 @@
+import { EngineHttpError, SimulatorSocketError, SdkValidationError, socketPayloadCodeForKind, } from '../internal/errors.js';
+/** Converts arbitrary thrown values into renderable SDK error payloads. */
+export function errorPayloadFromUnknown(error) {
+    if (error instanceof EngineHttpError) {
+        return {
+            code: error.code ?? 'sdk_http_error',
+            message: error.message,
+        };
+    }
+    if (error instanceof SimulatorSocketError) {
+        // A rejection close frame names the engine error that refused the socket;
+        // keep it so clients map the failure exactly like the HTTP equivalent.
+        return {
+            code: error.serverCode ?? socketPayloadCodeForKind(error.kind),
+            message: error.message,
+        };
+    }
+    if (error instanceof SdkValidationError) {
+        return {
+            code: 'sdk_validation_error',
+            message: error.message,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: 'sdk_session_error',
+            message: error.message,
+        };
+    }
+    return {
+        code: 'sdk_session_error',
+        message: String(error),
+    };
+}