601 lines
16 KiB
TypeScript
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;
|
|
}
|