@dbx-tools/appkit-lakebox 0.0.0-stage → 0.9.131

package/lib/src/runtime.d.ts

@@ -0,0 +1,154 @@
+import type { IncomingHttpHeaders } from "node:http";
+import { type LakeboxAuth } from "@dbx-tools/lakebox/rest";
+import { SshCommand } from "@dbx-tools/lakebox/session";
+import { type CreateLakeboxServiceRequest, type LakeboxCommandRequest, type LakeboxMetricsResponse, type LakeboxMetricsSnapshot, type LakeboxService, type LakeboxServiceLogsRequest, type LakeboxSummary, type LakeboxUser } from "@dbx-tools/shared-lakebox";
+import { LakeboxResourceRegistry } from "./_resource-registry.ts";
+import { LakeboxServiceSnapshots } from "./_service-snapshots.ts";
+import type { ResolvedLakeboxPluginConfig } from "./config.ts";
+import { LakeboxMetrics } from "./metrics.ts";
+import { LakeboxRouteRegistry } from "./routes.ts";
+/** Resolves the authenticated identity for raw request headers. */
+export type LakeboxIdentityResolver = (headers: IncomingHttpHeaders) => string | undefined;
+/** Minimal Lakebase pool used to drop legacy ownership schemas. */
+export interface LakeboxLegacyPool {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+/**
+ * Owns the single lazily created Lakebox of one application.
+ *
+ * Every Databricks Lakebox REST call uses the app service principal supplied
+ * through {@link initialize}; request identity only selects the internal Linux
+ * account. Each authenticated identity maps through one FNV-1a hash to a locked
+ * account, persistent home, route segment, and service ports. Lifecycle and
+ * per-boot bootstrap are serialized in-process; the persistent resource
+ * registry serializes first creation across replicas.
+ */
+export declare class LakeboxRuntime {
+    readonly config: ResolvedLakeboxPluginConfig;
+    readonly routes: LakeboxRouteRegistry;
+    readonly metrics: LakeboxMetrics;
+    private readonly keys;
+    private readonly stopParentTerminationSignal;
+    private readonly shutdownController;
+    private api?;
+    private identity;
+    /** In-memory identities of routed users; never persisted. */
+    private readonly routedIdentities;
+    private cached?;
+    private boot?;
+    /** Last boot that completed runtime bootstrap and produced a metrics sample. */
+    private readyBootKey?;
+    private converging?;
+    private waking?;
+    private metricsLease?;
+    private idleTimer?;
+    private lastActivity;
+    private activeCommands;
+    /** Last service states per user hash, kept after an idle session release. */
+    private readonly lastServices;
+    private readonly lastServicesObservedAt;
+    private resourceRegistry?;
+    private serviceSnapshots?;
+    private closing?;
+    /** Creates a runtime from resolved plugin configuration. */
+    constructor(config: ResolvedLakeboxPluginConfig);
+    /**
+     * Supplies app service-principal credentials and the request identity
+     * resolver used by routes.
+     */
+    initialize(auth: LakeboxAuth, identity?: LakeboxIdentityResolver, serviceSnapshots?: LakeboxServiceSnapshots, resourceRegistry?: LakeboxResourceRegistry): void;
+    /** Derives the Lakebox account for one authenticated identity. */
+    user(identity: string): LakeboxUser;
+    /** Summarizes the app Lakebox for one user without creating it. */
+    summary(identity: string, signal?: AbortSignal): Promise<LakeboxSummary>;
+    /** Creates the Lakebox when needed, starts it, and restores saved services. */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Stops the shared Lakebox for every user. Files and saved services persist. */
+    stop(signal?: AbortSignal): Promise<void>;
+    /** Permanently deletes the managed Lakebox and every user's files. */
+    delete(signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Runs one command as the user's account, creating or starting the Lakebox
+     * when `auto` is enabled.
+     */
+    execute(identity: string, input: LakeboxCommandRequest, signal?: AbortSignal): SshCommand;
+    /** Lists the user's services, including idle built-ins. Never creates the Lakebox. */
+    listServices(identity: string, signal?: AbortSignal): Promise<LakeboxService[]>;
+    /** Creates or replaces one image service and waits until it is ready or failed. */
+    createService(identity: string, input: CreateLakeboxServiceRequest, signal?: AbortSignal): Promise<LakeboxService>;
+    /** Starts a saved service or a built-in and waits until it is ready or failed. */
+    startService(identity: string, name: string, signal?: AbortSignal): Promise<LakeboxService>;
+    /** Stops one running service without removing its definition. */
+    stopService(identity: string, name: string, signal?: AbortSignal): Promise<LakeboxService>;
+    /** Stops and deletes one saved service. Mounted home directories are preserved. */
+    removeService(identity: string, name: string, signal?: AbortSignal): Promise<boolean>;
+    /** Reads a bounded tail of one service log. */
+    serviceLogs(identity: string, input: LakeboxServiceLogsRequest, signal?: AbortSignal): Promise<{
+        log: string;
+    }>;
+    /**
+     * Returns recent metrics and keeps sampling for one lease interval. Sampling
+     * runs only while the Lakebox runs and a caller is watching, so metrics never
+     * keep an otherwise idle Lakebox awake.
+     */
+    metricsResponse(signal?: AbortSignal): Promise<LakeboxMetricsResponse>;
+    /** Subscribes to metrics snapshots while the Lakebox runs. */
+    subscribeMetrics(listener: (snapshot: LakeboxMetricsSnapshot) => void): () => void;
+    /**
+     * Deletes legacy per-user Lakeboxes and drops legacy ownership schemas.
+     *
+     * There is no migration: the earlier one-machine-per-user model is removed.
+     * The managed app Lakebox and Lakeboxes with other names are never touched.
+     */
+    cleanupLegacy(pool?: LakeboxLegacyPool, signal?: AbortSignal): Promise<void>;
+    /** Cancels in-flight work before teardown. */
+    abortActiveOperations(): void;
+    /** Closes routes, metrics, and the SSH session without changing the Lakebox. */
+    close(): Promise<void>;
+    private client;
+    private resources;
+    /** Returns the managed Lakebox entry, cached briefly to keep routes cheap. */
+    private entry;
+    private bootKey;
+    private productStatus;
+    /** Serializes create, start, connect, and bootstrap for the current boot. */
+    private ready;
+    private converge;
+    private connect;
+    /** Runs the fixed privileged bootstrap and returns the restored user hashes. */
+    private bootstrap;
+    private admin;
+    /** Marks activity, readies the current boot, and converges the user's account. */
+    private readyUser;
+    /** Creates or verifies the user's account once per boot. */
+    private convergeUser;
+    private restoreUser;
+    private controller;
+    private runService;
+    private refreshServices;
+    private cacheService;
+    private serviceListing;
+    private persistServiceSnapshot;
+    private withBuiltIns;
+    private idleServices;
+    /** Resolves one routed request, waking the Lakebox or service in the background. */
+    private resolveRoute;
+    private markUnavailable;
+    private wake;
+    private readMetrics;
+    private leaseMetrics;
+    /**
+     * Releases the SSH session after the idle timeout without commands, service
+     * operations, routed traffic, open streams, or metrics watchers. An open
+     * session counts as activity for the platform watchdog, so releasing it lets
+     * the platform stop the Lakebox after its own idle timeout. The next request
+     * reconnects.
+     */
+    private watchIdle;
+    private touch;
+    private discardBoot;
+}
+/** Returns whether an error means the managed Lakebox no longer exists. */
+export declare function isLakeboxMissing(error: unknown): boolean;