@oatscenter/trellis 0.100.0-rc.1

package/connection.js

@@ -0,0 +1,396 @@
+import { logger as noopLogger } from "./globals.js";
+const EMPTY_AVAILABILITY = Object.freeze({
+    capabilities: Object.freeze({}),
+    resources: Object.freeze({}),
+});
+const installAvailability = Symbol("installAvailability");
+function immutableAvailability(availability) {
+    return Object.freeze({
+        capabilities: Object.freeze({ ...availability.capabilities }),
+        resources: Object.freeze({ ...availability.resources }),
+    });
+}
+/**
+ * Framework-neutral Trellis connection lifecycle handle.
+ *
+ * The class stores the latest transport-neutral status, delivers it immediately
+ * to subscribers, and owns lifecycle cleanup without exposing raw transport
+ * handles to framework adapters.
+ */
+export class TrellisConnection {
+    #status;
+    #listeners = new Set();
+    #availability;
+    #availabilityListeners = new Set();
+    #closeTransport;
+    #stopObserving;
+    #observationStopped = Promise.resolve();
+    #observationFailure;
+    #log;
+    #stopped = false;
+    /** Creates a Trellis connection lifecycle handle. */
+    constructor(options) {
+        this.#status = options.initialStatus ??
+            createStatus(options.kind, "connected");
+        this.#closeTransport = options.close ?? (async () => { });
+        this.#stopObserving = options.stopObserving ?? (async () => { });
+        this.#log = options.log === false ? noopLogger : options.log ?? noopLogger;
+        this.#availability = options.availability
+            ? immutableAvailability(options.availability)
+            : EMPTY_AVAILABILITY;
+    }
+    /** Returns the latest observed connection status. */
+    get status() {
+        return this.#status;
+    }
+    /** Returns the current immutable installed availability snapshot. */
+    availability() {
+        return this.#availability;
+    }
+    /** Yields the current availability and each subsequent installed replacement. */
+    watchAvailability() {
+        const availabilityListeners = this.#availabilityListeners;
+        const initialAvailability = this.#availability;
+        return {
+            async *[Symbol.asyncIterator]() {
+                const pending = [initialAvailability];
+                let wake;
+                const listener = (availability) => {
+                    pending.push(availability);
+                    wake?.();
+                    wake = undefined;
+                };
+                availabilityListeners.add(listener);
+                try {
+                    while (true) {
+                        if (pending.length === 0) {
+                            await new Promise((resolve) => {
+                                wake = resolve;
+                            });
+                        }
+                        const next = pending.shift();
+                        if (next)
+                            yield next;
+                    }
+                }
+                finally {
+                    availabilityListeners.delete(listener);
+                }
+            },
+        };
+    }
+    [installAvailability](availability) {
+        if (availability === this.#availability)
+            return;
+        this.#availability = immutableAvailability(availability);
+        for (const listener of this.#availabilityListeners) {
+            listener(this.#availability);
+        }
+    }
+    /**
+     * Subscribes to status changes and immediately delivers the current status.
+     *
+     * The returned function removes the listener. Calling it more than once is
+     * safe.
+     */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#status);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Stops status observation without closing the underlying transport. */
+    stopObserving() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#observationStopped = Promise.resolve().then(() => this.#stopObserving()).catch((error) => {
+            this.#observationFailure = error;
+        });
+    }
+    /** Closes the underlying transport and publishes a terminal closed status. */
+    async close() {
+        this.stopObserving();
+        try {
+            await this.#closeTransport();
+            await this.#observationStopped;
+            if (this.#observationFailure !== undefined) {
+                throw this.#observationFailure;
+            }
+            this.setStatus(createStatus(this.#status.kind, "closed"));
+        }
+        catch (error) {
+            this.setStatus(createStatus(this.#status.kind, "error", { error }));
+            throw error;
+        }
+    }
+    /** Publishes a new status to all active listeners. */
+    setStatus(status) {
+        if (this.#stopped && status.phase !== "closed" && status.phase !== "error") {
+            return;
+        }
+        this.#status = status;
+        this.#log.debug({
+            kind: status.kind,
+            phase: status.phase,
+            transport: status.transport,
+        }, "Trellis connection status changed");
+        for (const listener of this.#listeners) {
+            listener(status);
+        }
+    }
+}
+/** @internal Installs one immutable availability snapshot after bootstrap verification. */
+export function installConnectionAvailability(connection, availability) {
+    connection[installAvailability](availability);
+}
+/** Observes a narrow transport status stream as a Trellis connection lifecycle. */
+export function observeTrellisConnection(options) {
+    let stopped = false;
+    const statusStream = options.transport.status;
+    const statusIterator = typeof statusStream === "function"
+        ? statusStream.call(options.transport)[Symbol.asyncIterator]()
+        : undefined;
+    let statusTask;
+    let closedFailure;
+    let closedTask = Promise.resolve();
+    const connection = new TrellisConnection({
+        kind: options.kind,
+        availability: options.availability,
+        close: async () => {
+            const alreadyClosed = options.transport.isClosed?.() ?? false;
+            await options.transport.close();
+            await statusIterator?.return?.();
+            await statusTask;
+            await closedTask;
+            if (!alreadyClosed && closedFailure !== undefined)
+                throw closedFailure;
+        },
+        stopObserving: () => {
+            stopped = true;
+        },
+        log: options.log,
+    });
+    const baseTransport = createTransportMetadata(options.transport, options.transportName);
+    if (statusIterator) {
+        statusTask = (async () => {
+            try {
+                while (true) {
+                    const next = await statusIterator.next();
+                    if (next.done)
+                        return;
+                    const event = next.value;
+                    options.onTransportEvent?.(event);
+                    if (stopped) {
+                        return;
+                    }
+                    const status = statusFromTransportEvent(options.kind, event, baseTransport);
+                    if (status) {
+                        logTransportLifecycleEvent(options, event);
+                        connection.setStatus(status);
+                    }
+                }
+            }
+            catch (error) {
+                if (!stopped) {
+                    logTransportStatusWatcherFailure(options, error);
+                    connection.setStatus(createStatus(options.kind, "error", {
+                        ...baseTransport,
+                        error,
+                    }));
+                }
+            }
+        })();
+    }
+    closedTask = options.transport.closed().then((closedError) => {
+        if (closedError instanceof Error)
+            closedFailure = closedError;
+        if (stopped)
+            return;
+        if (closedError instanceof Error) {
+            logTransportClosed(options, closedError);
+            connection.setStatus(createStatus(options.kind, "error", {
+                ...baseTransport,
+                error: closedError,
+            }));
+            return;
+        }
+        logTransportClosed(options);
+        connection.setStatus(createStatus(options.kind, "closed", baseTransport));
+    }, (error) => {
+        closedFailure = error;
+        if (stopped)
+            return;
+        logTransportClosed(options, error);
+        connection.setStatus(createStatus(options.kind, "error", {
+            ...baseTransport,
+            error,
+        }));
+    });
+    return connection;
+}
+/** Observes a NATS connection without exposing the raw NATS handle publicly. */
+export function observeNatsTrellisConnection(options) {
+    return observeTrellisConnection({
+        kind: options.kind,
+        transport: options.nc,
+        transportName: "nats",
+        log: options.log,
+        lifecycleLog: options.lifecycleLog,
+        availability: options.availability,
+        onTransportEvent: options.onTransportEvent,
+    });
+}
+function lifecycleLabel(kind) {
+    switch (kind) {
+        case "client":
+            return "Client";
+        case "device":
+            return "Device";
+        case "service":
+            return "Service";
+    }
+}
+function normalizeTransportError(error) {
+    const record = error;
+    return {
+        name: error.name,
+        message: error.message,
+        ...(typeof record.operation === "string"
+            ? { operation: record.operation }
+            : {}),
+        ...(typeof record.subject === "string" ? { subject: record.subject } : {}),
+        ...(typeof record.queue === "string" ? { queue: record.queue } : {}),
+    };
+}
+function normalizeTransportStatus(status) {
+    if (!status || typeof status !== "object") {
+        return { status };
+    }
+    const record = status;
+    return {
+        ...(typeof record.type === "string" ? { type: record.type } : {}),
+        ...(record.error instanceof Error
+            ? { error: normalizeTransportError(record.error) }
+            : {}),
+        ...(typeof record.data === "string" ? { data: record.data } : {}),
+        ...(record.data && typeof record.data === "object"
+            ? { data: record.data }
+            : {}),
+    };
+}
+function getNatsLifecycleLog(kind, event) {
+    if (!event || typeof event !== "object") {
+        return null;
+    }
+    const label = lifecycleLabel(kind);
+    switch (event.type) {
+        case "disconnect":
+            return { level: "warn", message: `${label} disconnected from NATS` };
+        case "reconnecting":
+            return { level: "warn", message: `${label} attempting NATS reconnect` };
+        case "forceReconnect":
+            return { level: "warn", message: `${label} forcing NATS reconnect` };
+        case "reconnect":
+            return { level: "info", message: `${label} reconnected to NATS` };
+        case "staleConnection":
+            return {
+                level: "warn",
+                message: `${label} NATS connection became stale`,
+            };
+        case "error":
+            return { level: "error", message: `${label} NATS error` };
+        default:
+            return null;
+    }
+}
+function logTransportLifecycleEvent(options, event) {
+    if (!options.lifecycleLog) {
+        return;
+    }
+    const lifecycleLog = getNatsLifecycleLog(options.kind, event);
+    if (!lifecycleLog) {
+        return;
+    }
+    options.lifecycleLog.log[lifecycleLog.level]({
+        ...options.lifecycleLog.context,
+        connection: normalizeTransportStatus(event),
+    }, lifecycleLog.message);
+}
+function logTransportStatusWatcherFailure(options, error) {
+    if (!options.lifecycleLog) {
+        return;
+    }
+    options.lifecycleLog.log.warn({ ...options.lifecycleLog.context, error }, `${lifecycleLabel(options.kind)} NATS status watcher failed`);
+}
+function logTransportClosed(options, error) {
+    if (!options.lifecycleLog) {
+        return;
+    }
+    const label = lifecycleLabel(options.kind);
+    if (error) {
+        options.lifecycleLog.log.error({ ...options.lifecycleLog.context, error }, `${label} NATS connection closed with error`);
+        return;
+    }
+    options.lifecycleLog.log.warn(options.lifecycleLog.context, `${label} NATS connection closed`);
+}
+function createStatus(kind, phase, transport) {
+    return {
+        kind,
+        phase,
+        observedAt: new Date(),
+        ...(transport ? { transport } : {}),
+    };
+}
+function createTransportMetadata(transport, name) {
+    return {
+        ...(name ? { name } : {}),
+        ...(typeof transport.getServer === "function"
+            ? { server: transport.getServer() }
+            : {}),
+    };
+}
+function statusFromTransportEvent(kind, event, baseTransport) {
+    const transportEvent = normalizeTransportEvent(event);
+    if (!transportEvent.type) {
+        return null;
+    }
+    const transport = {
+        ...baseTransport,
+        event: transportEvent.type,
+        ...(transportEvent.data === undefined ? {} : { data: transportEvent.data }),
+        ...(transportEvent.error === undefined
+            ? {}
+            : { error: transportEvent.error }),
+    };
+    switch (transportEvent.type) {
+        case "disconnect":
+        case "disconnected":
+            return createStatus(kind, "disconnected", transport);
+        case "reconnecting":
+        case "forceReconnect":
+        case "staleConnection":
+            return createStatus(kind, "reconnecting", transport);
+        case "reconnect":
+            return createStatus(kind, "connected", transport);
+        case "error":
+            return createStatus(kind, "error", transport);
+        case "closed":
+            return createStatus(kind, "closed", transport);
+        default:
+            return null;
+    }
+}
+function normalizeTransportEvent(event) {
+    if (!event || typeof event !== "object") {
+        return {};
+    }
+    const record = event;
+    return {
+        ...(typeof record.type === "string" ? { type: record.type } : {}),
+        ...("data" in record ? { data: record.data } : {}),
+        ...("error" in record ? { error: record.error } : {}),
+    };
+}

package/device/activation.d.ts

@@ -0,0 +1,42 @@
+import type { TrellisDeviceActivationArgs } from "../device.ts";
+/**
+ * Options for the native device activation status helper.
+ */
+export type CheckDeviceActivationArgs<TContract extends TrellisDeviceActivationArgs["participant"] = TrellisDeviceActivationArgs["participant"]> = TrellisDeviceActivationArgs<TContract> & {
+    stateDir?: string;
+    statePath?: string;
+};
+/**
+ * Activation status for a device that is already ready to connect.
+ */
+export type TrellisDeviceActivatedStatus = {
+    status: "activated";
+};
+/**
+ * Activation status for a device that cannot proceed yet.
+ */
+export type TrellisDeviceNotReadyStatus = {
+    status: "not_ready";
+    reason: string;
+};
+/**
+ * Activation status for a device that still needs activation.
+ */
+export type TrellisDeviceActivationRequiredStatus = {
+    status: "activation_required";
+    activationUrl: string;
+    /** Device-local code the activating user must confirm in the portal. */
+    confirmationCode: string;
+    waitForOnlineApproval(opts?: {
+        signal?: AbortSignal;
+    }): Promise<TrellisDeviceActivatedStatus>;
+    acceptConfirmationCode(code: string): Promise<TrellisDeviceActivatedStatus>;
+};
+/**
+ * Caller-facing activation status union for native device runtimes.
+ */
+export type TrellisDeviceActivationStatus = TrellisDeviceActivatedStatus | TrellisDeviceNotReadyStatus | TrellisDeviceActivationRequiredStatus;
+/**
+ * Reports native device activation status and hides local activation persistence details.
+ */
+export declare function checkDeviceActivation<TContract extends TrellisDeviceActivationArgs["participant"]>(args: CheckDeviceActivationArgs<TContract>): Promise<TrellisDeviceActivationStatus>;