Function downloadBookFile

packages/core/src/sync/sync-files.ts:1238–1372

(
  backend: ISyncBackend,
  bookId: string,
  filePath: string,
  onProgress?: (progress: { downloaded: number; total: number }) => void,
)

 * pushed (and therefore not yet migrated) can still serve the book.
 */
export async function downloadBookFile(
  backend: ISyncBackend,
  bookId: string,
  filePath: string,
  onProgress?: (progress: { downloaded: number; total: number }) => void,
): Promise<DownloadBookOutcome> {
  const adapter = getSyncAdapter();
  const { setBookSyncStatus } = await import("../db/database");

  try {
    const ext = getExt(filePath) || "epub";

    // Resolve book title for new-path computation.
    const db = await getDB();
    const rows = await db.select<{ id: string; title: string }>(
      "SELECT id, title FROM books WHERE id = ?",
      [bookId],
    );
    const book = rows[0] ?? null;

    const newPath = book ? buildBookRemoteFile(book, ext) : "";
    const legacyPath = `${REMOTE_FILES}/${bookId}.${ext}`;

    onProgress?.({ downloaded: 0, total: 100 });

    // Track whether *every* failure we saw was a 404. If so, the remote
    // genuinely doesn't have the file. If at least one attempt failed with
    // some other error, it's an "error" outcome — the caller can retry.
    let sawNon404Error = false;
    const noteFailure = (e: unknown) => {
      const msg = (e as { message?: string })?.message ?? "";
      if (!/404|not found/i.test(msg)) sawNon404Error = true;
    };

    const appDataDir = await adapter.getAppDataDir();
    const localPath = isAbsoluteOrProtocolPath(filePath)
      ? filePath
      : adapter.joinPath(appDataDir, filePath);
    const reportDownloadProgress = (loaded: number, total: number) => {
      if (total > 0) onProgress?.({ downloaded: loaded, total });
    };
    let downloaded = false;
    if (newPath) {
      try {
        await downloadRemoteFileToPath(backend, newPath, localPath, reportDownloadProgress);
        downloaded = true;
        console.log(`[Sync] Downloaded ${newPath} (new layout)`);
      } catch (e) {
        noteFailure(e);
        const msg = (e as { message?: string })?.message ?? "";
        if (!/404|not found/i.test(msg)) {
          console.warn(`[Sync] New-layout fetch failed (${msg}); trying legacy path`);
        }
      }
    }
    if (!downloaded) {
      try {
        await downloadRemoteFileToPath(backend, legacyPath, localPath, reportDownloadProgress);