@kici-dev/orchestrator 0.1.15 → 0.1.17

package/dist/routes/uploads.d.ts

@@ -1,38 +1,48 @@
 /**
- * REST endpoints for test run upload management.
+ * Test-run upload provisioning.
  *
- * POST /api/v1/uploads/init           - Initialize an upload (returns signed URL + public key)
- * GET  /api/v1/uploads/:uploadId/status - Check upload status
- *
- * Uploads support the repo state transfer mechanism: CLI uploads an encrypted
- * tarball of changed files to S3 via a pre-signed URL, then references the
- * upload ID in the test trigger request.
+ * Mints an upload record and a presigned PUT URL + ephemeral X25519 public key
+ * for the overlay tarball. The developer encrypts the tarball with the returned
+ * public key and PUTs it directly to the object store; a test trigger then
+ * references the upload id. This is invoked by the Platform-first
+ * `test.relay.uploads.init` relay handler — the developer never reaches the
+ * orchestrator's HTTP API directly.
  */
-import { Hono } from 'hono';
-import type { AppConfig } from '../config.js';
-import type { TokenManager } from '../secrets/token-manager.js';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { CacheStorage } from '../storage/types.js';
-/**
- * Dependencies for upload routes.
- */
-export interface UploadRouteDeps {
-    config: AppConfig;
+/** Parameters for {@link initTestUpload}. */
+export interface InitTestUploadParams {
+    routingKey: string;
+    sha?: string;
+    fileCount?: number;
+    compressedSize?: number;
+    /** PAT/actor identity that owns this upload, written to `test_uploads.created_by`. */
+    createdBy?: string | null;
+    /**
+     * When true, presign with the host-facing internal endpoint. When false (the
+     * Platform-relayed path), presign with the external/dev-reachable endpoint so
+     * a developer on a different network can PUT directly to the object store.
+     */
+    internal?: boolean;
+}
+/** Result of {@link initTestUpload}. */
+export interface InitTestUploadResult {
+    uploadId: string;
+    signedUrl: string;
+    publicKey: string;
+    expiresIn: number;
+}
+/** Dependencies for {@link initTestUpload}. */
+export interface InitTestUploadDeps {
     db: Kysely<Database>;
-    tokenManager?: TokenManager;
     cacheStorage?: CacheStorage;
 }
-/** Hono env type for upload routes with context variables. */
-type UploadEnv = {
-    Variables: {
-        userId: string;
-        routingKey: string | null;
-    };
-};
 /**
- * Create Hono routes for upload management endpoints.
+ * Mint an upload record and return a presigned PUT URL + ephemeral X25519
+ * public key. The encryption keypair is generated per upload; the private key
+ * is stored orchestrator-side for post-PUT decryption. The `internal` flag
+ * selects the host-facing vs the external/dev-reachable presign endpoint.
  */
-export declare function createUploadRoutes(deps: UploadRouteDeps): Hono<UploadEnv>;
-export {};
+export declare function initTestUpload(deps: InitTestUploadDeps, params: InitTestUploadParams): Promise<InitTestUploadResult>;
 //# sourceMappingURL=uploads.d.ts.map

package/dist/scaler/config.d.ts

@@ -89,6 +89,7 @@ export declare const firecrackerNetworkSchema: z.ZodObject<{
     bridgeName: z.ZodDefault<z.ZodString>;
     gateway: z.ZodDefault<z.ZodString>;
     netmask: z.ZodDefault<z.ZodString>;
+    table: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Zod schema for the complete scaler configuration file.
@@ -241,10 +242,10 @@ export declare const scalerFileSchema: z.ZodObject<{
         }, z.core.$strip>>;
         mandatoryLabels: z.ZodDefault<z.ZodArray<z.ZodString>>;
         roles: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            all: "all";
             builder: "builder";
             "init-runner": "init-runner";
-            all: "all";
-        }>>>, z.ZodTransform<string[] | undefined, ("builder" | "init-runner" | "all")[] | undefined>>;
+        }>>>, z.ZodTransform<string[] | undefined, ("all" | "builder" | "init-runner")[] | undefined>>;
         resourceCap: z.ZodOptional<z.ZodPipe<z.ZodObject<{
             maxCpu: z.ZodOptional<z.ZodNumber>;
             maxMemory: z.ZodOptional<z.ZodString>;
@@ -272,6 +273,7 @@ export declare const scalerFileSchema: z.ZodObject<{
         bridgeName: z.ZodDefault<z.ZodString>;
         gateway: z.ZodDefault<z.ZodString>;
         netmask: z.ZodDefault<z.ZodString>;
+        table: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**

package/dist/scaler/disk-guard.d.ts

@@ -0,0 +1,27 @@
+import { type ReapCounts } from './reap-orphans.js';
+import type { ScalerConfig } from './index.js';
+/** Default minimum free space before startup is allowed to proceed: 1 GiB. */
+export declare const DEFAULT_DISK_GUARD_THRESHOLD_BYTES: number;
+export interface DiskGuardResult {
+    reaped: boolean;
+    recovered: boolean;
+    freeBytesAfter: number;
+}
+interface DiskGuardOpts {
+    scalerConfig: ScalerConfig;
+    thresholdBytes?: number;
+    /** Injectable for tests. */
+    statfsFn?: (path: string) => Promise<{
+        bavail: bigint;
+        bsize: number;
+    }>;
+    reapFn?: (cfg: ScalerConfig) => Promise<ReapCounts>;
+}
+/**
+ * Run the disk guard. Returns reaped/recovered status; the caller decides
+ * whether to proceed or exit with backoff. No-ops (recovered=true) when there
+ * is no FC scaler or free space is already above threshold.
+ */
+export declare function runDiskGuard(opts: DiskGuardOpts): Promise<DiskGuardResult>;
+export {};
+//# sourceMappingURL=disk-guard.d.ts.map

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

@@ -61,10 +61,14 @@ export interface FirecrackerScalerBackendOptions {
     memSizeMib?: number;
     /** Bridge interface name for TAP attachment */
     bridgeName: string;
+    /** Network CIDR (e.g. '10.0.0.0/24'); supplies the prefix for the bridge gateway CIDR. */
+    cidr?: string;
     /** Gateway IP for guest networking */
     gateway: string;
     /** Netmask for guest networking */
     netmask: string;
+    /** nft table name for host-network diagnostics. @default 'kici' */
+    table?: string;
     /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
@@ -99,8 +103,10 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     private readonly vcpuCount;
     private readonly memSizeMib;
     private readonly bridgeName;
+    private readonly cidr;
     private readonly gateway;
     private readonly netmask;
+    private readonly table;
     private readonly tokenStore?;
     private readonly tokenTtlMs;
     private readonly roles;
@@ -120,6 +126,18 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     getActiveCount(): number;
     spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
+    /**
+     * Bridge config for host-network diagnostics (read-only snapshot).
+     * `bridgeCidr` is the gateway IP with the network prefix (e.g. '10.0.0.1/24'),
+     * which is exactly what `provisionBridge`/`verifyBridge` consume. The prefix
+     * comes from the configured network `cidr`; if absent, it is derived from the
+     * dotted `netmask`.
+     */
+    getBridgeConfig(): {
+        bridgeName: string;
+        bridgeCidr: string;
+        table: string;
+    };
     destroy(managedId: string): Promise<void>;
     shutdownAll(): Promise<void>;
     /**

package/dist/scaler/manager.d.ts

@@ -336,6 +336,12 @@ export declare class ScalerManager {
      * Returns null if the agent is not scaler-managed (standalone).
      */
     getBackendForAgent(agentId: string): string | null;
+    /**
+     * Get a backend instance by scaler name. Returns undefined for an unknown
+     * name. Used by diagnostics to reach backend-specific accessors (e.g. the
+     * Firecracker backend's `getBridgeConfig()`).
+     */
+    getBackend(name: string): ScalerBackend | undefined;
     /**
      * Get scaler-specific configuration metadata for a managed agent.
      * Returns undefined for non-scaler-managed (static) agents.

package/dist/scaler/nftables.d.ts

@@ -17,6 +17,10 @@ import type { NetworkPolicy } from './types.js';
  * - 'saddr': Match on source IP address (container backends)
  */
 export type NftMatchMode = 'iifname' | 'saddr';
+/** RFC1918 private address ranges. */
+export declare const RFC1918_RANGES: string[];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+export declare const METADATA_RANGE = "169.254.0.0/16";
 /**
  * Options for nft command execution.
  */

package/dist/scaler/reap-orphans.d.ts

@@ -0,0 +1,27 @@
+import type { ScalerConfig } from './index.js';
+/** Per-scaler orphan counts, keyed by scaler name. */
+export type ReapCounts = Record<string, number>;
+/**
+ * Reap orphan Firecracker resources (dead-VM chroots + TAPs) for every
+ * `firecracker` scaler in the config. Safe to run alongside a live
+ * orchestrator: the reap is liveness-driven and only touches dead VMs.
+ */
+export declare function reapFirecrackerOrphans(scalerConfig: ScalerConfig): Promise<ReapCounts>;
+/**
+ * Reap orphan container resources for every `container` scaler. Unlike the FC
+ * reap, container cleanup is unconditional (it removes every kici-managed
+ * container), so callers MUST ensure the orchestrator is NOT running before
+ * invoking this — otherwise live agents are killed. The CLI command enforces
+ * this via the /health gate.
+ */
+export declare function reapContainerOrphans(scalerConfig: ScalerConfig): Promise<ReapCounts>;
+/**
+ * Reap orphans for all supported backends. Firecracker is always reaped
+ * (liveness-driven, safe). Containers are reaped only when includeContainers
+ * is set (caller has confirmed the orchestrator is down).
+ */
+export declare function reapAllOrphans(opts: {
+    scalerConfig: ScalerConfig;
+    includeContainers: boolean;
+}): Promise<ReapCounts>;
+//# sourceMappingURL=reap-orphans.d.ts.map

package/dist/scaler/types.d.ts

@@ -248,6 +248,8 @@ export interface FirecrackerNetworkConfig {
     gateway?: string;
     /** Subnet mask for guest networking @default '255.255.255.0' */
     netmask?: string;
+    /** nft table name for this coordinator's host bridge @default 'kici' */
+    table?: string;
 }
 /**
  * Parsed and validated scaler configuration from YAML.