Files
clean-architecture-frontend…/src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts
T

601 lines
16 KiB
TypeScript

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<ArrayBuffer>;
}>;
export type UploadSourceSnapshot =
| Readonly<{
kind: "FILE_BYTE_SOURCE";
byteLength: number;
stream(
signal: AbortSignal,
): AsyncIterable<BrowserDataResult<Uint8Array>>;
}>
| Readonly<{
kind: "RANGE_READER";
byteLength: number;
readRange(input: Readonly<{
offset: number;
length: number;
signal: AbortSignal;
}>): Promise<BrowserDataResult<Uint8Array>>;
}>;
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<ArrayBuffer> {
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<BrowserDataResult<UploadPartManifest>> {
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<UploadSourceSnapshot, { kind: "RANGE_READER" }>;
part: UploadPartDescriptor;
crypto: UploadCrypto;
signal: AbortSignal;
}>): Promise<BrowserDataResult<Uint8Array>> {
if (input.signal.aborted) {
return browserDataFailure("ABORTED", "UPLOAD_PART");
}
let result: BrowserDataResult<Uint8Array>;
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<BrowserDataResult<Uint8Array>> {
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<BrowserDataResult<string>> {
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<BrowserDataResult<string>> {
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<BrowserDataResult<string>> {
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<Uint8Array>;
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<BrowserDataResult<Uint8Array>>;
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<BrowserDataResult<string>> {
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<never> {
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;
}