fix(browser-transfer): refuse transport byte caps that cannot carry maxPartCount receipts (01-09)

The policy allows 10,000 parts but a 1 MiB request cap overflows near 5,300,
so the upload failed at complete after every part was sent. Given
maxPartCount, the fetch transport now rejects such a combination at
composition using a worst-case receipt size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:36:00 +09:00
co-authored by Claude Opus 5.5
parent 8f65eabadd
commit 1eee2ac580
3 changed files with 125 additions and 3 deletions
@@ -212,6 +212,15 @@ capability는 앞 절의 별도 fixed BFF endpoint를 redirect 금지로 사용
response envelope 및 request/response의 `UPLOAD_PART` binding protocol이
`PRESIGNED_MULTIPART_V1`인지 대조한다.
part 수 상한과 byte cap은 서로 맞아야 한다. complete 요청과 status 응답에는 part
receipt가 모두 들어간다. 조립할 때 runtime 정책의 `maxPartCount`를 전송의
`maxPartCount`로 넘기면, 전송 factory가 최악의 receipt(모든 필드가 문법 최대,
token 512자, part당 691바이트)로 계산해 들어가지 않는 조합을 `TypeError`로
거절한다(`fetch-json-transport.ts` `MAX_RECEIPT_JSON_BYTES`). 기본값(1,024 part,
요청 1MiB, 응답 2MiB)은 들어간다. 요청 1MiB로는 약 1,500 part, 최대치 4MiB로는
약 6,000 part까지다. 넘기지 않으면 검사하지 않고, 넘치는 upload는 모든 part를
보낸 뒤 complete에서 `LIMIT_EXCEEDED`로 끝난다.
Session은 적어도 opaque ID, protocol version, exact total bytes, media type,
part size, part count, concurrency ceiling, checksum algorithm과 expiry를 묶는다.
part number는 1부터 연속적이어야 하고 마지막 part를 제외한 part length는
@@ -37,6 +37,13 @@ export type ResumableUploadFetchTransportDependencies = Readonly<{
timeoutMs?: number;
maxRequestBytes?: number;
maxResponseBytes?: number;
/**
* 01-09. The runtime policy's `maxPartCount`. When given, the byte limits
* must carry that many worst-case part receipts in a complete request and a
* status response, or composition fails here instead of the upload failing
* at complete after every part was sent.
*/
maxPartCount?: number;
maxRetryAfterMs?: number;
expectedSuccessStatuses?: Partial<
Readonly<Record<ResumableUploadControlOperation, number>>
@@ -63,6 +70,20 @@ const DEFAULT_MAX_REQUEST_BYTES = 1024 * 1024;
const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
const DEFAULT_MAX_RETRY_AFTER_MS = 30_000;
const ABSOLUTE_MAX_JSON_BYTES = 4 * 1024 * 1024;
/**
* 01-09. The most JSON one part receipt can add to a complete request or a
* status response: every field at its grammar maximum, plus a comma.
*/
const MAX_RECEIPT_JSON_BYTES =
JSON.stringify({
partNumber: 10_000,
offset: Number.MAX_SAFE_INTEGER,
byteLength: Number.MAX_SAFE_INTEGER,
checksumSha256: "f".repeat(64),
receiptToken: "r".repeat(512),
}).length + 1;
/** Everything else in either body (IDs up to 512 chars, fingerprint). */
const MAX_ENVELOPE_JSON_BYTES = 4 * 1024;
const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
const OPERATIONS = Object.freeze(
Object.keys(
@@ -133,6 +154,17 @@ export function createResumableUploadFetchJsonTransport(
ABSOLUTE_MAX_JSON_BYTES,
"response bytes",
);
if (input.maxPartCount !== undefined) {
const needed =
MAX_ENVELOPE_JSON_BYTES +
boundedPositiveInteger(input.maxPartCount, 1, 10_000, "part count") *
MAX_RECEIPT_JSON_BYTES;
if (maxRequestBytes < needed || maxResponseBytes < needed) {
throw new TypeError(
"Upload fetch transport byte limits cannot carry maxPartCount receipts.",
);
}
}
const maxRetryAfterMs = boundedPositiveInteger(
input.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS,
1,
@@ -4,10 +4,13 @@ import {
createResumableUploadFetchJsonTransport,
type ResumableUploadFetchTransportDependencies,
} from "../../src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts";
import type {
ResumableUploadControlOperation,
ResumableUploadJsonTransport,
import {
createResumableUploadHttpControlPlane,
type ResumableUploadControlOperation,
type ResumableUploadJsonTransport,
} from "../../src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../src/application/ports/browser-transfer/resumable-upload.ts";
import { browserDataFailure } from "../../src/adapters/browser-file-storage/result.ts";
import { createResumableUploadWebLock } from "../../src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts";
const API_ORIGIN = "https://api.example";
@@ -656,3 +659,81 @@ describe("resumable upload Web Lock", () => {
});
});
});
describe("transport byte limits against the part count (01-09)", () => {
const base = {
endpoints: ENDPOINTS,
allowedOrigins: [API_ORIGIN],
credentials: "same-origin" as const,
fetcher: vi.fn() as unknown as typeof fetch,
};
it("accepts the default limits for the default 1,024-part policy", () => {
expect(() =>
createResumableUploadFetchJsonTransport({ ...base, maxPartCount: 1_024 }),
).not.toThrow();
});
it.each([
["the policy ceiling of 10,000 parts", { maxPartCount: 10_000 }],
[
"a 64 KiB response cap",
{ maxPartCount: 1_024, maxResponseBytes: 64 * 1024 },
],
[
"a 64 KiB request cap",
{ maxPartCount: 1_024, maxRequestBytes: 64 * 1024 },
],
] as const)("refuses %s at composition", (_label, overrides) => {
expect(() =>
createResumableUploadFetchJsonTransport({ ...base, ...overrides }),
).toThrow(TypeError);
});
it("never accepts a request cap below a real worst-case complete body", async () => {
const partCount = 100;
const partSizeBytes = 64 * 1024 * 1024;
let body: unknown;
const controlPlane = createResumableUploadHttpControlPlane({
transport: {
async execute(request) {
body = request.body;
return browserDataFailure("UNAVAILABLE", "UPLOAD_COMPLETE");
},
},
partCapabilities: { issueUploadPart: vi.fn() },
});
await controlPlane.complete({
protocol: RESUMABLE_UPLOAD_PROTOCOL,
sessionId: "s".repeat(512),
requestBindingSha256: "c".repeat(64),
fingerprint: {
algorithm: "SHA-256-PARTS-V1",
digestHex: "d".repeat(64),
byteLength: partCount * partSizeBytes,
partSizeBytes,
partCount,
},
orderedParts: Array.from({ length: partCount }, (_, index) => ({
partNumber: index + 1,
offset: index * partSizeBytes,
byteLength: partSizeBytes,
checksumSha256: "a".repeat(64),
receiptToken: "r".repeat(512),
})),
idempotencyKey: "k".repeat(160),
signal: activeSignal,
});
const bodyBytes = new TextEncoder().encode(JSON.stringify(body)).byteLength;
// The adapter really built the body: every receipt is in it.
expect(bodyBytes).toBeGreaterThan(partCount * 600);
expect(() =>
createResumableUploadFetchJsonTransport({
...base,
maxPartCount: partCount,
maxRequestBytes: bodyBytes - 1,
}),
).toThrow(TypeError);
});
});