@vtechcom/hexcore 2.0.0-beta.1

package/dist/hydra/node-monitor.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-monitor.service.js","sourceRoot":"","sources":["../../src/hydra/node-monitor.service.ts"],"names":[],"mappings":"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"}

package/dist/hydra/ws-client.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHydraState = toHydraState;
+exports.describeConnectError = describeConnectError;
+exports.probeNode = probeNode;
+exports.waitForNodes = waitForNodes;
+exports.aggregateHydraState = aggregateHydraState;
+/**
+ * One-shot readiness probe for a hydra-node.
+ *
+ * Used while a head is booting, where the only question is "has this node come
+ * up yet, and in what phase". Ongoing status does NOT come from here — see
+ * node-monitor.service.ts, which holds a connection open, because connectivity
+ * events (a peer dropping out) are not observable by anything that connects
+ * after the fact.
+ *
+ * Built on `@hydra-sdk/bridge` rather than a raw socket so the frame shapes
+ * come from the SDK that tracks hydra-node's releases, instead of being decoded
+ * by hand here and quietly going stale at the next version — which is exactly
+ * what happened to `connectedPeers`, dropped from `Greetings` in 2.x.
+ */
+const bridge_1 = require("@hydra-sdk/bridge");
+/**
+ * Client-facing head status vocabulary.
+ *
+ * Sourced from `Hydra.API.ServerOutput.HeadStatus`. Note this is NOT the same
+ * set as the `tag` of `GET /head`, which returns a HeadState — that one has no
+ * `FanoutPossible` at all. Both are accepted here, since this maps whichever
+ * of the two a caller happens to hold.
+ */
+function toHydraState(raw) {
+    switch (String(raw ?? '').toLowerCase()) {
+        case 'idle':
+            return 'IDLE';
+        case 'initializing':
+            return 'INITIALIZING';
+        case 'open':
+            return 'OPEN';
+        case 'closed':
+            return 'CLOSED';
+        case 'fanoutpossible':
+            return 'FANOUT_POSSIBLE';
+        case 'fanningout':
+            return 'FANNING_OUT';
+        case 'final':
+            return 'FINAL';
+        default:
+            return 'UNKNOWN';
+    }
+}
+/**
+ * A readable reason from whatever the socket threw.
+ *
+ * The bridge surfaces connection failures as a DOM `ErrorEvent`, which is not
+ * an `Error`, so the obvious `String(err)` yields the literal
+ * `[object ErrorEvent]` — which is exactly the useless message this whole
+ * boot-progress work exists to stop producing. The underlying cause hangs off
+ * `.error`; `.message` and `.type` are the fallbacks.
+ */
+function describeConnectError(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object') {
+        const e = err;
+        if (e.error instanceof Error)
+            return e.error.message;
+        if (typeof e.message === 'string' && e.message)
+            return e.message;
+        if (typeof e.type === 'string' && e.type)
+            return `socket ${e.type}`;
+    }
+    const text = String(err ?? '');
+    return text && text !== '[object Object]' ? text : 'connection failed';
+}
+/**
+ * Connect to a node's API port and wait for the `Greetings` frame that
+ * hydra-node emits to every new client. Resolves as soon as it arrives.
+ */
+function probeNode(port, timeoutMs = 8000, host = '127.0.0.1') {
+    return new Promise(resolvePromise => {
+        let settled = false;
+        let timer = null;
+        // history=no keeps the node from replaying its whole event log at us,
+        // which on a long-running head is thousands of frames for one answer.
+        const bridge = new bridge_1.HydraBridge({ url: `ws://${host}:${port}`, history: false, noSnapshotUtxo: false });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            // Nothing useful to do if the socket is already gone.
+            void Promise.resolve(bridge.disconnect()).catch(() => undefined);
+            resolvePromise(result);
+        };
+        timer = setTimeout(() => finish({ reachable: false, error: `timeout after ${timeoutMs}ms` }), timeoutMs);
+        bridge.events.on('onMessage', (payload) => {
+            const msg = payload;
+            if (msg.tag !== 'Greetings')
+                return;
+            const snapshot = msg.snapshotUtxo;
+            const synced = msg.chainSyncedStatus;
+            /**
+             * `connectedPeers` is deliberately not read here. 2.x dropped it
+             * from Greetings — peer membership is delivered as events instead —
+             * so a probe cannot answer it at all and must leave it undefined
+             * rather than report a confident zero. NodeMonitorService is what
+             * knows the real answer.
+             */
+            finish({
+                reachable: true,
+                info: {
+                    hydraState: toHydraState(msg.headStatus),
+                    version: typeof msg.hydraNodeVersion === 'string' ? msg.hydraNodeVersion : undefined,
+                    snapshotUtxoCount: snapshot ? Object.keys(snapshot).length : undefined,
+                    headId: typeof msg.hydraHeadId === 'string' ? msg.hydraHeadId : undefined,
+                    chainSynced: synced === 'InSync' || synced === 'CatchingUp' ? synced : undefined,
+                    currentSlot: typeof msg.currentSlot === 'number' ? msg.currentSlot : undefined,
+                },
+            });
+        });
+        bridge.events.on('onConnectError', (err) => finish({ reachable: false, error: describeConnectError(err) }));
+        bridge.events.on('onDisconnected', () => finish({ reachable: false, error: 'connection closed before Greetings' }));
+        void bridge.connect().catch((err) => finish({ reachable: false, error: describeConnectError(err) }));
+    });
+}
+/**
+ * Poll every node until all of them greet us, or the deadline passes.
+ * Returns the per-port result so the caller can report exactly which node
+ * failed instead of v1's opaque "timeout waiting for nodes".
+ */
+async function waitForNodes(ports, opts = {}) {
+    const { timeoutMs = 180_000, intervalMs = 2000, probeTimeoutMs = 6000, onProgress, onTick } = opts;
+    const results = new Map();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const pending = ports.filter(p => !results.get(p)?.reachable);
+        if (pending.length === 0)
+            return results;
+        const probes = await Promise.all(pending.map(async (p) => [p, await probeNode(p, probeTimeoutMs)]));
+        for (const [port, res] of probes)
+            results.set(port, res);
+        const ready = ports.filter(p => results.get(p)?.reachable).length;
+        onProgress?.(ready, ports.length);
+        // Awaited before the readiness check so a boot that succeeds on this
+        // poll still leaves the node's own greeting in the log pane.
+        await onTick?.();
+        if (ready === ports.length)
+            return results;
+        await sleep(intervalMs);
+    }
+    return results;
+}
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+/**
+ * Aggregate node states into one head-level state.
+ *
+ * UNKNOWN entries are dropped before comparing, because UNKNOWN is "this node
+ * has no opinion" — an unreachable node, or one we have not heard from yet.
+ * Folding it in as a disagreement made a three-node head with one node down
+ * report UNKNOWN for the whole head, hiding the fact that the other two were
+ * still Open. That the head is short a node is reported separately, as
+ * `degraded`, which is the thing an operator can act on.
+ *
+ * Nodes that genuinely disagree — one Open, one Closed — still collapse to
+ * UNKNOWN. That is a real inconsistency and naming either one would be a guess.
+ */
+function aggregateHydraState(states) {
+    const known = states.filter(s => s !== 'UNKNOWN');
+    if (known.length === 0)
+        return 'UNKNOWN';
+    const first = known[0];
+    return known.every(s => s === first) ? first : 'UNKNOWN';
+}
+//# sourceMappingURL=ws-client.js.map

