@slicervm/sdk 0.1.1 → 0.1.3

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) };
@@ -147,9 +150,9 @@ var TransportClient = class {
     });
   }
   /** Streaming request producing a Node Readable of the response body. */
-  requestStreamRaw(method, reqPath, body, contentType = "application/octet-stream") {
+  requestStreamRaw(method, reqPath, body, contentType = "application/octet-stream", extraHeaders = {}) {
     return new Promise((resolve, reject) => {
-      const headers = {};
+      const headers = { ...extraHeaders };
       if (body instanceof Buffer) {
         headers["Content-Type"] = contentType;
         headers["Content-Length"] = String(body.length);
@@ -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",
@@ -384,9 +639,88 @@ var VMFileSystem = class {
     );
     for await (const _ of res) void _;
   }
+  /**
+   * Open a Server-Sent Events stream of filesystem events from the VM.
+   * Yields one `FSWatchEvent` per agent-side event. The stream stays open
+   * until the supplied request's `timeout` / `maxEvents` is hit, the daemon
+   * tears it down, or the caller breaks out of the loop.
+   *
+   * Heartbeat SSE comments and named `event:` lines are silently dropped.
+   *
+   * Example:
+   * ```ts
+   * for await (const e of vm.fs.watch({ paths: ['/tmp'], recursive: true })) {
+   *   console.log(e.type, e.path);
+   * }
+   * ```
+   */
+  async *watch(req) {
+    if (!req.paths || req.paths.length === 0) {
+      throw new Error("vm.fs.watch: paths is required");
+    }
+    const q = new URLSearchParams();
+    for (const p of req.paths) if (p) q.append("paths", p);
+    for (const p of req.patterns ?? []) if (p) q.append("patterns", p);
+    for (const e of req.events ?? []) if (e) q.append("events", e);
+    if (req.uid !== void 0 && req.uid !== 0) q.set("uid", String(req.uid));
+    if (req.recursive) q.set("recursive", "true");
+    if (req.oneShot) q.set("one_shot", "true");
+    if (req.debounce) q.set("debounce", req.debounce);
+    if (req.timeout) q.set("timeout", req.timeout);
+    if (req.maxEvents !== void 0 && req.maxEvents > 0) {
+      q.set("max_events", String(req.maxEvents));
+    }
+    const extraHeaders = { Accept: "text/event-stream" };
+    if (req.lastEventId) extraHeaders["Last-Event-ID"] = req.lastEventId;
+    const res = await this.transport.requestStreamRaw(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/fs/watch?${q.toString()}`,
+      void 0,
+      void 0,
+      extraHeaders
+    );
+    res.setEncoding("utf8");
+    let buffer = "";
+    let dataLines = [];
+    let pendingId = 0;
+    for await (const chunk of res) {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf("\n")) >= 0) {
+        const raw = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line === "") {
+          if (dataLines.length > 0) {
+            const payload = dataLines.join("\n");
+            dataLines = [];
+            try {
+              const parsed = JSON.parse(payload);
+              const evt = {
+                id: typeof parsed.id === "number" && parsed.id !== 0 ? parsed.id : pendingId,
+                type: parsed.type ?? "",
+                path: parsed.path ?? "",
+                timestamp: parsed.timestamp ?? "",
+                size: parsed.size ?? 0,
+                isDir: parsed.isDir ?? false,
+                ...parsed.message !== void 0 && { message: parsed.message }
+              };
+              yield evt;
+            } catch {
+            }
+          }
+        } else if (line.startsWith(":")) ; else if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).replace(/^ /, ""));
+        } else if (line.startsWith("id:")) {
+          const v = parseInt(line.slice(3).trim(), 10);
+          if (!Number.isNaN(v)) pendingId = v;
+        }
+      }
+    }
+  }
   /** 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 +825,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 +857,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 +871,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 +1096,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