import type { ResumableUploadSource, UploadFileFingerprint, UploadPartDescriptor, } from "../../../application/ports/browser-transfer/resumable-upload.ts"; import type { BrowserDataFailure, BrowserDataOperation, BrowserDataResult, } from "../../../application/ports/browser-file-storage/shared.ts"; import { browserDataFailure, browserDataSuccess, } from "../../browser-file-storage/result.ts"; import { samePart } from "./checkpoint-schema.ts"; export type UploadCrypto = Readonly<{ digestSha256(bytes: Uint8Array): Promise; }>; export type UploadSourceSnapshot = | Readonly<{ kind: "FILE_BYTE_SOURCE"; byteLength: number; stream( signal: AbortSignal, ): AsyncIterable>; }> | Readonly<{ kind: "RANGE_READER"; byteLength: number; readRange(input: Readonly<{ offset: number; length: number; signal: AbortSignal; }>): Promise>; }>; export type UploadPartManifest = Readonly<{ fingerprint: UploadFileFingerprint; parts: readonly UploadPartDescriptor[]; }>; export function snapshotUploadSource( source: ResumableUploadSource, ): UploadSourceSnapshot { if (!source || typeof source !== "object") { throw new TypeError("Upload source is invalid."); } if (source.kind === "FILE_BYTE_SOURCE") { const bytes = source.bytes; const stream = bytes?.stream; if ( typeof stream !== "function" || !positiveSafeInteger(bytes.byteLength) ) { throw new TypeError("Upload byte source is invalid."); } return Object.freeze({ kind: "FILE_BYTE_SOURCE" as const, byteLength: bytes.byteLength, stream(signal: AbortSignal) { return stream.call(bytes, signal); }, }); } if (source.kind === "RANGE_READER") { const reader = source.reader; const readRange = reader?.readRange; if ( typeof readRange !== "function" || !positiveSafeInteger(reader.byteLength) ) { throw new TypeError("Upload range source is invalid."); } return Object.freeze({ kind: "RANGE_READER" as const, byteLength: reader.byteLength, async readRange(input) { return await readRange.call(reader, input); }, }); } throw new TypeError("Upload source kind is invalid."); } export function snapshotUploadCrypto(crypto: Crypto): UploadCrypto { const subtle = crypto?.subtle; const digest = subtle?.digest; if (typeof digest !== "function") { throw new TypeError("Upload crypto capability is invalid."); } return Object.freeze({ async digestSha256(bytes: Uint8Array): Promise { return await digest.call( subtle, "SHA-256", Uint8Array.from(bytes), ); }, }); } export async function buildUploadPartManifest(input: Readonly<{ source: UploadSourceSnapshot; partSizeBytes: number; maxPartCount: number; maxSourceChunkBytes: number; crypto: UploadCrypto; signal: AbortSignal; onPreparedBytes?: (bytes: number) => void; }>): Promise> { const parts: UploadPartDescriptor[] = []; let preparedBytes = 0; for await (const partResult of iterateUploadParts({ source: input.source, partSizeBytes: input.partSizeBytes, maxSourceChunkBytes: input.maxSourceChunkBytes, signal: input.signal, operation: "UPLOAD_SESSION", })) { if (!partResult.ok) return partResult; if (parts.length >= input.maxPartCount) { return browserDataFailure("LIMIT_EXCEEDED", "UPLOAD_SESSION"); } const checksum = await digestHex( input.crypto, partResult.value.bytes, input.signal, "UPLOAD_SESSION", ); if (!checksum.ok) return checksum; const descriptor: UploadPartDescriptor = Object.freeze({ partNumber: partResult.value.partNumber, offset: partResult.value.offset, byteLength: partResult.value.bytes.byteLength, checksumSha256: checksum.value, }); parts.push(descriptor); preparedBytes += descriptor.byteLength; try { input.onPreparedBytes?.(preparedBytes); } catch { // Progress observation cannot affect transfer correctness. } } if ( parts.length === 0 || preparedBytes !== input.source.byteLength ) { return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", { recovery: "RESELECT", }); } const canonical = canonicalPartManifest( input.source.byteLength, input.partSizeBytes, parts, ); const fingerprintDigest = await digestHex( input.crypto, canonical, input.signal, "UPLOAD_SESSION", ); if (!fingerprintDigest.ok) return fingerprintDigest; const fingerprint: UploadFileFingerprint = Object.freeze({ algorithm: "SHA-256-PARTS-V1", digestHex: fingerprintDigest.value, byteLength: input.source.byteLength, partSizeBytes: input.partSizeBytes, partCount: parts.length, }); return browserDataSuccess( Object.freeze({ fingerprint, parts: Object.freeze(parts), }), ); } export async function readAndVerifyRangePart(input: Readonly<{ source: Extract; part: UploadPartDescriptor; crypto: UploadCrypto; signal: AbortSignal; }>): Promise> { if (input.signal.aborted) { return browserDataFailure("ABORTED", "UPLOAD_PART"); } let result: BrowserDataResult; try { result = await input.source.readRange({ offset: input.part.offset, length: input.part.byteLength, signal: input.signal, }); } catch { return browserDataFailure("UNAVAILABLE", "UPLOAD_PART", { retryable: true, recovery: "RESUME", }); } if (!result.ok) return remapFailure(result.error, "UPLOAD_PART"); if ( !(result.value instanceof Uint8Array) || result.value.byteLength !== input.part.byteLength ) { return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_PART", { recovery: "RESELECT", }); } const bytes = Uint8Array.from(result.value); const checksum = await digestHex( input.crypto, bytes, input.signal, "UPLOAD_PART", ); if (!checksum.ok) return checksum; return checksum.value === input.part.checksumSha256 ? browserDataSuccess(bytes) : browserDataFailure("STALE_RESULT", "UPLOAD_PART", { recovery: "RESELECT", }); } export async function verifyUploadPartBytes(input: Readonly<{ bytes: Uint8Array; part: UploadPartDescriptor; crypto: UploadCrypto; signal: AbortSignal; }>): Promise> { if ( !(input.bytes instanceof Uint8Array) || input.bytes.byteLength !== input.part.byteLength ) { return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_PART", { recovery: "RESELECT", }); } const bytes = Uint8Array.from(input.bytes); const checksum = await digestHex( input.crypto, bytes, input.signal, "UPLOAD_PART", ); if (!checksum.ok) return checksum; return checksum.value === input.part.checksumSha256 ? browserDataSuccess(bytes) : browserDataFailure("STALE_RESULT", "UPLOAD_PART", { recovery: "RESELECT", }); } export async function digestRequestBinding(input: Readonly<{ uploadKey: string; purpose: string; mediaType: string; fingerprint: UploadFileFingerprint; crypto: UploadCrypto; signal: AbortSignal; }>): Promise> { const canonical = new TextEncoder().encode( [ "RESUMABLE-UPLOAD-BINDING-V1", input.uploadKey, input.purpose, input.mediaType, input.fingerprint.algorithm, input.fingerprint.digestHex, String(input.fingerprint.byteLength), String(input.fingerprint.partSizeBytes), String(input.fingerprint.partCount), ].join("\n"), ); return await digestHex( input.crypto, canonical, input.signal, "UPLOAD_SESSION", ); } export async function deriveUploadIdempotencyKey(input: Readonly<{ label: "CREATE" | "PART" | "COMPLETE" | "ABORT"; requestBindingSha256: string; sessionId?: string; part?: UploadPartDescriptor; crypto: UploadCrypto; signal: AbortSignal; }>): Promise> { const fields = [ "RESUMABLE-UPLOAD-IDEMPOTENCY-V1", input.label, input.requestBindingSha256, input.sessionId ?? "-", ]; if (input.part) { fields.push( String(input.part.partNumber), String(input.part.offset), String(input.part.byteLength), input.part.checksumSha256, ); } const digest = await digestHex( input.crypto, new TextEncoder().encode(fields.join("\n")), input.signal, input.label === "PART" ? "UPLOAD_PART" : input.label === "COMPLETE" ? "UPLOAD_COMPLETE" : input.label === "ABORT" ? "UPLOAD_ABORT" : "UPLOAD_SESSION", ); return digest.ok ? browserDataSuccess(`upload-${input.label.toLowerCase()}-${digest.value}`) : digest; } export async function digestUploadSessionBinding(input: Readonly<{ requestBindingSha256: string; sessionId: string; fingerprint: UploadFileFingerprint; crypto: UploadCrypto; signal: AbortSignal; }>): Promise> { return await digestHex( input.crypto, new TextEncoder().encode( [ "RESUMABLE-UPLOAD-SESSION-BINDING-V1", input.requestBindingSha256, input.sessionId, input.fingerprint.algorithm, input.fingerprint.digestHex, String(input.fingerprint.byteLength), String(input.fingerprint.partSizeBytes), String(input.fingerprint.partCount), ].join("\n"), ), input.signal, "UPLOAD_PART", ); } export async function* iterateUploadParts(input: Readonly<{ source: UploadSourceSnapshot; partSizeBytes: number; maxSourceChunkBytes: number; signal: AbortSignal; operation: "UPLOAD_SESSION" | "UPLOAD_PART"; }>): AsyncIterable< BrowserDataResult< Readonly<{ partNumber: number; offset: number; bytes: Uint8Array; }> > > { if (input.source.kind === "RANGE_READER") { let partNumber = 1; for ( let offset = 0; offset < input.source.byteLength; offset += input.partSizeBytes ) { if (input.signal.aborted) { yield browserDataFailure("ABORTED", input.operation); return; } const length = Math.min( input.partSizeBytes, input.source.byteLength - offset, ); let result: BrowserDataResult; try { result = await input.source.readRange({ offset, length, signal: input.signal, }); } catch { yield browserDataFailure("UNAVAILABLE", input.operation, { retryable: true, recovery: "RESUME", }); return; } if (!result.ok) { yield remapFailure(result.error, input.operation); return; } if ( !(result.value instanceof Uint8Array) || result.value.byteLength !== length ) { yield browserDataFailure("INTEGRITY_FAILED", input.operation, { recovery: "RESELECT", }); return; } yield browserDataSuccess( Object.freeze({ partNumber, offset, bytes: Uint8Array.from(result.value), }), ); partNumber += 1; } return; } let iterable: AsyncIterable>; try { iterable = input.source.stream(input.signal); } catch { yield browserDataFailure("UNAVAILABLE", input.operation, { retryable: true, recovery: "RESUME", }); return; } let partNumber = 1; let offset = 0; let totalBytes = 0; let buffer = new Uint8Array(input.partSizeBytes); let bufferedBytes = 0; try { for await (const chunkResult of iterable) { if (input.signal.aborted) { yield browserDataFailure("ABORTED", input.operation); return; } if (!chunkResult.ok) { yield remapFailure(chunkResult.error, input.operation); return; } const chunk = chunkResult.value; if ( !(chunk instanceof Uint8Array) || chunk.byteLength < 1 || chunk.byteLength > input.maxSourceChunkBytes || totalBytes + chunk.byteLength > input.source.byteLength ) { yield browserDataFailure( chunk instanceof Uint8Array && chunk.byteLength > input.maxSourceChunkBytes ? "LIMIT_EXCEEDED" : "INTEGRITY_FAILED", input.operation, { recovery: "RESELECT" }, ); return; } let position = 0; while (position < chunk.byteLength) { const length = Math.min( buffer.byteLength - bufferedBytes, chunk.byteLength - position, ); buffer.set(chunk.subarray(position, position + length), bufferedBytes); position += length; bufferedBytes += length; totalBytes += length; if (bufferedBytes === buffer.byteLength) { yield browserDataSuccess( Object.freeze({ partNumber, offset, bytes: buffer, }), ); offset += buffer.byteLength; partNumber += 1; buffer = new Uint8Array(input.partSizeBytes); bufferedBytes = 0; } } } } catch { yield browserDataFailure("UNAVAILABLE", input.operation, { retryable: true, recovery: "RESUME", }); return; } if (totalBytes !== input.source.byteLength) { yield browserDataFailure("INTEGRITY_FAILED", input.operation, { recovery: "RESELECT", }); return; } if (bufferedBytes > 0) { yield browserDataSuccess( Object.freeze({ partNumber, offset, bytes: buffer.slice(0, bufferedBytes), }), ); } } export function findManifestPart( manifest: UploadPartManifest, partNumber: number, ): UploadPartDescriptor | null { return manifest.parts[partNumber - 1] ?? null; } export function verifyPartAgainstManifest( part: UploadPartDescriptor, manifest: UploadPartManifest, ): boolean { const expected = findManifestPart(manifest, part.partNumber); return Boolean(expected && samePart(part, expected)); } async function digestHex( crypto: UploadCrypto, bytes: Uint8Array, signal: AbortSignal, operation: BrowserDataOperation, ): Promise> { if (signal.aborted) { return browserDataFailure("ABORTED", operation); } try { const digest = new Uint8Array(await crypto.digestSha256(bytes)); if (signal.aborted) { return browserDataFailure("ABORTED", operation); } if (digest.byteLength !== 32) { return browserDataFailure("UNAVAILABLE", operation, { retryable: true, recovery: "RESUME", }); } return browserDataSuccess( Array.from( digest, (byte) => byte.toString(16).padStart(2, "0"), ).join(""), ); } catch { return browserDataFailure("UNAVAILABLE", operation, { retryable: true, recovery: "RESUME", }); } } function canonicalPartManifest( byteLength: number, partSizeBytes: number, parts: readonly UploadPartDescriptor[], ): Uint8Array { return new TextEncoder().encode( [ "SHA-256-PARTS-V1", String(byteLength), String(partSizeBytes), String(parts.length), ...parts.map((part) => [ part.partNumber, part.offset, part.byteLength, part.checksumSha256, ].join(":"), ), ].join("\n"), ); } function remapFailure( failure: BrowserDataFailure, operation: BrowserDataOperation, ): BrowserDataResult { return Object.freeze({ ok: false, error: Object.freeze({ code: failure.code, operation, retryable: failure.retryable, recovery: failure.recovery, }), }); } function positiveSafeInteger(value: unknown): value is number { return Number.isSafeInteger(value) && (value as number) > 0; }