package/dist/hydra/ws-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-client.js","sourceRoot":"","sources":["../../src/hydra/ws-client.ts"],"names":[],"mappings":"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"}

package/dist/main.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrap = bootstrap;
+require("reflect-metadata");
+const core_1 = require("@nestjs/core");
+const platform_fastify_1 = require("@nestjs/platform-fastify");
+const swagger_1 = require("@nestjs/swagger");
+const common_1 = require("@nestjs/common");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const app_module_1 = require("./app.module");
+const setup_service_1 = require("./setup.service");
+const version_1 = require("./version");
+const http_1 = require("./common/http");
+const config_1 = require("./config");
+const preflight_1 = require("./preflight");
+async function bootstrap() {
+    let config;
+    try {
+        config = (0, config_1.loadConfig)();
+    }
+    catch (err) {
+        if (err instanceof config_1.ConfigError) {
+            // A bad .env prints exactly which key is wrong and how to fix it,
+            // instead of v1's stack trace from inside the DI container.
+            console.error(`\n${err.message}\n`);
+            console.error('Fix the values above in your .env, then start again. See .env.example.\n');
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Preflight before Nest boots: failing here is far cheaper than failing
+    // later inside a container create with an unrelated-looking error.
+    const report = await (0, preflight_1.runPreflight)(config);
+    console.log((0, preflight_1.formatReport)(report));
+    if (report.some(c => c.status === 'fail' && c.fatal)) {
+        console.error('Preflight failed — refusing to start.\n');
+        process.exit(1);
+    }
+    const app = await core_1.NestFactory.create(app_module_1.AppModule, new platform_fastify_1.FastifyAdapter({ bodyLimit: 8 * 1024 * 1024 }));
+    app.enableCors({
+        origin: config.corsOrigin === '*' ? true : config.corsOrigin.split(',').map(s => s.trim()),
+        credentials: true,
+    });
+    /**
+     * Single-process mode: serve the built web UI from this same port so a
+     * deployment is one container instead of v1's separate UI and API repos.
+     *
+     * The UI is a client-rendered SPA, so a deep link like /heads/3 has no file
+     * on disk and must fall back to index.html for vue-router to resolve.
+     * Nest installs its own not-found handler, so the fallback is expressed as
+     * a @fastify/static option rather than a second setNotFoundHandler, which
+     * Fastify rejects outright.
+     */
+    if (config.serveWeb && (0, node_fs_1.existsSync)(config.webDist)) {
+        app.useStaticAssets({
+            root: config.webDist,
+            wildcard: false,
+        });
+        // The filter serves this for any non-API 404 so deep links resolve.
+        http_1.ApiExceptionFilter.spaIndexPath = (0, node_path_1.join)(config.webDist, 'index.html');
+        new common_1.Logger('Bootstrap').log(`serving web UI from ${config.webDist}`);
+    }
+    const swagger = new swagger_1.DocumentBuilder()
+        .setTitle('Hexcore v2 control-plane')
+        .setDescription('Boot and operate Hydra Heads on Cardano.')
+        .setVersion(version_1.VERSION)
+        .addBearerAuth()
+        .build();
+    swagger_1.SwaggerModule.setup('api-docs', app, swagger_1.SwaggerModule.createDocument(app, swagger));
+    app.enableShutdownHooks();
+    await app.listen({ port: config.port, host: config.host });
+    const logger = new common_1.Logger('Bootstrap');
+    const base = `http://localhost:${config.port}`;
+    logger.log(`control-plane ready on ${base}`);
+    logger.log(`API docs at ${base}/api-docs`);
+    logger.log(`network=${config.network} backend=${config.chainBackend} state=${config.stateDir}`);
+    /**
+     * The setup link, with its token already in it.
+     *
+     * Setup is necessarily reachable without a login — it is where the login is
+     * created — so it is gated on a token instead. Printing the whole URL is
+     * the difference between a security measure and an obstacle: the person who
+     * just started Hexcore is looking at this line.
+     */
+    const setup = app.get(setup_service_1.SetupService);
+    const token = setup.setupToken();
+    if (token) {
+        logger.warn('Hexcore is not configured yet. Open this link to finish setup:');
+        logger.warn(`  ${base}/setup?token=${token}`);
+    }
+}
+/**
+ * Only self-start when run directly.
+ *
+ * `hexcore start` imports this module so it can set defaults first — serving
+ * the bundled UI, above all — and an unconditional call here would boot the
+ * server on import, before any of that was applied.
+ */
+if (require.main === module) {
+    bootstrap().catch(err => {
+        console.error('Fatal startup error:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/preflight.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPreflight = runPreflight;
+exports.formatReport = formatReport;
+/**
+ * Preflight checks.
+ *
+ * The single biggest v1 complaint was "it doesn't start and I can't tell why":
+ * a missing docker group membership, an unreachable MySQL, a Blockfrost key for
+ * the wrong network, or an unwritable hydra folder all surfaced as unrelated
+ * stack traces at some later point. Every one of those is checked here, up
+ * front, with a message that says what to do about it.
+ */
+const promises_1 = require("node:fs/promises");
+const node_net_1 = require("node:net");
+const node_os_1 = require("node:os");
+const shared_1 = require("@hexcore/shared");
+const docker_service_1 = require("./docker/docker.service");
+const provider_1 = require("./chain/provider");
+const socket_1 = require("./chain/socket");
+async function check(name, fatal, fn, hintOnFail) {
+    try {
+        const res = await fn();
+        return { name, status: res.status ?? 'pass', fatal, message: res.message, hint: res.hint };
+    }
+    catch (err) {
+        return { name, status: 'fail', fatal, message: err.message, hint: hintOnFail };
+    }
+}
+async function runPreflight(config) {
+    const results = [];
+    results.push(await check('node runtime', true, async () => {
+        const major = Number(process.versions.node.split('.')[0]);
+        if (major < 20)
+            throw new Error(`Node ${process.versions.node} is too old; v2 needs Node >= 20`);
+        return { message: `Node ${process.versions.node}` };
+    }));
+    results.push(await check('state directory', true, async () => {
+        await (0, promises_1.mkdir)(config.stateDir, { recursive: true });
+        // Prove it is actually writable rather than just present —
+        // a root-owned bind mount passes existsSync and fails on write.
+        const probe = `${config.stateDir}/.write-probe`;
+        await (0, promises_1.writeFile)(probe, 'ok');
+        await (0, promises_1.rm)(probe, { force: true });
+        return { message: config.stateDir };
+    }, 'Pick a directory your user owns via STATE_DIR, or fix its permissions with chown.'));
+    /**
+     * Never fatal, for the same reason the backend credentials are not.
+     *
+     * An unreachable daemon used to abort startup, which is the one outcome
+     * that leaves an operator with nothing: the UI is built to run without
+     * Docker — it reports the daemon as down, says so in a banner and refuses
+     * every lifecycle action with a reason — but none of that can be shown by a
+     * process that exited. Docker also comes and goes under the running server
+     * (Docker Desktop paused, a restart), and `reconcile()` already survives
+     * that, so refusing only the boot case was inconsistent as well as unhelpful.
+     */
+    results.push(await check('docker daemon', false, async () => {
+        const docker = new docker_service_1.DockerService(config);
+        await docker.ping();
+        const version = await docker.version();
+        return { message: `reachable (engine ${version}) via ${config.dockerSocket}` };
+    }, (0, node_os_1.platform)() === 'darwin'
+        ? 'Start Docker Desktop. The control-plane starts anyway; heads cannot be started until it is back.'
+        : 'Run `sudo systemctl start docker`, and add yourself to the docker group: `sudo usermod -aG docker $USER` (re-login required). The control-plane starts anyway; heads cannot be started until it is back.'));
+    results.push(await check('docker socket permissions', false, async () => {
+        await (0, promises_1.access)(config.dockerSocket, promises_1.constants.R_OK | promises_1.constants.W_OK);
+        return { message: 'read/write ok' };
+    }, 'Your user cannot write to the Docker socket. `sudo usermod -aG docker $USER` then log out and back in.'));
+    results.push(await check('hydra-node image', false, async () => {
+        const docker = new docker_service_1.DockerService(config);
+        const present = await docker.hasImage(config.hydraNodeImage);
+        return present
+            ? { message: `${config.hydraNodeImage} present` }
+            : {
+                status: 'warn',
+                message: `${config.hydraNodeImage} not pulled yet`,
+                hint: 'It will be pulled automatically on the first head start (~200MB).',
+            };
+    }));
+    if (config.chainBackend === 'blockfrost') {
+        /**
+         * Non-fatal, and skipped entirely with no server-wide key: the key is a
+         * default now, not a requirement. An operator who gives every head its
+         * own key has nothing to configure here, and must still be able to boot.
+         */
+        results.push(await check('blockfrost', false, async () => {
+            if (!config.blockfrostProjectId) {
+                return {
+                    status: 'warn',
+                    message: 'no server-wide key',
+                    hint: 'Every Blockfrost head will have to carry its own project id, entered ' +
+                        'when the head is created. Set BLOCKFROST_PROJECT_ID to give them a default.',
+                };
+            }
+            const provider = new provider_1.BlockfrostProvider(config.blockfrostProjectId, config.blockfrostBaseUrl);
+            try {
+                await provider.latestEpochParameters();
+            }
+            catch (err) {
+                return {
+                    status: 'warn',
+                    message: err.message,
+                    hint: 'Check BLOCKFROST_PROJECT_ID and that its network prefix matches ' +
+                        'CARDANO_NETWORK (a key starting with "preprod" only works on preprod). ' +
+                        'Heads carrying their own key are unaffected.',
+                };
+            }
+            return { message: `${config.network} key valid` };
+        }));
+        /**
+         * Warn when the unsynced budget sits inside Blockfrost's observed drift
+         * band. Upstream measured 50-80s of tip lag on preprod, and past
+         * --unsynced-period hydra-node stops signing snapshots and rejects
+         * client input — so a head boots fine and then quietly refuses to work.
+         *
+         * Checked against the default image's version profile, since that is
+         * what a head created without an explicit image will boot with. A head
+         * pinned to another version resolves its own value at start.
+         */
+        results.push(await check('blockfrost sync budget', false, async () => {
+            const profile = (0, shared_1.findVersionProfile)(config.hydraNodeImage);
+            const args = (0, shared_1.resolveHydraArgs)(profile, config.hydraArgOverrides);
+            const source = config.hydraArgOverrides.unsyncedPeriod !== undefined
+                ? 'HYDRA_UNSYNCED_PERIOD'
+                : `${profile?.label ?? 'default'} profile`;
+            if (!profile?.flags.unsyncedPeriod && profile) {
+                return {
+                    status: 'warn',
+                    message: `${profile.label} has no --unsynced-period`,
+                    hint: 'This version runs with a 60s unsynced budget inside Blockfrost’s 50-80s ' +
+                        'drift band. Create heads on 2.3.x for drift tolerance.',
+                };
+            }
+            if (args.unsyncedPeriod < 120) {
+                throw new Error(`${source} gives ${args.unsyncedPeriod}s, inside the 50-80s tip drift ` +
+                    'Blockfrost typically shows. Nodes may flip to "unsynced" during normal ' +
+                    'operation and stop signing snapshots.');
+            }
+            return { message: `${args.unsyncedPeriod}s from ${source} (drift-tolerant)` };
+        }));
+    }
+    /**
+     * Reported for every configuration, not just CHAIN_BACKEND=cardano-node,
+     * because the backend is now a per-head choice: a server defaulting to
+     * Blockfrost can still host a cardano-node head, and vice versa.
+     *
+     * Never fatal. An unusable socket used to abort startup, which took the
+     * whole control-plane down over one backend while the other needed nothing
+     * but an API key. Heads that would need the socket are refused at creation
+     * instead, with a message that says why.
+     */
+    results.push(await check('cardano-node socket', false, async () => {
+        const socket = await (0, socket_1.checkNodeSocket)(config.cardanoNodeSocket);
+        if (socket.available)
+            return { message: config.cardanoNodeSocket };
+        const wanted = config.chainBackend === 'cardano-node';
+        return {
+            status: 'warn',
+            message: socket.reason ?? 'unavailable',
+            hint: wanted
+                ? 'CHAIN_BACKEND=cardano-node but the socket is unusable — new heads must use ' +
+                    'the Blockfrost backend until it is. `chmod 660` plus group membership is enough.'
+                : 'Only needed for heads on the cardano-node backend; Blockfrost heads are unaffected.',
+        };
+    }));
+    results.push(await check('port availability', false, async () => {
+        const busy = await firstBusyPort([config.port]);
+        if (busy)
+            throw new Error(`port ${busy} is already in use`);
+        return { message: `API port ${config.port} free` };
+    }, 'Another process is on that port — change PORT in .env or stop the other process.'));
+    return results;
+}
+/** Return the first port that already has a listener, or null. */
+async function firstBusyPort(ports) {
+    for (const port of ports) {
+        const inUse = await new Promise(resolve => {
+            const socket = (0, node_net_1.createConnection)({ port, host: '127.0.0.1' });
+            const done = (result) => {
+                socket.removeAllListeners();
+                socket.destroy();
+                resolve(result);
+            };
+            socket.setTimeout(500);
+            socket.on('connect', () => done(true));
+            socket.on('timeout', () => done(false));
+            socket.on('error', () => done(false));
+        });
+        if (inUse)
+            return port;
+    }
+    return null;
+}
+const ICON = { pass: '✔', warn: '!', fail: '✖' };
+function formatReport(results) {
+    const lines = ['', 'Hexcore preflight', '─────────────────'];
+    for (const r of results) {
+        lines.push(`  ${ICON[r.status]} ${r.name.padEnd(26)} ${r.message}`);
+        if (r.status !== 'pass' && r.hint)
+            lines.push(`      → ${r.hint}`);
+    }
+    const failed = results.filter(r => r.status === 'fail');
+    lines.push('');
+    if (failed.length === 0) {
+        lines.push('  All checks passed.');
+    }
+    else {
+        const fatal = failed.filter(f => f.fatal).length;
+        lines.push(`  ${failed.length} check(s) failed${fatal ? `, ${fatal} fatal` : ' (non-fatal)'}.`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"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"}