@trillboards/edge-core 0.2.2 → 0.2.3

package/dist/ModelManager.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ModelManager — Model lifecycle management with OTA (over-the-air) updates.
+ * Port of CTV agent's ModelManager.kt (387 lines), adapted for Node.js/ONNX.
+ *
+ * Manages registration, version-checking, and atomic download of ML model files.
+ * Downloads use a .tmp + rename pattern to prevent corrupted model loads.
+ * The version check timer is unref()'d so it does not keep the process alive.
+ *
+ * Events emitted:
+ *   'modelUpdated'      — { name, oldVersion, newVersion, path }
+ *   'updateAvailable'   — { name, currentVersion, availableVersion }
+ *   'downloadProgress'  — { name, bytesDownloaded, totalBytes, percent }
+ *   'downloadError'     — { name, error }
+ *   'checkComplete'     — { checkedCount, updatesAvailable }
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+export interface ModelInfo {
+    /** Model identifier, e.g. 'blazeface', 'yamnet', 'ageGender'. */
+    name: string;
+    /** Semver version string, e.g. '1.2.0'. */
+    version: string;
+    /** Absolute path to the .onnx file on disk. */
+    filePath: string;
+    /** SHA-256 hex digest of the current file. */
+    sha256: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+    /** Timestamp (ms) of last version check against the API. */
+    lastChecked: number;
+    /** Timestamp (ms) of last successful download. */
+    lastUpdated: number;
+}
+export interface ModelVersionResponse {
+    name: string;
+    version: string;
+    sha256: string;
+    downloadUrl: string;
+    sizeBytes: number;
+    releaseNotes?: string;
+}
+export interface ModelManagerOptions {
+    /** Directory for storing model files and manifest. */
+    modelsDir: string;
+    /** Backend API base URL (e.g. 'https://api.trillboards.com'). */
+    apiBaseUrl: string;
+    /** Device fingerprint for the version-check API call. */
+    deviceFingerprint: string;
+    /** Interval between automatic version checks. Default: 3600000 (1 hour). */
+    checkIntervalMs?: number;
+    /** Maximum concurrent model downloads. Default: 1. */
+    maxConcurrentDownloads?: number;
+    /** Whether to auto-download discovered updates. Default: true. */
+    autoUpdate?: boolean;
+    /** Request timeout for API calls in milliseconds. Default: 30000. */
+    requestTimeoutMs?: number;
+    /** Request timeout for file downloads in milliseconds. Default: 300000 (5 min). */
+    downloadTimeoutMs?: number;
+    /** Maximum number of HTTP redirects to follow. Default: 5. */
+    maxRedirects?: number;
+}
+export declare class ModelManager extends EventEmitter {
+    private models;
+    private readonly options;
+    private checkTimer;
+    private downloading;
+    private readonly manifestPath;
+    constructor(options: ModelManagerOptions);
+    /**
+     * Initialize — ensure models directory exists, load manifest, compute
+     * hashes for any registered model files already on disk.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Start periodic version checking.  The timer is unref()'d so it does not
+     * prevent the Node.js process from exiting naturally.
+     */
+    start(): void;
+    /**
+     * Stop periodic checking and cancel any in-flight state tracking.
+     */
+    stop(): void;
+    /**
+     * Register a model to track.  Called during EdgeAgent init for each model type.
+     * If the file exists on disk, its SHA-256 is computed immediately.
+     * If the manifest already has version info for this name, it is merged.
+     */
+    registerModel(name: string, filePath: string): void;
+    /**
+     * Check for updates for all registered models by calling the backend API.
+     * Endpoint: GET /v1/federated/models?deviceFingerprint=X&modelType=Y
+     *
+     * Returns the list of ModelVersionResponse objects for which a newer
+     * version is available.  If autoUpdate is enabled, downloads are
+     * initiated automatically (respecting maxConcurrentDownloads).
+     */
+    checkForUpdates(): Promise<ModelVersionResponse[]>;
+    /**
+     * Download a specific model update.
+     *
+     * 1. Download to a .tmp file alongside the target path
+     * 2. Verify SHA-256 checksum matches the expected value
+     * 3. Atomic swap: rename .tmp -> target .onnx path
+     * 4. Update manifest with new version info
+     * 5. Emit 'modelUpdated' event
+     *
+     * Returns true if the model was successfully downloaded and verified.
+     */
+    downloadUpdate(update: ModelVersionResponse): Promise<boolean>;
+    /**
+     * Get info about a registered model.  Returns null if not registered.
+     */
+    getModel(name: string): ModelInfo | null;
+    /**
+     * Get all registered models.
+     */
+    getModels(): ModelInfo[];
+    /**
+     * Check if a model's file exists on disk.
+     */
+    hasModel(name: string): boolean;
+    /**
+     * Check if a download is currently in progress for a model.
+     */
+    isDownloading(name: string): boolean;
+    /**
+     * Compute the SHA-256 hex digest of a file using a streaming reader.
+     */
+    private computeFileHash;
+    /**
+     * Download a file from a URL to a local destination path.
+     * Follows HTTP redirects (up to maxRedirects), emits progress events,
+     * and enforces a download timeout.
+     */
+    private downloadFile;
+    private downloadFileWithRedirects;
+    /**
+     * Load model manifest from disk.  If the file does not exist or is corrupt,
+     * start with an empty manifest — never crash.
+     */
+    private loadManifest;
+    /**
+     * Save the current model state to the manifest file on disk.
+     * Uses atomic write: write to .tmp, then rename.
+     */
+    private saveManifest;
+    /**
+     * Make an HTTPS GET request to the backend API and return parsed JSON.
+     */
+    private apiGet;
+    /**
+     * Verify that a model file exists on disk, recompute its hash if present,
+     * or clear stale info if the file has been deleted.
+     */
+    private verifyModelOnDisk;
+    /**
+     * Semver comparison: returns true if `available` is strictly newer than `current`.
+     * Handles non-semver gracefully by falling back to string comparison.
+     */
+    private isNewerVersion;
+    /**
+     * Safely remove a .tmp file if it exists.  Never throws.
+     */
+    private cleanupTmpFile;
+}
+//# sourceMappingURL=ModelManager.d.ts.map

package/dist/ModelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelManager.d.ts","sourceRoot":"","sources":["../src/ModelManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAStC,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAiBD,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,OAAO,EAAE,mBAAmB;IAkBxC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAgBb;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAyBnD;;;;;;;OAOG;IACG,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAwDxD;;;;;;;;;;OAUG;IACG,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IA6EpE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,IAAI,SAAS,EAAE;IAIxB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAM/B;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAMpC;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,yBAAyB;IA0GjC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAsCpB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA6BpB;;OAEG;IACH,OAAO,CAAC,MAAM;IAmDd;;;OAGG;YACW,iBAAiB;IAmB/B;;;OAGG;IACH,OAAO,CAAC,cAAc;IActB;;OAEG;IACH,OAAO,CAAC,cAAc;CASvB"}