Selva Compute API Reference - v3.0.1
    Preparing search index...

    Class ComputeServerStats

    ComputeServerStats provides methods to query Rhino Compute server statistics.

    Use this for server health monitoring and statistics.

    const stats = new ComputeServerStats('http://localhost:6500', 'your-api-key');

    try {
      const isOnline = await stats.isServerOnline();
      const children = await stats.getActiveChildren();
      const version = await stats.getVersion();

      // Or get everything at once
      const allStats = await stats.getServerStats();
    } finally {
      await stats.dispose(); // Clean up resources
    }
    Index

    Constructors

    constructor

    Methods

    dispose getActiveChildren getIdleSpan getInstalledPlugins getServerStats getServerTime getVersion isServerOnline launchChild launchChildren monitor purgeAllChildren purgeCache recycleChildren shutdownChildren

    Constructors

    Methods

    • Get the number of active child processes on the server.

      By default the proxy's /activechildren endpoint will spawn children up to the configured count if none are running, then report the count — which wakes (and bills) an idle server. Pass { initialize: false } for a passive read that reports the current count without spawning; use this for monitoring or before a purge/probe where you must not wake the server.

      Parameters

      • options: { initialize?: boolean } = {}
        • Optionalinitialize?: boolean

          When false, append ?initialize=false so the server reports without spawning. Defaults to true (the server's default).

      Returns Promise<number | null>

      Number of active children, or null if unavailable

    • Get how long the rhino.compute proxy has been idle.

      GETs /idlespan on the proxy, which returns the seconds elapsed since the last request was forwarded to a compute child. This is a proxy-level metric (not proxied to a child) used by autoscalers to decide when a node can be drained. Returns null if unavailable.

      Returns Promise<number | null>

      Idle time in seconds, or null on failure.

    • Get the plugins installed on the server.

      Returns a name → version map of non-core plugins the server has loaded, or null if the request failed. Pass kind to choose which inventory: 'gh' (default) lists Grasshopper add-on assemblies via /plugins/gh/installed; 'rhino' lists Rhino plugins via /plugins/rhino/installed. Plugins that ship with Rhino / are core libraries are excluded by the server.

      Parameters

      • kind: "rhino" | "gh" = 'gh'

        'gh' for Grasshopper add-ons (default) or 'rhino' for Rhino plugins.

      Returns Promise<Record<string, string> | null>

      Map of plugin name to version, or null on failure.

      const gh = await stats.getInstalledPlugins();        // Grasshopper add-ons
      const selvaVersion = gh?.['Selva'] ?? null;

    • Get comprehensive server statistics. Fetches all available server information in parallel.

      Returns Promise<
          {
              activeChildren?: number;
              isOnline: boolean;
              version?: { compute: string; git_sha: string
              | null; rhino: string };
          },
      >

      Object containing server status and available stats

    • Get the server's current UTC clock.

      GETs /servertime, which the server emits as a JSON-encoded ISO-8601 timestamp (e.g. "2026-06-18T08:30:00Z"). Useful for detecting clock skew between caller and server. Returns null if the request failed or the body isn't a parseable date.

      Returns Promise<Date | null>

      A Date for the server's UTC time, or null on failure.

    • Get the server version information.

      Returns Promise<{ compute: string; git_sha: string | null; rhino: string } | null>

      Version object with rhino, compute, and git_sha, or null if unavailable

    • Check if the server is online.

      This is a single-sample probe: it returns true only on a 2xx from the proxy liveness root /, and false for every other outcome (non-2xx, network error, or timeout). A cold or briefly-busy-but-up server can therefore read as offline — callers that gate on this (e.g. client construction) should retry rather than treat a single false as authoritative.

      Parameters

      • timeoutMs: number = 5000

        Abort the probe after this many ms (default: 5000). Pass 0 to disable the timeout. Prevents a hung connection from stalling the caller indefinitely.

      Returns Promise<boolean>

    • Add a single compute child to the pool, optionally on a specific port.

      POSTs /launch-child (with ?port=N when port is given). Unlike launchChildren, this can push the pool above the baseline, up to the server's MaxChildren cap. Returns { spawned: [port] } on success, or null on failure (server replies 400 for a bad port, 409 if the port is in use, 503 at the max-children cap).

      Parameters

      • Optionalport: number

        Optional specific port to launch on; otherwise the next free one.

      Returns Promise<{ spawned: number[] } | null>

      { spawned } listing the launched port, or null on failure.

    • Fill the compute child pool up to the server's configured baseline.

      POSTs /launch-children. No-op when the pool is already at or above the configured --childcount. Returns { spawned, active } — how many children were started and the resulting child count — or null on failure.

      To raise capacity above the baseline use launchChild; the baseline itself can only be changed by restarting rhino.compute.

      Returns Promise<{ active: number; spawned: number[] } | null>

      { spawned, active }, or null on failure.

    • Continuously monitor server stats at specified interval.

      Parameters

      • callback: (
            stats: {
                activeChildren?: number;
                isOnline: boolean;
                version?: { compute: string; git_sha: string | null; rhino: string };
            },
        ) => void

        Function called with stats on each interval

      • intervalMs: number = 5000

        Milliseconds between checks (default: 5000)

      Returns () => void

      Function to stop monitoring

      const stopMonitoring = stats.monitor((data) => {
        console.log('Server stats:', data);
      }, 3000);

      // Later...
      stopMonitoring();

    • Best-effort fleet-wide cache purge across a multi-child deployment.

      A single purgeCache POST is forwarded by the rhino.compute proxy to just ONE round-robin-selected child, so the other children keep serving stale cached solves. There is no proxy endpoint that addresses children individually, so this method reads the active child count (passively, never spawning) and fires 2 × count sequential purges, relying on the proxy's round-robin to spread the hits across the pool.

      This is best-effort, not a guarantee. Round-robin can revisit one child and skip another; under concurrent traffic the rotation drifts. The result's confident flag is true only when the server reports a single child (where one purge is exact) — surface it so callers don't over-promise. For a hard fleet-wide guarantee, run the deployment at --childcount 1 or add a server-side fan-out endpoint.

      Returns Promise<
          | {
              calls: number;
              children: number;
              confident: boolean;
              totalPurged: number;
          }
          | null,
      >

      { totalPurged, calls, children, confident }, or null if the child count couldn't be read (server unreachable). totalPurged sums the per-call counts; calls is how many purges were issued; children is the reported pool size; confident is true only at a single-child pool.

      const r = await stats.purgeAllChildren();
      if (r && !r.confident) {
        console.warn(`Purged ~${r.totalPurged} across ${r.children} children (best-effort)`);
      }

    • Purge the server's solve-results / URL-data cache.

      POSTs to cache/purge and returns the number of entries removed, or null if the request failed. This clears cached solve responses and fetched definition-URL data; it does NOT evict the definition cache (active pointer references stay valid).

      Caveat: cache/purge is forwarded by the rhino.compute proxy to a single round-robin-selected child, so in a multi-child deployment one call purges one child's cache. Call repeatedly (or size the pool to 1) if you need a fleet-wide purge.

      Returns Promise<number | null>

      Number of entries removed, or null on failure.

      const removed = await stats.purgeCache();
      if (removed !== null) console.log(`Purged ${removed} cached solves`);

    • Shut down compute children and respawn replacements (rolling restart).

      POSTs /recycle-children. With no port it recycles every child; with port it recycles just that one. The server recycles sequentially (each replacement is serving before the next child is stopped) so the pool never drops to zero mid-recycle. Returns { shutdown, spawned, active }, or null on failure.

      Parameters

      • Optionalport: number

        Optional port to target; omit to recycle all children.

      Returns Promise<{ active: number; shutdown: number; spawned: number[] } | null>

      { shutdown, spawned, active }, or null on failure.

    • Gracefully shut down compute children without respawning them.

      POSTs /shutdown-children. With no port it shuts down every child; with port it targets just that one. Children do not respawn, but the next /grasshopper request auto-spawns the pool back to the baseline. Returns { shutdown, active } — how many were stopped and the remaining count — or null on failure.

      Parameters

      • Optionalport: number

        Optional port to target; omit to shut down all children.

      Returns Promise<{ active: number; shutdown: number } | null>

      { shutdown, active }, or null on failure.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods