stream-doctor 0.0.4 → 0.0.6

package/README.md

@@ -5,7 +5,7 @@ your pipeline, watch what comes out the other end and assert on the metrics.
 An early proof of concept, currently a single RTMP to HLS scenario with a
 single metric, the audio/video drift.
 
-This is the TypeScript client for the StreamDoctor daemon. It brings the
+This is the TypeScript client for the stream-doctor daemon. It brings the
 daemon binary along, as an optional dependency on `@stream-doctor/<platform>`.
 Setup, usage and the roadmap are described in the
-[StreamDoctor repository](https://github.com/membraneframework-labs/stream_doctor).
+[stream-doctor repository](https://github.com/membraneframework/stream-doctor).

package/dist/stream_doctor.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess } from "node:child_process";
-export declare function bundledBinary(): string | null;
+/** Lifecycle state of a streamer or viewer. */
 export type Status = "streaming" | "receiving" | "waiting_for_playlist" | "ended" | "failed" | "stopped";
+/** State of the publisher, as reported by the daemon. */
 export interface StreamerStatus {
     input: string;
     rtmp_url: string;
@@ -8,15 +9,18 @@ export interface StreamerStatus {
     error: string | null;
     live: boolean;
 }
+/** Audio/video drift measured by a viewer, in milliseconds. */
 export interface AvDrift {
     drift_ms: number | null;
     frame_duration_ms: number | null;
     latest_samples: number[];
 }
+/** Metrics collected by a viewer. */
 export interface Metrics {
     av_drift?: AvDrift;
     error?: string;
 }
+/** State of a viewer, as reported by the daemon. */
 export interface ViewerStatus {
     id: string;
     hls_url: string;
@@ -24,47 +28,66 @@ export interface ViewerStatus {
     error: string | null;
     metrics: Metrics;
 }
-export interface ServerStatus {
+/** State of the whole daemon. */
+export interface DaemonStatus {
     streamer: StreamerStatus | null;
     viewers: ViewerStatus[];
 }
-export declare function session({ server, binary, }?: {
-    server?: string;
+/** Spawns a daemon from `binary` (the bundled one by default) on `port` (a free one by default), or connects to a running one when `daemonUrl` is set. */
+export declare function session({ daemonUrl, binary, port, }?: {
+    daemonUrl?: string;
     binary?: string;
+    port?: number;
 }): Promise<Session>;
+/** Path to the daemon binary bundled for this platform, or null if there is none. */
+export declare function bundledBinary(): string | null;
+/** A connection to the daemon, grouping one publisher and any number of viewers. */
 declare class Session {
-    server: string;
+    daemonUrl: string;
     child: ChildProcess | null;
     logFile: string | null;
-    constructor(server: string, child: ChildProcess | null, logFile?: string | null);
+    constructor(daemonUrl: string, child: ChildProcess | null, logFile?: string | null);
+    /** Starts publishing `file` to `rtmpUrl`. */
     publish(rtmpUrl: string, { file }?: {
         file?: string;
     }): Streamer;
+    /** Starts a viewer collecting metrics from the HLS playlist at `hlsUrl`. */
     watch(hlsUrl: string): Promise<Viewer>;
-    status(): Promise<ServerStatus>;
+    /** Current state of the daemon. */
+    status(): Promise<DaemonStatus>;
+    /** Stops the daemon if this session spawned it. */
     close(): Promise<void>;
 }
+/** The publisher of a session. */
 declare class Streamer {
-    server: string;
+    daemonUrl: string;
     ready: Promise<StreamerStatus>;
-    constructor(server: string, ready: Promise<StreamerStatus>);
+    constructor(daemonUrl: string, ready: Promise<StreamerStatus>);
+    /** Current state of the publisher. */
     status(): Promise<StreamerStatus>;
+    /** Resolves once the stream is live, rejects if it ends or fails first. */
     waitUntilLive({ timeoutMs, intervalMs, }?: {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<StreamerStatus>;
+    /** Stops publishing. */
     stop(): Promise<StreamerStatus>;
 }
+/** A viewer of a session. */
 declare class Viewer {
-    server: string;
+    daemonUrl: string;
     id: string;
-    constructor(server: string, id: string);
+    constructor(daemonUrl: string, id: string);
+    /** Current state of the viewer. */
     status(): Promise<ViewerStatus>;
+    /** Metrics collected so far. */
     metrics(): Promise<Metrics>;
+    /** Resolves once the viewer ends, fails or is stopped, calling `onUpdate` with each polled state. */
     waitUntilDone({ intervalMs, onUpdate, }?: {
         intervalMs?: number;
         onUpdate?: (viewer: ViewerStatus) => void;
     }): Promise<ViewerStatus>;
+    /** Stops the viewer and returns its final metrics. */
     stop(): Promise<Metrics>;
 }
 export type { Session, Streamer, Viewer };

package/dist/stream_doctor.js

@@ -1,19 +1,39 @@
-// Client for the stream_doctor server. `session()` spawns the binary (the one
-// bundled for this platform, or `binary`) when no server is listening;
-// `session.close()` stops it. The daemon's output goes to `session.logFile`.
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
+import net, {} from "node:net";
 import os from "node:os";
 import path from "node:path";
-const DEFAULT_SERVER = "http://localhost:4040";
+const LOG_FILE = path.join(os.tmpdir(), "stream_doctor.log");
 const PLATFORM_PACKAGES = {
     "darwin-arm64": "@stream-doctor/darwin-arm64",
     "linux-arm64": "@stream-doctor/linux-arm64",
     "linux-x64": "@stream-doctor/linux-x64",
 };
-// The daemon ships as one package per platform, all optional dependencies of
-// this one, so only the matching one is installed.
+const TERMINAL_STATUSES = ["ended", "failed", "stopped"];
+/** Spawns a daemon from `binary` (the bundled one by default) on `port` (a free one by default), or connects to a running one when `daemonUrl` is set. */
+export async function session({ daemonUrl, binary, port, } = {}) {
+    if (daemonUrl) {
+        if (binary !== undefined || port !== undefined) {
+            throw new Error("`daemonUrl` connects to a running daemon, it cannot be combined with `binary` or `port`");
+        }
+        await api("GET", "/status", null, daemonUrl);
+        return new Session(daemonUrl, null);
+    }
+    let installDir;
+    if (!binary) {
+        binary = bundledBinary() ?? undefined;
+        if (!binary) {
+            throw new Error(`no stream_doctor binary bundled for ${process.platform}-${process.arch}, pass one with \`binary\` or a running daemon with \`daemonUrl\``);
+        }
+        installDir = path.join(path.dirname(binary), "..", ".burrito");
+    }
+    port ??= await freePort();
+    const url = `http://localhost:${port}`;
+    const child = await spawnDaemon(binary, url, port, installDir);
+    return new Session(url, child, LOG_FILE);
+}
+/** Path to the daemon binary bundled for this platform, or null if there is none. */
 export function bundledBinary() {
     const pkg = PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
     if (!pkg)
@@ -25,95 +45,31 @@ export function bundledBinary() {
         return null;
     }
 }
-async function api(method, path, body, server) {
-    let res;
-    try {
-        res = await fetch(server + path, {
-            method,
-            headers: body ? { "content-type": "application/json" } : undefined,
-            body: body ? JSON.stringify(body) : undefined,
-        });
-    }
-    catch (e) {
-        throw new Error(`${method} ${path}: cannot reach ${server} (is the server running?): ${e.message}`);
-    }
-    const text = await res.text();
-    if (!res.ok)
-        throw new Error(`${method} ${path}: HTTP ${res.status}: ${text}`);
-    return JSON.parse(text);
-}
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const TERMINAL_STATUSES = ["ended", "failed", "stopped"];
-export async function session({ server = DEFAULT_SERVER, binary, } = {}) {
-    try {
-        await api("GET", "/status", null, server);
-        return new Session(server, null);
-    }
-    catch (e) {
-        let installDir;
-        const logFile = path.join(os.tmpdir(), "stream_doctor.log");
-        if (!binary) {
-            binary = bundledBinary() ?? undefined;
-            if (!binary) {
-                throw new Error(`${e.message}; no stream_doctor binary bundled for ${process.platform}-${process.arch}, pass one with \`binary\``);
-            }
-            // Burrito unpacks the payload once per release name + ERTS + app version,
-            // none of which change between npm releases, so its default cache under
-            // ~/.local/share would keep serving the previous package's daemon.
-            installDir = path.join(path.dirname(binary), "..", ".burrito");
-        }
-        const child = await spawnServer(binary, server, logFile, installDir);
-        return new Session(server, child, logFile);
-    }
-}
-async function spawnServer(binary, server, logFile, installDir) {
-    if (!fs.existsSync(binary)) {
-        throw new Error(`${binary} not found, build it with: MIX_ENV=prod mix release`);
-    }
-    const env = {
-        ...process.env,
-        // the daemon quits once its stdin (the pipe below) breaks, i.e. when this
-        // process dies, however it dies
-        STREAM_DOCTOR_EXIT_ON_STDIN_EOF: "1",
-        ...(installDir ? { STREAM_DOCTOR_INSTALL_DIR: installDir } : {}),
-    };
-    const log = fs.openSync(logFile, "a");
-    // own process group, so that killing the burrito launcher takes the BEAM with it
-    const child = spawn(binary, [], { stdio: ["pipe", log, log], detached: true, env });
-    child.on("exit", () => fs.closeSync(log));
-    for (const deadline = Date.now() + 120_000; Date.now() < deadline;) {
-        if (child.exitCode !== null) {
-            throw new Error(`server exited with ${child.exitCode}, see ${logFile}`);
-        }
-        await sleep(1000);
-        try {
-            await api("GET", "/status", null, server);
-            return child;
-        }
-        catch { }
-    }
-    throw new Error(`server didn't come up in 2 minutes, see ${logFile}`);
-}
+/** A connection to the daemon, grouping one publisher and any number of viewers. */
 class Session {
-    server;
+    daemonUrl;
     child;
     logFile;
-    constructor(server, child, logFile = null) {
-        this.server = server;
+    constructor(daemonUrl, child, logFile = null) {
+        this.daemonUrl = daemonUrl;
         this.child = child;
         this.logFile = logFile;
     }
+    /** Starts publishing `file` to `rtmpUrl`. */
     publish(rtmpUrl, { file = "test.mp4" } = {}) {
-        const ready = api("POST", "/streamer", { input: file, rtmp_url: rtmpUrl }, this.server);
-        return new Streamer(this.server, ready);
+        const ready = api("POST", "/streamer", { input: file, rtmp_url: rtmpUrl }, this.daemonUrl);
+        return new Streamer(this.daemonUrl, ready);
     }
+    /** Starts a viewer collecting metrics from the HLS playlist at `hlsUrl`. */
     async watch(hlsUrl) {
-        const { id } = await api("POST", "/viewers", { hls_url: hlsUrl }, this.server);
-        return new Viewer(this.server, id);
+        const { id } = await api("POST", "/viewers", { hls_url: hlsUrl }, this.daemonUrl);
+        return new Viewer(this.daemonUrl, id);
     }
+    /** Current state of the daemon. */
     status() {
-        return api("GET", "/status", null, this.server);
+        return api("GET", "/status", null, this.daemonUrl);
     }
+    /** Stops the daemon if this session spawned it. */
     close() {
         const child = this.child;
         if (!child || child.exitCode !== null || child.pid === undefined)
@@ -126,22 +82,25 @@ class Session {
         });
     }
 }
+/** The publisher of a session. */
 class Streamer {
-    server;
+    daemonUrl;
     ready;
-    constructor(server, ready) {
-        this.server = server;
+    constructor(daemonUrl, ready) {
+        this.daemonUrl = daemonUrl;
         this.ready = ready;
         ready.catch(() => { });
     }
+    /** Current state of the publisher. */
     status() {
-        return this.ready.then(() => api("GET", "/streamer", null, this.server));
+        return this.ready.then(() => api("GET", "/streamer", null, this.daemonUrl));
     }
+    /** Resolves once the stream is live, rejects if it ends or fails first. */
     async waitUntilLive({ timeoutMs = 60_000, intervalMs = 250, } = {}) {
         await this.ready;
         const deadline = Date.now() + timeoutMs;
         for (;;) {
-            const streamer = await api("GET", "/streamer", null, this.server);
+            const streamer = await api("GET", "/streamer", null, this.daemonUrl);
             if (streamer.live)
                 return streamer;
             if (TERMINAL_STATUSES.includes(streamer.status)) {
@@ -152,25 +111,30 @@ class Streamer {
             await sleep(intervalMs);
         }
     }
+    /** Stops publishing. */
     async stop() {
         await this.ready;
-        return api("DELETE", "/streamer", null, this.server);
+        return api("DELETE", "/streamer", null, this.daemonUrl);
     }
 }
+/** A viewer of a session. */
 class Viewer {
-    server;
+    daemonUrl;
     id;
-    constructor(server, id) {
-        this.server = server;
+    constructor(daemonUrl, id) {
+        this.daemonUrl = daemonUrl;
         this.id = id;
     }
+    /** Current state of the viewer. */
     status() {
-        return api("GET", `/viewers/${this.id}`, null, this.server);
+        return api("GET", `/viewers/${this.id}`, null, this.daemonUrl);
     }
+    /** Metrics collected so far. */
     async metrics() {
         const { metrics } = await this.status();
         return metrics;
     }
+    /** Resolves once the viewer ends, fails or is stopped, calling `onUpdate` with each polled state. */
     async waitUntilDone({ intervalMs = 1000, onUpdate, } = {}) {
         for (;;) {
             const viewer = await this.status();
@@ -180,8 +144,63 @@ class Viewer {
             await sleep(intervalMs);
         }
     }
+    /** Stops the viewer and returns its final metrics. */
     async stop() {
-        const { metrics } = await api("DELETE", `/viewers/${this.id}`, null, this.server);
+        const { metrics } = await api("DELETE", `/viewers/${this.id}`, null, this.daemonUrl);
         return metrics;
     }
 }
+async function spawnDaemon(binary, daemonUrl, port, installDir) {
+    if (!fs.existsSync(binary)) {
+        throw new Error(`${binary} not found, build it with: MIX_ENV=prod mix release`);
+    }
+    const env = {
+        ...process.env,
+        STREAM_DOCTOR_EXIT_ON_STDIN_EOF: "1",
+        PORT: String(port),
+        ...(installDir ? { STREAM_DOCTOR_INSTALL_DIR: installDir } : {}),
+    };
+    const log = fs.openSync(LOG_FILE, "a");
+    const child = spawn(binary, [], { stdio: ["pipe", log, log], detached: true, env });
+    child.on("exit", () => fs.closeSync(log));
+    for (const deadline = Date.now() + 120_000; Date.now() < deadline;) {
+        if (child.exitCode !== null) {
+            throw new Error(`daemon exited with ${child.exitCode}, see ${LOG_FILE}`);
+        }
+        await sleep(1000);
+        try {
+            await api("GET", "/status", null, daemonUrl);
+            return child;
+        }
+        catch { }
+    }
+    throw new Error(`daemon didn't come up in 2 minutes, see ${LOG_FILE}`);
+}
+async function api(method, path, body, daemonUrl) {
+    let res;
+    try {
+        res = await fetch(daemonUrl + path, {
+            method,
+            headers: body ? { "content-type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (e) {
+        throw new Error(`${method} ${path}: cannot reach ${daemonUrl} (is the daemon running?): ${e.message}`);
+    }
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`${method} ${path}: HTTP ${res.status}: ${text}`);
+    return JSON.parse(text);
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const probe = net.createServer();
+        probe.once("error", reject);
+        probe.listen(0, () => {
+            const { port } = probe.address();
+            probe.close(() => resolve(port));
+        });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "stream-doctor",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Automated end-to-end testing for video infrastructure (early proof of concept)",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/membraneframework-labs/stream_doctor.git"
+    "url": "git+https://github.com/membraneframework/stream-doctor.git"
   },
   "type": "module",
   "exports": "./dist/stream_doctor.js",
@@ -33,8 +33,8 @@
     "typescript-eslint": "^8.70.0"
   },
   "optionalDependencies": {
-    "@stream-doctor/darwin-arm64": "0.0.4",
-    "@stream-doctor/linux-arm64": "0.0.4",
-    "@stream-doctor/linux-x64": "0.0.4"
+    "@stream-doctor/darwin-arm64": "0.0.6",
+    "@stream-doctor/linux-arm64": "0.0.6",
+    "@stream-doctor/linux-x64": "0.0.6"
   }
 }