@cogcoin/client 0.5.3 → 0.5.5

package/dist/bitcoind/client/sync-engine.js

@@ -2,9 +2,39 @@ import { formatManagedSyncErrorMessage } from "../errors.js";
 import { normalizeRpcBlock } from "../normalize.js";
 import { estimateEtaSeconds } from "./rate-tracker.js";
 const DEFAULT_SYNC_CATCH_UP_POLL_MS = 2_000;
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
+function createAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    const error = new Error("managed_sync_aborted");
+    error.name = "AbortError";
+    return error;
+}
+function isAbortError(error, signal) {
+    if (signal?.aborted) {
+        return true;
+    }
+    return error instanceof Error
+        && (error.name === "AbortError" || error.message === "managed_sync_aborted");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError(signal);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(createAbortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
 async function setBitcoinSyncProgress(dependencies, info) {
@@ -81,9 +111,12 @@ async function syncAgainstBestHeight(dependencies, bestHeight) {
 }
 export async function syncToTip(dependencies) {
     try {
+        throwIfAborted(dependencies.abortSignal);
         await dependencies.node.validate();
         const indexedTipBeforeBootstrap = await dependencies.client.getTip();
-        await dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain);
+        await dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
+            signal: dependencies.abortSignal,
+        });
         const startTip = await dependencies.client.getTip();
         const aggregate = {
             appliedBlocks: 0,
@@ -95,6 +128,7 @@ export async function syncToTip(dependencies) {
             bestHashHex: "",
         };
         while (true) {
+            throwIfAborted(dependencies.abortSignal);
             const startInfo = await dependencies.rpc.getBlockchainInfo();
             await setBitcoinSyncProgress(dependencies, startInfo);
             const pass = await syncAgainstBestHeight(dependencies, startInfo.blocks);
@@ -129,10 +163,13 @@ export async function syncToTip(dependencies) {
             if (endInfo.blocks >= dependencies.startHeight && finalTip?.height !== endInfo.blocks) {
                 continue;
             }
-            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS);
+            await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS, dependencies.abortSignal);
         }
     }
     catch (error) {
+        if (isAbortError(error, dependencies.abortSignal)) {
+            throw createAbortError(dependencies.abortSignal);
+        }
         const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
         await dependencies.progress.setPhase("error", {
             lastError: message,

package/dist/bitcoind/errors.js

@@ -18,6 +18,15 @@ export function formatManagedSyncErrorMessage(message) {
     if (message === "snapshot_response_body_missing") {
         return appendNextStep("Snapshot server returned an empty response body.", "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
     }
+    if (message === "snapshot_resume_requires_partial_content") {
+        return appendNextStep("Snapshot server ignored the resume request for a partial download.", "Wait a moment and rerun sync. If this keeps happening, confirm the snapshot host supports HTTP range requests.");
+    }
+    if (message.startsWith("snapshot_chunk_sha256_mismatch_")) {
+        return appendNextStep("A downloaded snapshot chunk was corrupted and was rolled back to the last verified checkpoint.", "Wait a moment and rerun sync. If this keeps happening, check local disk health and the stability of the snapshot connection.");
+    }
+    if (message.startsWith("snapshot_download_incomplete_")) {
+        return appendNextStep("Snapshot download ended before the expected file size was reached.", "Wait a moment and rerun sync. The downloader will resume from the last verified checkpoint.");
+    }
     if (message === "bitcoind_cookie_timeout") {
         return appendNextStep("The managed Bitcoin node did not finish starting in time.", "Check the node logs and local permissions for the Bitcoin data directory, then rerun sync.");
     }

package/dist/bitcoind/indexer-daemon.d.ts

@@ -73,6 +73,10 @@ export interface IndexerDaemonProbeResult {
     client: IndexerDaemonClient | null;
     error: string | null;
 }
+export interface IndexerDaemonStopResult {
+    status: "stopped" | "not-running";
+    walletRootId: string;
+}
 export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
@@ -92,6 +96,11 @@ export declare function attachOrStartIndexerDaemon(options: {
     walletRootId?: string;
     startupTimeoutMs?: number;
 }): Promise<IndexerDaemonClient>;
+export declare function stopIndexerDaemonService(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<IndexerDaemonStopResult>;
 export declare function shutdownIndexerDaemonForTesting(options: {
     dataDir: string;
     walletRootId?: string;

package/dist/bitcoind/indexer-daemon.js

@@ -39,6 +39,20 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+async function waitForProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await sleep(50);
+    }
+    throw new Error(errorCode);
+}
+async function clearIndexerDaemonRuntimeArtifacts(paths) {
+    await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+}
 function createIndexerDaemonClient(socketPath) {
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
@@ -357,26 +371,49 @@ export async function attachOrStartIndexerDaemon(options) {
         throw error;
     }
 }
-export async function shutdownIndexerDaemonForTesting(options) {
+export async function stopIndexerDaemonService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.indexerDaemonStatusPath);
-    if (status?.processId !== null && status?.processId !== undefined) {
+    const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
+        purpose: "indexer-daemon-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
+    try {
+        const status = await readJsonFile(paths.indexerDaemonStatusPath);
+        const processId = status?.processId ?? null;
+        if (status === null || processId === null || !await isProcessAlive(processId)) {
+            await clearIndexerDaemonRuntimeArtifacts(paths);
+            return {
+                status: "not-running",
+                walletRootId,
+            };
+        }
         try {
-            process.kill(status.processId, "SIGTERM");
-            const deadline = Date.now() + 5_000;
-            while (Date.now() < deadline) {
-                if (!await isProcessAlive(status.processId)) {
-                    break;
-                }
-                await sleep(50);
-            }
+            process.kill(processId, "SIGTERM");
         }
-        catch {
-            // ignore stale pid cleanup failures
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
         }
+        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            status: "stopped",
+            walletRootId,
+        };
     }
-    await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    finally {
+        await lock.release();
+    }
+}
+export async function shutdownIndexerDaemonForTesting(options) {
+    await stopIndexerDaemonService(options).catch(async () => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    });
 }
 export async function readIndexerDaemonStatusForTesting(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;

package/dist/bitcoind/service.d.ts

@@ -25,11 +25,20 @@ export interface ManagedBitcoindServiceProbeResult {
     status: ManagedBitcoindObservedStatus | null;
     error: string | null;
 }
+export interface ManagedBitcoindServiceStopResult {
+    status: "stopped" | "not-running";
+    walletRootId: string;
+}
 export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
     managedWalletPassphrase?: string;
 }): Promise<ManagedCoreWalletReplicaStatus>;
 export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
 export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
+export declare function stopManagedBitcoindService(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<ManagedBitcoindServiceStopResult>;
 export declare function readManagedBitcoindServiceStatusForTesting(dataDir: string, walletRootId?: string): Promise<ManagedBitcoindObservedStatus | null>;
 export declare function shutdownManagedBitcoindServiceForTesting(options: {
     dataDir: string;

package/dist/bitcoind/service.js

@@ -21,6 +21,16 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+async function waitForProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await sleep(250);
+    }
+    throw new Error(errorCode);
+}
 function getWalletReplicaName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
@@ -488,6 +498,12 @@ async function writeBitcoindStatus(paths, status) {
         p2pPort: status.p2pPort,
     });
 }
+async function clearManagedBitcoindRuntimeArtifacts(paths) {
+    await rm(paths.bitcoindStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindPidPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
+}
 async function refreshManagedBitcoindStatus(status, paths, options) {
     const nowUnixMs = Date.now();
     const rpc = createRpcClient(status.rpc);
@@ -699,37 +715,62 @@ export async function attachOrStartManagedBitcoindService(options) {
         throw error;
     }
 }
-export async function readManagedBitcoindServiceStatusForTesting(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
-    const paths = resolveManagedServicePaths(dataDir, walletRootId);
-    return readJsonFile(paths.bitcoindStatusPath);
-}
-export async function shutdownManagedBitcoindServiceForTesting(options) {
+export async function stopManagedBitcoindService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.bitcoindStatusPath);
-    if (status === null) {
-        return;
-    }
-    const rpc = createRpcClient(status.rpc);
+    const lock = await acquireFileLock(paths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
     try {
-        await rpc.stop();
-    }
-    catch {
-        if (status.processId !== null) {
+        const status = await readJsonFile(paths.bitcoindStatusPath);
+        const processId = status?.processId ?? null;
+        if (status === null || processId === null || !await isProcessAlive(processId)) {
+            await clearManagedBitcoindRuntimeArtifacts(paths);
+            return {
+                status: "not-running",
+                walletRootId,
+            };
+        }
+        const rpc = createRpcClient(status.rpc);
+        try {
+            await rpc.stop();
+        }
+        catch {
             try {
-                process.kill(status.processId, "SIGTERM");
+                process.kill(processId, "SIGTERM");
             }
-            catch {
-                // ignore
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                    throw error;
+                }
             }
         }
+        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, "managed_bitcoind_service_stop_timeout");
+        await clearManagedBitcoindRuntimeArtifacts(paths);
+        return {
+            status: "stopped",
+            walletRootId,
+        };
     }
-    const deadline = Date.now() + (options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
-    while (Date.now() < deadline) {
-        if (!await isProcessAlive(status.processId)) {
-            break;
-        }
-        await sleep(250);
+    finally {
+        await lock.release();
     }
-    await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+}
+export async function readManagedBitcoindServiceStatusForTesting(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
+    const paths = resolveManagedServicePaths(dataDir, walletRootId);
+    return readJsonFile(paths.bitcoindStatusPath);
+}
+export async function shutdownManagedBitcoindServiceForTesting(options) {
+    await stopManagedBitcoindService({
+        dataDir: options.dataDir,
+        walletRootId: options.walletRootId,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+    }).catch(async (error) => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+        throw error;
+    });
 }

package/dist/bitcoind/testing.d.ts

@@ -1,8 +1,8 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
-export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
 export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
 export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
 export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";

package/dist/bitcoind/testing.js

@@ -1,8 +1,8 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
-export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
 export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
 export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
 export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";

package/dist/bitcoind/types.d.ts

@@ -8,6 +8,15 @@ export interface SnapshotMetadata {
     sha256: string;
     sizeBytes: number;
 }
+export interface SnapshotChunkManifest {
+    formatVersion: number;
+    chunkSizeBytes: number;
+    snapshotFilename: string;
+    snapshotHeight: number;
+    snapshotSizeBytes: number;
+    snapshotSha256: string;
+    chunkSha256s: string[];
+}
 export interface WritingQuote {
     quote: string;
     author: string;

package/dist/cli/commands/service-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "../types.js";
+export declare function runServiceRuntimeCommand(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<number>;