Files
clean-architecture-frontend…/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts
T
DongHyeonkaandClaude Opus 5.5 09402478d6 perf(file-transfer): share byte-bucket, integer and control-character guards (Q-B)
Identical private copies lived in both file adapters and in five
browser-transfer modules. One copy each now lives next to isValidByteLength
in the browser-file-storage port (outside every reference-runtime source
root, so it adds no namespace export):
- byteBucket (browser-files/file-observer, presigned/http-common) ->
  browserDataByteBucket; both modules re-export it under the old name
- positiveSafeInteger / nonNegativeSafeInteger (checkpoint-schema,
  http-control-plane-adapter, runtime-policy, upload-byte-source,
  image-cdn-policy, browser-image-probe, file-policy's isPositiveSafeInteger)
  -> isPositiveSafeInteger / isNonNegativeSafeInteger
- hasControlCharacters (image-cdn-policy) and
  hasForbiddenHeaderValueCharacter (fetch-json-transport) -> hasControlCharacter

Same predicates, same results for every input.

file-transfer reference runtime: 55306 -> 55154 gzip bytes.
offline-indexeddb: 35957 -> 35951. realtime, service-worker-pwa unchanged.

Verified: check:architecture, check:types:app, check:types:test, lint,
test:unit, test:component, check:adapter-inventory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 14:49:19 +09:00

204 lines
6.2 KiB
TypeScript

import type {
ResumableUploadCheckpoint,
UploadFileFingerprint,
UploadPartDescriptor,
UploadPartReceipt,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
isNonNegativeSafeInteger as nonNegativeSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export const SAFE_UPLOAD_KEY = /^[A-Za-z0-9][A-Za-z0-9._~:-]{7,127}$/u;
export const SAFE_REGISTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
export const SAFE_OPAQUE_ID = /^[A-Za-z0-9_-]{8,512}$/u;
/**
* R-1.2. The one grammar the presigned layer applies to the IDs a capability
* binds (session, resource, idempotency key, capability receipt). A superset
* of SAFE_OPAQUE_ID, so an ID the control plane accepted is never refused
* later in the same transfer.
*/
export const SAFE_TRANSFER_ID = /^[A-Za-z0-9_-][A-Za-z0-9._:-]{0,511}$/u;
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
const RECEIPT_TOKEN =
/^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/u;
export const MEDIA_TYPE =
/^[a-z0-9!#$&^_.+-]{1,63}\/[a-z0-9!#$&^_.+-]{1,63}$/u;
const CHECKPOINT_KEYS = Object.freeze([
"schemaVersion",
"protocol",
"revision",
"state",
"uploadKey",
"requestBindingSha256",
"fingerprint",
"sessionId",
"sessionExpiresAtEpochMs",
"sessionMaxConcurrency",
"acceptedParts",
"updatedAtEpochMs",
] as const);
const FINGERPRINT_KEYS = Object.freeze([
"algorithm",
"digestHex",
"byteLength",
"partSizeBytes",
"partCount",
] as const);
const PART_KEYS = Object.freeze([
"partNumber",
"offset",
"byteLength",
"checksumSha256",
] as const);
const RECEIPT_KEYS = Object.freeze([...PART_KEYS, "receiptToken"] as const);
export function isUploadFileFingerprint(
value: unknown,
): value is UploadFileFingerprint {
if (!exactRecord(value, FINGERPRINT_KEYS)) return false;
return (
value.algorithm === "SHA-256-PARTS-V1" &&
typeof value.digestHex === "string" &&
SHA256_HEX.test(value.digestHex) &&
positiveSafeInteger(value.byteLength) &&
positiveSafeInteger(value.partSizeBytes) &&
positiveSafeInteger(value.partCount) &&
Math.ceil(value.byteLength / value.partSizeBytes) ===
value.partCount
);
}
function isUploadPartDescriptor(
value: unknown,
): value is UploadPartDescriptor {
if (!exactRecord(value, PART_KEYS)) return false;
return (
positiveSafeInteger(value.partNumber) &&
nonNegativeSafeInteger(value.offset) &&
positiveSafeInteger(value.byteLength) &&
typeof value.checksumSha256 === "string" &&
SHA256_HEX.test(value.checksumSha256)
);
}
export function isUploadPartReceipt(
value: unknown,
): value is UploadPartReceipt {
return (
exactRecord(value, RECEIPT_KEYS) &&
isUploadPartDescriptor({
partNumber: value.partNumber,
offset: value.offset,
byteLength: value.byteLength,
checksumSha256: value.checksumSha256,
}) &&
typeof value.receiptToken === "string" &&
isSafeUploadReceiptToken(value.receiptToken)
);
}
export function isSafeUploadReceiptToken(value: string): boolean {
return RECEIPT_TOKEN.test(value) && !value.includes("://");
}
export function isResumableUploadCheckpoint(
value: unknown,
): value is ResumableUploadCheckpoint {
if (!exactRecord(value, CHECKPOINT_KEYS)) return false;
if (
value.schemaVersion !== 1 ||
value.protocol !== RESUMABLE_UPLOAD_PROTOCOL ||
!positiveSafeInteger(value.revision) ||
(value.state !== "ACTIVE" && value.state !== "ABORT_PENDING") ||
typeof value.uploadKey !== "string" ||
!SAFE_UPLOAD_KEY.test(value.uploadKey) ||
typeof value.requestBindingSha256 !== "string" ||
!SHA256_HEX.test(value.requestBindingSha256) ||
!isUploadFileFingerprint(value.fingerprint) ||
typeof value.sessionId !== "string" ||
!SAFE_OPAQUE_ID.test(value.sessionId) ||
!positiveSafeInteger(value.sessionExpiresAtEpochMs) ||
!positiveSafeInteger(value.sessionMaxConcurrency) ||
!Array.isArray(value.acceptedParts) ||
value.acceptedParts.length > value.fingerprint.partCount ||
!nonNegativeSafeInteger(value.updatedAtEpochMs)
) {
return false;
}
let previousPartNumber = 0;
for (const part of value.acceptedParts) {
if (
!isUploadPartReceipt(part) ||
part.partNumber <= previousPartNumber ||
!partMatchesFingerprint(part, value.fingerprint)
) {
return false;
}
previousPartNumber = part.partNumber;
}
return true;
}
function partMatchesFingerprint(
part: UploadPartDescriptor,
fingerprint: UploadFileFingerprint,
): boolean {
if (
part.partNumber < 1 ||
part.partNumber > fingerprint.partCount ||
part.offset !== (part.partNumber - 1) * fingerprint.partSizeBytes
) {
return false;
}
const remaining = fingerprint.byteLength - part.offset;
return (
remaining > 0 &&
part.byteLength === Math.min(fingerprint.partSizeBytes, remaining)
);
}
export function samePart(
left: UploadPartDescriptor,
right: UploadPartDescriptor,
): boolean {
return (
left.partNumber === right.partNumber &&
left.offset === right.offset &&
left.byteLength === right.byteLength &&
left.checksumSha256 === right.checksumSha256
);
}
export function exactRecord<const Keys extends readonly string[]>(
value: unknown,
keys: Keys,
): value is Record<Keys[number], unknown> {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return false;
}
const actual = Object.keys(value).sort();
const expected = [...keys].sort();
return (
actual.length === expected.length &&
actual.every((key, index) => key === expected[index])
);
}
/**
* BT-UP-01. The structural guard must cover every method cleanup will call.
* Admitting a signal without `removeEventListener` turned a `finally` into a
* Promise rejection instead of the typed terminal result.
*/
export function isAbortSignal(value: unknown): value is AbortSignal {
return Boolean(
value &&
typeof value === "object" &&
typeof (value as AbortSignal).aborted === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
}