libre-webui 0.19.6 → 0.20.0

package/backend/dist/services/workRuntimeDriver.d.ts

@@ -0,0 +1,166 @@
+import type { Duplex } from 'node:stream';
+import type { WorkTaskRecord } from '../types/work.js';
+import { ProcessOptions, ProcessResult, ResolvedWorkRuntimePolicy } from './workRuntimeShared.js';
+export interface WorkExecOptions extends ProcessOptions {
+    /** Working directory inside the sandbox. Defaults to /workspace. */
+    workdir?: string;
+}
+export interface DiscoveredWorkContainer {
+    name: string;
+    taskId: string;
+    running: boolean;
+}
+export type WorkRuntimeState = 'absent' | 'stopped' | 'running';
+/**
+ * A raw interactive TTY attached to the sandbox: bidirectional terminal
+ * bytes plus a resize control channel. Session policy (per-task limits,
+ * holds, idle timeouts) lives with the terminal service, not here.
+ */
+export interface WorkTerminalTransport {
+    stream: Duplex;
+    resize: (cols: number, rows: number) => Promise<void>;
+}
+/**
+ * The mechanics of running one task sandbox, behind which a runtime backend
+ * (Docker today, Kubernetes later) is interchangeable. The runtime service
+ * owns every policy decision — admission, leases, lifecycle locks, task
+ * ownership rules, output budgets — and calls a driver only to make the
+ * sandbox world match what policy already decided. Drivers verify resource
+ * ownership labels before every destructive operation; they never decide
+ * whether an operation should happen.
+ */
+export interface WorkRuntimeDriver {
+    /** Reject with an operator-actionable reason when the backend is down. */
+    probe(): Promise<void>;
+    /** Kill in-flight backend processes during shutdown. */
+    shutdown(): void;
+    /** Make a runtime image available. No cross-call deduplication. */
+    ensureImage(image?: string): Promise<void>;
+    /** Create the task workspace if needed; verify ownership if it exists. */
+    ensureWorkspace(task: WorkTaskRecord): Promise<void>;
+    /**
+     * Bring the sandbox to a running state with a policy-fresh configuration,
+     * recreating it when its recorded policy is stale.
+     */
+    ensureRuntime(task: WorkTaskRecord): Promise<void>;
+    /** Current sandbox state; verifies ownership when the sandbox exists. */
+    runtimeState(task: WorkTaskRecord): Promise<WorkRuntimeState>;
+    /** Stop the sandbox if it exists. Ownership-checked; absent is a no-op. */
+    stopRuntime(task: WorkTaskRecord): Promise<void>;
+    /** Remove the sandbox if it exists. Ownership-checked; absent is a no-op. */
+    removeRuntime(task: WorkTaskRecord): Promise<void>;
+    /**
+     * Remove the sandbox and workspace together. Every destructive target is
+     * ownership-validated before either is removed, so a conflicting unmanaged
+     * resource cannot cause partial cleanup.
+     */
+    removeTaskResources(task: WorkTaskRecord): Promise<void>;
+    /** Run a command inside the sandbox as the unprivileged sandbox user. */
+    exec(task: WorkTaskRecord, command: string[], options?: WorkExecOptions): Promise<ProcessResult>;
+    /**
+     * Endpoint the backend can reach the task's preview server on, if any.
+     * A missing host means the proxy's configured upstream host (the Docker
+     * publish interface); Kubernetes returns the sandbox Pod IP.
+     */
+    previewEndpoint(task: WorkTaskRecord): Promise<{
+        host?: string;
+        port: number;
+    } | undefined>;
+    /** Every sandbox this runtime has ever created, by ownership label. */
+    listManaged(): Promise<DiscoveredWorkContainer[]>;
+    /** Force-remove a managed sandbox whose task record no longer exists. */
+    removeOrphan(name: string): Promise<void>;
+    /**
+     * Every workspace this runtime has created, by ownership label, so
+     * reconciliation can report workspaces whose task record no longer
+     * exists. Orphaned workspaces are only reported, never auto-deleted.
+     */
+    listWorkspaces?(): Promise<{
+        name: string;
+        taskId: string;
+    }[]>;
+    /** Why interactive terminals are unavailable on this backend, if so. */
+    terminalUnavailableReason(): string | null;
+    /** Open an interactive TTY inside the sandbox as the unprivileged user. */
+    openTerminal(containerName: string): Promise<WorkTerminalTransport>;
+}
+export declare class DockerWorkRuntimeDriver implements WorkRuntimeDriver {
+    readonly image: string;
+    probe(): Promise<void>;
+    shutdown(): void;
+    ensureImage(image?: string): Promise<void>;
+    ensureWorkspace(task: WorkTaskRecord): Promise<void>;
+    ensureRuntime(task: WorkTaskRecord): Promise<void>;
+    runtimeState(task: WorkTaskRecord): Promise<WorkRuntimeState>;
+    stopRuntime(task: WorkTaskRecord): Promise<void>;
+    removeRuntime(task: WorkTaskRecord): Promise<void>;
+    removeTaskResources(task: WorkTaskRecord): Promise<void>;
+    exec(task: WorkTaskRecord, command: string[], options?: WorkExecOptions): Promise<ProcessResult>;
+    previewEndpoint(task: WorkTaskRecord): Promise<{
+        host?: string;
+        port: number;
+    } | undefined>;
+    /**
+     * Every container the Work runtime has ever created, in one daemon query,
+     * identified by the managed label stamped at `docker run` time.
+     */
+    listManaged(): Promise<DiscoveredWorkContainer[]>;
+    removeOrphan(name: string): Promise<void>;
+    /**
+     * The terminal talks to the Docker Engine API directly because a TTY exec
+     * needs a hijacked bidirectional stream, which the docker CLI only offers
+     * to an interactive controlling terminal. The connection is the resolved
+     * Docker endpoint: the Unix socket, or a plain-HTTP tcp:// endpoint such
+     * as a socket proxy holding the socket on the app's behalf — the hijacked
+     * stream survives an HTTP-aware proxy because it rides a standard
+     * Connection: Upgrade tunnel. Endpoints this client cannot speak to
+     * (ssh://, TLS-verified tcp) make the terminal report itself unavailable
+     * instead of guessing.
+     */
+    private readonly terminalEndpoint;
+    terminalUnavailableReason(): string | null;
+    openTerminal(containerName: string): Promise<WorkTerminalTransport>;
+    /**
+     * Transport options for the resolved endpoint. A Unix socket needs an
+     * explicit Host header (there is no authority in the request target); a
+     * tcp endpoint gets the real host:port so an HTTP-aware proxy can route
+     * on it.
+     */
+    private terminalTransport;
+    private terminalApi;
+    private startExecStream;
+    private ensureWorkNetwork;
+    private initializeVolume;
+    private volumeExists;
+    private containerExists;
+    private containerIsRunning;
+    private assertManagedContainer;
+    private containerMatchesTaskPolicy;
+    private assertManagedVolume;
+    docker(args: string[], options?: ProcessOptions): Promise<ProcessResult>;
+}
+export interface ExecCreatePayload {
+    AttachStdin: boolean;
+    AttachStdout: boolean;
+    AttachStderr: boolean;
+    Tty: boolean;
+    User: string;
+    WorkingDir: string;
+    Env: string[];
+    Cmd: string[];
+}
+export declare function buildExecCreatePayload(shell?: readonly string[]): ExecCreatePayload;
+/** Parse `docker ps` lines of `name\tstate\ttask-label` into containers. */
+export declare function parseManagedContainerList(stdout: string): DiscoveredWorkContainer[];
+/** Bracket a bare IPv6 literal so it can carry a port in a URL. */
+export declare function formatPreviewHost(host: string): string;
+/**
+ * Turn a failed `docker info` into the change an operator has to make. These
+ * are the three ways a containerized Libre WebUI fails to reach the daemon:
+ * the image has no CLI, the bind-mounted socket is owned by a group the
+ * backend user is not in, or no daemon is listening.
+ */
+export declare function describeDockerUnavailable(error: unknown, dockerCommand?: string): string;
+export declare function buildWorkContainerRunArgs(task: WorkTaskRecord, policy?: ResolvedWorkRuntimePolicy): string[];
+export declare function parsePublishedPort(output: string, _containerPort?: number, bindAddress?: string): number | undefined;
+//# sourceMappingURL=workRuntimeDriver.d.ts.map

package/backend/dist/services/workRuntimeDriver.d.ts.map

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