diff --git a/src/commands/cli/upgrade.ts b/src/commands/cli/upgrade.ts index 9ccac9801c..2b3fa1afb2 100644 --- a/src/commands/cli/upgrade.ts +++ b/src/commands/cli/upgrade.ts @@ -558,7 +558,8 @@ async function executeStandardUpgrade(opts: { channel === "nightly" && !versionArg ? NIGHTLY_TAG : undefined; const downloadResult = await withProgress( { message: `Downloading ${target}...`, json }, - async () => executeUpgrade(method, target, downloadTag, offline) + async (setMessage) => + executeUpgrade(method, target, downloadTag, offline, setMessage) ); if (downloadResult?.patchBytes) { @@ -629,7 +630,8 @@ async function migrateToStandaloneForNightly( const downloadTag = versionArg ? undefined : NIGHTLY_TAG; const downloadResult = await withProgress( { message: `Downloading ${target}...`, json }, - async () => executeUpgrade("curl", target, downloadTag) + async (setMessage) => + executeUpgrade("curl", target, downloadTag, undefined, setMessage) ); if (downloadResult?.patchBytes) { diff --git a/src/lib/bspatch.ts b/src/lib/bspatch.ts index 7df06205e6..c795660ded 100644 --- a/src/lib/bspatch.ts +++ b/src/lib/bspatch.ts @@ -588,7 +588,8 @@ async function transformPatch( async function applyReaderToFile( oldReader: OldReader, patchData: Uint8Array, - destPath: string + destPath: string, + onBytes?: (bytes: number) => void ): Promise { const writer = createWriteStream(destPath); const hasher = createHash("sha256"); @@ -610,6 +611,7 @@ async function applyReaderToFile( } writer.write(chunk); hasher.update(chunk); + onBytes?.(chunk.byteLength); }); } finally { await new Promise((resolve, reject) => { @@ -642,7 +644,8 @@ async function applyReaderToFile( */ async function applyReaderToMemory( oldReader: OldReader, - patchData: Uint8Array + patchData: Uint8Array, + onBytes?: (bytes: number) => void ): Promise { // Preallocate the exact output size from the header so chunks can be copied // in place — avoids a final concat pass over ~100 MB of output. @@ -653,6 +656,7 @@ async function applyReaderToMemory( await transformPatch(oldReader, patchData, (chunk) => { output.set(chunk, offset); offset += chunk.byteLength; + onBytes?.(chunk.byteLength); }); return output; @@ -701,7 +705,8 @@ export function applyPatchToMemory( export async function applyPatchChainInMemory( oldPath: string, patches: Uint8Array[], - destPath: string + destPath: string, + onBytes?: (bytes: number) => void ): Promise { if (patches.length === 0) { throw new Error("Cannot apply an empty patch chain"); @@ -719,7 +724,7 @@ export async function applyPatchChainInMemory( if (!patch) { throw new Error(`Missing patch at index ${i}`); } - const next = await applyReaderToMemory(reader, patch); + const next = await applyReaderToMemory(reader, patch, onBytes); await reader.close(); reader = new MemoryOldReader(next); } @@ -729,7 +734,7 @@ export async function applyPatchChainInMemory( if (!finalPatch) { throw new Error("Missing final patch"); } - return await applyReaderToFile(reader, finalPatch, destPath); + return await applyReaderToFile(reader, finalPatch, destPath, onBytes); } finally { await reader.close(); } diff --git a/src/lib/delta-upgrade.ts b/src/lib/delta-upgrade.ts index b6e0a2fee5..6225bcdb58 100644 --- a/src/lib/delta-upgrade.ts +++ b/src/lib/delta-upgrade.ts @@ -27,7 +27,7 @@ import { isDowngrade, isNightlyVersion, } from "./binary.js"; -import { applyPatchChainInMemory } from "./bspatch.js"; +import { applyPatchChainInMemory, parsePatchHeader } from "./bspatch.js"; import { CLI_VERSION } from "./constants.js"; import { customFetch } from "./custom-ca.js"; import { formatBytes } from "./formatters/numbers.js"; @@ -40,6 +40,7 @@ import { } from "./ghcr.js"; import { logger } from "./logger.js"; import { loadCachedChain, savePatchesToCache } from "./patch-cache.js"; +import { makeByteProgress, type SetMessage } from "./progress.js"; import { withTracing, withTracingSpan } from "./telemetry.js"; /** Scoped logger for delta upgrade operations */ @@ -835,11 +836,13 @@ export async function resolveNightlyChain(opts: { * @param destPath - Path to write the patched binary * @returns Delta result with SHA-256 and size info, or null if delta is unavailable */ +// biome-ignore lint/nursery/useMaxParams: established 4-param shape; setMessage is a defaulted spinner-progress extension export function attemptDeltaUpgrade( targetVersion: string, oldBinaryPath: string, destPath: string, - offline?: boolean + offline?: boolean, + setMessage?: SetMessage ): Promise { if (!canAttemptDelta(targetVersion)) { return Promise.resolve(null); @@ -865,13 +868,15 @@ export function attemptDeltaUpgrade( targetVersion, oldBinaryPath, destPath, - offline + offline, + setMessage ) : await resolveStableDelta( targetVersion, oldBinaryPath, destPath, - offline + offline, + setMessage ); if (result) { @@ -977,13 +982,41 @@ async function tryLoadCachedChain( async function applyChainAndReturn( chain: PatchChain, oldBinaryPath: string, - destPath: string + destPath: string, + setMessage?: SetMessage ): Promise { - const sha256 = await withTracing( - "apply-patch-chain", - "upgrade.delta.apply", - () => applyPatchChain(chain, oldBinaryPath, destPath) + // Progress for the apply phase. The `onBytes` callback fires for every + // output byte of every hop — intermediate in-memory hops AND the final disk + // write — so the total must be the SUM of all hops' output sizes (each + // patch's declared `newSize`), not just the final binary size. Using only + // the last patch's size would make a multi-hop bar hit 100% after hop 1 and + // then freeze. Feeds the surrounding spinner via setMessage — cosmetic, a + // render failure never aborts the apply. + let totalBytes: number | null = 0; + try { + for (const p of chain.patches) { + totalBytes += parsePatchHeader(p.data).newSize; + } + } catch { + // Header parse is best-effort for the bar; a corrupt header is rejected + // properly downstream. Leave the bar indeterminate in that case. + totalBytes = null; + } + const progress = makeByteProgress( + `Applying ${chain.patches.length} patch(es)`, + totalBytes, + setMessage ); + + let sha256: string; + try { + sha256 = await withTracing("apply-patch-chain", "upgrade.delta.apply", () => + applyPatchChain(chain, oldBinaryPath, destPath, progress.onProgress) + ); + } finally { + progress.done(); + } + return { sha256, patchBytes: chain.totalSize, @@ -1002,6 +1035,8 @@ type ResolveAndApplyOpts = { channel: string; /** When true, skip the network fallback — only use cached patches */ offline?: boolean; + /** Spinner message setter for apply-phase progress (from withProgress) */ + setMessage?: SetMessage; }; /** @@ -1021,6 +1056,7 @@ async function resolveAndApplyDelta( resolveFromNetwork, channel, offline, + setMessage, } = opts; // Check patch cache first — enables fully offline upgrades const cached = await tryLoadCachedChain(CLI_VERSION, targetVersion); @@ -1029,7 +1065,12 @@ async function resolveAndApplyDelta( log.debug( `Using cached patches: ${cached.patches.length} patch(es), ${formatBytes(cached.totalSize)} total` ); - return await applyChainAndReturn(cached, oldBinaryPath, destPath); + return await applyChainAndReturn( + cached, + oldBinaryPath, + destPath, + setMessage + ); } // In offline mode, skip the network resolution entirely — if the cache @@ -1051,7 +1092,7 @@ async function resolveAndApplyDelta( return null; } - return await applyChainAndReturn(chain, oldBinaryPath, destPath); + return await applyChainAndReturn(chain, oldBinaryPath, destPath, setMessage); } /** @@ -1062,11 +1103,13 @@ async function resolveAndApplyDelta( * * @returns Delta result with SHA-256 and size info, or null if delta is unavailable */ +// biome-ignore lint/nursery/useMaxParams: established 4-param shape; setMessage is a defaulted spinner-progress extension export function resolveStableDelta( targetVersion: string, oldBinaryPath: string, destPath: string, - offline?: boolean + offline?: boolean, + setMessage?: SetMessage ): Promise { return resolveAndApplyDelta({ targetVersion, @@ -1078,6 +1121,7 @@ export function resolveStableDelta( ), channel: "stable", offline, + setMessage, }); } @@ -1089,11 +1133,13 @@ export function resolveStableDelta( * * @returns Delta result with SHA-256 and size info, or null if delta is unavailable */ +// biome-ignore lint/nursery/useMaxParams: established 4-param shape; setMessage is a defaulted spinner-progress extension export function resolveNightlyDelta( targetVersion: string, oldBinaryPath: string, destPath: string, - offline?: boolean + offline?: boolean, + setMessage?: SetMessage ): Promise { return resolveAndApplyDelta({ targetVersion, @@ -1102,6 +1148,7 @@ export function resolveNightlyDelta( resolveFromNetwork: () => resolveNightlyChainWithContext(targetVersion), channel: "nightly", offline, + setMessage, }); } @@ -1178,7 +1225,8 @@ async function resolveNightlyChainWithContext( export function applyPatchChain( chain: PatchChain, oldBinaryPath: string, - destPath: string + destPath: string, + onBytes?: (bytes: number) => void ): Promise { return withTracingSpan( "apply-patches", @@ -1197,7 +1245,8 @@ export function applyPatchChain( const sha256 = await applyPatchChainInMemory( oldBinaryPath, chain.patches.map((p) => p.data), - destPath + destPath, + onBytes ); // Verify the final SHA-256 matches diff --git a/src/lib/progress.ts b/src/lib/progress.ts new file mode 100644 index 0000000000..e7000673b7 --- /dev/null +++ b/src/lib/progress.ts @@ -0,0 +1,100 @@ +/** + * Byte-driven progress reporting for long-running upgrade phases (patch apply, + * full-binary download). + * + * sentry upgrade already runs under `withProgress`, which animates a spinner + * and passes down a `setMessage(text)` callback. To avoid two competing + * in-place redraws fighting over the same terminal line, this helper does NOT + * draw its own bar — it formats a compact progress string and pushes it into + * that `setMessage` callback, so the byte counter rides on the existing spinner. + * + * Design contract: + * - Cosmetic ONLY — a formatting/callback failure must never abort the work. + * - Determinate ("152 MB / 310 MB [====> ] 49%") when a byte `total` is given; + * an indeterminate byte counter ("38 MB") otherwise (the decompressed + * download size isn't known ahead of time). + * - Updates are throttled so a fast byte stream doesn't spam the spinner. + */ + +import { formatBytes } from "./formatters/numbers.js"; + +/** Callback that sets the surrounding spinner's message text. */ +export type SetMessage = (message: string) => void; + +export type ByteProgress = { + /** Report `bytes` additional bytes processed since the last call. */ + onProgress: (bytes: number) => void; + /** Emit a final message reflecting the total processed (best-effort). */ + done: () => void; +}; + +const BAR_WIDTH = 16; +/** Minimum gap between spinner message updates. */ +const THROTTLE_MS = 100; + +function renderBar(frac: number, width = BAR_WIDTH): string { + const filled = Math.max(0, Math.min(width, Math.round(width * frac))); + return "█".repeat(filled) + "░".repeat(width - filled); +} + +/** + * Create a byte-progress reporter that feeds a spinner `setMessage` callback. + * + * @param label - Short label prefix (e.g. "Applying 3 patch(es)"). + * @param totalBytes - Expected total bytes; `null` renders an indeterminate + * byte counter instead of a bar. + * @param setMessage - Spinner message setter (from `withProgress`). When + * undefined (JSON mode / non-TTY / no surrounding spinner), this is a no-op + * so nothing is drawn. + * @param nowMs - Injectable clock for tests. + */ +export function makeByteProgress( + label: string, + totalBytes: number | null, + setMessage?: SetMessage, + nowMs: () => number = Date.now +): ByteProgress { + let written = 0; + let lastEmit = 0; + + const format = (): string => { + if (totalBytes === null || totalBytes <= 0) { + return `${label} ${formatBytes(written)}`; + } + const frac = Math.min(written / totalBytes, 1); + const pct = Math.round(frac * 100); + return ( + `${label} [${renderBar(frac)}] ` + + `${formatBytes(written)} / ${formatBytes(totalBytes)} (${pct}%)` + ); + }; + + const emit = (): void => { + // Cosmetic only — a formatting or callback failure must never propagate. + try { + setMessage?.(format()); + } catch { + // ignore — progress is cosmetic + } + }; + + const onProgress = (bytes: number): void => { + written += bytes; + if (!setMessage) { + return; + } + const now = nowMs(); + if (now - lastEmit < THROTTLE_MS) { + return; + } + lastEmit = now; + emit(); + }; + + // Emit a final, un-throttled message so the last state is always shown. + const done = (): void => { + emit(); + }; + + return { onProgress, done }; +} diff --git a/src/lib/upgrade.ts b/src/lib/upgrade.ts index d15f036e9f..a56bb98a6a 100644 --- a/src/lib/upgrade.ts +++ b/src/lib/upgrade.ts @@ -50,6 +50,7 @@ import { } from "./ghcr.js"; import { logger } from "./logger.js"; import { clearPatchCache } from "./patch-cache.js"; +import { makeByteProgress, type SetMessage } from "./progress.js"; /** Scoped logger for upgrade operations */ const log = logger.withTag("upgrade"); @@ -574,22 +575,34 @@ export type DownloadResult = { */ async function streamDecompressToFile( body: ReadableStream, - destPath: string + destPath: string, + setMessage?: SetMessage ): Promise { const stream = body.pipeThrough(new DecompressionStream("gzip")); const writer = createWriteStream(destPath); + // Indeterminate byte counter: the decompressed size isn't known ahead of + // time (Content-Length covers only the compressed stream), so we show a live + // byte count rather than a misleading fraction. Feeds the surrounding + // spinner via setMessage — cosmetic, never aborts. + const progress = makeByteProgress("Downloading", null, setMessage); // Capture write errors early — without a listener, Node crashes with // ERR_UNHANDLED_ERROR if a write fails (ENOSPC, EIO, etc.) during the loop. let writeError: Error | undefined; writer.on("error", (err) => { writeError ??= err; }); + + // Track the original streaming error so a later writer.end() rejection can't + // mask it: an exception thrown from a finally overwrites a pending try + // exception. We rethrow the ORIGINAL error preferentially. + let streamError: unknown; try { for await (const chunk of stream) { if (writeError) { break; } const ok = writer.write(chunk); + progress.onProgress(chunk.byteLength); if (!(ok || writeError)) { // Race drain against error — an I/O failure (ENOSPC) while the // buffer is full would never emit 'drain', causing a hang. @@ -608,7 +621,16 @@ async function streamDecompressToFile( }); } } + } catch (err) { + streamError = err; } finally { + progress.done(); + } + + // Always flush/close the writer. If the stream already failed, surface THAT + // error (the root cause) and demote any end() rejection to a debug log so it + // can't mask the original. + try { await new Promise((resolve, reject) => { writer.end((err?: Error | null) => { const finalErr = err ?? writeError; @@ -619,6 +641,15 @@ async function streamDecompressToFile( } }); }); + } catch (endErr) { + if (streamError === undefined) { + throw endErr; + } + log.debug(`writer.end failed after a stream error: ${String(endErr)}`); + } + + if (streamError !== undefined) { + throw streamError; } } @@ -651,7 +682,8 @@ function getNightlyGzFilename(): string { */ async function downloadNightlyToPath( destPath: string, - version?: string + version?: string, + setMessage?: SetMessage ): Promise { const token = await getAnonymousToken(); const manifest = version @@ -667,7 +699,7 @@ async function downloadNightlyToPath( "GHCR blob response had no body" ); } - await streamDecompressToFile(response.body, destPath); + await streamDecompressToFile(response.body, destPath, setMessage); } /** @@ -683,7 +715,8 @@ async function downloadNightlyToPath( */ async function downloadStableToPath( version: string, - destPath: string + destPath: string, + setMessage?: SetMessage ): Promise { const url = getBinaryDownloadUrl(version); const headers = getGitHubHeaders(); @@ -696,7 +729,7 @@ async function downloadStableToPath( "GitHub" ); if (gzResponse.ok && gzResponse.body) { - await streamDecompressToFile(gzResponse.body, destPath); + await streamDecompressToFile(gzResponse.body, destPath, setMessage); return; } } catch { @@ -823,7 +856,8 @@ async function waitForBinaryVisible(path: string): Promise { export async function downloadBinaryToTemp( version: string, downloadTag?: string, - offline?: OfflineMode + offline?: OfflineMode, + setMessage?: SetMessage ): Promise { const { tempPath, lockPath } = getCurlInstallPaths(); @@ -839,7 +873,12 @@ export async function downloadBinaryToTemp( // Try delta upgrade first — downloads tiny patches instead of full binary. // Falls back to full download on any failure (missing patches, hash mismatch, etc.) - const deltaResult = await tryDeltaUpgrade(version, tempPath, !!offline); + const deltaResult = await tryDeltaUpgrade( + version, + tempPath, + !!offline, + setMessage + ); let patchBytes: number | undefined; if (deltaResult) { patchBytes = deltaResult.patchBytes; @@ -854,7 +893,7 @@ export async function downloadBinaryToTemp( ); } else { log.debug("Downloading full binary"); - await downloadFullBinary(version, downloadTag, tempPath); + await downloadFullBinary(version, downloadTag, tempPath, setMessage); } // Verify the download produced a real, non-empty file before the caller @@ -898,13 +937,15 @@ export async function downloadBinaryToTemp( async function tryDeltaUpgrade( version: string, destPath: string, - offline?: boolean + offline?: boolean, + setMessage?: SetMessage ): Promise { return await attemptDeltaUpgrade( version, process.execPath, destPath, - offline + offline, + setMessage ); } @@ -918,12 +959,13 @@ async function tryDeltaUpgrade( async function downloadFullBinary( version: string, downloadTag: string | undefined, - destPath: string + destPath: string, + setMessage?: SetMessage ): Promise { if (isNightlyVersion(version)) { - await downloadNightlyToPath(destPath, version); + await downloadNightlyToPath(destPath, version, setMessage); } else { - await downloadStableToPath(downloadTag ?? version, destPath); + await downloadStableToPath(downloadTag ?? version, destPath, setMessage); } } @@ -1028,15 +1070,17 @@ function executeUpgradePackageManager( * @returns Download result with paths (curl), or null (package manager) * @throws {UpgradeError} When method is unknown or installation fails */ +// biome-ignore lint/nursery/useMaxParams: established 4-param shape; setMessage is a defaulted spinner-progress extension export async function executeUpgrade( method: InstallationMethod, version: string, downloadTag?: string, - offline?: OfflineMode + offline?: OfflineMode, + setMessage?: SetMessage ): Promise { switch (method) { case "curl": - return downloadBinaryToTemp(version, downloadTag, offline); + return downloadBinaryToTemp(version, downloadTag, offline, setMessage); case "brew": await executeUpgradeHomebrew(); return null; diff --git a/test/lib/bspatch.test.ts b/test/lib/bspatch.test.ts index 1d10bbb0c4..6e4cd59330 100644 --- a/test/lib/bspatch.test.ts +++ b/test/lib/bspatch.test.ts @@ -287,6 +287,38 @@ describe("applyPatchChainInMemory", () => { } }); + test("onBytes reports every hop's output — total = sum of all newSizes", async () => { + // The progress callback fires for the output bytes of EVERY hop (the + // in-memory intermediate AND the final disk write), so a multi-hop total + // must be the sum of all hops' newSize, not just the final binary's. + // (Guards the delta-upgrade progress-bar total; a last-hop-only total + // would freeze the bar at 100% after hop 1.) + const oldBytes = makeBytes(1, 4096); + const midBytes = makeBytes(2, 4096); + const newBytes = makeBytes(3, 4096); + const p1 = buildDiffOnlyPatch(oldBytes, midBytes); + const p2 = buildDiffOnlyPatch(midBytes, newBytes); + + const oldPath = tempFile("old-ob.bin"); + const destPath = tempFile("out-ob.bin"); + await writeFile(oldPath, oldBytes); + + try { + let reported = 0; + await applyPatchChainInMemory(oldPath, [p1, p2], destPath, (n) => { + reported += n; + }); + // Two hops, each emitting 4096 output bytes. + expect(reported).toBe(midBytes.length + newBytes.length); + } finally { + for (const p of [oldPath, destPath]) { + if (existsSync(p)) { + unlinkSync(p); + } + } + } + }); + test("single-element chain matches the on-disk patcher on a real fixture", async () => { // Exercises the fd-backed reader against a real zig-bsdiff patch whose // control entries include diff, extra, and seek operations. diff --git a/test/lib/progress.test.ts b/test/lib/progress.test.ts new file mode 100644 index 0000000000..901cc8ee8d --- /dev/null +++ b/test/lib/progress.test.ts @@ -0,0 +1,119 @@ +/** + * Unit tests for the byte-driven upgrade progress reporter. + * + * The reporter is cosmetic-only and must never abort the operation it + * decorates. It feeds a `setMessage` callback (the surrounding withProgress + * spinner) rather than drawing its own bar, so there's no second in-place + * redraw competing with the spinner. + * + * Coverage: determinate vs indeterminate formatting, byte accumulation, + * full-bar clamping, update throttling, a final un-throttled done() emit, the + * no-op path when no setMessage is provided, and the never-throws contract. + */ + +import { describe, expect, test, vi } from "vitest"; + +import { makeByteProgress } from "../../src/lib/progress.js"; + +describe("makeByteProgress", () => { + test("formats a determinate bar with size and percent", () => { + const msgs: string[] = []; + let now = 0; + const p = makeByteProgress( + "Applying 3 patch(es)", + 1000, + (m) => msgs.push(m), + () => now + ); + p.onProgress(500); // first call: now=0, lastEmit=0 → throttled (0-0 < 100) + now = 200; + p.onProgress(500); // now past throttle → emits at 1000/1000 + const last = msgs.at(-1) ?? ""; + expect(last).toContain("Applying 3 patch(es)"); + expect(last).toContain("1000 B / 1000 B"); + expect(last).toContain("100%"); + expect(last).toContain("█".repeat(16)); + }); + + test("formats an indeterminate byte counter when total is null", () => { + const msgs: string[] = []; + let now = 0; + const p = makeByteProgress( + "Downloading", + null, + (m) => msgs.push(m), + () => now + ); + now = 200; + p.onProgress(2048); + const last = msgs.at(-1) ?? ""; + expect(last).toContain("Downloading"); + expect(last).toContain("2.0 KB"); + expect(last).not.toContain("░"); // no bar in indeterminate mode + }); + + test("accumulates bytes across calls and clamps the bar at full", () => { + const msgs: string[] = []; + let now = 0; + const p = makeByteProgress( + "Applying", + 100, + (m) => msgs.push(m), + () => now + ); + p.onProgress(50); + now = 500; + p.onProgress(9000); // way over total → clamp to 100% + const last = msgs.at(-1) ?? ""; + expect(last).toContain("100%"); + expect(last).toContain("█".repeat(16)); + expect(last).not.toContain("░"); + }); + + test("throttles updates so a fast byte stream doesn't spam the spinner", () => { + const set = vi.fn(); + const now = 1000; + const p = makeByteProgress("Applying", 1000, set, () => now); + // Many calls within the same throttle window → at most one emit. + for (let i = 0; i < 50; i++) { + p.onProgress(10); + } + expect(set.mock.calls.length).toBeLessThanOrEqual(1); + }); + + test("done() emits a final, un-throttled message reflecting the total", () => { + const set = vi.fn(); + const now = 0; + const p = makeByteProgress("Applying", 100, set, () => now); + p.onProgress(100); // throttled (now-0 < 100), no emit yet + set.mockClear(); + p.done(); // must emit regardless of throttle + expect(set).toHaveBeenCalledTimes(1); + expect(set.mock.calls[0]?.[0]).toContain("100%"); + }); + + test("is a no-op when no setMessage is provided (JSON/non-TTY)", () => { + // Nothing to assert beyond: it must not throw and must still track bytes + // so a later done() with a setMessage-less reporter is harmless. + const p = makeByteProgress("Applying", 100); + expect(() => { + p.onProgress(50); + p.done(); + }).not.toThrow(); + }); + + test("never throws even if setMessage throws", () => { + const p = makeByteProgress( + "Applying", + 100, + () => { + throw new Error("boom"); + }, + () => 1000 + ); + expect(() => { + p.onProgress(100); + p.done(); + }).not.toThrow(); + }); +});