@protontech/drive-sdk 0.0.10

package/src/internal/download/fileDownloader.test.ts

@@ -0,0 +1,381 @@
+import { Revision } from '../../interface';
+import { FileDownloader } from './fileDownloader';
+import { DownloadTelemetry } from './telemetry';
+import { DownloadAPIService } from './apiService';
+import { DownloadCryptoService } from './cryptoService';
+import { APIHTTPError, HTTPErrorCode } from '../apiService';
+
+function mockBlockDownload(_: string, token: string, onProgress: (downloadedBytes: number) => void) {
+    const index = parseInt(token.slice(5, 6));
+    const array = new Uint8Array(index);
+    for (let i = 0; i < index; i++) {
+        array[i] = i;
+    }
+
+    onProgress(array.length);
+    return array;
+}
+
+describe('FileDownloader', () => {
+    let telemetry: DownloadTelemetry;
+    let apiService: DownloadAPIService;
+    let cryptoService: DownloadCryptoService;
+    let nodeKey: { key: object; contentKeyPacketSessionKey: string };
+    let revision: Revision;
+
+    beforeEach(() => {
+        // @ts-expect-error No need to implement all methods for mocking
+        telemetry = {
+            getLoggerForRevision: jest.fn().mockReturnValue({
+                debug: jest.fn(),
+                info: jest.fn(),
+                warn: jest.fn(),
+                error: jest.fn(),
+            }),
+            downloadInitFailed: jest.fn(),
+            downloadFailed: jest.fn(),
+            downloadFinished: jest.fn(),
+        };
+        // @ts-expect-error No need to implement all methods for mocking
+        apiService = {
+            iterateRevisionBlocks: jest.fn().mockImplementation(async function* () {
+                yield { type: 'manifestSignature', armoredManifestSignature: 'manifestSignature' };
+                yield { type: 'thumbnail', base64sha256Hash: 'aGFzaDA=' };
+                yield { type: 'block', index: 1, bareUrl: 'url', token: 'token1', base64sha256Hash: 'aGFzaDE=' };
+                yield { type: 'block', index: 2, bareUrl: 'url', token: 'token2', base64sha256Hash: 'aGFzaDI=' };
+                yield { type: 'block', index: 3, bareUrl: 'url', token: 'token3', base64sha256Hash: 'aGFzaDM=' };
+            }),
+            getRevisionBlockToken: jest.fn().mockImplementation(async (_, blockIndex: number) => ({
+                index: blockIndex,
+                bareUrl: 'url',
+                token: `token${blockIndex}-refreshed`,
+                base64sha256Hash: `hash${blockIndex}`,
+            })),
+            // By default, return a block of length equal to the index number.
+            downloadBlock: jest.fn().mockImplementation(mockBlockDownload),
+        };
+        // @ts-expect-error No need to implement all methods for mocking
+        cryptoService = {
+            getRevisionKeys: jest.fn().mockImplementation(async () => ({
+                key: 'privateKey',
+                contentKeyPacketSessionKey: 'contentSessionKey',
+                verificationKeys: 'verificationKeys',
+            })),
+            decryptBlock: jest.fn().mockImplementation(async (encryptedBlock) => encryptedBlock),
+            verifyBlockIntegrity: jest.fn().mockResolvedValue(undefined),
+            verifyManifest: jest.fn().mockResolvedValue(undefined),
+        };
+
+        nodeKey = {
+            key: { _idx: 32131 },
+            contentKeyPacketSessionKey: 'sessionKey',
+        };
+
+        revision = {
+            uid: 'revisionUid',
+            claimedSize: 1024,
+        } as Revision;
+    });
+
+    describe('writeToStream', () => {
+        let onProgress: (downloadedBytes: number) => void;
+        let onFinish: () => void;
+
+        let downloader: FileDownloader;
+        let writer: WritableStreamDefaultWriter<Uint8Array>;
+        let stream: WritableStream<Uint8Array>;
+
+        const verifySuccess = async (
+            fileProgress: number = 6, // 3 blocks of length 1, 2, 3
+        ) => {
+            const controller = downloader.writeToStream(stream, onProgress);
+            await controller.completion();
+
+            expect(apiService.iterateRevisionBlocks).toHaveBeenCalledWith('revisionUid', undefined);
+            expect(cryptoService.verifyManifest).toHaveBeenCalledTimes(1);
+            expect(writer.close).toHaveBeenCalledTimes(1);
+            expect(writer.abort).not.toHaveBeenCalled();
+            expect(telemetry.downloadFinished).toHaveBeenCalledTimes(1);
+            expect(telemetry.downloadFinished).toHaveBeenCalledWith('revisionUid', fileProgress);
+            expect(telemetry.downloadFailed).not.toHaveBeenCalled();
+            expect(onFinish).toHaveBeenCalledTimes(1);
+        }
+
+        const verifyFailure = async (error: string, downloadedBytes: number | undefined) => {
+            const controller = downloader.writeToStream(stream, onProgress);
+
+            await expect(controller.completion()).rejects.toThrow(error);
+
+            expect(apiService.iterateRevisionBlocks).toHaveBeenCalledWith('revisionUid', undefined);
+            expect(writer.close).not.toHaveBeenCalled();
+            expect(writer.abort).toHaveBeenCalledTimes(1);
+            expect(telemetry.downloadFinished).not.toHaveBeenCalled();
+            expect(telemetry.downloadFailed).toHaveBeenCalledTimes(1);
+            expect(telemetry.downloadFailed).toHaveBeenCalledWith(
+                'revisionUid',
+                new Error(error),
+                downloadedBytes === undefined ? expect.anything() : downloadedBytes,
+                revision.claimedSize,
+            );
+            expect(onFinish).toHaveBeenCalledTimes(1);
+        };
+
+        const verifyOnProgress = async (downloadedBytes: number[]) => {
+            expect(onProgress).toHaveBeenCalledTimes(downloadedBytes.length);
+            for (let i = 0; i < downloadedBytes.length; i++) {
+                expect(onProgress).toHaveBeenNthCalledWith(i + 1, downloadedBytes[i]);
+            }
+        };
+
+        beforeEach(() => {
+            onProgress = jest.fn();
+            onFinish = jest.fn();
+
+            // @ts-expect-error Mocking WritableStreamDefaultWriter
+            writer = {
+                write: jest.fn(),
+                close: jest.fn(),
+                abort: jest.fn(),
+            }
+            // @ts-expect-error Mocking WritableStream
+            stream = {
+                getWriter: () => writer,
+            }
+            downloader = new FileDownloader(telemetry, apiService, cryptoService, nodeKey as any, revision, undefined, onFinish);
+        });
+
+        it('should reject two download starts', async () => {
+            downloader.writeToStream(stream, onProgress);
+            expect(() => downloader.writeToStream(stream, onProgress)).toThrow('Download already started');
+            expect(() => downloader.unsafeWriteToStream(stream, onProgress)).toThrow('Download already started');
+        });
+
+        it('should start a download and write to the stream', async () => {
+            await verifySuccess();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(3);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(3);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            await verifyOnProgress([1, 2, 3]);
+        });
+
+        // Use over MAX_DOWNLOAD_BLOCK_SIZE blocks to test that the downloader is not stuck in a loop.
+        it('should start a download and write to the stream with random order', async () => {
+            let count = 0;
+            // Keep first block with high timeout to make sure it is not finished first.
+            const timeouts = [90, 50, 40, 80, 70, 60, 30, 20, 10, 90, 10];
+
+            apiService.iterateRevisionBlocks = jest.fn().mockImplementation(async function* () {
+                yield { type: 'manifestSignature', armoredManifestSignature: 'manifestSignature' };
+                yield { type: 'thumbnail', base64sha256Hash: 'aGFzaDA=' };
+                yield { type: 'block', index: 1, bareUrl: 'url', token: 'token1', base64sha256Hash: 'aGFzaDE=' };
+                yield { type: 'block', index: 2, bareUrl: 'url', token: 'token2', base64sha256Hash: 'aGFzaDI=' };
+                yield { type: 'block', index: 3, bareUrl: 'url', token: 'token3', base64sha256Hash: 'aGFzaDM=' };
+                yield { type: 'block', index: 4, bareUrl: 'url', token: 'token1', base64sha256Hash: 'aGFzaDE=' };
+                yield { type: 'block', index: 5, bareUrl: 'url', token: 'token2', base64sha256Hash: 'aGFzaDI=' };
+                yield { type: 'block', index: 6, bareUrl: 'url', token: 'token3', base64sha256Hash: 'aGFzaDM=' };
+                yield { type: 'block', index: 7, bareUrl: 'url', token: 'token1', base64sha256Hash: 'aGFzaDE=' };
+                yield { type: 'block', index: 8, bareUrl: 'url', token: 'token2', base64sha256Hash: 'aGFzaDI=' };
+                yield { type: 'block', index: 9, bareUrl: 'url', token: 'token3', base64sha256Hash: 'aGFzaDM=' };
+                yield { type: 'block', index: 10, bareUrl: 'url', token: 'token1', base64sha256Hash: 'aGFzaDE=' };
+                yield { type: 'block', index: 11, bareUrl: 'url', token: 'token2', base64sha256Hash: 'aGFzaDI=' };
+            })
+            apiService.downloadBlock = jest.fn().mockImplementation(async function (bareUrl, token, onProgress) {
+                await new Promise(resolve => setTimeout(resolve, timeouts[count++]));
+                return mockBlockDownload(bareUrl, token, onProgress);
+            });
+
+            await verifySuccess(21); // Progress is 1 + 2 + 3 + 1 + 2 + 3 + 1 + 2 + 3 + 1 + 2 = 21
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(11);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(11);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(11);
+            expect(writer.write).toHaveBeenNthCalledWith(1, new Uint8Array([0]));
+            expect(writer.write).toHaveBeenNthCalledWith(2, new Uint8Array([0, 1]));
+            expect(writer.write).toHaveBeenNthCalledWith(3, new Uint8Array([0, 1, 2]));
+            expect(writer.write).toHaveBeenNthCalledWith(4, new Uint8Array([0]));
+            expect(writer.write).toHaveBeenNthCalledWith(5, new Uint8Array([0, 1]));
+            expect(writer.write).toHaveBeenNthCalledWith(6, new Uint8Array([0, 1, 2]));
+            expect(writer.write).toHaveBeenNthCalledWith(7, new Uint8Array([0]));
+            expect(writer.write).toHaveBeenNthCalledWith(8, new Uint8Array([0, 1]));
+            expect(writer.write).toHaveBeenNthCalledWith(9, new Uint8Array([0, 1, 2]));
+            expect(writer.write).toHaveBeenNthCalledWith(10, new Uint8Array([0]));
+            expect(writer.write).toHaveBeenNthCalledWith(11, new Uint8Array([0, 1]));
+        });
+
+        it('should handle failure when iterating blocks', async () => {
+            apiService.iterateRevisionBlocks = jest.fn().mockImplementation(async function* () {
+                throw new Error('Failed to iterate blocks');
+            });
+
+            await verifyFailure('Failed to iterate blocks', 0);
+        });
+
+        it('should handle failure when downloading block', async () => {
+            apiService.downloadBlock = jest.fn().mockImplementation(async function () {
+                throw new Error('Failed to download block');
+            });
+
+            await verifyFailure('Failed to download block', 0);
+        });
+
+        it('should handle one time-off failure when downloading block', async () => {
+            let count = 0;
+            apiService.downloadBlock = jest.fn().mockImplementation(async function (bareUrl, token, onProgress) {
+                if (count === 0) {
+                    count++;
+                    onProgress?.(1); // Simulate the failure happens after some progress.
+                    throw new Error('Failed to download block');
+                }
+                return mockBlockDownload(bareUrl, token, onProgress);
+            });
+
+            await verifySuccess();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(4);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(3);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            await verifyOnProgress([1, -1, 1, 2, 3]);
+        });
+
+        it('should handle expired token when downloading block', async () => {
+            let count = 0;
+            apiService.downloadBlock = jest.fn().mockImplementation(async function (bareUrl, token, onProgress) {
+                if (count === 0) {
+                    count++;
+                    throw new APIHTTPError('Expired token', HTTPErrorCode.NOT_FOUND);
+                }
+                return mockBlockDownload(bareUrl, token, onProgress);
+            });
+
+            await verifySuccess();
+            expect(apiService.getRevisionBlockToken).toHaveBeenCalledTimes(1);
+            expect(apiService.getRevisionBlockToken).toHaveBeenCalledWith('revisionUid', 1, undefined);
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(4);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(3);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            await verifyOnProgress([1, 2, 3]);
+        });
+
+        it('should handle failure when veryfing block', async () => {
+            cryptoService.verifyBlockIntegrity = jest.fn().mockImplementation(async function () {
+                throw new Error('Failed to verify block');
+            });
+
+            await verifyFailure('Failed to verify block', undefined);
+        });
+
+        it('should handle one time-off failure when veryfing block', async () => {
+            let count = 0;
+            cryptoService.verifyBlockIntegrity = jest.fn().mockImplementation(async function () {
+                if (count === 0) {
+                    count++;
+                    throw new Error('Failed to verify block');
+                }
+            });
+
+            await verifySuccess();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(4);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(4);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            await verifyOnProgress([1, -1, 1, 2, 3]);
+        });
+
+        it('should handle failure when decrypting block', async () => {
+            cryptoService.decryptBlock = jest.fn().mockImplementation(async function () {
+                throw new Error('Failed to decrypt block');
+            });
+
+            await verifyFailure('Failed to decrypt block', undefined);
+        });
+
+        it('should handle one time-off failure when decrypting block', async () => {
+            let count = 0;
+            cryptoService.decryptBlock = jest.fn().mockImplementation(async function (encryptedBlock) {
+                if (count === 0) {
+                    count++;
+                    throw new Error('Failed to decrypt block');
+                }
+                return encryptedBlock;
+            });
+
+            await verifySuccess();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(4);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(4);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(4);
+            await verifyOnProgress([1, -1, 1, 2, 3]);
+        });
+
+        it('should handle failure when writing to the stream', async () => {
+            writer.write = jest.fn().mockImplementation(async function () {
+                throw new Error('Failed to write data');
+            });
+
+            await verifyFailure('Failed to write data', undefined);
+        });
+
+        it('should handle one time-off failure when writing to the stream', async () => {
+            let count = 0;
+            writer.write = jest.fn().mockImplementation(async function () {
+                if (count === 0) {
+                    count++;
+                    throw new Error('Failed to write data');
+                }
+            });
+
+            await verifySuccess();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(3);
+            expect(cryptoService.verifyBlockIntegrity).toHaveBeenCalledTimes(3);
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            await verifyOnProgress([1, 2, 3]);
+        });
+
+        it('should handle failure when veryfing manifest', async () => {
+            cryptoService.verifyManifest = jest.fn().mockImplementation(async function () {
+                throw new Error('Failed to verify manifest');
+            });
+
+            await verifyFailure('Failed to verify manifest', 6); // All blocks of length 1, 2, 3.
+        });
+    });
+
+    describe('unsafeWriteToStream', () => {
+        let onProgress: (downloadedBytes: number) => void;
+        let onFinish: () => void;
+
+        let downloader: FileDownloader;
+        let writer: WritableStreamDefaultWriter<Uint8Array>;
+        let stream: WritableStream<Uint8Array>;
+
+        beforeEach(() => {
+            onProgress = jest.fn();
+            onFinish = jest.fn();
+
+            // @ts-expect-error Mocking WritableStreamDefaultWriter
+            writer = {
+                write: jest.fn(),
+                close: jest.fn(),
+                abort: jest.fn(),
+            }
+            // @ts-expect-error Mocking WritableStream
+            stream = {
+                getWriter: () => writer,
+            }
+            downloader = new FileDownloader(telemetry, apiService, cryptoService, nodeKey as any, revision, undefined, onFinish);
+        });
+
+        it('should skip verification steps', async () => {
+            const controller = downloader.unsafeWriteToStream(stream, onProgress);
+            await controller.completion();
+
+            expect(apiService.iterateRevisionBlocks).toHaveBeenCalledWith('revisionUid', undefined);
+            expect(cryptoService.verifyManifest).not.toHaveBeenCalled();
+            expect(apiService.downloadBlock).toHaveBeenCalledTimes(3);
+            expect(cryptoService.verifyBlockIntegrity).not.toHaveBeenCalled();
+            expect(cryptoService.decryptBlock).toHaveBeenCalledTimes(3);
+            expect(writer.close).toHaveBeenCalledTimes(1);
+            expect(writer.abort).not.toHaveBeenCalled();
+            expect(telemetry.downloadFinished).toHaveBeenCalledTimes(1);
+            expect(telemetry.downloadFinished).toHaveBeenCalledWith('revisionUid', 6); // 3 blocks of length 1, 2, 3.
+            expect(telemetry.downloadFailed).not.toHaveBeenCalled();
+            expect(onFinish).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/src/internal/download/fileDownloader.ts

@@ -0,0 +1,266 @@
+import { PrivateKey, SessionKey, base64StringToUint8Array } from "../../crypto";
+import { Logger, Revision } from "../../interface";
+import { LoggerWithPrefix } from "../../telemetry";
+import { APIHTTPError, HTTPErrorCode } from '../apiService';
+import { DownloadAPIService } from "./apiService";
+import { DownloadController } from './controller';
+import { DownloadCryptoService } from "./cryptoService";
+import { BlockMetadata, RevisionKeys } from './interface';
+import { DownloadTelemetry } from './telemetry';
+
+/**
+ * Maximum number of blocks that can be downloaded at the same time
+ * for a single file. This is to prevent downloading too many blocks
+ * at the same time and running out of memory.
+ */
+const MAX_DOWNLOAD_BLOCK_SIZE = 10;
+
+export class FileDownloader {
+    private logger: Logger;
+
+    private controller: DownloadController;
+    private nextBlockIndex = 1;
+    private ongoingDownloads = new Map<number, {
+        downloadPromise: Promise<void>,
+        decryptedBufferedBlock?: Uint8Array,
+    }>();
+
+    constructor(
+        private telemetry: DownloadTelemetry,
+        private apiService: DownloadAPIService,
+        private cryptoService: DownloadCryptoService,
+        private nodeKey: { key: PrivateKey, contentKeyPacketSessionKey: SessionKey },
+        private revision: Revision,
+        private signal?: AbortSignal,
+        private onFinish?: () => void,
+    ) {
+        this.telemetry = telemetry;
+        this.logger = telemetry.getLoggerForRevision(revision.uid);
+        this.apiService = apiService;
+        this.cryptoService = cryptoService;
+        this.nodeKey = nodeKey;
+        this.revision = revision;
+        this.signal = signal;
+        this.onFinish = onFinish;
+        this.controller = new DownloadController();
+    }
+
+    getClaimedSizeInBytes(): number | undefined {
+        return this.revision.claimedSize;
+    }
+
+    writeToStream(stream: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController {
+        if (this.controller.promise) {
+            throw new Error(`Download already started`);
+        }
+        this.controller.promise = this.downloadToStream(stream, onProgress);
+        return this.controller;
+    }
+
+    unsafeWriteToStream(stream: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController {
+        if (this.controller.promise) {
+            throw new Error(`Download already started`);
+        }
+        const ignoreIntegrityErrors = true;
+        this.controller.promise = this.downloadToStream(stream, onProgress, ignoreIntegrityErrors);
+        return this.controller;
+    }
+
+    private async downloadToStream(
+        stream: WritableStream,
+        onProgress?: (writtenBytes: number) => void,
+        ignoreIntegrityErrors = false,
+    ): Promise<void> {
+        const writer = stream.getWriter();
+        const cryptoKeys = await this.cryptoService.getRevisionKeys(this.nodeKey, this.revision);
+
+        // File progress is tracked for telemetry - to track at what
+        // point the download failed.
+        let fileProgress = 0;
+
+        // Collection of all block hashes for manifest verification.
+        // This includes both thumbnail and regular blocks.
+        const allBlockHashes: Uint8Array[] = [];
+        let armoredManifestSignature: string | undefined;
+
+        try {
+            this.logger.info(`Starting download`);
+            for await (const blockMetadata of this.apiService.iterateRevisionBlocks(this.revision.uid, this.signal)) {
+                if (blockMetadata.type === 'manifestSignature') {
+                    armoredManifestSignature = blockMetadata.armoredManifestSignature;
+                    continue;
+                }
+
+                allBlockHashes.push(base64StringToUint8Array(blockMetadata.base64sha256Hash));
+                if (blockMetadata.type === 'thumbnail') {
+                    continue;
+                }
+
+                await this.controller.waitWhilePaused();
+
+                const downloadPromise = this.downloadBlock(
+                    blockMetadata,
+                    ignoreIntegrityErrors,
+                    cryptoKeys,
+                    (downloadedBytes) => {
+                        fileProgress += downloadedBytes;
+                        onProgress?.(downloadedBytes);
+                    },
+                );
+                this.ongoingDownloads.set(blockMetadata.index, { downloadPromise });
+
+                await this.waitForDownloadCapacity();
+                await this.flushCompletedBlocks(writer);
+            }
+
+            this.logger.debug(`All blocks downloading, waiting for them to finish`);
+            await Promise.all(this.downloadPromises);
+            await this.flushCompletedBlocks(writer);
+
+            if (this.ongoingDownloads.size > 0) {
+                this.logger.error(`Some blocks were not downloaded: ${this.ongoingDownloads.keys()}`);
+                // This is a bug in the algorithm.
+                throw new Error(`Some blocks were not downloaded`);
+            }
+
+            if (ignoreIntegrityErrors) {
+                this.logger.warn('Skipping manifest check');
+            } else {
+                this.logger.debug(`Verifying manifest`);
+                await this.cryptoService.verifyManifest(this.revision, this.nodeKey.key, allBlockHashes, armoredManifestSignature);
+            }
+
+            await writer.close();
+            void this.telemetry.downloadFinished(this.revision.uid, fileProgress);
+            this.logger.info(`Download succeeded`);
+        } catch (error: unknown) {
+            this.logger.error(`Download failed`, error);
+            void this.telemetry.downloadFailed(this.revision.uid, error, fileProgress, this.getClaimedSizeInBytes());
+            await writer.abort();
+            throw error;
+        } finally {
+            this.logger.debug(`Download cleanup`);
+            this.onFinish?.();
+        }
+    }
+
+    private async downloadBlock(
+        blockMetadata: BlockMetadata,
+        ignoreIntegrityErrors: boolean,
+        cryptoKeys: RevisionKeys,
+        onProgress: (downloadedBytes: number) => void,
+    ) {
+        const logger = new LoggerWithPrefix(this.logger, `block ${blockMetadata.index}`);
+        logger.info(`Download started`);
+
+        let blockProgress = 0;
+        let decryptedBlock: Uint8Array | null = null;
+        let retries = 0;
+
+        while (!decryptedBlock) {
+            logger.debug(`Downloading`);
+            await this.controller.waitWhilePaused();
+            try {
+                const encryptedBlock = await this.apiService.downloadBlock(blockMetadata.bareUrl, blockMetadata.token, (downloadedBytes) => {
+                    blockProgress += downloadedBytes;
+                    onProgress?.(downloadedBytes);
+                }, this.signal);
+
+                if (ignoreIntegrityErrors) {
+                    logger.warn('Skipping hash check');
+                } else {
+                    logger.debug(`Verifying hash`);
+                    await this.cryptoService.verifyBlockIntegrity(encryptedBlock, blockMetadata.base64sha256Hash);
+                }
+
+                logger.debug(`Decrypting`);
+                decryptedBlock = await this.cryptoService.decryptBlock(encryptedBlock, blockMetadata.armoredSignature!, cryptoKeys);
+            } catch (error) {
+                if (blockProgress !== 0) {
+                    onProgress?.(-blockProgress);
+                    blockProgress = 0;
+                }
+
+                if (error instanceof APIHTTPError && error.statusCode === HTTPErrorCode.NOT_FOUND) {
+                    logger.warn(`Token expired, fetching new token and retrying`);
+                    blockMetadata = await this.apiService.getRevisionBlockToken(this.revision.uid, blockMetadata.index, this.signal);
+                    continue;
+                }
+
+                // Download can fail for various reasons, for example integrity
+                // can fail due to bitflips. We want to retry and solve the issue
+                // seamlessly for the user. We retry only once, because we don't
+                // want to get stuck in a loop.
+                if (retries === 0) {
+                    logger.error(`Download failed, retrying`, error);
+                    retries++;
+                    continue;
+                }
+
+                logger.error(`Download failed`, error);
+                throw error;
+            }
+        }
+
+        this.ongoingDownloads.get(blockMetadata.index)!.decryptedBufferedBlock = decryptedBlock;
+        logger.info(`Downloaded`);
+    }
+
+    private async waitForDownloadCapacity() {
+        if (this.ongoingDownloads.size >= MAX_DOWNLOAD_BLOCK_SIZE) {
+            this.logger.info(`Download limit reached, waiting for next block to be finished`);
+
+            // We need to ensure the next block is downloaded, otherwise the
+            // buffer will still be full.
+            while (!this.isNextBlockDownloaded) {
+                // Promise.race never finishes if the passed array is empty.
+                // It shouldn't happen if at least next block is still not downloaded,
+                // also JS is single threaded, so it should be impossible to change
+                // the ongoing downloads in the middle of the loop. It is handled
+                // just in case something is changed that would affect this part
+                // without noticing.
+                const ongoingDownloadPromises = Array.from(this.ongoingDownloadPromises);
+                if (ongoingDownloadPromises.length === 0) {
+                    break;
+                }
+
+                // Promise.race is used to ensure if any block fails, the error is
+                // thrown up the chain and we dont end up in stuck loop here waiting
+                // for the next block to be ready.
+                // We wait only for the ongoing downloads as if we use all promises,
+                // some block can be finished and it would result in inifinite loop.
+                await Promise.race(ongoingDownloadPromises);
+            }
+        }
+    }
+
+    private async flushCompletedBlocks(writer: WritableStreamDefaultWriter<Uint8Array>) {
+        this.logger.debug(`Flushing completed blocks`);
+        while (this.isNextBlockDownloaded) {
+            const decryptedBlock = this.ongoingDownloads.get(this.nextBlockIndex)!.decryptedBufferedBlock!;
+            this.logger.info(`Flushing completed block ${this.nextBlockIndex}`);
+            try {
+                await writer.write(decryptedBlock);
+            } catch (error) {
+                this.logger.error(`Failed to write block, retrying once`, error);
+                await writer.write(decryptedBlock);
+            }
+            this.ongoingDownloads.delete(this.nextBlockIndex);
+            this.nextBlockIndex++;
+        }
+    }
+
+    private get downloadPromises() {
+        return this.ongoingDownloads.values().map(({ downloadPromise }) => downloadPromise);
+    }
+
+    private get ongoingDownloadPromises() {
+        return this.ongoingDownloads.values()
+            .filter((value) => value.decryptedBufferedBlock === undefined)
+            .map((value) => value.downloadPromise);
+    }
+
+    private get isNextBlockDownloaded() {
+        return !!this.ongoingDownloads.get(this.nextBlockIndex)?.decryptedBufferedBlock;
+    }
+}