@slicervm/sdk 0.1.4 → 0.1.6

package/dist/index.js

@@ -5,7 +5,7 @@ import os from 'os';
 import path2 from 'path';
 import net, { createServer } from 'net';
 import fs from 'fs';
-import { createWebSocketStream, WebSocket } from 'ws';
+import { createWebSocketStream, WebSocket as WebSocket$1 } from 'ws';
 
 // src/types.ts
 var ExecStdioText = "text";
@@ -526,7 +526,7 @@ function openWebSocket(init, mapping) {
   if (init.transport.kind === "socket") {
     opts.agent = unixAgent(init.transport.socketPath);
   }
-  return new WebSocket(url, opts);
+  return new WebSocket$1(url, opts);
 }
 function wsURLForVM(transport, hostname) {
   if (transport.kind === "socket") {
@@ -734,6 +734,7 @@ var VM = class {
   createdAt;
   arch;
   fs;
+  bg;
   transport;
   constructor(transport, init) {
     this.transport = transport;
@@ -743,6 +744,7 @@ var VM = class {
     if (init.createdAt !== void 0) this.createdAt = init.createdAt;
     if (init.arch !== void 0) this.arch = init.arch;
     this.fs = new VMFileSystem(transport, this.hostname);
+    this.bg = new VMBg(transport, this.hostname);
   }
   // --- lifecycle --------------------------------------------------------
   async delete() {
@@ -944,6 +946,169 @@ function sleep(ms) {
 function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
+var VMBg = class {
+  constructor(transport, hostname) {
+    this.transport = transport;
+    this.hostname = hostname;
+  }
+  transport;
+  hostname;
+  /**
+   * Launch a long-running process. `command` + `args` is the deterministic
+   * exec form (no shell). Set `shell: '/bin/bash'` (or similar) to opt in
+   * to shell semantics — `$VAR` expansion, globs, `&&`/`||`, etc.
+   */
+  async exec(req) {
+    if (!req.command) throw new Error("vm.bg.exec: command is required");
+    const q = new URLSearchParams();
+    q.set("background", "true");
+    q.set("cmd", req.command);
+    for (const a of req.args ?? []) q.append("args", a);
+    for (const e of req.env ?? []) q.append("env", e);
+    if (req.uid !== void 0) q.set("uid", String(req.uid));
+    if (req.gid !== void 0) q.set("gid", String(req.gid));
+    if (req.shell) q.set("shell", req.shell);
+    if (req.cwd) q.set("cwd", req.cwd);
+    if (req.ringBytes !== void 0 && req.ringBytes > 0) {
+      q.set("ring_bytes", String(req.ringBytes));
+    }
+    q.set("stdio", "base64");
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec?${q.toString()}`;
+    const wire = await this.transport.request("POST", path3);
+    return bgExecResponseFromWire(wire);
+  }
+  /** All background execs the agent currently tracks (running + exited-not-reaped). */
+  async list() {
+    const wire = await this.transport.request(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/exec`
+    );
+    return (wire ?? []).map(bgExecInfoFromWire);
+  }
+  /** Latest status snapshot for one bg exec. Throws 404 if reaped or never existed. */
+  async info(execId) {
+    const wire = await this.transport.request(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}`
+    );
+    return bgExecInfoFromWire(wire);
+  }
+  /**
+   * NDJSON log stream. Yields one frame per log line — `started`, `stdout`,
+   * `stderr`, `exit`, plus optional `gap` frames if the ring evicted history
+   * before the requested cursor. Frames carry `data` base64-encoded; the SDK
+   * also populates `dataBytes` / `stdoutBytes` / `stderrBytes` Buffers.
+   *
+   * `follow: false` (default) replays from the cursor and ends when the ring
+   * is drained. `follow: true` keeps the stream open until the child exits or
+   * the caller breaks out.
+   */
+  async *logs(execId, opts = {}) {
+    const q = new URLSearchParams();
+    if (opts.follow) q.set("follow", "true");
+    if (opts.fromId !== void 0 && opts.fromId > 0) q.set("from_id", String(opts.fromId));
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/logs` + (q.toString() ? `?${q.toString()}` : "");
+    for await (const raw of this.transport.requestNDJSON("GET", path3)) {
+      const frame = normalizeExecFrame(raw);
+      if (frame.encoding === "base64") {
+        if (frame.data) frame.dataBytes = Buffer.from(frame.data, "base64");
+        if (frame.stdout) frame.stdoutBytes = Buffer.from(frame.stdout, "base64");
+        if (frame.stderr) frame.stderrBytes = Buffer.from(frame.stderr, "base64");
+      }
+      yield frame;
+    }
+  }
+  /**
+   * Signal a running bg exec. Default: SIGTERM with a 5 s grace period before
+   * the agent escalates to SIGKILL. No-op (running=false) if the child has
+   * already exited.
+   */
+  async kill(execId, opts = {}) {
+    const body = {};
+    if (opts.signal) body.signal = opts.signal;
+    if (opts.graceMs !== void 0) body.grace_ms = opts.graceMs;
+    const wire = await this.transport.request(
+      "POST",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/kill`,
+      body
+    );
+    return bgKillResponseFromWire(wire);
+  }
+  /**
+   * Long-poll until the child exits or `timeoutSec` elapses. Returns
+   * `timedOut: true` if the deadline hit. Server default for `timeoutSec=0`
+   * is 30 s.
+   */
+  async wait(execId, timeoutSec = 0) {
+    const q = new URLSearchParams();
+    if (timeoutSec > 0) q.set("timeout", String(timeoutSec));
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/wait-exit` + (q.toString() ? `?${q.toString()}` : "");
+    const wire = await this.transport.request("GET", path3);
+    return bgWaitExitFromWire(wire);
+  }
+  /**
+   * Reap a bg exec's ring buffer + registry entry. Does NOT kill a running
+   * process — pair with `kill()` for "stop and clean up". After remove,
+   * info/logs/kill/wait return 410 Gone.
+   */
+  async remove(execId) {
+    const wire = await this.transport.request(
+      "DELETE",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}`
+    );
+    return bgDeleteFromWire(wire);
+  }
+};
+function bgExecResponseFromWire(w) {
+  return {
+    execId: w.exec_id,
+    pid: w.pid,
+    startedAt: w.started_at,
+    ringBytes: w.ring_bytes
+  };
+}
+function bgExecInfoFromWire(w) {
+  const out = {
+    execId: w.exec_id,
+    pid: w.pid,
+    command: w.command,
+    startedAt: w.started_at,
+    running: w.running,
+    bytesWritten: w.bytes_written,
+    bytesDropped: w.bytes_dropped,
+    nextId: w.next_id,
+    ringBytes: w.ring_bytes
+  };
+  if (w.args !== void 0) out.args = w.args;
+  if (w.cwd !== void 0) out.cwd = w.cwd;
+  if (w.uid !== void 0) out.uid = w.uid;
+  if (w.exit_code !== void 0) out.exitCode = w.exit_code;
+  if (w.signal !== void 0) out.signal = w.signal;
+  if (w.ended_at !== void 0) out.endedAt = w.ended_at;
+  return out;
+}
+function bgKillResponseFromWire(w) {
+  return {
+    execId: w.exec_id,
+    pid: w.pid,
+    running: w.running,
+    signalSent: w.signal_sent
+  };
+}
+function bgWaitExitFromWire(w) {
+  const out = {
+    execId: w.exec_id,
+    running: w.running,
+    timedOut: w.timed_out
+  };
+  if (w.exit_code !== void 0) out.exitCode = w.exit_code;
+  if (w.signal !== void 0) out.signal = w.signal;
+  if (w.ended_at !== void 0) out.endedAt = w.ended_at;
+  return out;
+}
+function bgDeleteFromWire(w) {
+  return { execId: w.exec_id, reaped: w.reaped };
+}
 
 // src/namespaces.ts
 var HostGroupsAPI = class {
@@ -1113,6 +1278,146 @@ var SlicerClient = class _SlicerClient {
   }
 };
 
-export { ExecStdioBase64, ExecStdioText, Forwarder, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, VM, VMFileSystem, VMsAPI, parseAddressMapping, resolveTransport };
+// src/shell.ts
+var FRAME_TYPE_DATA = 1;
+var FRAME_TYPE_WINDOW_SIZE = 2;
+var FRAME_TYPE_SHUTDOWN = 3;
+var FRAME_TYPE_HEARTBEAT = 4;
+var FRAME_TYPE_SESSION_CLOSE = 5;
+var HEADER_SIZE = 5;
+function encodeFrame(frameType, payload) {
+  const payloadLen = payload ? payload.byteLength : 0;
+  const buf = new Uint8Array(HEADER_SIZE + payloadLen);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, frameType);
+  view.setUint32(1, payloadLen, false);
+  if (payload) buf.set(payload, HEADER_SIZE);
+  return buf;
+}
+function parseFrame(data) {
+  if (data.byteLength < HEADER_SIZE) return null;
+  const view = new DataView(data);
+  const frameType = view.getUint8(0);
+  const payloadLen = view.getUint32(1, false);
+  if (data.byteLength < HEADER_SIZE + payloadLen) return null;
+  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);
+  return { frameType, payload };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var SlicerShellSession = class {
+  constructor(terminal, options) {
+    this.terminal = terminal;
+    this.options = options;
+  }
+  terminal;
+  options;
+  ws = null;
+  heartbeatTimer = null;
+  dataDisposable = null;
+  /** True when the WebSocket is open and relaying. */
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Open the WebSocket and begin relaying. */
+  connect() {
+    if (this.ws) return;
+    this.options.onStateChange?.("connecting");
+    const ws = new WebSocket(this.options.url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = () => {
+      this.options.onStateChange?.("connected");
+      this.terminal.reset();
+      this.sendResize(this.terminal.cols, this.terminal.rows);
+      this.startHeartbeat();
+    };
+    ws.onmessage = (ev) => {
+      if (!(ev.data instanceof ArrayBuffer)) return;
+      const frame = parseFrame(ev.data);
+      if (!frame) return;
+      switch (frame.frameType) {
+        case FRAME_TYPE_DATA:
+          this.terminal.write(decoder.decode(frame.payload));
+          break;
+        case FRAME_TYPE_SHUTDOWN:
+        case FRAME_TYPE_SESSION_CLOSE:
+          this.teardown();
+          break;
+      }
+    };
+    ws.onclose = () => {
+      this.teardown();
+    };
+    ws.onerror = () => {
+      this.options.onError?.("WebSocket error");
+      this.teardown();
+    };
+    this.dataDisposable = this.terminal.onData((data) => {
+      if (!this.connected) return;
+      const payload = encoder.encode(data);
+      this.ws.send(encodeFrame(FRAME_TYPE_DATA, payload));
+    });
+  }
+  /** Send a graceful shutdown frame and close. */
+  disconnect() {
+    if (this.ws) {
+      try {
+        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));
+      } catch {
+      }
+    }
+    this.teardown();
+  }
+  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+  resize(cols, rows) {
+    if (!this.connected) return;
+    this.sendResize(cols, rows);
+  }
+  // --- internals -------------------------------------------------------------
+  sendResize(cols, rows) {
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setUint32(0, cols, false);
+    view.setUint32(4, rows, false);
+    this.ws.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 3e4;
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.connected) return;
+      this.ws.send(encodeFrame(FRAME_TYPE_HEARTBEAT));
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  teardown() {
+    this.stopHeartbeat();
+    if (this.dataDisposable) {
+      this.dataDisposable.dispose();
+      this.dataDisposable = null;
+    }
+    if (this.ws) {
+      const ws = this.ws;
+      this.ws = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    this.options.onStateChange?.("disconnected");
+  }
+};
+
+export { ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, Forwarder, GiB, HostGroupsAPI, MiB, NonRootUser, SecretExistsError, SecretsAPI, SlicerAPIError, SlicerClient, SlicerShellSession, VM, VMBg, VMFileSystem, VMsAPI, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map