@exagone313/dsh-podman 0.2.0-rc.3 → 0.2.0

package/dist/workspace-binding.d.ts

@@ -4,6 +4,7 @@ export interface WorkspaceBinding {
     token: string;
     socket: string;
     defaultCwd?: string;
+    refresh?: () => Promise<WorkspaceBinding>;
 }
 export interface BindingConfig {
     socketsRoot: string;
@@ -11,30 +12,38 @@ export interface BindingConfig {
     projectsRoot: string;
     controlToken: string;
     readyTimeoutMs?: number;
+    containerEnv?: Record<string, string>;
 }
 export declare class WorkspaceResolver {
     private readonly config;
     private readonly registry;
     private readonly bindings;
-    constructor(config: BindingConfig, registry: any);
-    setConfig(patch: Partial<BindingConfig>): void;
+    private readonly containerBindings;
+    constructor(config: BindingConfig | (() => BindingConfig), registry: any);
     getConfig(): Readonly<BindingConfig>;
-    resolve(cwd: unknown): Promise<WorkspaceBinding>;
-    resolveForPath(path: string, cwd: unknown): Promise<WorkspaceBinding>;
+    dispose(): void;
+    forgetContainer(slug: string, container: string): void;
+    forgetWorkspace(slug: string): void;
+    resolve(cwd: unknown, signal?: AbortSignal): Promise<WorkspaceBinding>;
+    resolveForPath(path: string, cwd: unknown, signal?: AbortSignal): Promise<WorkspaceBinding>;
     private containingWorkspace;
     private workspaceForCwd;
-    resolveSlug(key: string): Promise<WorkspaceBinding>;
-    containerBinding(cwd: unknown, container: string): Promise<WorkspaceBinding>;
+    resolveSlug(key: string, signal?: AbortSignal): Promise<WorkspaceBinding>;
+    containerBinding(cwd: unknown, container: string, signal?: AbortSignal): Promise<WorkspaceBinding>;
+    private resolveContainerBinding;
+    private buildContainerBinding;
     private ready;
     private readyTimeoutMs;
-    private ensureReady;
+    private bindingFor;
+    private ensureAgentReady;
     private recoverContainer;
     private resolveBinding;
     private create;
-    control<T>(method: string, request: unknown): Promise<T>;
+    private ensureContainer;
+    control<T>(method: string, request: unknown, signal?: AbortSignal): Promise<T>;
+    private invalidateAfter;
 }
 export declare function containerNotFound(container: string, slug?: string): Error;
 export declare function normalizeToolError(error: unknown): Error;
 export declare function workspaceSlug(id: unknown): string;
-export declare function containerRowFor(containers: any[], slug: string, container: string): any | undefined;
-export declare function metadata(token: string): grpc.Metadata;
+export declare function metadata(token: string, pluginVersion?: string): grpc.Metadata;

package/dist/workspace-binding.js

@@ -1,31 +1,75 @@
 // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
 //
 // SPDX-License-Identifier: MIT
-import { guestClient, controlClient, grpc, unary, } from "./grpc/runtime-client.js";
+import { closeClients, controlClient, grpc, guestClient, unary, } from "./grpc/runtime-client.js";
+import { mergeDefaultEnv } from "./container-env.js";
 import { isAbsolute, join } from "node:path";
+import { VERSION } from "./generated/version.js";
+// The control calls that change a container's mount set or recreate it. A
+// successful call invalidates the cached binding for that container (or for
+// every container of a removed workspace), because the cached mounts decide
+// whether the session directory is exposed as the container's default cwd.
+const CONTAINER_MUTATIONS = {
+    startContainer: "container",
+    recreateContainer: "container",
+    removeContainer: "container",
+    addContainerMount: "container",
+    removeContainerMount: "container",
+    updateContainerMount: "container",
+    addContainerSecret: "container",
+    removeContainerSecret: "container",
+    removeWorkspace: "workspace",
+};
 export class WorkspaceResolver {
     config;
     registry;
     bindings = new Map();
-    constructor(config, registry) {
+    // Named containers get their own cache, keyed by "<slug>:<logical name>", so
+    // resolving one does not re-run ensureContainer, rebuild a gRPC channel, and
+    // wait for readiness on every tool call.
+    containerBindings = new Map();
+    constructor(
+    // A reader rather than a snapshot: the plugin's preferences are volatile
+    // config fields, so every call must observe their current values.
+    config, registry) {
         this.config = config;
         this.registry = registry;
     }
-    setConfig(patch) {
-        Object.assign(this.config, patch);
-    }
     getConfig() {
-        return this.config;
+        return typeof this.config === "function" ? this.config() : this.config;
+    }
+    // dispose closes every cached gRPC channel and drops the cached bindings.
+    // Called when the plugin is disposed so a reload does not leak unix sockets.
+    dispose() {
+        this.bindings.clear();
+        this.containerBindings.clear();
+        closeClients();
+    }
+    // forgetContainer drops the cached binding for one named container, so the
+    // next call re-resolves its row and picks up a changed mount set.
+    forgetContainer(slug, container) {
+        this.containerBindings.delete(`${slug}:${container}`);
+    }
+    // forgetWorkspace drops every cached container binding of one workspace, so
+    // a removed (or recreated) workspace cannot serve stale rows.
+    forgetWorkspace(slug) {
+        const prefix = `${slug}:`;
+        for (const key of [...this.containerBindings.keys()]) {
+            if (key.startsWith(prefix))
+                this.containerBindings.delete(key);
+        }
     }
-    async resolve(cwd) {
+    async resolve(cwd, signal) {
         const workspace = await this.workspaceForCwd(cwd);
-        const relativePath = String(workspace.path).replace(`${this.config.projectsRoot}/`, "");
         const key = workspaceSlug(workspace.id);
-        const binding = await this.ready(key, relativePath);
+        const projectName = projectNameForPath(this.getConfig().projectsRoot, workspace.path);
+        const binding = await this.ready(key, projectName, signal);
         // The default container always keeps its project mount, so the session
         // directory is always mounted in it.
         const session = defaultCwdOf(cwd);
-        return session === undefined ? binding : { ...binding, defaultCwd: session };
+        return session === undefined
+            ? binding
+            : { ...binding, defaultCwd: session };
     }
     // Resolve the workspace binding for a filesystem path when the caller did not
     // supply a session working directory. The 0.1.5 `fs.resolve` contract allows
@@ -33,13 +77,14 @@ export class WorkspaceResolver {
     // sensible owner, so match it by longest canonical-path prefix. A path
     // outside every workspace is not in any container's filesystem, so it is
     // reported as missing rather than failing the caller.
-    async resolveForPath(path, cwd) {
+    async resolveForPath(path, cwd, signal) {
         if (typeof cwd === "string" && cwd !== "")
-            return this.resolve(cwd);
+            return this.resolve(cwd, signal);
         if (isAbsolute(path)) {
             const workspace = this.containingWorkspace(path);
-            if (workspace !== undefined)
-                return this.resolve(String(workspace.path));
+            if (workspace !== undefined) {
+                return this.resolve(String(workspace.path), signal);
+            }
             throw notFoundError(`no DH workspace contains path ${JSON.stringify(path)}`);
         }
         throw new Error(`cannot resolve a DH workspace for path ${JSON.stringify(path)}; pass a session working directory`);
@@ -69,89 +114,141 @@ export class WorkspaceResolver {
         }
         return workspace;
     }
-    resolveSlug(key) {
-        return this.ready(key, key);
+    resolveSlug(key, signal) {
+        return this.ready(key, key, signal);
     }
-    async containerBinding(cwd, container) {
+    async containerBinding(cwd, container, signal) {
         const workspace = await this.workspaceForCwd(cwd);
         const slug = workspaceSlug(workspace.id);
-        const result = await this.control("listContainers", {});
-        const row = containerRowFor(result.containers ?? [], slug, container);
-        if (row === undefined) {
-            throw containerNotFound(container, slug);
+        const key = `${slug}:${container}`;
+        let entry = await this.resolveContainerBinding(slug, container, key, signal);
+        try {
+            entry = {
+                binding: await this.ensureAgentReady(entry.binding),
+                mounts: entry.mounts,
+            };
+        }
+        catch {
+            this.containerBindings.delete(key);
+            await this.recoverContainer(slug, container, signal);
+            entry = await this.resolveContainerBinding(slug, container, key, signal);
+            entry = {
+                binding: await this.ensureAgentReady(entry.binding),
+                mounts: entry.mounts,
+            };
         }
-        const socket = row.agentSocketPath;
-        const binding = {
-            guest: guestClient(socket),
-            token: row.agentToken,
-            socket,
-        };
         const session = defaultCwdOf(cwd);
         if (session !== undefined &&
-            projectMountCovers(this.config.projectsRoot, row.mounts ?? [], session)) {
-            binding.defaultCwd = session;
+            projectMountCovers(this.getConfig().projectsRoot, entry.mounts, session)) {
+            return { ...entry.binding, defaultCwd: session };
         }
-        await this.ensureReady(binding, slug, container);
-        return binding;
+        return entry.binding;
+    }
+    // resolveContainerBinding returns the cached promise for a named container,
+    // creating it once. It deliberately stops at an "ensureContainer + build a
+    // binding" step: readiness is per-call, so a credential refresh can never
+    // recurse through this path.
+    resolveContainerBinding(slug, container, key, signal) {
+        let entry = this.containerBindings.get(key);
+        if (entry === undefined) {
+            entry = this.buildContainerBinding(slug, container, key).catch((error) => {
+                if (this.containerBindings.get(key) === entry) {
+                    this.containerBindings.delete(key);
+                }
+                throw error;
+            });
+            this.containerBindings.set(key, entry);
+        }
+        return entry;
+    }
+    async buildContainerBinding(slug, container, key) {
+        const row = await this.ensureContainer(slug, container);
+        // refresh re-resolves the container row and swaps the cache entry, so a
+        // binding whose token rotated is not re-served from the stale cache.
+        const refresh = () => {
+            const next = this.buildContainerBinding(slug, container, key);
+            this.containerBindings.set(key, next);
+            return next.then((fresh) => fresh.binding);
+        };
+        return { binding: this.bindingFor(row, refresh), mounts: row.mounts ?? [] };
     }
     // ready resolves a workspace's default container and waits for its guest
     // agent, recreating the container once when it is reported running but its
     // agent never answers (a crashed agent or a lost socket).
-    async ready(key, projectName) {
-        let binding = await this.resolveBinding(key, projectName);
+    async ready(key, projectName, signal) {
+        let binding = await this.resolveBinding(key, projectName, signal);
         try {
-            await waitForReady(binding.guest, this.readyTimeoutMs());
+            return await this.ensureAgentReady(binding);
         }
         catch {
             this.bindings.delete(key);
-            binding = await this.resolveBinding(key, projectName);
+            binding = await this.resolveBinding(key, projectName, signal);
             try {
-                await waitForReady(binding.guest, this.readyTimeoutMs());
+                return await this.ensureAgentReady(binding);
             }
             catch {
-                await this.recoverContainer(key, "default");
+                await this.recoverContainer(key, "default", signal);
                 this.bindings.delete(key);
-                binding = await this.resolveBinding(key, projectName);
-                await waitForReady(binding.guest, this.readyTimeoutMs());
+                binding = await this.resolveBinding(key, projectName, signal);
+                return await this.ensureAgentReady(binding);
             }
         }
-        return binding;
     }
     readyTimeoutMs() {
-        const configured = Number(this.config.readyTimeoutMs);
+        const configured = Number(this.getConfig().readyTimeoutMs);
         return Number.isFinite(configured) && configured > 0 ? configured : 15000;
     }
-    // ensureReady waits for one binding's guest agent and recovers the container
-    // once when the wait fails.
-    async ensureReady(binding, slug, container) {
+    // bindingFor builds a binding from an orchestrator container row. refresh
+    // re-resolves it, so a caller can retry once after the agent rejects a token
+    // that went stale (the plugin caches bindings for its lifetime).
+    bindingFor(row, refresh) {
+        const socket = row.agentSocketPath;
+        return {
+            guest: guestClient(socket),
+            token: row.agentToken,
+            socket,
+            refresh,
+        };
+    }
+    // ensureAgentReady waits for the agent and verifies the credential with a
+    // Ping. A rejected credential is refreshed once (re-resolving the binding,
+    // which re-runs the orchestrator's ensure) and re-verified, so a token that
+    // rotated after the binding was cached does not fail the caller.
+    async ensureAgentReady(binding) {
+        await waitForReady(binding.guest, this.readyTimeoutMs());
         try {
-            await waitForReady(binding.guest, this.readyTimeoutMs());
-            return;
+            await pingAgent(binding);
+            return binding;
         }
-        catch {
-            // Recover below.
+        catch (error) {
+            if (error?.code !== grpc.status.UNAUTHENTICATED ||
+                binding.refresh === undefined) {
+                throw error;
+            }
+            const refreshed = await binding.refresh();
+            await waitForReady(refreshed.guest, this.readyTimeoutMs());
+            await pingAgent(refreshed);
+            return refreshed;
         }
-        await this.recoverContainer(slug, container);
-        await waitForReady(binding.guest, this.readyTimeoutMs());
     }
     // recoverContainer best-effort recreates a container whose agent is
     // unreachable. A failure here is not fatal: the caller's retry surfaces the
     // real readiness failure.
-    async recoverContainer(slug, container) {
+    async recoverContainer(slug, container, signal) {
         try {
             await this.control("recreateContainer", {
                 workspaceSlug: slug,
                 container,
-            });
+            }, signal);
         }
         catch {
             // Best-effort.
         }
     }
-    resolveBinding(key, projectName) {
+    resolveBinding(key, projectName, signal) {
         let binding = this.bindings.get(key);
         if (binding === undefined) {
-            binding = this.create(key, projectName).catch((error) => {
+            binding = this.create(key, projectName, signal).catch((error) => {
                 if (this.bindings.get(key) === binding)
                     this.bindings.delete(key);
                 throw error;
@@ -160,34 +257,79 @@ export class WorkspaceResolver {
         }
         return binding;
     }
-    async create(slug, projectName) {
-        const control = controlClient(join(this.config.socketsRoot, "orchestrator.sock"));
-        const controlMetadata = metadata(this.config.controlToken);
-        let workspace;
+    async create(slug, projectName, signal) {
+        const control = controlClient(join(this.getConfig().socketsRoot, "orchestrator.sock"));
+        const controlMetadata = metadata(this.getConfig().controlToken, VERSION);
         try {
-            workspace = await unary(control, "describeWorkspace", {
+            await unary(control, "describeWorkspace", {
                 workspaceSlug: slug,
-            }, controlMetadata);
+            }, controlMetadata, signal);
         }
         catch (error) {
             if (error.code !== grpc.status.NOT_FOUND)
                 throw error;
-            workspace = await unary(control, "createWorkspace", {
+            // A new workspace's default container is a creation: seed the default
+            // environment. An existing one keeps its stored env instead.
+            const env = mergeDefaultEnv(this.getConfig().containerEnv, undefined);
+            await unary(control, "createWorkspace", {
                 workspaceSlug: slug,
                 projectName,
-                imageId: this.config.defaultImage,
+                imageId: this.getConfig().defaultImage,
                 mounts: [{ projectName, mode: "MOUNT_MODE_READ_WRITE" }],
-            }, controlMetadata);
+                ...(Object.keys(env).length > 0 ? { env } : {}),
+            }, controlMetadata, signal);
+        }
+        const row = await this.ensureContainer(slug, "default", signal);
+        return this.bindingFor(row, () => {
+            this.bindings.delete(slug);
+            return this.resolveBinding(slug, projectName);
+        });
+    }
+    // ensureContainer asks the orchestrator for a usable container, recreating it
+    // when it is missing, stopped, or runs a guest agent from an outdated image,
+    // and returns its row. A container the orchestrator does not know is reported
+    // as the caller's missing container.
+    async ensureContainer(slug, container, signal) {
+        try {
+            return await this.control("ensureContainer", {
+                workspaceSlug: slug,
+                container,
+            }, signal);
+        }
+        catch (error) {
+            if (error.code !== grpc.status.NOT_FOUND)
+                throw error;
+            throw containerNotFound(container, slug);
         }
-        const socket = workspace.agentSocketPath;
-        return {
-            guest: guestClient(socket),
-            token: workspace.agentToken,
-            socket,
-        };
     }
-    async control(method, request) {
-        return unary(controlClient(join(this.config.socketsRoot, "orchestrator.sock")), method, request, metadata(this.config.controlToken));
+    async control(method, request, signal) {
+        const result = await unary(controlClient(join(this.getConfig().socketsRoot, "orchestrator.sock")), method, request, metadata(this.getConfig().controlToken, VERSION), signal);
+        this.invalidateAfter(method, request);
+        return result;
+    }
+    // invalidateAfter drops the cached bindings a successful mutation invalidated.
+    // Only reachable after the call resolved, so a failed mutation keeps the
+    // warm entry it did not change.
+    invalidateAfter(method, request) {
+        const scope = CONTAINER_MUTATIONS[method];
+        if (scope === undefined)
+            return;
+        const fields = (typeof request === "object" && request !== null ? request : {});
+        const slug = typeof fields.workspaceSlug === "string"
+            ? fields.workspaceSlug
+            : "";
+        if (slug === "")
+            return;
+        if (scope === "workspace") {
+            this.forgetWorkspace(slug);
+            return;
+        }
+        const container = typeof fields.container === "string"
+            ? fields.container
+            : "";
+        if (container === "")
+            return;
+        this.forgetContainer(slug, container);
     }
 }
 // notFoundError builds the harness's missing-path error (`FsErrorCode`
@@ -213,10 +355,15 @@ export function containerNotFound(container, slug) {
 // when the error carried one) so callers can branch without parsing text.
 export function normalizeToolError(error) {
     const raw = error instanceof Error ? error.message : String(error);
-    const message = raw.replace(/^\d+\s+[A-Z_]+:\s*/, "");
     const code = error.code;
-    const name = typeof code === "number"
-        ? grpc.status[code]
+    const numericCode = typeof code === "number" ? code : undefined;
+    // Only a real gRPC status renders the "<code> <NAME>: " prefix; a plain
+    // message that merely looks like one must stay intact.
+    const message = numericCode === undefined
+        ? raw
+        : raw.replace(/^\d+\s+[A-Z_]+:\s*/, "");
+    const name = numericCode !== undefined
+        ? grpc.status[numericCode]
         : typeof code === "string"
             ? code
             : undefined;
@@ -230,6 +377,15 @@ function waitForReady(agent, timeoutMs = 15000) {
         agent.waitForReady(Date.now() + timeoutMs, (error) => error ? reject(error) : resolve());
     });
 }
+// pingAgent makes the guest readiness call, which also exercises the credential
+// (the agent's auth interceptor guards every call, Ping included). Unlike
+// waitForReady, which only proves connectivity, it fails when the token is
+// rejected — which is exactly what a rotated credential looks like.
+function pingAgent(binding) {
+    return new Promise((resolveDone, reject) => {
+        binding.guest.ping({}, metadata(binding.token), (error) => (error ? reject(error) : resolveDone()));
+    });
+}
 // workspaceSlug validates the workspace id that names this workspace's pod
 // (dsh-podman-<slug>) and containers (dsh-podman-<slug>-<logical>). It must be
 // a UUID so a container name can never collide with a pod name.
@@ -241,14 +397,17 @@ export function workspaceSlug(id) {
     return value.toLowerCase();
 }
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-export function containerRowFor(containers, slug, container) {
-    return containers.find((row) => row.workspaceSlug === slug && row.containerName === container);
-}
-export function metadata(token) {
+// metadata builds the call metadata. The plugin version is sent on control
+// calls so the orchestrator can refuse an incompatible plugin; guest calls omit
+// it, since the guest agent does not check it.
+export function metadata(token, pluginVersion) {
     const result = new grpc.Metadata();
     if (token !== "") {
         result.set("authorization", `bearer ${token}`);
     }
+    if (pluginVersion !== undefined && pluginVersion !== "") {
+        result.set("x-dsh-podman-plugin-version", pluginVersion);
+    }
     return result;
 }
 // defaultCwdOf returns the session working directory as a usable container
@@ -256,6 +415,21 @@ export function metadata(token) {
 function defaultCwdOf(cwd) {
     return typeof cwd === "string" && cwd !== "" ? cwd : undefined;
 }
+// projectNameForPath maps a dsh workspace's host path to the project path a
+// mount stores: the path relative to the projects root. It is a prefix test,
+// not a String.replace, so a root that appears later in the path cannot corrupt
+// the name, and a workspace outside the root fails with a clear error instead
+// of silently producing an absolute "project name".
+function projectNameForPath(projectsRoot, path) {
+    const root = String(projectsRoot ?? "").replace(/\/+$/, "");
+    const value = String(path ?? "").replace(/\/+$/, "");
+    if (root === "" || value === root)
+        return "";
+    if (!value.startsWith(`${root}/`)) {
+        throw new Error(`workspace path ${JSON.stringify(value)} is not under the projects root ${JSON.stringify(root)}`);
+    }
+    return value.slice(root.length + 1);
+}
 // projectMountCovers reports whether a project mount of a container makes the
 // given container path reachable: the mount destination itself or a path below
 // it.