Daemon cluster client

@voltstack/daemon-cluster-client owns the protocol between a cluster daemon and the VOLT server. It has two parts:

• the protocol's constants, types and codecs: socket event and channel names, reverse-channel messages, the object gateway's paths, headers and buckets, direct-access tokens, binary stream chunks, service exposures, and the daemon's runtime configuration with its defaults. The VOLT server and the daemon both import these, so they are the reference for the wire format;
• ClusterDaemonClient, a client for the daemon's side of the control connection: enrollment, the Socket.IO registration, a heartbeat loop, commands to the server, and handlers for the commands the server sends. VOLT's own daemon does not use this class; it opens one socket per channel itself.

You need it to write your own daemon, or tooling that speaks the daemon protocol. To add a machine to a team, install VOLT's daemon instead; see Clusters.

Install

# in a checkout of the VOLT monorepo
pnpm --filter @voltstack/daemon-cluster-client build

The build writes ESM, CommonJS and type declarations to dist/. Inside the workspace, depend on it as "@voltstack/daemon-cluster-client": "workspace:*", as the server and the daemon do. It runs on Node.js, needs socket.io-client 4 or later as a peer dependency, and depends on jose. Its scripts are build, dev, typecheck and test (a node:test suite under tests/).

ClusterDaemonClient

import { ClusterDaemonClient, DaemonClientErrorCode } from '@voltstack/daemon-cluster-client';

const server = 'https://volt.example.com';
const teamClusterId = process.env.TEAM_CLUSTER_ID!;

const client = new ClusterDaemonClient({
    serverUrl: server,
    controlSocketUrl: server,
    credentials: {
        teamClusterId,
        daemonPassword: process.env.TEAM_CLUSTER_DAEMON_PASSWORD ?? '',
        enrollmentToken: process.env.TEAM_CLUSTER_ENROLLMENT_TOKEN,
        installedVersion: '1.0.0'
    },
    enrollment: { url: `${server}/api/team-clusters/${teamClusterId}/healthcheck` }
});

// Handlers survive reconnections; register them once.
client.registerHandler('runtime.queues.snapshot', {
    async handle(payload, { requestId }) {
        return { data: await snapshotQueues(payload) };   // your code
    }
});

client.onError((error) => console.error(error.code, error.message));
client.onDisconnected((reason) => console.warn('disconnected:', reason));

await client.connect();
const config = await client.sendCommand('runtime.config.get');

connect() does three things:

1. Enrollment, when the credentials have an enrollmentToken and the options have enrollment. It sends POST <enrollment.url> with { enrollmentToken, installedVersion }. The server's endpoint is POST /api/team-clusters/:teamClusterId/healthcheck, and it answers { data: { daemonPassword, teamCluster } }. The client keeps the new password; getDaemonPassword() returns it, so store it for the next start.
2. Registration. It connects a Socket.IO client to controlSocketUrl and, on each connection, emits team-cluster-daemon:register with { teamClusterId, daemonPassword }. The server checks the password, registers the socket on the control channel (the default when the payload names no channel), marks the cluster connected and answers team-cluster-daemon:registered. connect() resolves then, or rejects with SOCKET_CONNECTION_FAILED on a connection error.
3. Heartbeat. It starts sending runtime.heartbeat commands, the first right away, with the payload from heartbeat.payloadFactory.

Options

Methods

The methods that add listeners or handlers return the client, so they chain. EnrollmentClient, ControlSocketManager, HeartbeatManager and ReverseChannelBridge, the parts it is built from, are exported too.

Handling the server's commands

The server sends commands to the daemon over the same socket: running analyses and pipelines, plugin installs and warm-ups, notebook sessions, trajectory queries, runtime configuration and more. The names are listed in DaemonCommand, in packages/shared/contracts/src/modules/cluster/daemon-commands.ts. A handler is { handle(payload, { command, requestId }) }, and returns, or resolves to, a CommandResult:

A command with no handler is answered with 404 Unknown daemon command: <name>. A handler that throws is answered with 500 and reported as HANDLER_ERROR.

Errors

Every failure is a DaemonClientError with a code from DaemonClientErrorCode:

Protocol exports

For how the daemon uses these, see Cluster daemon.