diff --git a/src/adapters/browser-transfer/presigned/http-common.ts b/src/adapters/browser-transfer/presigned/http-common.ts index 6c55ffbd..fda25e82 100644 --- a/src/adapters/browser-transfer/presigned/http-common.ts +++ b/src/adapters/browser-transfer/presigned/http-common.ts @@ -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>, + 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 } : {}), + }); +} diff --git a/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts b/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts index d7b5a920..a64ddb6d 100644 --- a/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts +++ b/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts @@ -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, byteLength?: number, ): BrowserDataResult { - 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; } diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index afbf8b3c..8bfba6b4 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -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, - 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 } : {}), - }); -} diff --git a/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts b/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts index 14b1e82d..9c00647a 100644 --- a/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts +++ b/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts @@ -168,7 +168,7 @@ export function samePart( ); } -function exactRecord( +export function exactRecord( value: unknown, keys: Keys, ): value is Record { @@ -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", + ); +} diff --git a/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts b/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts index 8dd4a5d1..6e5fe041 100644 --- a/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts +++ b/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts @@ -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 @@ -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, -): 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, ): 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 { diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index bf8dfe87..ae6b23a4 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -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 = 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 = new Set([ "NONE", "RETRY", @@ -824,7 +806,7 @@ async function transferMissingParts( part, bytes.value, ); - observeTerminal( + observeTransferResult( dependencies.observer, "UPLOAD_PART", uploaded, @@ -887,7 +869,7 @@ async function transferMissingParts( part, verified.value, ); - observeTerminal( + observeTransferResult( dependencies.observer, "UPLOAD_PART", uploaded, @@ -1093,7 +1075,7 @@ async function completeUpload( 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( return stripProviderFailure(aborted); } if ( - !exactKeys(aborted.value, ["state"]) || + !exactRecord(aborted.value, ["state"]) || ![ "ABORTED", "NOT_FOUND", @@ -1271,12 +1253,12 @@ async function callWithRetry( 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( "RESUME", ), }) as UploadProviderResult; - 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( - observer: BrowserDataObserver | undefined, - operation: BrowserDataOperation, - result: BrowserDataResult | UploadProviderResult, - 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[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", - ); -} - diff --git a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts index adc87087..8cd48536 100644 --- a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts +++ b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts @@ -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( dependencies: RuntimeDependencies, ): BrowserDataResult> { if ( - !exactKeys(value, [ + !exactRecord(value, [ "capability", "uploadBindingSha256", "expiresAtEpochMs", @@ -85,7 +86,7 @@ export function validateStatus( }); } 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( ); } 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( } if ( !["ABORTED", "EXPIRED", "NOT_FOUND"].includes(value.state) || - !exactKeys(value, [ + !exactRecord(value, [ "state", "protocol", "sessionId", @@ -197,7 +198,7 @@ export function validateSession( requireActiveExpiry = true, ): BrowserDataResult { 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 { - 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]) - ); -}