@slicervm/sdk 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -143,6 +143,42 @@ interface FSMkdirRequest {
     recursive?: boolean;
     mode?: string;
 }
+type FSWatchEventType = 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+interface FSWatchRequest {
+    /** Absolute paths inside the VM to watch. At least one is required. */
+    paths: string[];
+    /** Optional glob patterns to filter event paths (e.g. `["*.go", "bin/*"]`). */
+    patterns?: string[];
+    /**
+     * Restrict to a subset of event types. When omitted, all types are delivered.
+     */
+    events?: FSWatchEventType[];
+    /** UID used by the agent to resolve `~` in paths. Default: 0 (root). */
+    uid?: number;
+    /** Watch directories recursively. */
+    recursive?: boolean;
+    /** Stop the stream after the first matching event. */
+    oneShot?: boolean;
+    /** Coalesce events arriving within this window. Go-duration string e.g. `"100ms"`. */
+    debounce?: string;
+    /** Server-side wall-clock cap on the stream. Go-duration string e.g. `"5m"`. */
+    timeout?: string;
+    /** Stop after delivering this many events. */
+    maxEvents?: number;
+    /** Forwarded as the SSE `Last-Event-ID` header for cross-connection resume. */
+    lastEventId?: string;
+}
+interface FSWatchEvent {
+    /** Monotonic per-stream ID (from the SSE `id:` line). */
+    id: number;
+    type: FSWatchEventType | string;
+    path: string;
+    /** RFC3339Nano string (when present). */
+    timestamp: string;
+    size: number;
+    isDir: boolean;
+    message?: string;
+}
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
@@ -261,8 +297,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;
@@ -271,11 +307,99 @@ declare class TransportClient {
     /** Raw-bytes request (for binary cp endpoints). */
     requestRaw(method: string, reqPath: string, body?: Buffer, contentType?: string): Promise<Buffer>;
     /** Streaming request producing a Node Readable of the response body. */
-    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string): Promise<IncomingMessage>;
+    requestStreamRaw(method: string, reqPath: string, body?: Buffer | Readable, contentType?: string, extraHeaders?: Record<string, string>): Promise<IncomingMessage>;
     /** Yields decoded JSON frames from an NDJSON response (one JSON object per line). */
     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).
@@ -299,6 +423,22 @@ declare class VMFileSystem {
     }): Promise<void>;
     /** Upload a tar archive, expanded into the VM at `path`. */
     tarTo(path: string, tar: Buffer | Readable): Promise<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);
+     * }
+     * ```
+     */
+    watch(req: FSWatchRequest): AsyncGenerator<FSWatchEvent, void, void>;
     /** Download `path` from the VM as a tar archive. */
     tarFrom(path: string): Promise<Buffer>;
 }
@@ -331,6 +471,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 +575,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, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, 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 };