signalk-piper 0.0.1 → 0.2.0

package/dist/service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * PiperService — the plugin's whole runtime: managed container lifecycle,
+ * Wyoming describe readiness gate, periodic health loop, `wyoming-service`
+ * PropertyValues emission (with the family's emission discipline) and the
+ * plugin router endpoints.
+ *
+ * One instance lives for the whole server process (plugin routers cannot be
+ * deregistered); `start()`/`stop()` may run many times against it.
+ */
+import { ManagedContainer, type RouterLike } from "signalk-container-helper";
+import { type PiperSettings } from "./config.js";
+export declare const PLUGIN_ID = "signalk-piper";
+export declare const SERVICE_TYPE = "tts";
+export declare const NOTIFICATION_PATH = "notifications.voice.piper";
+export type ServiceStatus = "starting" | "ready" | "stopped" | "error";
+/** The subset of the Signal K plugin app surface this plugin uses. */
+export interface ServiceApp {
+    debug(msg: string): void;
+    error(msg: string): void;
+    setPluginStatus(msg: string): void;
+    setPluginError(msg: string): void;
+    emitPropertyValue(name: string, value: unknown): void;
+    handleMessage(id: string, delta: unknown): void;
+    savePluginOptions(configuration: object, callback: (err: unknown) => void): void;
+}
+/** All intervals/deadlines, overridable for tests. Defaults per family spec. */
+export interface ServiceTiming {
+    /** Delay between describe attempts while waiting for readiness. */
+    gateIntervalMs: number;
+    /** Give up on the readiness gate after this long (model downloads are slow). */
+    gateDeadlineMs: number;
+    /** Progress line frequency while the gate is waiting. */
+    gateStatusEveryMs: number;
+    /** Per-attempt describe timeout (gate + health loop). */
+    describeTimeoutMs: number;
+    /** Health loop period. */
+    healthIntervalMs: number;
+    /** Consecutive failed probes before alarming. */
+    healthFailThreshold: number;
+    /** Minimum spacing between wyoming-service emissions (flap collapse). */
+    emitDebounceMs: number;
+    /** Flap guard window and transition budget. */
+    flapWindowMs: number;
+    flapMaxTransitions: number;
+}
+export declare const DEFAULT_TIMING: ServiceTiming;
+export interface HealthSample {
+    ok: boolean;
+    at: number;
+    latencyMs: number | null;
+}
+export declare class PiperService {
+    readonly container: ManagedContainer;
+    settings: PiperSettings;
+    private readonly app;
+    private readonly timing;
+    private running;
+    /** Increments per start() so stale async work from a prior run is inert. */
+    private runId;
+    private uri;
+    private lastInfo;
+    private lastHealth;
+    private consecutiveFailures;
+    private probeInFlight;
+    /** True while an update apply recreates the container (pauses probes). */
+    private updating;
+    private healthTimer;
+    private currentStatus;
+    private lastEmittedStatus;
+    private lastEmittedUri;
+    private lastEmitAt;
+    private pendingEmitTimer;
+    private transitionTimes;
+    private flapSuppressed;
+    private emissionsDisabled;
+    constructor(app: ServiceApp, timing?: Partial<ServiceTiming>);
+    get isRunning(): boolean;
+    /** Called from the synchronous plugin start(). */
+    start(rawConfig: unknown): void;
+    /** Async server stop() — awaited by Signal K before a restart. */
+    stop(): Promise<void>;
+    private startAsync;
+    /**
+     * Resolve the service address, gate on Wyoming `describe`, go ready and
+     * start the health loop. Shared by first start and the post-update resume.
+     * A gate failure after the uri is known is surfaced loudly (spec §3.3:
+     * wyoming-service 'error' + notification alarm) and the health loop still
+     * starts, so eventual recovery is detected without a manual restart.
+     */
+    private becomeReady;
+    /**
+     * host:port of the Wyoming port. Default networking declares the port via
+     * signalkAccessiblePorts and must resolve; the explicit 0.0.0.0 publish
+     * ("bind") is not manager-resolvable, but is by definition reachable on
+     * the loopback of the host.
+     */
+    private resolveServiceAddress;
+    /**
+     * Poll Wyoming `describe` until the service answers with `info` — which
+     * proves the model is downloaded and the service is actually serving.
+     * Returns null when the run was superseded while waiting.
+     */
+    private describeGate;
+    private validateInfo;
+    /** Warn (loudly, once per start) about 16 kHz voices; never block. */
+    private validateVoice;
+    private runningStatusLine;
+    private startHealthLoop;
+    private stopHealthLoop;
+    private healthProbe;
+    /** Boolean describe probe for signalk-container's recurring healthCheck. */
+    private probeOk;
+    /**
+     * Request an emission of `status`. Rules:
+     * - never emit the same (status, uri) pair twice in a row — a uri change
+     *   (post-update port move) re-emits even when the status is unchanged;
+     * - at most one emission per emitDebounceMs (later requests collapse into
+     *   the trailing timer, so a flap that settles back emits nothing);
+     * - >flapMaxTransitions transitions per flapWindowMs → warn and suppress;
+     * - omitted while the uri is unknown, except "stopped";
+     * - a throwing emitPropertyValue (server-wide PropertyValues cap) disables
+     *   all further emissions for this run;
+     * - "stopped" flushes immediately (stop() must not race the debounce).
+     */
+    private emit;
+    private emitNow;
+    private notify;
+    /**
+     * The container was just recreated (and started) by an update apply: the
+     * host port can change and the new instance must answer `describe` before
+     * it is advertised again. Supersede the current run and re-run the
+     * readiness flow (resolve → gate → ready → health loop) against it.
+     */
+    private resumeAfterUpdate;
+    /**
+     * Mount plugin routes. Called once per server process (even while the
+     * plugin is disabled), so every handler checks the running flag.
+     */
+    registerRoutes(router: RouterLike, rawOptionsForSave: () => unknown): void;
+    private active;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}