perf(browser-transfer): reuse one copy of duplicated upload helpers (Q-B)

The resumable-upload runtime and fetch transport carried private copies of
helpers that already exist once in the same adapter or its port:
- the 18-code failure list -> isBrowserDataFailureCode (same list, same order)
- observeTerminal/transferByteBucket -> observeTransferResult, moved from the
  presigned executor into presigned/http-common.ts and also used by the
  capability provider
- cancelResponseBody/cancelReader in the fetch transport -> http-common copies
- the loose isAbortSignal guard (transport + runtime) -> one export in
  checkpoint-schema.ts
- upload-response-validation's exactKeys -> checkpoint-schema's exactRecord

file-transfer reference runtime: 55704 -> 55382 gzip bytes. Other reference
runtimes 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>
This commit is contained in:
DongHyeonka
2026-09-24 14:49:19 +09:00
co-authored by Claude Opus 5.5
parent 07937fa59c
commit cc37f577e3
7 changed files with 73 additions and 163 deletions
@@ -4,10 +4,16 @@ import {
} from "../../platform/abortable-operation.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataOperation,
BrowserDataRecovery,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { browserDataFailure } from "../../browser-file-storage/result.ts";
import type { Result } from "../../../contracts/result.ts";
import {
browserDataFailure,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
/**
* Q-6.1-9. HTTP mechanics shared by the presigned executor (object-store
@@ -252,3 +258,22 @@ export function byteBucket(
if (byteLength < 104_857_600) return "10_TO_99MIB";
return "GTE100MIB";
}
/**
* One terminal observation for presigned and resumable transfers. An absent or
* invalid byte length leaves `byteBucket` out rather than guessing one.
*/
export function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: Result<unknown, Readonly<{ code: BrowserDataFailureCode }>>,
byteLength?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
}
@@ -19,7 +19,6 @@ import type {
import {
browserDataFailure,
browserDataSuccess,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
import type {
PresignedCapabilityRegistration,
@@ -27,12 +26,12 @@ import type {
PresignedHeaderBinding,
} from "./presigned-capability-vault.ts";
import {
byteBucket,
cancelBody,
cancelReader,
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
@@ -176,15 +175,12 @@ export function createPresignedCapabilityHttpProvider(
result: BrowserDataResult<Capability>,
byteLength?: number,
): BrowserDataResult<Capability> {
const bucket = byteBucket(
observeTransferResult(
observer,
"PRESIGNED_TRANSFER",
result,
result.ok ? result.value.byteLength : byteLength,
);
observeBrowserData(observer, {
operation: "PRESIGNED_TRANSFER",
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
return result;
}
@@ -37,6 +37,7 @@ import {
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
@@ -1096,18 +1097,3 @@ function safeInputByteLength(value: unknown): number | undefined {
}
return undefined;
}
function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: BrowserDataResult<unknown>,
byteLength?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
}
@@ -168,7 +168,7 @@ export function samePart(
);
}
function exactRecord<const Keys extends readonly string[]>(
export function exactRecord<const Keys extends readonly string[]>(
value: unknown,
keys: Keys,
): value is Record<Keys[number], unknown> {
@@ -190,3 +190,18 @@ function positiveSafeInteger(value: unknown): value is number {
function nonNegativeSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) >= 0;
}
/**
* 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",
);
}
@@ -19,6 +19,8 @@ import type {
ResumableUploadControlOperation,
ResumableUploadJsonTransport,
} from "./http-control-plane-adapter.ts";
import { cancelBody, cancelReader } from "../presigned/http-common.ts";
import { isAbortSignal } from "./checkpoint-schema.ts";
export type ResumableUploadEndpointMap = Readonly<
Record<ResumableUploadControlOperation, string>
@@ -210,7 +212,7 @@ export function createResumableUploadFetchJsonTransport(
const raced = await attempt.race(
Promise.resolve(fetchPromise),
(late) => {
cancelResponseBody(late);
cancelBody(late);
},
);
if (raced.kind !== "VALUE") {
@@ -222,7 +224,7 @@ export function createResumableUploadFetchJsonTransport(
response.type === "opaqueredirect" ||
!sameUrl(response.url, endpoint)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"POLICY_REJECTED",
operation,
@@ -237,11 +239,11 @@ export function createResumableUploadFetchJsonTransport(
maxRetryAfterMs,
safeNowEpochMs(),
);
cancelResponseBody(response);
cancelBody(response);
return failed;
}
if (!jsonContentType(response.headers.get("content-type"))) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"CORRUPT_DATA",
operation,
@@ -414,7 +416,7 @@ async function readBoundedJson(
(!/^(0|[1-9][0-9]*)$/u.test(contentLength) ||
Number(contentLength) > maxBytes)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"LIMIT_EXCEEDED",
operation,
@@ -635,28 +637,6 @@ function attemptFailure(
: failure("UNAVAILABLE", operation, true, "RESUME");
}
function cancelResponseBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Response cancellation is best effort after closed classification.
});
} catch {
// A cancellation failure cannot change the already classified result.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Reader cancellation is best effort after closed classification.
});
} catch {
// A cancellation failure cannot change the already classified result.
}
}
function releaseReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
@@ -721,21 +701,6 @@ function boundedPositiveInteger(
return value;
}
/**
* 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.
*/
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",
);
}
function isControlOperation(
value: unknown,
): value is ResumableUploadControlOperation {
@@ -14,18 +14,21 @@ import type {
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataOperation,
BrowserDataRecovery,
BrowserDataResult,
TransferProgress,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { isBrowserDataFailureCode } from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import { observeTransferResult } from "../presigned/http-common.ts";
import {
exactRecord,
isAbortSignal,
isResumableUploadCheckpoint,
isUploadPartReceipt,
MEDIA_TYPE,
@@ -56,7 +59,6 @@ import {
type RuntimeDependencies,
} from "./runtime-dependencies.ts";
import {
exactKeys,
sameFingerprint,
snapshotReceipts,
validatePartCapability,
@@ -107,26 +109,6 @@ type ActiveResolution =
upload: QuarantinedUpload;
}>;
const FAILURE_CODES: ReadonlySet<string> = new Set([
"ABORTED",
"BLOCKED",
"CONFLICT",
"CORRUPT_DATA",
"EXPIRED_RESOURCE",
"INTEGRITY_FAILED",
"INVALID_INPUT",
"LIMIT_EXCEEDED",
"MIGRATION_FAILED",
"NOT_FOUND",
"NOT_READABLE",
"PERMISSION_DENIED",
"POLICY_REJECTED",
"QUOTA_EXCEEDED",
"STALE_RESULT",
"STORAGE_EVICTED",
"UNAVAILABLE",
"UNSUPPORTED",
]);
const RECOVERIES: ReadonlySet<string> = new Set([
"NONE",
"RETRY",
@@ -824,7 +806,7 @@ async function transferMissingParts<Capability>(
part,
bytes.value,
);
observeTerminal(
observeTransferResult(
dependencies.observer,
"UPLOAD_PART",
uploaded,
@@ -887,7 +869,7 @@ async function transferMissingParts<Capability>(
part,
verified.value,
);
observeTerminal(
observeTransferResult(
dependencies.observer,
"UPLOAD_PART",
uploaded,
@@ -1093,7 +1075,7 @@ async function completeUpload<Capability>(
if (!completed.ok) return stripProviderFailure(completed);
const value = completed.value;
if (
!exactKeys(value, [
!exactRecord(value, [
"state",
"protocol",
"sessionId",
@@ -1208,7 +1190,7 @@ async function executeAbort<Capability>(
return stripProviderFailure(aborted);
}
if (
!exactKeys(aborted.value, ["state"]) ||
!exactRecord(aborted.value, ["state"]) ||
![
"ABORTED",
"NOT_FOUND",
@@ -1271,12 +1253,12 @@ async function callWithRetry<Capability, Value>(
action,
);
if (result.ok) {
observeTerminal(dependencies.observer, operation, result);
observeTransferResult(dependencies.observer, operation, result);
return result;
}
lastFailure = result.error;
if (!canRetry(result.error, attempt, dependencies.policy)) {
observeTerminal(dependencies.observer, operation, result);
observeTransferResult(dependencies.observer, operation, result);
return result;
}
}
@@ -1291,7 +1273,7 @@ async function callWithRetry<Capability, Value>(
"RESUME",
),
}) as UploadProviderResult<Value>;
observeTerminal(dependencies.observer, operation, exhausted);
observeTransferResult(dependencies.observer, operation, exhausted);
return exhausted;
}
@@ -1517,7 +1499,7 @@ function normalizeProviderFailure(
if (
!input ||
typeof input !== "object" ||
!FAILURE_CODES.has(input.code) ||
!isBrowserDataFailureCode(input.code) ||
typeof input.retryable !== "boolean" ||
!RECOVERIES.has(input.recovery) ||
(input.retryAfterMs !== undefined &&
@@ -1608,40 +1590,6 @@ function reportProgress(
}
}
function observeTerminal<Value>(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: BrowserDataResult<Value> | UploadProviderResult<Value>,
byteLength?: number,
): void {
try {
observer?.record(
Object.freeze({
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(result.ok ? {} : { failureCode: result.error.code }),
...(byteLength === undefined
? {}
: { byteBucket: transferByteBucket(byteLength) }),
}),
);
} catch {
// Upload correctness is independent from best-effort observation.
}
}
function transferByteBucket(
byteLength: number,
): NonNullable<
Parameters<BrowserDataObserver["record"]>[0]["byteBucket"]
> {
if (byteLength === 0) return "ZERO";
if (byteLength < 1024 * 1024) return "LT1MIB";
if (byteLength < 10 * 1024 * 1024) return "1_TO_9MIB";
if (byteLength < 100 * 1024 * 1024) return "10_TO_99MIB";
return "GTE100MIB";
}
function mapLockFailure(
error: unknown,
operation: BrowserDataOperation,
@@ -1684,14 +1632,3 @@ function combineAbortSignals(
},
});
}
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",
);
}
@@ -17,6 +17,7 @@ import {
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
exactRecord,
isUploadFileFingerprint,
isUploadPartReceipt,
SAFE_OPAQUE_ID,
@@ -41,7 +42,7 @@ export function validatePartCapability<Capability>(
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadPartCapability<Capability>> {
if (
!exactKeys(value, [
!exactRecord(value, [
"capability",
"uploadBindingSha256",
"expiresAtEpochMs",
@@ -85,7 +86,7 @@ export function validateStatus<Capability>(
});
}
if (value.state === "ACTIVE") {
if (!exactKeys(value, ["state", "session", "acceptedParts"])) {
if (!exactRecord(value, ["state", "session", "acceptedParts"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
@@ -127,7 +128,7 @@ export function validateStatus<Capability>(
);
}
if (value.state === "QUARANTINED") {
if (!exactKeys(value, ["state", "session", "resourceId"])) {
if (!exactRecord(value, ["state", "session", "resourceId"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
@@ -165,7 +166,7 @@ export function validateStatus<Capability>(
}
if (
!["ABORTED", "EXPIRED", "NOT_FOUND"].includes(value.state) ||
!exactKeys(value, [
!exactRecord(value, [
"state",
"protocol",
"sessionId",
@@ -197,7 +198,7 @@ export function validateSession<Capability>(
requireActiveExpiry = true,
): BrowserDataResult<UploadSession> {
if (
!exactKeys(value, [
!exactRecord(value, [
"protocol",
"sessionId",
"requestBindingSha256",
@@ -293,18 +294,3 @@ export function snapshotReceipts(
parts.map((part) => Object.freeze({ ...part })),
);
}
export function exactKeys(
value: unknown,
keys: readonly string[],
): value is Record<string, 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])
);
}