@shiprev/server-sdk-node 0.0.0-stage → 0.1.0-beta.1

package/dist/client/connection-supervisor.js

@@ -0,0 +1,650 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionSupervisor = void 0;
+const token_verifier_1 = require("../auth/token-verifier");
+const degradation_1 = require("../mirror/degradation");
+const entitlement_mirror_1 = require("../mirror/entitlement-mirror");
+const event_stream_1 = require("../transport/event-stream");
+const http_transport_1 = require("../transport/http.transport");
+/** Retry interval while the instance refuses the API key (401 or 403 on the token exchange). */
+const REFUSED_RETRY_MS = 30_000;
+const BACKOFF_STEPS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
+const RENEW_AT = 0.8;
+const HEARTBEAT_TIMEOUT_FACTOR = 3;
+/** Shortest time between two renewals of the same entry. */
+const MIN_RENEWAL_SPACING_MS = 10_000;
+/** Wait before renewing an entry again after a renewal pull failed. */
+const RENEWAL_RETRY_MS = 30_000;
+function backoffDelay(step) {
+    const base = BACKOFF_STEPS_MS[Math.min(step, BACKOFF_STEPS_MS.length - 1)];
+    return Math.round(base * (0.8 + Math.random() * 0.4));
+}
+function unrefTimer(callback, ms) {
+    const timer = setTimeout(callback, Math.max(0, ms));
+    timer.unref();
+    return timer;
+}
+class ConnectionSupervisor {
+    host;
+    token = null;
+    tokenExpiresAt = 0;
+    projectId = null;
+    credentialRefused = false;
+    exchangeInFlight = null;
+    keysLoaded = false;
+    stream = null;
+    streams = new Set();
+    live = false;
+    running = false;
+    paused = false;
+    /** Bumped by stop, pause and start; work begun under an older generation drops its result. */
+    generation = 0;
+    connecting = null;
+    rotating = false;
+    backoffStep = 0;
+    renewalBackoffStep = 0;
+    /** When the next renewal is due (local clock), kept across a pause. */
+    renewDueAt = null;
+    renewTimer = null;
+    reconnectTimer = null;
+    watchdogTimer = null;
+    renewalTimer = null;
+    refillTargets = new Map();
+    refillsInFlight = new Set();
+    /** Per-organization pulls in flight, shared by refills, renewals and `refresh()`. */
+    organizationPulls = new Map();
+    /** Organizations whose last renewal pull failed, with the time a renewal may be tried again. */
+    renewalRetryAt = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    /** The machine token in use, or `null`. */
+    currentToken() {
+        return this.token;
+    }
+    /**
+     * Keys, token, stream (waiting for `ready`), then a full pull. Never throws: whatever fails is
+     * retried in the background.
+     */
+    async start() {
+        this.halt();
+        this.running = true;
+        this.paused = false;
+        this.keysLoaded = false;
+        const attempt = this.attempt(true);
+        this.connecting = attempt;
+        try {
+            await attempt;
+        }
+        finally {
+            if (this.connecting === attempt)
+                this.connecting = null;
+        }
+    }
+    /** Closes the stream and stops every timer. */
+    stop() {
+        this.running = false;
+        this.paused = false;
+        this.halt();
+    }
+    /** `setOnline(false)`: closes the stream and suspends supervision until `resume()`. */
+    pause() {
+        if (!this.running)
+            return;
+        this.paused = true;
+        this.halt();
+    }
+    /** `setOnline(true)`: resumes supervision; the next attempt corrects the state. */
+    resume() {
+        if (!this.running)
+            return;
+        if (this.paused) {
+            this.paused = false;
+            if (this.renewDueAt !== null) {
+                this.scheduleRenewal(this.renewDueAt - Date.now());
+            }
+        }
+        if (!this.live) {
+            void this.reconnect();
+        }
+    }
+    /** A token set by hand (`setM2MToken`): used as is, never renewed on a timer. */
+    injectToken(token) {
+        this.token = token;
+        this.tokenExpiresAt = (0, token_verifier_1.expiryOfToken)(token) ?? Number.POSITIVE_INFINITY;
+        const expectations = (0, token_verifier_1.expectationsFromMachineToken)(token);
+        if (expectations)
+            this.projectId = expectations.projectId;
+    }
+    /**
+     * Runs an authenticated request. A 401 triggers one renewal, shared by every request that failed
+     * with the same token, and one retry with the new token; a second failure is the request's own.
+     */
+    async authorized(call) {
+        const token = this.token;
+        if (!token) {
+            throw new Error('Client is not authenticated: M2M token missing');
+        }
+        try {
+            return await call(token);
+        }
+        catch (error) {
+            if (!(0, http_transport_1.isHttpStatus)(error, 401))
+                throw error;
+            let fresh;
+            try {
+                fresh = await this.renewAfterUnauthorized(token);
+            }
+            catch {
+                throw error;
+            }
+            return call(fresh);
+        }
+    }
+    // ─── Connection attempts ──────────────────────────────────────────────────
+    /**
+     * One attempt to get online. `initial` (start) pulls even when the stream cannot be opened, so the
+     * mirror is loaded; later attempts pull only once a stream is ready, except while the mirror is
+     * still empty.
+     */
+    async attempt(initial) {
+        const generation = this.generation;
+        const current = () => generation === this.generation;
+        let opened = null;
+        try {
+            if (initial || !this.keysLoaded) {
+                await this.host.loadKeys();
+                this.keysLoaded = true;
+            }
+            if (!current())
+                return;
+            const token = await this.validToken();
+            if (!current())
+                return;
+            let streamError;
+            try {
+                opened = await this.openStream(token);
+            }
+            catch (error) {
+                streamError = error;
+                if ((0, http_transport_1.isHttpStatus)(error, 401) && this.token === token) {
+                    // The instance no longer accepts this token: exchange a new one on the next attempt.
+                    this.tokenExpiresAt = 0;
+                }
+            }
+            if (!current())
+                return;
+            if (streamError !== undefined && !initial && !this.host.mirror.isEmpty())
+                throw streamError;
+            await this.pull();
+            if (!current())
+                return;
+            if (streamError !== undefined)
+                throw streamError;
+            if (opened.closed)
+                throw new Error('The event stream ended');
+            this.adopt(opened);
+            opened = null;
+            this.goLive(!initial);
+        }
+        catch {
+            if (!current())
+                return;
+            this.goOffline();
+            this.scheduleReconnect();
+        }
+        finally {
+            if (opened)
+                this.retire(opened);
+        }
+    }
+    reconnect() {
+        if (!this.running || this.paused)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        this.clearTimer('reconnectTimer');
+        const attempt = this.attempt(false);
+        this.connecting = attempt;
+        void attempt.finally(() => {
+            if (this.connecting === attempt)
+                this.connecting = null;
+        });
+        return attempt;
+    }
+    scheduleReconnect() {
+        if (!this.running || this.paused)
+            return;
+        // While the API key is refused the 30-second renewal drives recovery (§5.2 rule 4).
+        if (this.credentialRefused && !(this.token && this.tokenExpiresAt > Date.now()))
+            return;
+        this.clearTimer('reconnectTimer');
+        this.reconnectTimer = unrefTimer(() => {
+            this.reconnectTimer = null;
+            void this.reconnect();
+        }, backoffDelay(this.backoffStep++));
+    }
+    goLive(flush) {
+        this.live = true;
+        this.backoffStep = 0;
+        this.host.setOnline(true);
+        this.armWatchdog();
+        this.scheduleRenewals();
+        if (flush) {
+            void this.host.flush().catch(() => undefined);
+        }
+    }
+    goOffline() {
+        this.live = false;
+        if (this.stream) {
+            this.retire(this.stream);
+            this.stream = null;
+        }
+        this.clearTimer('watchdogTimer');
+        this.clearTimer('renewalTimer');
+        this.host.setOnline(false);
+    }
+    /** An unplanned break of the active stream: one immediate reconnect, still LIVE meanwhile. */
+    onBreak(stream) {
+        if (stream !== this.stream || !this.running || this.paused)
+            return;
+        this.retire(stream);
+        this.stream = null;
+        this.clearTimer('watchdogTimer');
+        void this.reconnect();
+    }
+    // ─── Token ────────────────────────────────────────────────────────────────
+    async validToken() {
+        if (this.token && this.tokenExpiresAt > Date.now()) {
+            return this.token;
+        }
+        if (this.credentialRefused) {
+            throw new Error('The API key was refused; waiting for the next renewal attempt');
+        }
+        return this.exchange();
+    }
+    exchange() {
+        if (!this.exchangeInFlight) {
+            const exchange = (async () => {
+                try {
+                    const issuedAt = Date.now();
+                    const auth = await this.host.transport.exchangeM2MToken(this.host.apiKey);
+                    const expectations = (0, token_verifier_1.expectationsFromMachineToken)(auth.access_token);
+                    if (!expectations) {
+                        throw new Error('The service token names no application (pid)');
+                    }
+                    this.credentialRefused = false;
+                    this.token = auth.access_token;
+                    this.projectId = expectations.projectId;
+                    const lifetimeMs = auth.expires_in * 1000;
+                    this.tokenExpiresAt = Math.min(issuedAt + lifetimeMs, (0, token_verifier_1.expiryOfToken)(auth.access_token) ?? Infinity);
+                    this.host.onToken(auth.access_token);
+                    this.scheduleRenewal(lifetimeMs * RENEW_AT);
+                    return auth.access_token;
+                }
+                catch (error) {
+                    if ((0, http_transport_1.isHttpStatus)(error, 401, 403)) {
+                        this.credentialRefused = true;
+                        this.scheduleRenewal(REFUSED_RETRY_MS);
+                    }
+                    throw error;
+                }
+            })();
+            this.exchangeInFlight = exchange;
+            void exchange.then(() => this.clearExchange(exchange), () => this.clearExchange(exchange));
+        }
+        return this.exchangeInFlight;
+    }
+    clearExchange(exchange) {
+        if (this.exchangeInFlight === exchange)
+            this.exchangeInFlight = null;
+    }
+    async renewAfterUnauthorized(staleToken) {
+        if (this.token && this.token !== staleToken) {
+            return this.token;
+        }
+        if (this.credentialRefused && !this.exchangeInFlight) {
+            throw new Error('The API key was refused');
+        }
+        const token = await this.exchange();
+        this.afterRenewal(token);
+        return token;
+    }
+    scheduleRenewal(delayMs) {
+        this.renewDueAt = Date.now() + delayMs;
+        if (!this.running || this.paused)
+            return;
+        this.clearTimer('renewTimer');
+        this.renewTimer = unrefTimer(() => {
+            this.renewTimer = null;
+            void this.renew();
+        }, delayMs);
+    }
+    async renew() {
+        if (!this.running || this.paused)
+            return;
+        try {
+            const token = await this.exchange();
+            this.renewalBackoffStep = 0;
+            this.afterRenewal(token);
+        }
+        catch (error) {
+            // A refusal already scheduled the 30-second retry.
+            if ((0, http_transport_1.isHttpStatus)(error, 401, 403))
+                return;
+            const delay = backoffDelay(this.renewalBackoffStep++);
+            // Past the old token's expiry the reconnection exchanges a new one itself.
+            if (Date.now() + delay < this.tokenExpiresAt) {
+                this.scheduleRenewal(delay);
+            }
+        }
+    }
+    /** A new token: rotate a live stream onto it, or reconnect if the client is not live. */
+    afterRenewal(token) {
+        if (!this.running || this.paused)
+            return;
+        if (this.live && this.stream) {
+            void this.rotate(token);
+        }
+        else if (!this.live) {
+            void this.reconnect();
+        }
+    }
+    /** Planned rotation: the new stream must be ready before the old one is closed; no pull. */
+    async rotate(token) {
+        if (this.rotating)
+            return;
+        this.rotating = true;
+        const generation = this.generation;
+        try {
+            const fresh = await this.openStream(token);
+            if (generation !== this.generation || !this.live || this.token !== token || fresh.closed) {
+                this.retire(fresh);
+                return;
+            }
+            const old = this.stream;
+            this.adopt(fresh);
+            if (old)
+                this.retire(old);
+        }
+        catch {
+            // Keep the old stream; the instance ends it at the old token's expiry, which reconnects.
+        }
+        finally {
+            this.rotating = false;
+        }
+    }
+    // ─── Stream ───────────────────────────────────────────────────────────────
+    /** Opens a stream and resolves once its `ready` frame arrived (bounded by the connect timeout). */
+    openStream(token) {
+        const stream = {
+            controller: new AbortController(),
+            heartbeatTimeoutMs: 0,
+            lastFrameAt: 0,
+            ready: false,
+            retired: false,
+            closed: false,
+        };
+        this.streams.add(stream);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.retire(stream);
+                reject(error);
+            };
+            const timer = unrefTimer(() => fail(new Error(`No ready frame within ${this.host.connectTimeoutMs}ms`)), this.host.connectTimeoutMs);
+            const onFrame = (event, data) => {
+                if (stream.retired)
+                    return;
+                stream.lastFrameAt = Date.now();
+                if (stream.ready) {
+                    this.onFrame(event, data);
+                    return;
+                }
+                if (event !== 'ready')
+                    return;
+                const ready = (data ?? {});
+                if (typeof ready.project_id !== 'string' || ready.project_id !== this.projectId) {
+                    fail(new Error('The event stream belongs to another application'));
+                    return;
+                }
+                const interval = typeof ready.heartbeat_interval_s === 'number' && ready.heartbeat_interval_s > 0
+                    ? ready.heartbeat_interval_s
+                    : 15;
+                stream.heartbeatTimeoutMs = interval * 1000 * HEARTBEAT_TIMEOUT_FACTOR;
+                stream.ready = true;
+                settled = true;
+                clearTimeout(timer);
+                resolve(stream);
+            };
+            const ended = (error) => {
+                stream.closed = true;
+                if (!settled) {
+                    fail(error instanceof Error ? error : new Error('The event stream ended before ready'));
+                    return;
+                }
+                this.streams.delete(stream);
+                this.onBreak(stream);
+            };
+            this.host.transport
+                .openEventStream(token, stream.controller.signal)
+                .then((response) => (0, event_stream_1.readEventStream)(response.body, (frame) => {
+                let data;
+                try {
+                    data = JSON.parse(frame.data);
+                }
+                catch {
+                    // Not JSON: only an unknown event could carry it, and unknown events are ignored.
+                    return;
+                }
+                onFrame(frame.event, data);
+            }))
+                .then(() => ended(), (error) => ended(error));
+        });
+    }
+    adopt(stream) {
+        this.stream = stream;
+        this.armWatchdog();
+    }
+    retire(stream) {
+        stream.retired = true;
+        this.streams.delete(stream);
+        stream.controller.abort();
+    }
+    armWatchdog() {
+        this.clearTimer('watchdogTimer');
+        const stream = this.stream;
+        if (!stream || !stream.ready)
+            return;
+        const due = stream.lastFrameAt + stream.heartbeatTimeoutMs - Date.now();
+        this.watchdogTimer = unrefTimer(() => {
+            this.watchdogTimer = null;
+            if (stream !== this.stream)
+                return;
+            if (Date.now() - stream.lastFrameAt >= stream.heartbeatTimeoutMs) {
+                this.onBreak(stream);
+            }
+            else {
+                this.armWatchdog();
+            }
+        }, due);
+    }
+    // ─── Push consumption ─────────────────────────────────────────────────────
+    onFrame(event, data) {
+        if (event === 'snapshot.changed') {
+            const changed = (data ?? {});
+            if (typeof changed.organization_id === 'string' && typeof changed.revision === 'number') {
+                this.onChanged(changed.organization_id, changed.revision);
+            }
+        }
+        else if (event === 'snapshot.resync') {
+            void this.pull().catch(() => undefined);
+        }
+        // `heartbeat` only refreshes lastFrameAt; unknown events are ignored.
+    }
+    onChanged(organizationId, revision) {
+        const known = this.host.mirror.getOrganizationRevision(organizationId) ?? 0;
+        if (known >= revision)
+            return;
+        this.refillTargets.set(organizationId, Math.max(this.refillTargets.get(organizationId) ?? 0, revision));
+        if (this.refillsInFlight.has(organizationId))
+            return;
+        void this.refill(organizationId);
+    }
+    /** Refills one organization until the mirror reaches the highest announced revision. */
+    async refill(organizationId) {
+        this.refillsInFlight.add(organizationId);
+        try {
+            for (;;) {
+                const { envelope, outcome } = await this.pullOrganization(organizationId);
+                if (!this.running)
+                    return;
+                if (!envelope.organizations || !(organizationId in envelope.organizations)) {
+                    this.refillTargets.delete(organizationId);
+                    return;
+                }
+                // An answer the mirror did not take (stale or unsupported) is not asked again at once; the target
+                // stays for the next notification or full pull.
+                if (outcome === 'ignored')
+                    return;
+                const target = this.refillTargets.get(organizationId) ?? 0;
+                if ((this.host.mirror.getOrganizationRevision(organizationId) ?? 0) >= target) {
+                    this.refillTargets.delete(organizationId);
+                    return;
+                }
+            }
+        }
+        catch {
+            // The state does not change; the target stays for the next notification or full pull.
+        }
+        finally {
+            this.refillsInFlight.delete(organizationId);
+        }
+    }
+    /**
+     * One pull of one organization, shared by every concurrent caller, merged into the mirror (or removing the
+     * organization when the answer no longer holds it). A pull that finishes after `stop()` or `pause()` leaves
+     * the mirror as it is.
+     */
+    pullOrganization(organizationId) {
+        const inFlight = this.organizationPulls.get(organizationId);
+        if (inFlight)
+            return inFlight;
+        const generation = this.generation;
+        const pull = (async () => {
+            const heldBefore = this.host.mirror.getOrganization(organizationId);
+            const envelope = await this.authorized((token) => this.host.transport.fetchSnapshot(token, organizationId));
+            const usable = generation === this.generation &&
+                typeof envelope?.schema_version === 'number' &&
+                envelope.schema_version <= entitlement_mirror_1.MAX_SUPPORTED_SCHEMA_VERSION;
+            if (!usable)
+                return { envelope, outcome: 'ignored' };
+            const answered = envelope.organizations?.[organizationId];
+            if (answered) {
+                this.host.mirror.mergeSnapshot(envelope);
+                const held = this.host.mirror.getOrganization(organizationId);
+                return held === answered ? { envelope, outcome: 'applied', entry: held } : { envelope, outcome: 'ignored' };
+            }
+            // Drop the organization only if the mirror still holds what it held when the pull started: a newer entry
+            // that arrived meanwhile is not removed by an older answer.
+            if (this.host.mirror.getOrganization(organizationId) !== heldBefore)
+                return { envelope, outcome: 'ignored' };
+            this.host.mirror.removeOrganization(organizationId);
+            return { envelope, outcome: 'removed' };
+        })();
+        this.organizationPulls.set(organizationId, pull);
+        const clear = () => {
+            if (this.organizationPulls.get(organizationId) === pull)
+                this.organizationPulls.delete(organizationId);
+        };
+        void pull.then(clear, clear);
+        return pull;
+    }
+    // ─── Renewal of entries with a validity ───────────────────────────────────
+    /** Re-arms the renewal timer for the earliest entry due; nothing while offline. Called on every mirror change. */
+    scheduleRenewals() {
+        this.clearTimer('renewalTimer');
+        if (!this.running || this.paused || !this.live)
+            return;
+        let next = Number.POSITIVE_INFINITY;
+        for (const organizationId of this.host.mirror.organizationIds()) {
+            const due = this.renewalDue(organizationId);
+            if (due !== undefined)
+                next = Math.min(next, due);
+        }
+        if (next === Number.POSITIVE_INFINITY)
+            return;
+        this.renewalTimer = unrefTimer(() => {
+            this.renewalTimer = null;
+            this.renewDueEntries();
+        }, next - Date.now());
+    }
+    /** Halfway between receiving an entry and its `valid_until`; undefined for an entry without a usable one. */
+    renewalDue(organizationId) {
+        const entry = this.host.mirror.getOrganization(organizationId);
+        const receivedAt = this.host.mirror.getReceivedAt(organizationId);
+        if (!entry || receivedAt === undefined)
+            return undefined;
+        const validUntil = (0, degradation_1.validUntilOf)(entry);
+        if (validUntil === undefined || validUntil <= receivedAt)
+            return undefined;
+        const due = Math.max(receivedAt + (validUntil - receivedAt) / 2, receivedAt + MIN_RENEWAL_SPACING_MS);
+        return Math.max(due, this.renewalRetryAt.get(organizationId) ?? 0);
+    }
+    renewDueEntries() {
+        if (!this.running || this.paused || !this.live)
+            return;
+        const now = Date.now();
+        for (const organizationId of this.host.mirror.organizationIds()) {
+            const due = this.renewalDue(organizationId);
+            if (due === undefined || due > now)
+                continue;
+            this.renewalRetryAt.set(organizationId, now + RENEWAL_RETRY_MS);
+            // The retry time set above stays unless the renewal was taken: a stale or unsupported answer does not
+            // move the entry's receipt time, and renewing it again at once would pull without end.
+            void this.pullOrganization(organizationId).then(({ outcome }) => {
+                if (outcome !== 'ignored')
+                    this.renewalRetryAt.delete(organizationId);
+                this.scheduleRenewals();
+            }, () => this.scheduleRenewals());
+        }
+        this.scheduleRenewals();
+    }
+    /** Full pull: replaces the whole mirror. */
+    async pull() {
+        const snapshot = await this.authorized((token) => this.host.transport.fetchSnapshot(token));
+        this.host.mirror.loadSnapshot(snapshot);
+        for (const [organizationId, target] of this.refillTargets) {
+            if ((this.host.mirror.getOrganizationRevision(organizationId) ?? 0) >= target) {
+                this.refillTargets.delete(organizationId);
+            }
+        }
+    }
+    // ─── Housekeeping ─────────────────────────────────────────────────────────
+    /** Drops the stream, every timer and any attempt in flight. */
+    halt() {
+        this.generation++;
+        this.live = false;
+        this.connecting = null;
+        this.stream = null;
+        for (const stream of [...this.streams]) {
+            this.retire(stream);
+        }
+        this.clearTimer('renewTimer');
+        this.clearTimer('reconnectTimer');
+        this.clearTimer('watchdogTimer');
+        this.clearTimer('renewalTimer');
+    }
+    clearTimer(name) {
+        const timer = this[name];
+        if (timer)
+            clearTimeout(timer);
+        this[name] = null;
+    }
+}
+exports.ConnectionSupervisor = ConnectionSupervisor;
+//# sourceMappingURL=connection-supervisor.js.map