@slicervm/sdk 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -261,8 +261,8 @@ interface TransportClientOptions {
 }
 declare class TransportClient {
     readonly transport: Transport;
-    private readonly token?;
-    private readonly userAgent;
+    readonly token?: string;
+    readonly userAgent: string;
     constructor(opts: TransportClientOptions);
     private agent;
     private buildRequestOptions;
@@ -276,6 +276,94 @@ declare class TransportClient {
     requestNDJSON<Frame = unknown>(method: string, reqPath: string, body?: Buffer | Readable): AsyncGenerator<Frame, void, void>;
 }
 
+/**
+ * Port forwarding for Slicer VMs.
+ *
+ * Per-connection WebSocket model: each accepted local TCP/Unix connection
+ * opens a fresh WebSocket to /vm/{hostname}/forward on the daemon. The
+ * WebSocket carries raw bytes both directions (binary frames, no framing
+ * subprotocol). The daemon uses the `X-Inlets-Upstream` header on the
+ * upgrade request to decide where to dial inside the VM.
+ */
+
+interface AddressMapping {
+    rawSpec: string;
+    /** TCP listen address, or undefined when listening on a Unix socket. */
+    listenAddr?: string;
+    /** TCP listen port, or undefined when listening on a Unix socket. */
+    listenPort?: number;
+    /** Listen Unix socket path, or undefined when listening on TCP. */
+    listenUnixPath?: string;
+    /** Remote host inside the VM, or undefined when targeting a Unix socket. */
+    remoteHost?: string;
+    /** Remote port inside the VM, or undefined when targeting a Unix socket. */
+    remotePort?: number;
+    /** Remote Unix socket path inside the VM, or undefined when targeting TCP. */
+    remoteUnixPath?: string;
+}
+/**
+ * Parse a `-L`-style spec into an {@link AddressMapping}. Supported formats
+ * mirror the Go SDK's `slicer vm forward` CLI:
+ *
+ * - `127.0.0.1:9000` — listen and forward on the same TCP host:port
+ * - `9001:127.0.0.1:9000` — listen on `0.0.0.0:9001`, forward to `127.0.0.1:9000`
+ * - `0:127.0.0.1:9000` — listen on a random TCP port, forward as above
+ * - `0.0.0.0:9000:127.0.0.1:9000` — listen and forward, fully explicit
+ * - `127.0.0.1:9000:/var/run/docker.sock` — TCP listen, Unix socket forward
+ * - `9000:/var/run/docker.sock` — `0.0.0.0:9000` listen, Unix socket forward
+ * - `/tmp/docker.sock:/var/run/docker.sock` — Unix-to-Unix forward
+ * - `./docker.sock:/var/run/docker.sock` — Unix-to-Unix with relative local
+ */
+declare function parseAddressMapping(spec: string): AddressMapping;
+interface ForwarderListener {
+    /** The original spec string that produced this listener. */
+    spec: string;
+    /** Human-readable local address (`127.0.0.1:8080`, `/tmp/docker.sock`, etc). */
+    local: string;
+    /** Human-readable upstream target inside the VM. */
+    remote: string;
+    /** Resolved port for TCP listeners (useful when caller asked for `0`). */
+    port?: number;
+}
+interface ForwarderOptions {
+    /** Identifies this client to the daemon. Defaults to `os.hostname()`. */
+    clientId?: string;
+    /** WebSocket dial timeout (ms). Default 10_000. */
+    dialTimeoutMs?: number;
+    /**
+     * Optional logger for connection events. Receives short strings. Default: silent.
+     */
+    log?: (msg: string) => void;
+}
+interface ForwarderInit {
+    hostname: string;
+    transport: Transport;
+    token?: string;
+    userAgent: string;
+    specs: string[];
+    options?: ForwarderOptions;
+}
+/**
+ * A live set of port forwards for one VM. Returned by `vm.forward(...)`.
+ * Closing the forwarder tears down all local listeners and any in-flight
+ * tunnel WebSockets.
+ */
+declare class Forwarder {
+    private readonly init;
+    private readonly mappings;
+    readonly listeners: ForwarderListener[];
+    private readonly servers;
+    private readonly liveSockets;
+    private closed;
+    private constructor();
+    static start(init: ForwarderInit): Promise<Forwarder>;
+    private bindAll;
+    private handleAccept;
+    /** Tear down all listeners and any in-flight tunnel sockets. */
+    close(): Promise<void>;
+    private log;
+}
+
 /**
  * VM handle — returned from `client.vms.create()` / `client.vms.get()`.
  * Exposes per-VM operations (exec, fs, power, lifecycle).
@@ -331,6 +419,20 @@ declare class VM {
     suspend(): Promise<void>;
     /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
     restore(): Promise<void>;
+    /**
+     * Open one or more port forwards from the host to this VM. Each spec follows
+     * the same syntax as `slicer vm forward -L`:
+     *
+     *   `127.0.0.1:9000`              — listen and forward on the same TCP port
+     *   `8081:127.0.0.1:8080`         — listen on `0.0.0.0:8081`, forward to `127.0.0.1:8080`
+     *   `0.0.0.0:8080:127.0.0.1:8080` — fully explicit
+     *   `9000:/var/run/docker.sock`   — TCP listen, Unix socket forward
+     *   `/tmp/docker.sock:/var/run/docker.sock` — Unix-to-Unix
+     *
+     * Returns a {@link Forwarder} handle. Call `forwarder.close()` to tear down
+     * all listeners and any in-flight tunnel sockets.
+     */
+    forward(specs: string | string[], options?: ForwarderOptions): Promise<Forwarder>;
     /**
      * Streaming exec — yields NDJSON frames (`started`, `stdout`, `stderr`, `exit`).
      * When `req.stdio === 'base64'`, each frame's `data`/`stdout`/`stderr` string
@@ -421,4 +523,4 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AgentHealth, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, resolveTransport };
+export { type AddressMapping, type AgentHealth, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };

package/dist/index.js

@@ -2,7 +2,10 @@ import http from 'http';
 import https from 'https';
 import { URL } from 'url';
 import os from 'os';
-import path from 'path';
+import path2 from 'path';
+import net, { createServer } from 'net';
+import fs from 'fs';
+import { createWebSocketStream, WebSocket } from 'ws';
 
 // src/types.ts
 var ExecStdioText = "text";
@@ -18,11 +21,11 @@ var SlicerAPIError = class extends Error {
   method;
   path;
   body;
-  constructor(method, path2, status, body) {
-    super(`slicer ${method} ${path2} failed: ${status} ${body}`);
+  constructor(method, path3, status, body) {
+    super(`slicer ${method} ${path3} failed: ${status} ${body}`);
     this.name = "SlicerAPIError";
     this.method = method;
-    this.path = path2;
+    this.path = path3;
     this.status = status;
     this.body = body;
   }
@@ -35,7 +38,7 @@ function resolveTransport(baseURL) {
   if (!trimmed) throw new Error("Slicer baseURL is required");
   let candidate = trimmed;
   if (candidate.startsWith("unix://")) candidate = candidate.slice("unix://".length);
-  if (candidate.startsWith("~/")) candidate = path.join(os.homedir(), candidate.slice(2));
+  if (candidate.startsWith("~/")) candidate = path2.join(os.homedir(), candidate.slice(2));
   const socketLike = candidate.startsWith("/") || candidate.startsWith("./") || candidate.startsWith("../") || candidate.endsWith(".sock");
   if (socketLike) return { kind: "socket", socketPath: candidate };
   return { kind: "net", url: new URL(trimmed) };
@@ -294,6 +297,258 @@ function secretFromWire(w) {
     ...w.modified_at !== void 0 && { modifiedAt: w.modified_at }
   };
 }
+function looksLikeUnixSocketPath(s) {
+  if (!s) return false;
+  return s.startsWith("/") || s.startsWith("./") || s.startsWith("../") || s.includes("/");
+}
+function parseAddressMapping(spec) {
+  const lastColon = spec.lastIndexOf(":");
+  if (lastColon !== -1) {
+    const localPart = spec.slice(0, lastColon);
+    const remotePart = spec.slice(lastColon + 1);
+    if (looksLikeUnixSocketPath(localPart) && looksLikeUnixSocketPath(remotePart)) {
+      const localAbs = path2.isAbsolute(localPart) ? localPart : path2.resolve(localPart);
+      return { rawSpec: spec, listenUnixPath: localAbs, remoteUnixPath: remotePart };
+    }
+  }
+  const tcpToUnix = spec.indexOf(":/");
+  if (tcpToUnix !== -1) {
+    const listenPart = spec.slice(0, tcpToUnix);
+    const socketPath = spec.slice(tcpToUnix + 1);
+    const innerColon = listenPart.lastIndexOf(":");
+    if (innerColon === -1) {
+      return {
+        rawSpec: spec,
+        listenAddr: "0.0.0.0",
+        listenPort: parsePort(listenPart, spec),
+        remoteUnixPath: socketPath
+      };
+    }
+    return {
+      rawSpec: spec,
+      listenAddr: listenPart.slice(0, innerColon),
+      listenPort: parsePort(listenPart.slice(innerColon + 1), spec),
+      remoteUnixPath: socketPath
+    };
+  }
+  const parts = spec.split(":");
+  switch (parts.length) {
+    case 2:
+      return {
+        rawSpec: spec,
+        listenAddr: parts[0],
+        listenPort: parsePort(parts[1], spec),
+        remoteHost: parts[0],
+        remotePort: parsePort(parts[1], spec)
+      };
+    case 3:
+      return {
+        rawSpec: spec,
+        listenAddr: parts[1],
+        listenPort: parsePort(parts[0], spec),
+        remoteHost: parts[1],
+        remotePort: parsePort(parts[2], spec)
+      };
+    case 4:
+      return {
+        rawSpec: spec,
+        listenAddr: parts[0],
+        listenPort: parsePort(parts[1], spec),
+        remoteHost: parts[2],
+        remotePort: parsePort(parts[3], spec)
+      };
+    default:
+      throw new Error(`invalid forward spec ${JSON.stringify(spec)}: expected 2-4 colon-separated parts`);
+  }
+}
+function parsePort(s, spec) {
+  const n = Number(s);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    throw new Error(`invalid port ${JSON.stringify(s)} in forward spec ${JSON.stringify(spec)}`);
+  }
+  return n;
+}
+function isListenUnix(m) {
+  return m.listenUnixPath !== void 0;
+}
+function remoteTargetHeader(m) {
+  if (m.remoteUnixPath) return `unix:${m.remoteUnixPath}`;
+  return `${m.remoteHost}:${m.remotePort}`;
+}
+function listenAddressDescription(m) {
+  if (isListenUnix(m)) return m.listenUnixPath;
+  return `${m.listenAddr}:${m.listenPort}`;
+}
+var Forwarder = class _Forwarder {
+  constructor(init, mappings) {
+    this.init = init;
+    this.mappings = mappings;
+  }
+  init;
+  mappings;
+  listeners = [];
+  servers = [];
+  liveSockets = /* @__PURE__ */ new Set();
+  closed = false;
+  static async start(init) {
+    if (init.specs.length === 0) {
+      throw new Error("Forwarder requires at least one forward spec");
+    }
+    const mappings = init.specs.map(parseAddressMapping);
+    const fwd = new _Forwarder(init, mappings);
+    try {
+      await fwd.bindAll();
+    } catch (err) {
+      await fwd.close();
+      throw err;
+    }
+    return fwd;
+  }
+  async bindAll() {
+    for (const m of this.mappings) {
+      const server = createServer((socket) => this.handleAccept(m, socket));
+      const { local, port } = await listen(server, m);
+      this.servers.push(server);
+      this.listeners.push({
+        spec: m.rawSpec,
+        local,
+        remote: remoteTargetHeader(m),
+        ...port !== void 0 && { port }
+      });
+      this.log(`listen ${local} \u2192 ${remoteTargetHeader(m)}`);
+    }
+  }
+  handleAccept(mapping, socket) {
+    if (this.closed) {
+      socket.destroy();
+      return;
+    }
+    socket.on("error", () => {
+    });
+    const ws = openWebSocket(this.init, mapping);
+    let closed = false;
+    const cleanup = () => {
+      if (closed) return;
+      closed = true;
+      try {
+        socket.destroy();
+      } catch {
+      }
+      try {
+        ws.close();
+      } catch {
+      }
+      this.liveSockets.delete(handle);
+    };
+    const handle = { close: cleanup };
+    this.liveSockets.add(handle);
+    ws.binaryType = "nodebuffer";
+    ws.on("open", () => {
+      const wsStream = createWebSocketStream(ws);
+      wsStream.on("error", cleanup);
+      socket.pipe(wsStream);
+      wsStream.pipe(socket);
+    });
+    ws.on("close", cleanup);
+    ws.on("error", (err) => {
+      this.log(`tunnel error: ${err.message}`);
+      cleanup();
+    });
+    socket.on("close", cleanup);
+  }
+  /** Tear down all listeners and any in-flight tunnel sockets. */
+  async close() {
+    this.closed = true;
+    for (const handle of [...this.liveSockets]) handle.close();
+    this.liveSockets.clear();
+    await Promise.all(
+      this.servers.map(
+        (s) => new Promise((resolve) => {
+          s.close(() => resolve());
+        })
+      )
+    );
+    for (const m of this.mappings) {
+      if (isListenUnix(m) && m.listenUnixPath) {
+        try {
+          fs.rmSync(m.listenUnixPath, { force: true });
+        } catch {
+        }
+      }
+    }
+  }
+  log(msg) {
+    this.init.options?.log?.(msg);
+  }
+};
+function listen(server, mapping) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    if (isListenUnix(mapping)) {
+      const p = mapping.listenUnixPath;
+      try {
+        fs.rmSync(p, { force: true });
+      } catch {
+      }
+      server.listen(p, () => {
+        try {
+          fs.chmodSync(p, 432);
+        } catch {
+        }
+        resolve({ local: p });
+      });
+      return;
+    }
+    server.listen({ host: mapping.listenAddr, port: mapping.listenPort }, () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        const local = `${mapping.listenAddr}:${addr.port}`;
+        resolve({ local, port: addr.port });
+      } else {
+        resolve({ local: listenAddressDescription(mapping) });
+      }
+    });
+  });
+}
+function openWebSocket(init, mapping) {
+  const url = wsURLForVM(init.transport, init.hostname);
+  const headers = {
+    "X-Inlets-Client-ID": init.options?.clientId ?? os.hostname(),
+    "X-Inlets-Mode": "local",
+    "X-Inlets-Upstream": remoteTargetHeader(mapping),
+    "User-Agent": init.userAgent
+  };
+  if (init.token) headers["Authorization"] = `Bearer ${init.token}`;
+  const opts = {
+    headers,
+    handshakeTimeout: init.options?.dialTimeoutMs ?? 1e4
+  };
+  if (init.transport.kind === "socket") {
+    opts.agent = unixAgent(init.transport.socketPath);
+  }
+  return new WebSocket(url, opts);
+}
+function wsURLForVM(transport, hostname) {
+  if (transport.kind === "socket") {
+    return `ws://localhost/vm/${encodeURIComponent(hostname)}/forward`;
+  }
+  const u = transport.url;
+  const scheme = u.protocol === "https:" ? "wss" : "ws";
+  const port = u.port ? `:${u.port}` : "";
+  return `${scheme}://${u.hostname}${port}/vm/${encodeURIComponent(hostname)}/forward`;
+}
+function unixAgent(socketPath) {
+  const agent = new http.Agent({ keepAlive: false });
+  agent.createConnection = ((_opts, cb) => {
+    const conn = net.createConnection({ path: socketPath });
+    if (cb) {
+      conn.once("connect", () => cb(null, conn));
+      conn.once("error", (err) => cb(err));
+    }
+    return conn;
+  });
+  return agent;
+}
 
 // src/vm.ts
 var VMFileSystem = class {
@@ -303,16 +558,16 @@ var VMFileSystem = class {
   }
   transport;
   hostname;
-  async readDir(path2) {
-    const q = new URLSearchParams({ path: path2 });
+  async readDir(path3) {
+    const q = new URLSearchParams({ path: path3 });
     const wire = await this.transport.request(
       "GET",
       `/vm/${encodeURIComponent(this.hostname)}/fs/readdir?${q.toString()}`
     );
     return (wire ?? []).map(fsEntryFromWire);
   }
-  async stat(path2) {
-    const q = new URLSearchParams({ path: path2 });
+  async stat(path3) {
+    const q = new URLSearchParams({ path: path3 });
     try {
       const wire = await this.transport.request(
         "GET",
@@ -324,8 +579,8 @@ var VMFileSystem = class {
       throw err;
     }
   }
-  async exists(path2) {
-    return await this.stat(path2) !== null;
+  async exists(path3) {
+    return await this.stat(path3) !== null;
   }
   async mkdir(req) {
     await this.transport.request(
@@ -338,22 +593,22 @@ var VMFileSystem = class {
       }
     );
   }
-  async remove(path2, recursive = false) {
-    const q = new URLSearchParams({ path: path2, recursive: String(recursive) });
+  async remove(path3, recursive = false) {
+    const q = new URLSearchParams({ path: path3, recursive: String(recursive) });
     await this.transport.request(
       "DELETE",
       `/vm/${encodeURIComponent(this.hostname)}/fs/remove?${q.toString()}`
     );
   }
-  async readFile(path2) {
-    const q = new URLSearchParams({ path: path2, mode: "binary" });
+  async readFile(path3) {
+    const q = new URLSearchParams({ path: path3, mode: "binary" });
     return this.transport.requestRaw(
       "GET",
       `/vm/${encodeURIComponent(this.hostname)}/cp?${q.toString()}`
     );
   }
-  async writeFile(path2, content, opts = {}) {
-    const q = new URLSearchParams({ path: path2, mode: "binary" });
+  async writeFile(path3, content, opts = {}) {
+    const q = new URLSearchParams({ path: path3, mode: "binary" });
     if (opts.uid !== void 0) q.set("uid", String(opts.uid));
     if (opts.gid !== void 0) q.set("gid", String(opts.gid));
     if (opts.permissions) q.set("permissions", opts.permissions);
@@ -365,8 +620,8 @@ var VMFileSystem = class {
     );
   }
   /** Upload a tar archive, expanded into the VM at `path`. */
-  async tarTo(path2, tar) {
-    const q = new URLSearchParams({ path: path2, mode: "tar" });
+  async tarTo(path3, tar) {
+    const q = new URLSearchParams({ path: path3, mode: "tar" });
     if (tar instanceof Buffer) {
       await this.transport.requestRaw(
         "POST",
@@ -385,8 +640,8 @@ var VMFileSystem = class {
     for await (const _ of res) void _;
   }
   /** Download `path` from the VM as a tar archive. */
-  async tarFrom(path2) {
-    const q = new URLSearchParams({ path: path2, mode: "tar" });
+  async tarFrom(path3) {
+    const q = new URLSearchParams({ path: path3, mode: "tar" });
     return this.transport.requestRaw(
       "GET",
       `/vm/${encodeURIComponent(this.hostname)}/cp?${q.toString()}`
@@ -491,6 +746,30 @@ var VM = class {
   async restore() {
     await this.transport.request("POST", `/vm/${encodeURIComponent(this.hostname)}/restore`);
   }
+  // --- port forwarding ---------------------------------------------------
+  /**
+   * Open one or more port forwards from the host to this VM. Each spec follows
+   * the same syntax as `slicer vm forward -L`:
+   *
+   *   `127.0.0.1:9000`              — listen and forward on the same TCP port
+   *   `8081:127.0.0.1:8080`         — listen on `0.0.0.0:8081`, forward to `127.0.0.1:8080`
+   *   `0.0.0.0:8080:127.0.0.1:8080` — fully explicit
+   *   `9000:/var/run/docker.sock`   — TCP listen, Unix socket forward
+   *   `/tmp/docker.sock:/var/run/docker.sock` — Unix-to-Unix
+   *
+   * Returns a {@link Forwarder} handle. Call `forwarder.close()` to tear down
+   * all listeners and any in-flight tunnel sockets.
+   */
+  async forward(specs, options) {
+    return Forwarder.start({
+      hostname: this.hostname,
+      transport: this.transport.transport,
+      ...this.transport.token !== void 0 && { token: this.transport.token },
+      userAgent: this.transport.userAgent,
+      specs: typeof specs === "string" ? [specs] : specs,
+      ...options !== void 0 && { options }
+    });
+  }
   // --- exec -------------------------------------------------------------
   /**
    * Streaming exec — yields NDJSON frames (`started`, `stdout`, `stderr`, `exit`).
@@ -499,8 +778,8 @@ var VM = class {
    * `dataBytes`/`stdoutBytes`/`stderrBytes` Buffers alongside for convenience.
    */
   async *exec(req) {
-    const { path: path2, body } = buildExecPath(this.hostname, req, false);
-    for await (const frame of this.transport.requestNDJSON("POST", path2, body)) {
+    const { path: path3, body } = buildExecPath(this.hostname, req, false);
+    for await (const frame of this.transport.requestNDJSON("POST", path3, body)) {
       if (frame.encoding === "base64") {
         if (frame.data) frame.dataBytes = Buffer.from(frame.data, "base64");
         if (frame.stdout) frame.stdoutBytes = Buffer.from(frame.stdout, "base64");
@@ -513,8 +792,8 @@ var VM = class {
     if (req.stdin !== void 0) {
       throw new Error("stdin is not supported by execBuffered; use exec() instead");
     }
-    const { path: path2, body } = buildExecPath(this.hostname, req, true);
-    const raw = await this.transport.requestRaw("POST", path2, body);
+    const { path: path3, body } = buildExecPath(this.hostname, req, true);
+    const raw = await this.transport.requestRaw("POST", path3, body);
     const text = raw.toString("utf8");
     const parsed = text ? JSON.parse(text) : {};
     const common = {
@@ -738,6 +1017,6 @@ var SlicerClient = class _SlicerClient {
   }
 };
 
-export { ExecStdioBase64, ExecStdioText, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, VM, VMFileSystem, VMsAPI, resolveTransport };
+export { ExecStdioBase64, ExecStdioText, Forwarder, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, VM, VMFileSystem, VMsAPI, parseAddressMapping, resolveTransport };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map