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

package/dist/client/connection-supervisor.js

@@ -0,0 +1,547 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionSupervisor = void 0;
+const token_verifier_1 = require("../auth/token-verifier");
+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;
+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;
+    refillTargets = new Map();
+    refillsInFlight = new Set();
+    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();
+        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.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 = await this.authorized((token) => this.host.transport.fetchSnapshot(token, organizationId));
+                if (!this.running)
+                    return;
+                if (envelope.organizations && organizationId in envelope.organizations) {
+                    this.host.mirror.mergeSnapshot(envelope);
+                }
+                else {
+                    this.host.mirror.removeOrganization(organizationId);
+                    this.refillTargets.delete(organizationId);
+                    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);
+        }
+    }
+    /** 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');
+    }
+    clearTimer(name) {
+        const timer = this[name];
+        if (timer)
+            clearTimeout(timer);
+        this[name] = null;
+    }
+}
+exports.ConnectionSupervisor = ConnectionSupervisor;
+//# sourceMappingURL=connection-supervisor.js.map

package/dist/client/shiprev-client.d.ts

@@ -0,0 +1,106 @@
+import { UsageBuffer } from '../metering/usage-buffer';
+import { HttpTransport } from '../transport/http.transport';
+import { AdjudicateOptions, ClientState, ConfirmReservationResult, ReleaseReservationResult, ReservationResult, ReserveOptions, Ruling, ShipRevClientOptions, Snapshot, TokenClaims, UsageEventItem } from '../types';
+export declare class ShipRevClient {
+    private readonly options;
+    private readonly transport;
+    private readonly tokenVerifier;
+    private readonly mirror;
+    private readonly adjudicator;
+    private readonly usageBuffer;
+    private readonly supervisor;
+    /** COLD until start() or setOnline(); otherwise the state follows the online signal and the mirror. */
+    private active;
+    private isOnline;
+    /** Issuer and application expected of session tokens, learned from the machine token. */
+    private expectations;
+    /** Amounts reserved by this client, so `confirm()` without an amount confirms what was reserved. */
+    private readonly reservedAmounts;
+    constructor(options: ShipRevClientOptions);
+    /**
+     * Connects the client: fetches the signing keys, exchanges the API key for a service token, opens
+     * the push stream and waits for its `ready` frame, then loads the full entitlement snapshot. Never
+     * throws: LIVE when all four succeed, DISCONNECTED when only the stream failed, COLD_OFFLINE when
+     * nothing could be loaded. From here until `stop()` the client renews its token, follows the push
+     * stream and reconnects by itself.
+     */
+    start(): Promise<{
+        project_id: string;
+        snapshot_revision: number;
+        state: ClientState;
+    }>;
+    /**
+     * Closes the push stream, stops every timer and flushes buffered usage events.
+     */
+    stop(): Promise<void>;
+    /**
+     * Enqueues a metered usage event into the memory buffer for batched delivery.
+     */
+    reportUsage(event: UsageEventItem): Promise<void>;
+    /**
+     * Manually flushes currently buffered usage events to the core service.
+     */
+    flush(): Promise<void>;
+    /**
+     * Verifies an RS256 JWT token locally and extracts subject and isolation keys.
+     */
+    verifyToken(jwt: string): Promise<TokenClaims>;
+    /**
+     * Executes a four-tier local adjudication (synchronous, zero-IO, P95 <= 5ms).
+     */
+    adjudicate(options: AdjudicateOptions): Ruling;
+    /**
+     * Asynchronous adjudication with authoritative fallback.
+     * If local mirror misses the organization or rule and client is online, queries core service and backfills mirror.
+     */
+    adjudicateAsync(options: AdjudicateOptions): Promise<Ruling>;
+    /**
+     * Guard for write operations (fail-closed).
+     * Intercepts action if write operation is denied (e.g. disconnected).
+     */
+    guardWrite<T>(options: Omit<AdjudicateOptions, 'operation'>, action: () => Promise<T> | T): Promise<T>;
+    /**
+     * Two-phase entitlement reservation: reserve
+     */
+    reserve(options: ReserveOptions): Promise<ReservationResult>;
+    /**
+     * Two-phase entitlement reservation: confirm. Without `actualAmount` the reserved amount is confirmed.
+     */
+    confirm(reservationId: string, actualAmount?: number): Promise<ConfirmReservationResult>;
+    /**
+     * Two-phase entitlement reservation: release
+     */
+    release(reservationId: string): Promise<ReleaseReservationResult>;
+    /**
+     * Directly loads a snapshot into the local mirror (e.g. for offline seed testing).
+     */
+    loadSnapshot(snapshot: Snapshot): boolean;
+    /**
+     * Returns current internal state and mirror revision.
+     */
+    state(): {
+        state: ClientState;
+        snapshot_revision: number;
+        last_sync_at?: number;
+    };
+    /**
+     * Switches the connection state by hand, for fault injection and tests. `false` closes the push
+     * stream and suspends reconnection until `setOnline(true)`, which sets LIVE at once and resumes
+     * supervision; on a started client the supervisor then corrects the state.
+     */
+    setOnline(online: boolean): void;
+    /**
+     * Sets the machine token by hand (for tests without `start()`); a decodable JWT also sets the
+     * issuer and application `verifyToken()` expects.
+     */
+    setM2MToken(token: string): void;
+    /**
+     * Directly preloads a public key into the token verifier cache (for testing without network).
+     */
+    setPublicKey(kid: string, pem: string): void;
+    getUsageBuffer(): UsageBuffer;
+    getTransport(): HttpTransport;
+    private applyOnline;
+    private learnExpectations;
+    private refillOrganization;
+}