@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/scaler/failure-tracker.d.ts

@@ -1,33 +1,27 @@
 /**
  * In-process bounded record of recent scaler spawn failures.
  *
- * The scaler manager records every `scaler.failed` event here at the same site
- * it increments the fleet-wide Prometheus counter. The diagnose scaler check
- * reads recent failures grouped per backend instance to produce its rows. This
- * is memory-only and bounded — the recent-failures window resets on restart,
+ * The scaler manager records every `scaler.failed` event here where it
+ * increments the fleet-wide Prometheus counter; the diagnose scaler check reads
+ * it grouped per backend instance. Memory-only: the window resets on restart,
  * which is acceptable for an on-demand operator view over a short window.
  */
-/** A single recorded scaler spawn failure. */
 export interface ScalerFailureRecord {
-    /** Scaler instance name (the configured scaler `name`); the diagnose row key. */
+    /** Configured scaler `name`; the diagnose row key. */
     backendName: string;
-    /** Backend type: 'container' | 'bare-metal' | 'firecracker' | 'event' | 'unknown'. */
+    /** 'container' | 'bare-metal' | 'firecracker' | 'event' | 'unknown'. */
     backendType: string;
     /** True when the failed spawn was bound to a queued job (a run was affected). */
     bound: boolean;
-    /** Captured error string from the scaler event detail. */
     detail: string;
-    /** Event timestamp in epoch milliseconds. */
     timestampMs: number;
 }
-/** Per-backend summary of recent failures within a window. */
 export interface BackendFailureSummary {
     backendType: string;
     boundCount: number;
     unboundCount: number;
     /** Detail of the most recent failure in the window. */
     lastError: string;
-    /** Timestamp of the most recent failure in the window. */
     lastAtMs: number;
 }
 export declare class ScalerFailureTracker {
@@ -38,8 +32,7 @@ export declare class ScalerFailureTracker {
     record(rec: ScalerFailureRecord): void;
     /**
      * Group failures newer than `nowMs - windowMs` by backend instance name.
-     * `nowMs` is injected so callers control the clock (and tests are
-     * deterministic).
+     * `nowMs` is injected so callers control the clock (and tests are deterministic).
      */
     recentByBackend(windowMs: number, nowMs: number): Map<string, BackendFailureSummary>;
 }

package/dist/scaler/file-tail.d.ts

@@ -1,12 +1,6 @@
 /**
- * File tailing utility for append-only log files.
- *
- * Provides an async generator that yields complete lines as they are appended
- * to a file, using `fs.watchFile()` for change notifications and partial line
- * buffering for split writes.
- *
- * Used by the Firecracker backend to tail serial console and VMM log files
- * from the jailer chroot directory. The guest writes to `/dev/console`
+ * Tails append-only log files: the Firecracker backend tails the serial console
+ * and VMM log files in the jailer chroot. The guest writes to `/dev/console`
  * unprivileged, so everything this module buffers is tenant-controlled: every
  * buffer here is bounded, and an overflow is reported in-band rather than
  * growing the orchestrator's heap.
@@ -19,8 +13,8 @@
  */
 export declare const MAX_LINE_BYTES: number;
 /**
- * Largest slice read from the file per poll. A burst is drained across several
- * ticks instead of materialising the whole delta in one string.
+ * Largest slice read per poll, so a burst drains across several reads instead
+ * of materialising the whole delta in one string.
  */
 export declare const MAX_READ_BYTES: number;
 /**
@@ -32,15 +26,8 @@ export declare const MAX_READ_BYTES: number;
  */
 export declare const MAX_QUEUED_LINES = 10000;
 /**
- * Tail an append-only file, yielding complete lines as they are written.
- *
- * Pre-creates the file if it does not exist to avoid watch errors.
- * Tracks byte offset and partial (incomplete) trailing lines across reads.
- * Stops when the provided AbortSignal is triggered.
- *
- * @param filePath - Path to the file to tail
- * @param signal - AbortSignal to stop tailing
- * @yields Complete lines (non-empty) as they are appended to the file
+ * Tail an append-only file, yielding complete non-empty lines as they are
+ * written, until `signal` aborts. Pre-creates the file to avoid watch errors.
  */
 export declare function tailFile(filePath: string, signal: AbortSignal): AsyncGenerator<string>;
 //# sourceMappingURL=file-tail.d.ts.map

package/dist/scaler/firecracker-api.d.ts

@@ -1,10 +1,7 @@
 /**
- * Firecracker REST API client over Unix domain sockets.
+ * Firecracker REST API client over a Unix domain socket (`http` with `socketPath`).
  *
- * Provides a thin wrapper around Node.js built-in `http` module for communicating
- * with Firecracker's REST API. Uses the `socketPath` option for HTTP-over-Unix-socket.
- *
- * Only used for post-boot operations:
+ * Post-boot operations only:
  * - MMDS data injection (passing agent config to the guest VM)
  * - Graceful shutdown via SendCtrlAltDel (x86_64 only)
  * - Socket readiness polling after jailer invocation
@@ -14,94 +11,53 @@
  * @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md
  * @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md
  */
-/**
- * Error thrown when the Firecracker API returns a non-2xx status code
- * or a network-level error occurs.
- */
+/** A non-2xx Firecracker API response, or a network-level error. */
 export declare class FirecrackerApiError extends Error {
-    /** HTTP status code from the Firecracker API (undefined for network errors) */
+    /** Undefined for a network error. */
     readonly statusCode: number | undefined;
-    /** The API path that was requested */
     readonly path: string;
-    /** The response body from the Firecracker API */
     readonly responseBody: string;
     constructor(message: string, path: string, statusCode?: number, responseBody?: string);
 }
-/**
- * Thin REST client for the Firecracker API over Unix domain sockets.
- *
- * No external dependencies -- uses Node.js built-in `http` module with
- * the `socketPath` option for HTTP-over-Unix-socket communication.
- */
 export declare class FirecrackerApi {
     private readonly socketPath;
     /**
-     * Aborts every in-flight and subsequent request on this client.
-     *
-     * Set by the spawn path so a spawn deadline actually stops the VM
-     * provisioning calls, rather than leaving them running against a VM the
-     * manager has already given up on.
+     * Aborts every in-flight and later request. The spawn path sets it so a spawn
+     * deadline stops the provisioning calls against a VM the manager gave up on.
      */
     private signal;
     constructor(socketPath: string, signal?: AbortSignal);
-    /**
-     * Send an HTTP request to the Firecracker API.
-     *
-     * @param method - HTTP method (GET, PUT, PATCH)
-     * @param path - API path (e.g., '/mmds', '/actions', '/')
-     * @param body - Optional JSON body for PUT/PATCH requests
-     * @returns Response with statusCode and body
-     * @throws FirecrackerApiError on non-2xx status or network error
-     */
+    /** @throws FirecrackerApiError on a non-2xx status or a network error */
     private request;
     /**
-     * Inject MMDS (Micro VM Metadata Service) data into a running VM.
-     *
-     * Uses MMDS v2 data injection endpoint. The data should follow the structure:
-     * `{ latest: { 'meta-data': { ... } } }`
+     * Inject MMDS (Micro VM Metadata Service) v2 data into a running VM, shaped
+     * `{ latest: { 'meta-data': { ... } } }`. The guest reads it from
+     * http://169.254.169.254/latest/meta-data/ with a token-based session.
      *
-     * The guest VM reads this data from http://169.254.169.254/latest/meta-data/
-     * using a token-based session (MMDS v2).
-     *
-     * @param data - Metadata object to inject
      * @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md
      */
     putMmds(data: Record<string, unknown>): Promise<void>;
     /**
-     * Clear MMDS data after agent has received config via WS.
-     * Replaces the MMDS data with an empty meta-data object.
-     * Called after receiving config.ack from the agent.
+     * Replace the MMDS data with an empty meta-data object once the agent's
+     * config.ack confirms it received its config over WS.
      */
     clearMmds(): Promise<void>;
     /**
-     * Send a SendCtrlAltDel action for graceful x86_64 shutdown.
-     *
-     * This simulates pressing Ctrl+Alt+Del on the virtual keyboard,
-     * which triggers a clean shutdown in most Linux distributions.
-     *
-     * Note: Only works on x86_64. On arm64, the i8042 keyboard controller
-     * is not available, so this action is not supported. Use process kill
-     * as fallback on arm64.
+     * Graceful shutdown: Ctrl+Alt+Del on the virtual keyboard, which most Linux
+     * distributions answer with a clean shutdown. x86_64 only: arm64 has no i8042
+     * keyboard controller, so kill the process there instead.
      *
      * @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md
      */
     sendCtrlAltDel(): Promise<void>;
     /**
-     * Get instance info from the Firecracker API root endpoint.
-     *
-     * Used to check if the API socket is reachable and the VM is running.
-     * Returns the parsed JSON response with instance information.
+     * Instance info from the API root, parsed. Doubles as the check that the API
+     * socket is reachable and the VM is running.
      */
     getInstanceInfo(): Promise<Record<string, unknown>>;
     /**
-     * Poll the Firecracker API socket until it becomes reachable or timeout expires.
-     *
-     * Used after jailer invocation to wait for Firecracker to create the API socket
-     * and become ready to accept requests.
-     *
-     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
-     * @param intervalMs - Polling interval in milliseconds (default: 100)
-     * @returns true if socket became reachable, false on timeout
+     * Poll the API socket after the jailer starts, until Firecracker accepts
+     * requests (true) or `timeoutMs` passes (false). Both arguments are in ms.
      */
     waitForSocket(timeoutMs?: number, intervalMs?: number): Promise<boolean>;
 }