From 09402478d69f67156bd7edfc7c6c8e10be8370ec Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 14:44:45 +0900 Subject: [PATCH] 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 --- src/adapters/browser-files/file-observer.ts | 15 +------- src/adapters/browser-files/file-policy.ts | 5 +-- .../image-cdn/browser-image-probe.ts | 7 ++-- .../image-cdn/image-cdn-policy.ts | 22 +++-------- .../browser-transfer/presigned/http-common.ts | 26 ++----------- .../resumable-upload/checkpoint-schema.ts | 12 ++---- .../resumable-upload/fetch-json-transport.ts | 16 +++----- .../http-control-plane-adapter.ts | 12 ++---- .../resumable-upload/runtime-policy.ts | 13 +++---- .../resumable-upload/upload-byte-source.ts | 7 ++-- .../ports/browser-file-storage/shared.ts | 37 +++++++++++++++++++ 11 files changed, 74 insertions(+), 98 deletions(-) diff --git a/src/adapters/browser-files/file-observer.ts b/src/adapters/browser-files/file-observer.ts index d03ac2d5..e2026aa0 100644 --- a/src/adapters/browser-files/file-observer.ts +++ b/src/adapters/browser-files/file-observer.ts @@ -6,6 +6,8 @@ import type { } from "../../application/ports/browser-file-storage/shared.ts"; import { observeBrowserData } from "../browser-file-storage/result.ts"; +export { browserDataByteBucket as byteBucket } from "../../application/ports/browser-file-storage/shared.ts"; + type BrowserFileObservation = Readonly<{ operation: BrowserDataOperation; outcome: "SUCCESS" | "DISMISSED" | "FAILED"; @@ -19,19 +21,6 @@ type BrowserFileObservation = Readonly<{ */ export type BrowserFileObserver = BrowserDataObserver; -export function byteBucket( - byteLength: number | null, -): BrowserFileObservation["byteBucket"] | undefined { - if (byteLength === null || !Number.isSafeInteger(byteLength) || byteLength < 0) { - return undefined; - } - if (byteLength === 0) return "ZERO"; - if (byteLength < 1_048_576) return "LT1MIB"; - if (byteLength < 10_485_760) return "1_TO_9MIB"; - if (byteLength < 104_857_600) return "10_TO_99MIB"; - return "GTE100MIB"; -} - export function observeBrowserFile( observer: BrowserFileObserver | undefined, observation: BrowserFileObservation, diff --git a/src/adapters/browser-files/file-policy.ts b/src/adapters/browser-files/file-policy.ts index 85506b02..988fc285 100644 --- a/src/adapters/browser-files/file-policy.ts +++ b/src/adapters/browser-files/file-policy.ts @@ -52,9 +52,8 @@ export function isSafeGeneratedToken(value: string): boolean { return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value); } -export function isPositiveSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value > 0; -} +export { isPositiveSafeInteger } from "../../application/ports/browser-file-storage/shared.ts"; + const EXTENSION = /^\.[a-z0-9][a-z0-9+_-]{0,15}(?:\.[a-z0-9][a-z0-9+_-]{0,15})?$/i; const POLICY_TOKEN = /^[a-z0-9][a-z0-9._:-]{0,127}$/i; diff --git a/src/adapters/browser-transfer/image-cdn/browser-image-probe.ts b/src/adapters/browser-transfer/image-cdn/browser-image-probe.ts index 62129718..a20a5882 100644 --- a/src/adapters/browser-transfer/image-cdn/browser-image-probe.ts +++ b/src/adapters/browser-transfer/image-cdn/browser-image-probe.ts @@ -12,6 +12,9 @@ import { type AbortTimerSnapshot, } from "../../platform/abortable-operation.ts"; import { parseStaticImageHeaderMetadata } from "./image-header-metadata.ts"; +import { + isPositiveSafeInteger as positiveSafeInteger, +} from "../../../application/ports/browser-file-storage/shared.ts"; export type DecodedImageFacade = Readonly<{ width: number; @@ -685,7 +688,3 @@ function isRasterMediaType( "image/webp", ].includes(value); } - -function positiveSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value > 0; -} diff --git a/src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts b/src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts index 37e93ca6..25f1634d 100644 --- a/src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts +++ b/src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts @@ -4,6 +4,11 @@ import type { ImagePresetReference, ImageRasterMediaType, } from "../../../application/ports/browser-transfer/image-cdn.ts"; +import { + isPositiveSafeInteger as positiveSafeInteger, + isNonNegativeSafeInteger as nonNegativeSafeInteger, + hasControlCharacter, +} from "../../../application/ports/browser-file-storage/shared.ts"; export type ImageCdnOriginPolicy = Readonly<{ originKey: string; @@ -476,7 +481,7 @@ function snapshotPreset( !positiveSafeInteger(input.quality) || input.quality > hardLimits.maxQuality || !SAFE_SIZES.test(input.sizes) || - hasControlCharacters(input.sizes) || + hasControlCharacter(input.sizes) || !["eager", "lazy"].includes(input.loading) || !["async", "sync"].includes(input.decoding) || !["high", "low", "auto"].includes(input.fetchPriority) || @@ -726,14 +731,6 @@ function positiveDpr(value: number): boolean { ); } -function positiveSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value > 0; -} - -function nonNegativeSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value >= 0; -} - function hasExactOwnKeys( input: unknown, keys: readonly string[], @@ -748,10 +745,3 @@ function hasExactOwnKeys( actual.every((key, index) => key === expected[index]) ); } - -function hasControlCharacters(value: string): boolean { - return [...value].some((character) => { - const codePoint = character.codePointAt(0) ?? 0; - return codePoint < 0x20 || codePoint === 0x7f; - }); -} diff --git a/src/adapters/browser-transfer/presigned/http-common.ts b/src/adapters/browser-transfer/presigned/http-common.ts index fda25e82..451d109f 100644 --- a/src/adapters/browser-transfer/presigned/http-common.ts +++ b/src/adapters/browser-transfer/presigned/http-common.ts @@ -9,6 +9,7 @@ import type { BrowserDataRecovery, BrowserDataResult, } from "../../../application/ports/browser-file-storage/shared.ts"; +import { browserDataByteBucket as byteBucket } from "../../../application/ports/browser-file-storage/shared.ts"; import type { Result } from "../../../contracts/result.ts"; import { browserDataFailure, @@ -21,6 +22,8 @@ import { * near-identical copies whose status table had already drifted apart. */ +export { byteBucket }; + /** BT-PRE-03. The scope ended before the task settled. */ export const SCOPE_ENDED = Symbol("presigned-scope-ended"); @@ -236,29 +239,6 @@ export function isAbortSignal(value: unknown): value is AbortSignal { } } -export function byteBucket( - byteLength: number | undefined, -): - | "ZERO" - | "LT1MIB" - | "1_TO_9MIB" - | "10_TO_99MIB" - | "GTE100MIB" - | undefined { - if ( - byteLength === undefined || - !Number.isSafeInteger(byteLength) || - byteLength < 0 - ) { - return undefined; - } - if (byteLength === 0) return "ZERO"; - if (byteLength < 1_048_576) return "LT1MIB"; - if (byteLength < 10_485_760) return "1_TO_9MIB"; - 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. diff --git a/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts b/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts index 6311f51a..89ee3d40 100644 --- a/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts +++ b/src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts @@ -5,6 +5,10 @@ import type { 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; @@ -183,14 +187,6 @@ export function exactRecord( ); } -function positiveSafeInteger(value: unknown): value is number { - return Number.isSafeInteger(value) && (value as number) > 0; -} - -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 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 6e5fe041..427f6bc2 100644 --- a/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts +++ b/src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts @@ -2,9 +2,10 @@ import type { UploadProviderFailure, UploadProviderResult, } from "../../../application/ports/browser-transfer/resumable-upload.ts"; -import type { - BrowserDataFailureCode, - BrowserDataRecovery, +import { + hasControlCharacter, + type BrowserDataFailureCode, + type BrowserDataRecovery, } from "../../../application/ports/browser-file-storage/shared.ts"; import { browserDataFailure, @@ -343,7 +344,7 @@ function snapshotHeaders( seen.has(name) || typeof header.value !== "string" || header.value.length > 2048 || - hasForbiddenHeaderValueCharacter(header.value) + hasControlCharacter(header.value) ) { throw new TypeError("Upload request header is invalid."); } @@ -731,13 +732,6 @@ function snapshotTransportRequest( } } -function hasForbiddenHeaderValueCharacter(value: string): boolean { - return [...value].some((character) => { - const codePoint = character.codePointAt(0); - return codePoint !== undefined && (codePoint <= 31 || codePoint === 127); - }); -} - function isPlainRecord( value: unknown, ): value is Readonly> { diff --git a/src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts b/src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts index bfd942ef..c5d2dfd7 100644 --- a/src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts +++ b/src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts @@ -30,6 +30,10 @@ import { SAFE_UPLOAD_KEY, SHA256_HEX, } from "./checkpoint-schema.ts"; +import { + isPositiveSafeInteger as positiveSafeInteger, + isNonNegativeSafeInteger as nonNegativeSafeInteger, +} from "../../../application/ports/browser-file-storage/shared.ts"; export type ResumableUploadControlOperation = | "CREATE_SESSION" @@ -679,11 +683,3 @@ function safeIdempotencyKey(value: string): boolean { /^[A-Za-z0-9._~-]+$/u.test(value) ); } - -function positiveSafeInteger(value: unknown): value is number { - return Number.isSafeInteger(value) && (value as number) > 0; -} - -function nonNegativeSafeInteger(value: unknown): value is number { - return Number.isSafeInteger(value) && (value as number) >= 0; -} diff --git a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts index 57838b75..9ced011a 100644 --- a/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts +++ b/src/adapters/browser-transfer/resumable-upload/runtime-policy.ts @@ -1,3 +1,8 @@ +import { + isPositiveSafeInteger as positiveSafeInteger, + isNonNegativeSafeInteger as nonNegativeSafeInteger, +} from "../../../application/ports/browser-file-storage/shared.ts"; + export type ResumableUploadRuntimePolicy = Readonly<{ partSizeBytes: number; maxFileBytes: number; @@ -116,11 +121,3 @@ export function resolveResumableUploadRuntimePolicy( } return policy; } - -function positiveSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value > 0; -} - -function nonNegativeSafeInteger(value: number): boolean { - return Number.isSafeInteger(value) && value >= 0; -} diff --git a/src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts b/src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts index e2cecfeb..852d4551 100644 --- a/src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts +++ b/src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts @@ -13,6 +13,9 @@ import { browserDataSuccess, } from "../../browser-file-storage/result.ts"; import { samePart } from "./checkpoint-schema.ts"; +import { + isPositiveSafeInteger as positiveSafeInteger, +} from "../../../application/ports/browser-file-storage/shared.ts"; export type UploadCrypto = Readonly<{ digestSha256(bytes: Uint8Array): Promise; @@ -594,7 +597,3 @@ function remapFailure( }), }); } - -function positiveSafeInteger(value: unknown): value is number { - return Number.isSafeInteger(value) && (value as number) > 0; -} diff --git a/src/application/ports/browser-file-storage/shared.ts b/src/application/ports/browser-file-storage/shared.ts index 38448744..0a83b2b7 100644 --- a/src/application/ports/browser-file-storage/shared.ts +++ b/src/application/ports/browser-file-storage/shared.ts @@ -183,6 +183,43 @@ export function isValidByteLength(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; } +export function isNonNegativeSafeInteger(value: unknown): value is number { + return Number.isSafeInteger(value) && (value as number) >= 0; +} + +/** True when `value` carries a C0 control character or DEL. */ +export function hasControlCharacter(value: string): boolean { + return [...value].some((character) => { + const codePoint = character.codePointAt(0) ?? 0; + return codePoint < 0x20 || codePoint === 0x7f; + }); +} + +export function isPositiveSafeInteger(value: unknown): value is number { + return Number.isSafeInteger(value) && (value as number) > 0; +} + +/** + * The observation bucket for a byte length. An absent, fractional, negative or + * unsafe length has no bucket, so an observation never reports a guessed size. + */ +export function browserDataByteBucket( + byteLength: number | null | undefined, +): BrowserDataObservation["byteBucket"] { + if ( + byteLength === null || + byteLength === undefined || + !isValidByteLength(byteLength) + ) { + return undefined; + } + if (byteLength === 0) return "ZERO"; + if (byteLength < 1_048_576) return "LT1MIB"; + if (byteLength < 10_485_760) return "1_TO_9MIB"; + if (byteLength < 104_857_600) return "10_TO_99MIB"; + return "GTE100MIB"; +} + export function assertValidStoragePolicy( policy: BrowserStoragePolicy, ): void {