chore: sync the frontend template from ebea300 to af3d8e6

Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
@@ -9,6 +9,12 @@ import { CREDENTIAL_HEADER_NAMES } from "../../contracts/rest-profiles.ts";
export type ExternalSessionOwner = Readonly<{
readState(): SessionState;
/**
* Required. Opaque, stable per-user id, never a token (OIDC `sub`, Supabase
* `session.user.id`, Firebase `user.uid`); `null` when nobody is signed in.
* See `SessionGateway.getSubject` for what a missing subject costs.
*/
readSubject(): string | null;
subscribe(listener: () => void): () => void;
beginSignIn(returnTo?: string): Promise<void>;
signOut(): Promise<void>;
@@ -35,6 +41,8 @@ export function validateCredentialPatch(value: unknown): CredentialPatch {
for (const [name, headerValue] of Object.entries(headers)) {
const normalizedName = name.toLowerCase();
if (
// Names that differ only in case would silently overwrite each other.
Object.hasOwn(projected, normalizedName) ||
!ALLOWED_CREDENTIAL_HEADERS.has(normalizedName) ||
typeof headerValue !== "string" ||
headerValue.length === 0 ||
@@ -53,6 +61,7 @@ export function createExternalAuthSessionAdapter(
): AuthSessionPort {
return Object.freeze({
getState: () => owner.readState(),
getSubject: () => owner.readSubject(),
subscribe: (listener) => owner.subscribe(listener),
beginSignIn: (returnTo) => owner.beginSignIn(returnTo),
signOut: () => owner.signOut(),
@@ -77,6 +86,7 @@ const EMPTY_PATCH = Object.freeze({ headers: Object.freeze({}) });
export function createAnonymousSessionAdapter(): AuthSessionPort {
return createExternalAuthSessionAdapter({
readState: () => "unauthenticated",
readSubject: () => null,
subscribe: () => () => {},
beginSignIn: async () => {},
signOut: async () => {},
@@ -101,6 +111,9 @@ const DEMO_PATCH = Object.freeze({
headers: Object.freeze({ authorization: DEMO_AUTHORIZATION_MARKER }),
});
/** The one demo user. A stable subject lets a re-notification keep the cache. */
const DEMO_SUBJECT = "demo-user";
export function createDemoSessionAdapter(
initialState: SessionState = "unauthenticated",
demoPatch: CredentialPatch = DEMO_PATCH,
@@ -109,11 +122,15 @@ export function createDemoSessionAdapter(
let state = initialState;
const listeners = new Set<() => void>();
const setState = (next: SessionState) => {
// A notification means "the session changed"; repeating the same value
// would make every subscriber redo its work for nothing.
if (next === state) return;
state = next;
for (const listener of listeners) listener();
};
return Object.freeze({
getState: () => state,
getSubject: () => (state === "authenticated" ? DEMO_SUBJECT : null),
subscribe(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
@@ -140,6 +157,7 @@ export function createDemoSessionAdapter(
export function createUnavailableSessionAdapter(): AuthSessionPort {
return Object.freeze({
getState: () => "integration-failed",
getSubject: () => null,
subscribe: () => () => {},
beginSignIn: async () => {},
signOut: async () => {},
@@ -40,6 +40,12 @@ export function abortedResult(
: null;
}
/**
* The table for File, Storage Manager, Cache Storage and download DOM errors.
* IndexedDB errors use `mapIndexedDbException` below: the same exception name
* means something else there (a `NotFoundError` is a missing store, not a
* missing file).
*/
export function mapBrowserDataException(
error: unknown,
operation: BrowserDataOperation,
@@ -89,6 +95,81 @@ export function mapBrowserDataException(
}
}
function exceptionName(error: unknown): string {
if (
error &&
typeof error === "object" &&
"name" in error &&
typeof error.name === "string"
) {
return error.name;
}
return "";
}
/**
* 05-11. The one table for native IndexedDB errors. It lives in this kernel
* exception file so the OPFS journal no longer reaches into the IndexedDB
* runtime's folder for it. It maps the closed DOMException vocabulary without
* exposing an exception object, message, key or stored value across the
* adapter boundary.
*
* Differences from `mapBrowserDataException`, on purpose: a missing store or
* index, an inactive or read-only transaction and a `VersionError` are schema
* problems (`MIGRATION_FAILED`, READ_ONLY), not a missing file or a transient
* failure; quota and constraint failures are not retried blindly.
*/
export function mapIndexedDbException(
error: unknown,
operation: BrowserDataOperation,
): BrowserDataResult<never> {
switch (exceptionName(error)) {
case "AbortError":
return browserDataFailure("ABORTED", operation);
case "ConstraintError":
return browserDataFailure("CONFLICT", operation);
case "DataCloneError":
case "DataError":
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "READ_ONLY",
});
case "InvalidAccessError":
case "InvalidStateError":
case "NotFoundError":
case "ReadOnlyError":
case "TransactionInactiveError":
case "VersionError":
return browserDataFailure("MIGRATION_FAILED", operation, {
recovery: "READ_ONLY",
});
case "NotAllowedError":
case "SecurityError":
return browserDataFailure("PERMISSION_DENIED", operation, {
recovery: "ONLINE_ONLY",
});
case "NotReadableError":
return browserDataFailure("NOT_READABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
case "QuotaExceededError":
case "NS_ERROR_DOM_QUOTA_REACHED":
return browserDataFailure("QUOTA_EXCEEDED", operation, {
recovery: "READ_ONLY",
});
case "UnknownError":
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
default:
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
});
}
}
export function observeBrowserData(
observer: BrowserDataObserver | undefined,
observation: BrowserDataObservation,
@@ -8,6 +8,7 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "./result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
export type StorageManagerFacade = Readonly<{
estimate(): Promise<Readonly<{ usage?: number; quota?: number }>>;
@@ -155,48 +156,22 @@ function snapshotPressurePolicy(
return snapshot;
}
/**
* The kernel race: a caller abort ends the wait, and a native call that settles
* afterwards — including one that rejects — is consumed rather than leaked.
*/
async function awaitStorageInspection<Value>(
inspection: Promise<Value>,
signal: AbortSignal | undefined,
): Promise<Value | typeof STORAGE_INSPECTION_ABORTED> {
if (!signal) return await inspection;
if (signal.aborted) {
// The native calls have already been invoked. Consume a later rejection
// even though the caller no longer waits for their result.
void inspection.catch(() => undefined);
return STORAGE_INSPECTION_ABORTED;
const operation = createAbortableOperation({ signal });
try {
const raced = await operation.race(inspection);
if (raced.kind === "REJECTED") throw raced.reason;
return raced.kind === "VALUE" ? raced.value : STORAGE_INSPECTION_ABORTED;
} finally {
operation.close();
}
return await new Promise<Value | typeof STORAGE_INSPECTION_ABORTED>(
(resolve, reject) => {
let settled = false;
const finish = (
outcome:
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "ERROR"; error: unknown }>,
): void => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
if (outcome.kind === "VALUE") {
resolve(outcome.value);
} else if (outcome.kind === "ABORTED") {
resolve(STORAGE_INSPECTION_ABORTED);
} else {
reject(outcome.error);
}
};
const onAbort = (): void => finish({ kind: "ABORTED" });
signal.addEventListener("abort", onAbort, { once: true });
inspection.then(
(value) => finish({ kind: "VALUE", value }),
(error: unknown) => finish({ kind: "ERROR", error }),
);
if (signal.aborted) onAbort();
},
);
}
async function inspectPersistenceState(
+106 -106
View File
@@ -23,6 +23,7 @@ import {
} from "./file-observer.ts";
import type { RegisteredFileSelectionPolicy } from "./file-policy.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
type UserActivationState = Readonly<{ isActive: boolean }>;
@@ -54,7 +55,8 @@ interface DisposableFilePicker extends FilePickerPort {
/**
* Focus can return before some engines dispatch the file input change event.
* This grace keeps the fallback from misclassifying a real selection as a
* dismissal. The native cancel event remains authoritative and immediate.
* dismissal. The native cancel event remains authoritative and immediate, and
* once a picker has seen it the fallback is no longer installed.
*/
export const DEFAULT_NATIVE_PICKER_FOCUS_GRACE_MS = 1_000;
@@ -97,6 +99,12 @@ export class NativeInputFilePicker implements DisposableFilePicker {
#pending = false;
#disposed = false;
#abortPending: (() => void) | undefined;
/**
* Q-6.2-8. Once this engine has dispatched a native `cancel`, dismissal is
* reported natively, so the focus heuristic would only turn a slow `change`
* (a cloud provider still fetching the file) into a false dismissal.
*/
#nativeCancelObserved = false;
constructor(options: NativeInputFilePickerOptions) {
this.#input = options.input;
@@ -200,23 +208,25 @@ export class NativeInputFilePicker implements DisposableFilePicker {
try {
request = snapshotSelectionRequest(input);
} catch {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#disposed) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("UNAVAILABLE", "FILE_SELECT"),
);
}
const cancelled = abortedResult(request.signal, "FILE_SELECT");
if (cancelled) return this.#finishObservation(cancelled);
if (cancelled) return observeSelection(this.#observer, cancelled);
const resolvedPolicy = this.#resolveSelection(
request.policy,
request.limits,
);
if (!resolvedPolicy.ok) {
return this.#finishObservation(resolvedPolicy);
return observeSelection(this.#observer, resolvedPolicy);
}
const policy = resolvedPolicy.value;
if (
@@ -225,17 +235,20 @@ export class NativeInputFilePicker implements DisposableFilePicker {
this.#inputEvents.getAttribute,
)
) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#pending) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("BLOCKED", "FILE_SELECT"),
);
}
if (this.#userActivation && !this.#userActivation.isActive) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("PERMISSION_DENIED", "FILE_SELECT"),
);
}
@@ -248,6 +261,8 @@ export class NativeInputFilePicker implements DisposableFilePicker {
let settled = false;
let focusTimer: unknown;
const signal = request.signal;
// The kernel operation owns the caller signal listener.
const operation = createAbortableOperation({ signal });
const finish = (
outcome: BrowserDataResult<FileSelectionOutcome>,
): void => {
@@ -255,7 +270,7 @@ export class NativeInputFilePicker implements DisposableFilePicker {
settled = true;
this.#inputEvents.remove("change", onChange);
this.#inputEvents.remove("cancel", onCancel);
signal?.removeEventListener("abort", onAbort);
operation.close();
this.#windowEvents?.remove("focus", onWindowFocus);
if (focusTimer !== undefined) {
this.#scheduler.clearTimeout(focusTimer);
@@ -293,9 +308,10 @@ export class NativeInputFilePicker implements DisposableFilePicker {
: captured,
);
};
const onCancel = (): void => dismiss();
const onAbort = (): void =>
finish(browserDataFailure("ABORTED", "FILE_SELECT"));
const onCancel = (): void => {
this.#nativeCancelObserved = true;
dismiss();
};
const abortPending = (): void =>
finish(browserDataFailure("ABORTED", "FILE_SELECT"));
const onWindowFocus = (): void => {
@@ -318,8 +334,11 @@ export class NativeInputFilePicker implements DisposableFilePicker {
this.#inputEvents.add("change", onChange, { once: true });
this.#inputEvents.add("cancel", onCancel, { once: true });
signal?.addEventListener("abort", onAbort, { once: true });
this.#windowEvents?.add("focus", onWindowFocus);
// Settles only when the operation ends; after `finish` this is a no-op.
void operation.race(new Promise<never>(() => {})).then(abortPending);
if (!this.#nativeCancelObserved) {
this.#windowEvents?.add("focus", onWindowFocus);
}
this.#abortPending = abortPending;
try {
this.#input.accept = pickerAcceptValue(policy);
@@ -332,9 +351,10 @@ export class NativeInputFilePicker implements DisposableFilePicker {
}
},
);
return this.#finishObservation(result);
return observeSelection(this.#observer, result);
} catch (error) {
return this.#finishObservation(
return observeSelection(
this.#observer,
mapBrowserDataException(error, "FILE_SELECT"),
);
} finally {
@@ -356,33 +376,6 @@ export class NativeInputFilePicker implements DisposableFilePicker {
// Some test doubles or constrained DOM hosts expose a readonly value.
}
}
#finishObservation(
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (result.ok) {
const dismissed = result.value.kind === "DISMISSED";
const bytes =
result.value.kind === "SELECTED"
? result.value.files.reduce(
(total, candidate) => total + candidate.sizeBytes,
0,
)
: null;
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: dismissed ? "DISMISSED" : "SUCCESS",
byteBucket: byteBucket(bytes),
});
} else {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
}
return result;
}
}
export type SystemOpenPickerAcceptType = Readonly<{
@@ -431,8 +424,11 @@ export class EnhancedFilePicker implements DisposableFilePicker {
if (typeof options.showOpenFilePicker !== "function") {
throw new TypeError("Enhanced file picker API is invalid.");
}
// Bound to undefined, not to options: `window.showOpenFilePicker` throws
// "Illegal invocation" for any other receiver, and Web IDL maps an
// undefined receiver to the global object.
this.#showOpenFilePicker =
options.showOpenFilePicker.bind(options);
options.showOpenFilePicker.bind(undefined);
this.#captureHandles =
options.vault.captureHandles.bind(options.vault);
this.#releaseFile = options.vault.release.bind(options.vault);
@@ -457,30 +453,36 @@ export class EnhancedFilePicker implements DisposableFilePicker {
try {
request = snapshotSelectionRequest(input);
} catch {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#disposed) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("UNAVAILABLE", "FILE_SELECT"),
);
}
const cancelled = abortedResult(request.signal, "FILE_SELECT");
if (cancelled) return this.#observe(cancelled);
if (cancelled) return observeSelection(this.#observer, cancelled);
const resolvedPolicy = this.#resolveSelection(
request.policy,
request.limits,
);
if (!resolvedPolicy.ok) return this.#observe(resolvedPolicy);
if (!resolvedPolicy.ok) {
return observeSelection(this.#observer, resolvedPolicy);
}
const policy = resolvedPolicy.value;
if (this.#pending) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("BLOCKED", "FILE_SELECT"),
);
}
if (this.#userActivation && !this.#userActivation.isActive) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("PERMISSION_DENIED", "FILE_SELECT"),
);
}
@@ -496,9 +498,10 @@ export class EnhancedFilePicker implements DisposableFilePicker {
request.signal,
);
const aborted = abortedResult(request.signal, "FILE_SELECT");
if (aborted) return this.#observe(aborted);
if (aborted) return observeSelection(this.#observer, aborted);
if (handles.length === 0) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataSuccess(
Object.freeze({ kind: "DISMISSED" as const }),
),
@@ -509,7 +512,8 @@ export class EnhancedFilePicker implements DisposableFilePicker {
policy,
request.signal ?? new AbortController().signal,
);
return this.#observe(
return observeSelection(
this.#observer,
captured.ok
? browserDataSuccess(
Object.freeze({
@@ -521,20 +525,23 @@ export class EnhancedFilePicker implements DisposableFilePicker {
);
} catch (error) {
if (error instanceof PickerDisposedError) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("ABORTED", "FILE_SELECT"),
);
}
if (error instanceof DOMException && error.name === "AbortError") {
const aborted = abortedResult(input.signal, "FILE_SELECT");
if (aborted) return this.#observe(aborted);
return this.#observe(
if (aborted) return observeSelection(this.#observer, aborted);
return observeSelection(
this.#observer,
browserDataSuccess(
Object.freeze({ kind: "DISMISSED" as const }),
),
);
}
return this.#observe(
return observeSelection(
this.#observer,
mapBrowserDataException(error, "FILE_SELECT"),
);
} finally {
@@ -561,59 +568,52 @@ export class EnhancedFilePicker implements DisposableFilePicker {
new DOMException("Picker aborted", "AbortError"),
);
}
return new Promise((resolve, reject) => {
let settled = false;
const finish = (callback: () => void): void => {
if (settled) return;
settled = true;
signal?.removeEventListener("abort", onAbort);
if (this.#abortPending === abortPending) {
this.#abortPending = undefined;
}
callback();
};
const abortPending = (): void =>
finish(() => reject(new PickerDisposedError()));
const onAbort = (): void =>
finish(() =>
reject(new DOMException("Picker aborted", "AbortError")),
);
this.#abortPending = abortPending;
signal?.addEventListener("abort", onAbort, { once: true });
picker.then(
(handles) => finish(() => resolve(handles)),
(error: unknown) => finish(() => reject(error)),
);
const operation = createAbortableOperation({ signal });
const abortPending = (): void => operation.close();
this.#abortPending = abortPending;
return operation.race(picker).then((outcome) => {
if (this.#abortPending === abortPending) {
this.#abortPending = undefined;
}
operation.close();
if (outcome.kind === "VALUE") return outcome.value;
throw outcome.kind === "REJECTED"
? outcome.reason
: outcome.terminal === "CALLER_ABORT"
? new DOMException("Picker aborted", "AbortError")
: new PickerDisposedError();
});
}
}
#observe(
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (!result.ok) {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
} else if (result.value.kind === "DISMISSED") {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "DISMISSED",
});
} else {
const bytes = result.value.files.reduce(
(total, file) => total + file.sizeBytes,
0,
);
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "SUCCESS",
byteBucket: byteBucket(bytes),
});
}
return result;
/** One observation per terminal selection result, shared by both pickers. */
function observeSelection(
observer: BrowserFileObserver | undefined,
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (!result.ok) {
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
} else if (result.value.kind === "DISMISSED") {
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "DISMISSED",
});
} else {
const bytes = result.value.files.reduce(
(total, file) => total + file.sizeBytes,
0,
);
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "SUCCESS",
byteBucket: byteBucket(bytes),
});
}
return result;
}
function pickerAcceptValue(
@@ -14,6 +14,8 @@ import {
import {
assertFileInspectionPolicy,
assertFileSelectionPolicy,
EXACT_MEDIA_TYPE,
isPositiveSafeInteger,
sanitizeSuggestedFileName,
type RegisteredFileInspectionPolicy,
type RegisteredFileSelectionPolicy,
@@ -81,8 +83,6 @@ type SnapshotProfile = Readonly<{
}>;
const POLICY_TOKEN = /^[a-z0-9][a-z0-9._:-]{0,127}$/i;
const MEDIA_TYPE =
/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
const ISSUED_POLICY_REFERENCES = new WeakSet<object>();
/**
@@ -417,7 +417,7 @@ function snapshotPreview(
hardMaxPreviewBytes: number,
): SnapshotProfile["preview"] {
if (
!positiveSafeInteger(input.maxPreviewBytes) ||
!isPositiveSafeInteger(input.maxPreviewBytes) ||
input.maxPreviewBytes > hardMaxPreviewBytes ||
!Array.isArray(input.allowedMediaTypes) ||
input.allowedMediaTypes.length < 1 ||
@@ -428,7 +428,7 @@ function snapshotPreview(
const allowedMediaTypes = new Set<string>();
for (const inputMediaType of input.allowedMediaTypes) {
const mediaType = inputMediaType.trim().toLowerCase();
if (!MEDIA_TYPE.test(mediaType)) {
if (!EXACT_MEDIA_TYPE.test(mediaType)) {
throw new TypeError("File preview media type is invalid.");
}
allowedMediaTypes.add(mediaType);
@@ -451,9 +451,9 @@ function snapshotDownload(
"PROMPT_AND_STREAM",
"BOUNDED_OBJECT_URL",
].includes(input.strategy) ||
!MEDIA_TYPE.test(mediaType) ||
!positiveSafeInteger(input.maxTransferBytes) ||
!positiveSafeInteger(input.maxBufferedBytes) ||
!EXACT_MEDIA_TYPE.test(mediaType) ||
!isPositiveSafeInteger(input.maxTransferBytes) ||
!isPositiveSafeInteger(input.maxBufferedBytes) ||
input.maxTransferBytes > hardLimits.maxTransferBytes ||
input.maxBufferedBytes > input.maxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
@@ -478,11 +478,11 @@ function assertHardLimits(
input: BrowserFilePolicyRegistryOptions["hardLimits"],
): void {
if (
!positiveSafeInteger(input.maxInspectionBytes) ||
!positiveSafeInteger(input.maxRetainedFileBytes) ||
!positiveSafeInteger(input.maxPreviewBytes) ||
!positiveSafeInteger(input.maxObjectUrlBytes) ||
!positiveSafeInteger(input.maxTransferBytes) ||
!isPositiveSafeInteger(input.maxInspectionBytes) ||
!isPositiveSafeInteger(input.maxRetainedFileBytes) ||
!isPositiveSafeInteger(input.maxPreviewBytes) ||
!isPositiveSafeInteger(input.maxObjectUrlBytes) ||
!isPositiveSafeInteger(input.maxTransferBytes) ||
input.maxObjectUrlBytes > input.maxTransferBytes
) {
throw new TypeError("Browser file policy hard limits are invalid.");
@@ -497,7 +497,7 @@ function reducedLimit(
if (requested === undefined) {
return browserDataSuccess(configured);
}
if (!positiveSafeInteger(requested)) {
if (!isPositiveSafeInteger(requested)) {
return browserDataFailure("INVALID_INPUT", operation);
}
if (requested > configured) {
@@ -520,7 +520,3 @@ function referenceKey(reference: FilePolicyReference): string {
reference.intention,
]);
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -19,10 +19,16 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
createAbortableOperation,
type AbortableOperation,
} from "../platform/abortable-operation.ts";
import {
assertFileInspectionPolicy,
assertFileSelectionPolicy,
findMatchingSignature,
isPositiveSafeInteger,
isSafeGeneratedToken,
matchesSelectionHint,
normalizedExtension,
signatureMetadataMatches,
@@ -119,7 +125,8 @@ export class BrowserFileVault
readonly #observer: BrowserFileObserver | undefined;
readonly #resolveInspection:
BrowserFilePolicyRegistry["resolveInspection"];
readonly #lifetime = new AbortController();
/** Open streams; dispose() closes each, which ends its pending read. */
readonly #streams = new Set<AbortableOperation>();
#disposed = false;
#retainedBytes = 0;
@@ -504,15 +511,12 @@ export class BrowserFileVault
signal: AbortSignal,
): AsyncIterable<BrowserDataResult<Uint8Array>> {
let transferred = 0;
const combined = combineAbortSignals(
signal,
vault.#lifetime.signal,
);
// Q-6.2-7. The kernel owner joins the caller signal and dispose().
const owner = createAbortableOperation({ signal });
if (vault.#disposed) owner.close();
else vault.#streams.add(owner);
try {
for await (const chunk of streamNativeFile(
file,
combined.signal,
)) {
for await (const chunk of streamNativeFile(file, owner)) {
transferred += chunk.byteLength;
yield browserDataSuccess(chunk);
}
@@ -533,7 +537,8 @@ export class BrowserFileVault
vault.#observeFailureResult(failure);
yield failure;
} finally {
combined.release();
vault.#streams.delete(owner);
owner.close();
}
},
});
@@ -620,7 +625,8 @@ export class BrowserFileVault
dispose(): void {
if (this.#disposed) return;
this.#disposed = true;
this.#lifetime.abort();
for (const stream of this.#streams) stream.close();
this.#streams.clear();
this.#verifications.clear();
this.#verificationReceiptsByRef.clear();
this.#records.clear();
@@ -681,7 +687,7 @@ export class BrowserFileVault
return browserDataFailure("LIMIT_EXCEEDED", "FILE_SELECT");
}
const refValue = this.#createReference();
if (!safeOpaqueValue(refValue)) {
if (!isSafeGeneratedToken(refValue)) {
return browserDataFailure("UNAVAILABLE", "FILE_SELECT");
}
const ref = refValue as LocalFileRef;
@@ -716,7 +722,7 @@ export class BrowserFileVault
#issueVerification(record: VerificationRecord):
BrowserDataResult<FileVerificationReceipt> {
const receiptValue = this.#createVerificationReceipt();
if (!safeOpaqueValue(receiptValue)) {
if (!isSafeGeneratedToken(receiptValue)) {
return browserDataFailure("UNAVAILABLE", "FILE_INSPECT");
}
const receipt = receiptValue as FileVerificationReceipt;
@@ -810,21 +816,20 @@ function snapshotSystemFileHandles(
async function* streamNativeFile(
file: File,
signal: AbortSignal,
owner: AbortableOperation,
): AsyncIterable<Uint8Array> {
if (signal.aborted) throw abortException();
if (owner.signal.aborted) throw abortException();
const reader = file.stream().getReader();
const abort = () => {
void reader.cancel(abortException()).catch(() => {});
};
signal.addEventListener("abort", abort, { once: true });
let transferred = 0;
let completed = false;
try {
while (true) {
if (signal.aborted) throw abortException();
const result = await reader.read();
if (signal.aborted) throw abortException();
const raced = await owner.race(reader.read());
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind === "TERMINAL" || owner.signal.aborted) {
throw abortException();
}
const result = raced.value;
if (result.done) break;
const chunk = result.value;
if (!(chunk instanceof Uint8Array)) {
@@ -844,12 +849,16 @@ async function* streamNativeFile(
}
completed = true;
} finally {
signal.removeEventListener("abort", abort);
if (!completed) {
try {
await reader.cancel();
// An aborted read never waits on the source's own cancel algorithm.
if (owner.signal.aborted) {
void reader.cancel(abortException()).catch(() => {});
} else {
await reader.cancel();
}
} catch {
// The stream may already be errored or cancelled by AbortSignal.
// The stream may already be errored.
}
}
reader.releaseLock();
@@ -861,35 +870,6 @@ function normalizedMediaType(value: string): string | null {
return normalized.length > 0 ? normalized : null;
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
function safeOpaqueValue(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
function combineAbortSignals(
caller: AbortSignal,
lifetime: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = (): void => controller.abort();
if (caller.aborted || lifetime.aborted) {
controller.abort();
} else {
caller.addEventListener("abort", abort, { once: true });
lifetime.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release(): void {
caller.removeEventListener("abort", abort);
lifetime.removeEventListener("abort", abort);
},
});
}
function abortException(): DOMException {
return new DOMException("Operation aborted", "AbortError");
}
@@ -24,6 +24,7 @@ import {
type DownloadDeliveryAdapterOptions,
} from "./download-delivery-adapter.ts";
import type { BrowserFileObserver } from "./file-observer.ts";
import { isPositiveSafeInteger } from "./file-policy.ts";
import {
BrowserTransientPreview,
ObjectUrlLeaseRegistry,
@@ -239,7 +240,3 @@ function resolveRuntimeLimits(
}
return resolved;
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -1,5 +1,4 @@
import type {
BrowserManagedDownloadCapability,
BrowserManagedDownloadCapabilityResolver,
DownloadDeliveryPort,
DownloadOutcome,
@@ -12,7 +11,6 @@ import type {
TransferProgress,
} from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
PresignedDownloadSourcePort,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
@@ -22,23 +20,32 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
createAbortableOperation,
type AbortableOperation,
} from "../platform/abortable-operation.ts";
import {
byteBucket,
observeBrowserFile,
type BrowserFileObserver,
} from "./file-observer.ts";
import {
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import {
ObjectUrlLeaseRegistry,
objectUrlLimitFailure,
type ObjectUrlLease,
} from "./object-url-lease.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { isPositiveSafeInteger, isSafeGeneratedToken } from "./file-policy.ts";
import {
BrowserFilePolicyRegistry,
type ResolvedDownloadPolicy,
} from "./browser-file-policy-registry.ts";
activeDeliveryInput,
resolveBrowserManagedTarget,
validByteSource,
validPresignedByteSource,
validateBrowserManagedCapability,
validateDownloadInput,
type DeliveryInput,
type DeliveryRequest,
} from "./download-input-validation.ts";
export type BrowserDownloadHost = Readonly<{
handoff(href: string, suggestedFileName: string): void;
@@ -134,9 +141,6 @@ export type DownloadDeliveryAdapterOptions = Readonly<{
observer?: BrowserFileObserver;
}>;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
const SHA256 = /^[a-f0-9]{64}$/i;
/**
* Keeps a one-shot Blob URL alive across browser download scheduling and
* process handoff. Runtime dispose() still revokes every active lease
@@ -170,7 +174,8 @@ export function createDownloadDeliveryAdapter(
options.baseOrigin ?? globalThis.location?.origin ?? "https://localhost";
const userActivation =
options.userActivation ?? globalThis.navigator?.userActivation;
const lifetime = new AbortController();
// Every delivery in flight; dispose() closes each, which aborts its signal.
const liveOperations = new Set<AbortableOperation>();
let disposed = false;
if (
@@ -178,8 +183,8 @@ export function createDownloadDeliveryAdapter(
progressMinIntervalMs < 0 ||
!Number.isSafeInteger(releaseDelayMs) ||
releaseDelayMs < 0 ||
!isPositiveByteLimit(options.hardMaxObjectUrlBytes) ||
!isPositiveByteLimit(options.hardMaxTransferBytes) ||
!isPositiveSafeInteger(options.hardMaxObjectUrlBytes) ||
!isPositiveSafeInteger(options.hardMaxTransferBytes) ||
options.hardMaxObjectUrlBytes > options.hardMaxTransferBytes ||
typeof options.host?.handoff !== "function" ||
typeof options.policies?.resolveDownload !== "function" ||
@@ -224,8 +229,11 @@ export function createDownloadDeliveryAdapter(
: {}),
...(originalShowSaveFilePicker
? {
// Bound to undefined, not to options: `window.showSaveFilePicker`
// throws "Illegal invocation" for any other receiver, and Web IDL
// maps an undefined receiver to the global object.
showSaveFilePicker:
originalShowSaveFilePicker.bind(options),
originalShowSaveFilePicker.bind(undefined),
}
: {}),
...(originalIntegrityVerifier
@@ -263,19 +271,23 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
const combined = combineAbortSignals(
input.signal,
lifetime.signal,
);
// Q-6.2-7. One owner per delivery: caller abort and dispose() both end
// it, and a lease or writable that lands after that is compensated by the
// kernel race instead of a hand-written listener pair.
const owner = createAbortableOperation({ signal: input.signal });
liveOperations.add(owner);
try {
return await deliverActive({ ...input, signal: combined.signal });
return await deliverActive({ ...input, signal: owner.signal }, owner);
} finally {
combined.release();
liveOperations.delete(owner);
owner.close();
}
}
async function deliverActive(input: DeliveryRequest):
Promise<BrowserDataResult<DownloadOutcome>> {
async function deliverActive(
input: DeliveryRequest,
owner: AbortableOperation,
): Promise<BrowserDataResult<DownloadOutcome>> {
const resolvedPolicy = resolveDownloadPolicy(
input.policy,
{
@@ -312,17 +324,10 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
let suggestedFileName: string;
// Q-6.2-10. Validation already sanitized the name; it is not redone.
const suggestedFileName = validation.value;
let transferId: string;
try {
suggestedFileName = sanitizeSuggestedFileName(
activeInput.suggestedFileName,
{
safeExtension: activeInput.safeExtension,
maxUtf8Bytes:
dependencies.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy,
);
transferId = createTransferId();
} catch {
return observeResult(
@@ -330,7 +335,7 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
if (!safeGeneratedToken(transferId)) {
if (!isSafeGeneratedToken(transferId)) {
return observeResult(
browserDataFailure("UNAVAILABLE", "DOWNLOAD"),
dependencies.observer,
@@ -355,6 +360,7 @@ export function createDownloadDeliveryAdapter(
if (activeInput.strategy === "PROMPT_AND_STREAM") {
return promptAndStream({
input: activeInput,
owner,
suggestedFileName,
transferId,
options: dependencies,
@@ -364,6 +370,7 @@ export function createDownloadDeliveryAdapter(
return boundedObjectUrlHandoff({
input: activeInput,
owner,
suggestedFileName,
transferId,
options: dependencies,
@@ -379,7 +386,8 @@ export function createDownloadDeliveryAdapter(
dispose(): void {
if (disposed) return;
disposed = true;
lifetime.abort();
for (const operation of liveOperations) operation.close();
liveOperations.clear();
objectUrls.dispose();
},
});
@@ -479,6 +487,7 @@ function browserManagedHandoff(context: Readonly<{
async function promptAndStream(context: Readonly<{
input: DeliveryInput;
owner: AbortableOperation;
suggestedFileName: string;
transferId: string;
options: DownloadDeliveryAdapterOptions;
@@ -539,10 +548,7 @@ async function promptAndStream(context: Readonly<{
let handle: SaveFileHandle;
try {
handle = await awaitWithSignal(
handlePromise,
context.input.signal,
);
handle = await raceOwner(context.owner, handlePromise);
} catch (error) {
if (
error instanceof DOMException &&
@@ -573,7 +579,7 @@ async function promptAndStream(context: Readonly<{
try {
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.owner,
context.options,
sourceHolder,
);
@@ -592,9 +598,14 @@ async function promptAndStream(context: Readonly<{
);
}
context.progress.report("PREPARING", 0, source.byteLength, true);
const writable = await awaitWithSignal(
const writable = await raceOwner(
context.owner,
handle.createWritable(),
context.input.signal,
// A writable that opens after the abort keeps a browser swap file
// until it is aborted.
(late) => {
void late.abort().catch(() => undefined);
},
);
const writer = writable.getWriter();
let committed = false;
@@ -603,7 +614,7 @@ async function promptAndStream(context: Readonly<{
try {
for await (const chunkResult of abortableFileChunks(
source,
context.input.signal,
context.owner,
)) {
if (!chunkResult.ok) {
throw new ClosedFileStreamError(chunkResult.error);
@@ -619,15 +630,12 @@ async function promptAndStream(context: Readonly<{
throw limitException();
}
if (verifier) {
await awaitWithSignal(
await raceOwner(
context.owner,
Promise.resolve(verifier.update(chunk)),
context.input.signal,
);
}
await awaitWithSignal(
writer.write(chunk),
context.input.signal,
);
await raceOwner(context.owner, writer.write(chunk));
transferred = next;
context.progress.report(
"TRANSFERRING",
@@ -644,9 +652,9 @@ async function promptAndStream(context: Readonly<{
true,
);
if (verifier) {
const verified = await awaitWithSignal(
const verified = await raceOwner(
context.owner,
Promise.resolve(verifier.verify()),
context.input.signal,
);
if (!verified) throw integrityException();
}
@@ -713,6 +721,7 @@ async function promptAndStream(context: Readonly<{
async function boundedObjectUrlHandoff(context: Readonly<{
input: DeliveryInput;
owner: AbortableOperation;
suggestedFileName: string;
transferId: string;
options: DownloadDeliveryAdapterOptions;
@@ -731,38 +740,38 @@ async function boundedObjectUrlHandoff(context: Readonly<{
);
}
const sourceHolder = createSourceHolder();
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
closeHeldSource(sourceHolder);
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
closeHeldSource(sourceHolder);
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
const chunks: ArrayBuffer[] = [];
let transferred = 0;
let lease: ObjectUrlLease | undefined;
try {
// Inside the try: an open that throws or is aborted must still resolve to
// a Result and reach the finally that closes the held lease.
const sourceResult = await resolveByteSource(
context.input,
context.owner,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
context.progress.report("PREPARING", 0, source.byteLength, true);
for await (const chunkResult of abortableFileChunks(
source,
context.input.signal,
context.owner,
)) {
if (!chunkResult.ok) {
throw new ClosedFileStreamError(chunkResult.error);
@@ -779,9 +788,9 @@ async function boundedObjectUrlHandoff(context: Readonly<{
throw limitException();
}
if (verifier) {
await awaitWithSignal(
await raceOwner(
context.owner,
Promise.resolve(verifier.update(chunk)),
context.input.signal,
);
}
const copy = chunk.slice();
@@ -801,9 +810,9 @@ async function boundedObjectUrlHandoff(context: Readonly<{
true,
);
if (verifier) {
const verified = await awaitWithSignal(
const verified = await raceOwner(
context.owner,
Promise.resolve(verifier.verify()),
context.input.signal,
);
if (!verified) throw integrityException();
}
@@ -854,168 +863,14 @@ async function boundedObjectUrlHandoff(context: Readonly<{
}
}
type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function validateDownloadInput(
input: DeliveryInput,
options: DownloadDeliveryAdapterOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<true> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
});
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
return browserDataSuccess(true);
}
/**
* TR-RR-04. A presigned byte source owns a fetch reader and a capability lease,
* and its port requires `close()`. The delivery consumer never called it, so
* every success, validation failure, writer failure and abort leaked both. The
* closeable subtype is lost in the `FileByteSource` projection, so the holder
* keeps it and the outermost boundary closes it exactly once.
* keeps it and the outermost boundary closes it exactly once. A lease that
* lands after the owner ended never reaches the holder; the owner's race
* compensates it instead.
*/
type CloseableSourceHolder = { source: FileByteSource | null; closed: boolean };
@@ -1023,32 +878,6 @@ function createSourceHolder(): CloseableSourceHolder {
return { source: null, closed: false };
}
/**
* TR-02. Closes a lease that fulfilled after the delivery already ended. The
* holder's own `closed` latch is the single close-once authority, so a lease
* the holder did adopt is never closed twice and a lease it never saw is still
* closed exactly once. A late rejection is observed and discarded.
*/
function compensateLateSource(
pending: Promise<BrowserDataResult<FileByteSource>>,
holder: CloseableSourceHolder | undefined,
): void {
if (!holder) return;
void pending.then(
(result) => {
if (!result.ok || !holder.closed) return;
// The holder was already closed, so this lease was never adopted.
if (!isVerifiedPresignedSource(result.value)) return;
try {
result.value.close();
} catch {
// Compensation is best effort and never changes the outcome.
}
},
() => undefined,
);
}
function closeHeldSource(holder: CloseableSourceHolder): void {
if (holder.closed) return;
holder.closed = true;
@@ -1064,12 +893,12 @@ function closeHeldSource(holder: CloseableSourceHolder): void {
async function resolveByteSource(
input: DeliveryInput,
signal: AbortSignal,
owner: AbortableOperation,
options: DownloadDeliveryAdapterOptions,
holder?: CloseableSourceHolder,
): Promise<BrowserDataResult<FileByteSource>> {
const source = input.source;
if (signal.aborted) {
if (owner.signal.aborted) {
return browserDataFailure("ABORTED", "DOWNLOAD");
}
if (source.kind === "GENERATED") {
@@ -1082,17 +911,22 @@ async function resolveByteSource(
}
const open = options.openAuthorizedSource;
if (!open) return browserDataFailure("UNSUPPORTED", "DOWNLOAD");
const pendingOpen = open({
resourceId: source.resourceId,
capability: source.capability,
signal,
});
// TR-02. A lease that arrives after the abort already ended the delivery
// never reaches the holder, so nothing would ever close it: the fetch reader
// and the capability lease outlived the terminal result. The compensator and
// the holder share one close-once latch, so exactly one of them closes it.
compensateLateSource(pendingOpen, holder);
const result = await awaitWithSignal(pendingOpen, signal);
// TR-02 / Q-6.2-7. A lease that arrives after the owner ended never reaches
// the holder, so the race closes it: exactly one of the two ever sees it,
// with no gap between the abort and the holder's own cleanup.
const result = await raceOwner(
owner,
open({
resourceId: source.resourceId,
capability: source.capability,
signal: owner.signal,
}),
(late) => {
if (late.ok && isVerifiedPresignedSource(late.value)) {
late.value.close();
}
},
);
if (!result.ok) {
return browserDataFailure(result.error.code, "DOWNLOAD", {
retryable: result.error.retryable,
@@ -1114,14 +948,6 @@ async function resolveByteSource(
: browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
function isVerifiedPresignedSource(
source: FileByteSource,
): source is PresignedDownloadByteSource {
@@ -1131,70 +957,16 @@ function isVerifiedPresignedSource(
);
}
function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveByteLimit(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
async function* abortableFileChunks(
source: FileByteSource,
signal: AbortSignal,
owner: AbortableOperation,
): AsyncIterable<BrowserDataResult<Uint8Array>> {
const signal = owner.signal;
const iterator = source.stream(signal)[Symbol.asyncIterator]();
let completed = false;
try {
while (true) {
const next = await awaitWithSignal(iterator.next(), signal);
const next = await raceOwner(owner, iterator.next());
if (next.done) {
completed = true;
return;
@@ -1261,122 +1033,12 @@ function mapDownloadException(
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (error.name === "FileTooLargeError") {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
return objectUrlLimitFailure(error, "DOWNLOAD");
}
}
return mapBrowserDataException(error, "DOWNLOAD");
}
function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveByteLimit(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
function safeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
type ProgressReporter = Readonly<{
report(
phase: TransferProgress["phase"],
@@ -1479,50 +1141,17 @@ class ClosedFileStreamError extends Error {
}
}
function combineAbortSignals(
caller: AbortSignal,
lifetime: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = (): void => controller.abort();
if (caller.aborted || lifetime.aborted) {
controller.abort();
} else {
caller.addEventListener("abort", abort, { once: true });
lifetime.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release(): void {
caller.removeEventListener("abort", abort);
lifetime.removeEventListener("abort", abort);
},
});
}
async function awaitWithSignal<Value>(
/**
* The owner's value, the task's own rejection, or an AbortError once the owner
* ended. `compensate` receives a value that lands after that.
*/
async function raceOwner<Value>(
owner: AbortableOperation,
pending: Promise<Value>,
signal: AbortSignal,
compensate?: (value: Value) => void,
): Promise<Value> {
if (signal.aborted) throw abortException();
return new Promise<Value>((resolve, reject) => {
let settled = false;
const finish = (callback: () => void): void => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
callback();
};
const onAbort = (): void =>
finish(() => reject(abortException()));
signal.addEventListener("abort", onAbort, { once: true });
pending.then(
(value) => finish(() => resolve(value)),
(error: unknown) => finish(() => reject(error)),
);
});
}
function isPositiveByteLimit(value: number): boolean {
return isValidByteLength(value) && value > 0;
const raced = await owner.race(pending, compensate);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
}
@@ -0,0 +1,367 @@
import type {
BrowserManagedDownloadCapability,
DownloadDeliveryPort,
DownloadSource,
FileByteSource,
} from "../../application/ports/browser-file-storage/file.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
import { isValidByteLength } from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../browser-file-storage/result.ts";
import {
EXACT_MEDIA_TYPE,
isPositiveSafeInteger,
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import type { ResolvedDownloadPolicy } from "./browser-file-policy-registry.ts";
/**
* Q-6.2-11. Input admission for download delivery: request snapshot, policy
* and limit checks, presigned and browser-managed capability validation, and
* canonical handoff target resolution. Moved verbatim out of the adapter.
*/
/** The adapter options that input validation reads. */
export type DownloadInputValidationOptions = Readonly<{
hardMaxObjectUrlBytes: number;
hardMaxTransferBytes: number;
openAuthorizedSource?: unknown;
showSaveFilePicker?: unknown;
filenameMaxUtf8Bytes?: number;
now?: () => number;
}>;
const SHA256 = /^[a-f0-9]{64}$/i;
export type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
export type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
export function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
export function validateDownloadInput(
input: DeliveryInput,
options: DownloadInputValidationOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<string> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!EXACT_MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
return browserDataSuccess(
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy),
);
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
export function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
export function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveSafeInteger(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
export function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveSafeInteger(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
export type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
export function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
+6 -15
View File
@@ -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";
@@ -15,23 +17,12 @@ type BrowserFileObservation = Readonly<{
/**
* File adapters use the platform BrowserDataObserver as the telemetry SSOT.
* The helper below is the sole mapper from file-local dismissal semantics.
* The helper below is the sole mapper from file-local outcomes. A dismissal
* stays `DISMISSED` (02-06): folded into `SUCCEEDED` it hid the save-dialog
* cancel rate inside the browser handoff success rate.
*/
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,
@@ -41,7 +32,7 @@ export function observeBrowserFile(
Object.freeze({
operation: observation.operation,
outcome:
observation.outcome === "FAILED" ? "FAILED" : "SUCCEEDED",
observation.outcome === "SUCCESS" ? "SUCCEEDED" : observation.outcome,
...(observation.failureCode
? { failureCode: observation.failureCode }
: {}),
+38 -14
View File
@@ -40,6 +40,20 @@ export type RegisteredFileInspectionPolicy = Readonly<{
}>;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+|\*)$/i;
/**
* Q-6.2-12. The shared browser-file copies of three checks that used to be
* redefined per module: an exact `type/subtype` media type (no wildcard), a
* generated opaque token (file reference, receipt or transfer ID) and a
* positive safe integer limit.
*/
export const EXACT_MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
export function isSafeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
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;
@@ -354,12 +368,7 @@ export function sanitizeSuggestedFileName(
base = fallbackBase.length > 0 ? fallbackBase : "download";
}
while (
base.length > 0 &&
utf8Length(`${base}${safeExtension}`) > maxUtf8Bytes
) {
base = Array.from(base).slice(0, -1).join("").trimEnd();
}
base = truncateUtf8(base, maxUtf8Bytes - utf8Length(safeExtension));
if (base.length === 0 || WINDOWS_RESERVED.test(base)) {
base = fallbackBase;
}
@@ -401,21 +410,36 @@ function utf8Length(value: string): number {
return new TextEncoder().encode(value).byteLength;
}
/**
* Q-6.2-10. The longest code-point prefix within `maxBytes` UTF-8 bytes, with
* trailing whitespace removed once it was cut; `value` itself when it fits.
* One pass: re-encoding the whole name per dropped code point was O(n^2).
*/
function truncateUtf8(value: string, maxBytes: number): string {
let bytes = 0;
let end = 0;
for (const character of value) {
const codePoint = character.codePointAt(0) ?? 0;
// A lone surrogate encodes as U+FFFD, three bytes, like any BMP point.
bytes +=
codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
if (bytes > maxBytes) return value.slice(0, end).trimEnd();
end += character.length;
}
return value;
}
function fitFallbackBaseName(
configured: string,
extension: string,
maxUtf8Bytes: number,
): string {
let fallback =
const fallback = truncateUtf8(
configured.length > 0 && !WINDOWS_RESERVED.test(configured)
? configured
: "download";
while (
fallback.length > 0 &&
utf8Length(`${fallback}${extension}`) > maxUtf8Bytes
) {
fallback = Array.from(fallback).slice(0, -1).join("").trimEnd();
}
: "download",
maxUtf8Bytes - utf8Length(extension),
);
return fallback.length > 0 && !WINDOWS_RESERVED.test(fallback)
? fallback
: "a";
+41 -21
View File
@@ -20,6 +20,7 @@ import {
type BrowserFileObserver,
} from "./file-observer.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { EXACT_MEDIA_TYPE, isPositiveSafeInteger } from "./file-policy.ts";
export type ObjectUrlApi = Readonly<{
createObjectURL(blob: Blob): string;
@@ -44,6 +45,31 @@ const DEFAULT_OBJECT_URL_LEASE_LIMITS: ObjectUrlLeaseLimits =
hardMaxAggregateLeaseBytes: 256 * 1024 * 1024,
});
/**
* 02-04. Every lease slot or the aggregate byte budget is in use. Leases free
* up when released (a download after its revoke grace), so unlike one Blob
* above the single-lease ceiling this is reported as retryable.
*/
class ObjectUrlLeasesExhaustedError extends DOMException {
constructor() {
super("Object URL leases exhausted", "FileTooLargeError");
}
}
/** Maps a `FileTooLargeError` from the registry or a byte cap. */
export function objectUrlLimitFailure(
error: DOMException,
operation: "PREVIEW" | "DOWNLOAD",
): BrowserDataResult<never> {
return browserDataFailure(
"LIMIT_EXCEEDED",
operation,
error instanceof ObjectUrlLeasesExhaustedError
? { retryable: true, recovery: "RETRY" }
: {},
);
}
/**
* The only low-level owner of object URL creation/revocation. Every lease is
* idempotent and dispose() is a final safety net for route/runtime teardown.
@@ -96,26 +122,23 @@ export class ObjectUrlLeaseRegistry {
create(blob: Blob): ObjectUrlLease {
if (
!isValidByteLength(blob.size) ||
blob.size > this.#limits.hardMaxSingleLeaseBytes ||
this.#active.size >= this.#limits.hardMaxActiveLeases ||
!Number.isSafeInteger(this.#aggregateByteLength + blob.size) ||
this.#aggregateByteLength + blob.size >
this.#limits.hardMaxAggregateLeaseBytes
blob.size > this.#limits.hardMaxSingleLeaseBytes
) {
throw new DOMException(
"Object URL lease limit exceeded",
"FileTooLargeError",
);
}
if (
this.#active.size >= this.#limits.hardMaxActiveLeases ||
!Number.isSafeInteger(this.#aggregateByteLength + blob.size) ||
this.#aggregateByteLength + blob.size >
this.#limits.hardMaxAggregateLeaseBytes
) {
throw new ObjectUrlLeasesExhaustedError();
}
const url = this.#createObjectURL(blob);
if (typeof url !== "string" || url.length === 0) {
if (typeof url === "string" && url.length > 0) {
try {
this.#revokeObjectURL(url);
} catch {
// The invalid lease is rejected regardless of cleanup support.
}
}
throw new DOMException(
"Object URL allocation failed",
"InvalidStateError",
@@ -184,7 +207,6 @@ const DEFAULT_ACTIVE_CONTENT = new Set([
"text/html",
"text/xml",
]);
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
export class BrowserTransientPreview implements TransientPreviewPort {
readonly #resolveVerifiedFile:
@@ -267,9 +289,13 @@ export class BrowserTransientPreview implements TransientPreviewPort {
browserDataFailure("UNAVAILABLE", "PREVIEW"),
);
}
// 02-01. The caller may abort while the file resolves; a lease created
// after that would never be released because the caller drops the result.
const abortedWhileResolving = abortedResult(input.signal, "PREVIEW");
if (abortedWhileResolving) return this.#observe(abortedWhileResolving);
const mediaType = resolved.value.mediaType.trim().toLowerCase();
if (
!MEDIA_TYPE.test(mediaType) ||
!EXACT_MEDIA_TYPE.test(mediaType) ||
!policy.allowedMediaTypes.has(mediaType) ||
this.#hardForbiddenMediaTypes.has(mediaType)
) {
@@ -306,9 +332,7 @@ export class BrowserTransientPreview implements TransientPreviewPort {
error instanceof DOMException &&
error.name === "FileTooLargeError"
) {
return this.#observe(
browserDataFailure("LIMIT_EXCEEDED", "PREVIEW"),
);
return this.#observe(objectUrlLimitFailure(error, "PREVIEW"));
}
return this.#observe(mapBrowserDataException(error, "PREVIEW"));
}
@@ -333,7 +357,3 @@ export class BrowserTransientPreview implements TransientPreviewPort {
return result;
}
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
+71 -63
View File
@@ -22,6 +22,7 @@ import {
import type { InstalledBoundaryMapper } from "../../contracts/boundary-mapper.ts";
import {
createFailure,
withFailureEffect,
type AppFailure,
type FailureKind,
} from "../../contracts/errors.ts";
@@ -292,6 +293,7 @@ async function executeUnary<Output>(
const { operation, profile, encoder, transport } = bound;
const linked = linkedAbortController(context.signal);
let attemptCount = 0;
let sent = false;
const finish = (
result: Result<Output, AppFailure>,
@@ -300,7 +302,11 @@ async function executeUnary<Output>(
// R-06. Listener and timer cleanup happens exactly once, on every exit.
linked.cleanup();
observe(dependencies, operation, outcome, attemptCount, result.ok ? 1 : 0);
return result;
// Q-6.3-9. Once a command reached the transport, no failure proves the
// server did not apply it, so it is never offered as a plain retry.
return !result.ok && sent && operation.semantics === "COMMAND"
? failureResult(withFailureEffect(result.error, "MAYBE_APPLIED"))
: result;
};
const generation = safeCapture(generationFence);
@@ -350,6 +356,21 @@ async function executeUnary<Output>(
}
for (let attempt = 0; attempt < profile.maxAttempts; attempt += 1) {
// Q-6.3-9. A retry never outlives the scope generation that started it,
// so a previous user's request is not sent again after a logout.
if (attempt > 0 && !safeIsCurrent(generationFence, generation)) {
return finish(
failureResult(
callFailure(
operation,
attempt - 1,
"SCOPE_GENERATION_CHANGED",
"RPC_SCOPE_GENERATION_CHANGED",
),
),
"ABORTED",
);
}
attemptCount = attempt + 1;
const attemptNow = safeNow(clock);
if (attemptNow === CLOCK_FAILURE) {
@@ -393,6 +414,7 @@ async function executeUnary<Output>(
? { idempotencyKey: context.idempotencyKey }
: {}),
});
sent = true;
const timed = await raceWithin(
Promise.resolve().then(() => transport.invokeUnary!(call)),
remainingMs,
@@ -549,10 +571,30 @@ async function* executeServerStream<Event>(
const deadlineAt = safeNowOrDeadline(clock, 0) + operation.totalDeadlineMs;
const linked = linkedAbortController(context.signal);
let iterator: AsyncIterator<BrowserRpcStreamFrame> | null = null;
let lease: BrowserRpcServerStreamLease | null = null;
let registered: ActiveStreamLease | null = null;
let observed = false;
let messageCount = 0;
// R-01 / RPC-RR-01. Runs once, when the stream's own signal aborts. The
// lease's `cancel` is what actually stops the physical stream, and the entry
// is removed only once the transport confirms the physical stream closed.
// Until then the operation stays DRAINING and admits nothing new — a bounded
// wait here would re-open the very hole this registry exists to close.
const releaseRegistered = () => {
const entry = registered;
if (!entry) return;
try {
entry.cancel("stream-closed");
} catch {
// A transport that refuses to cancel stays DRAINING below.
}
void entry.closed.then((confirmed) => {
if (confirmed && activeStreams.get(operation.operationId) === entry) {
activeStreams.delete(operation.operationId);
}
});
};
const finish = (outcome: BrowserRpcObservationOutcome) => {
if (observed) return;
observed = true;
@@ -662,21 +704,28 @@ async function* executeServerStream<Event>(
yield failureResult(protocolFailure(operation, 0));
return;
}
lease = decodedLease;
const lease = decodedLease;
// Registered at the moment the physical stream exists, not after a timeout.
activeStreams.set(
operation.operationId,
Object.freeze({
streamId: lease.streamId,
cancel: lease.cancel,
// RPC-01. Only a fulfilled, contract-shaped receipt is evidence that the
// physical stream closed. Absorbing a rejection, a synchronous throw or
// a non-promise into `undefined` forged that evidence, and the registry
// then admitted a second stream for the same operation while the first
// was still running against the server.
closed: confirmPhysicalClosure(lease),
}),
);
registered = Object.freeze({
streamId: lease.streamId,
cancel: lease.cancel,
// RPC-01. Only a fulfilled, contract-shaped receipt is evidence that the
// physical stream closed. Absorbing a rejection, a synchronous throw or
// a non-promise into `undefined` forged that evidence, and the registry
// then admitted a second stream for the same operation while the first
// was still running against the server.
closed: confirmPhysicalClosure(lease),
});
activeStreams.set(operation.operationId, registered);
// Q-6.3-9. A consumer that aborts and walks away without `return()` leaves
// this generator suspended at a `yield`, so `finally` never runs. The
// abort itself releases the physical stream.
if (linked.controller.signal.aborted) releaseRegistered();
else {
linked.controller.signal.addEventListener("abort", releaseRegistered, {
once: true,
});
}
try {
iterator = lease.frames[Symbol.asyncIterator]();
} catch {
@@ -842,38 +891,13 @@ async function* executeServerStream<Event>(
}
} finally {
// R-01 / RPC-RR-01. The commit/admission generation is fenced immediately
// and listeners are released without waiting for the transport.
// `iterator.return()` is a cleanup request, not a lifecycle authority, so
// the lease's own `cancel` is what actually stops the physical stream.
// and listeners are released without waiting for the transport. The abort
// runs `releaseRegistered` (cancel + positive-close subscription) unless
// an earlier abort already did. RPC-02: that happens before any fallible
// cleanup, so a throwing `return` accessor cannot strand the entry.
// `iterator.return()` is a cleanup request, not a lifecycle authority.
linked.controller.abort("stream-closed");
linked.cleanup();
const registered = lease
? activeStreams.get(operation.operationId)
: undefined;
if (registered && registered.streamId === lease?.streamId) {
try {
registered.cancel("stream-closed");
} catch {
// A transport that refuses to cancel stays DRAINING below.
}
}
if (registered && registered.streamId === lease?.streamId) {
// RPC-02. The positive-close subscription is installed before any
// fallible cleanup. Running cleanup first meant a throwing `return`
// accessor could skip it entirely and strand the registry entry.
// The entry is removed only once the transport confirms the physical
// stream closed. Until then the operation stays DRAINING and admits
// nothing new — a bounded wait here would re-open the very hole this
// registry exists to close.
void registered.closed.then((confirmed) => {
if (
confirmed &&
activeStreams.get(operation.operationId) === registered
) {
activeStreams.delete(operation.operationId);
}
});
}
const returnIterator = safeIteratorReturn(iterator);
if (returnIterator) {
const cleanup = Promise.resolve()
@@ -882,7 +906,7 @@ async function* executeServerStream<Event>(
.catch(() => undefined);
await boundedStreamCleanup(cleanup, clock, STREAM_CLEANUP_BOUND_MS);
}
if (registered && registered.streamId === lease?.streamId) {
if (registered) {
await boundedStreamCleanup(
registered.closed.then(() => undefined),
clock,
@@ -1465,22 +1489,6 @@ function decodeTransportFailure(
});
}
function validTransportFailure(
failure: unknown,
): failure is BrowserRpcTransportFailure {
if (!failure || typeof failure !== "object" || !("code" in failure)) {
return false;
}
const candidate = failure as BrowserRpcTransportFailure;
return (
TRANSPORT_FAILURE_CODES.has(candidate.code) &&
(candidate.retryAfterMs === undefined ||
(Number.isSafeInteger(candidate.retryAfterMs) &&
candidate.retryAfterMs >= 0 &&
candidate.retryAfterMs <= BROWSER_RPC_HARD_LIMITS.maxRetryAfterMs))
);
}
const TRANSPORT_FAILURE_CODES =
new Set<BrowserRpcTransportFailureCode>([
"NETWORK_UNREACHABLE",
@@ -133,7 +133,10 @@ and every CDN origin must differ from it. This is required because an
`anonymous` image request omits credentials only when it is cross-origin.
Private descriptors must be backend-signed, remain above the configured
minimum TTL at every resolve, and use an eager, non-low-priority
`PRIMARY_REQUIRED` preset. Digest and signature verification share one
`PRIMARY_REQUIRED` preset. A `PRIMARY_REQUIRED` preset must use `fit`
`cover`, `contain` or `fill`: the probe expects the exact primary pixel size,
and `inside`/`outside` keep the source ratio, so the registry rejects that
combination at composition time. Digest and signature verification share one
composition-owned deadline and race the caller's abort signal. The probe sends
no credentials, rejects any final URL other than the exact signed URL, and
requires the private response to declare the flag-only directive
@@ -7,11 +7,16 @@ import {
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
cancelBody,
cancelReader,
createAbortableOperation,
snapshotAbortTimers,
type AbortTimerSnapshot,
type AbortableOperation,
} 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;
@@ -49,7 +54,10 @@ export function createBrowserImageProbe(
const createBitmap =
dependencies.createBitmap ??
(typeof createImageBitmap === "function"
? async (image: Blob) => createImageBitmap(image)
? // Q-6.1-8. The header parser reads pre-rotation dimensions, so the
// decode must not apply EXIF/irot orientation and swap them.
async (image: Blob) =>
createImageBitmap(image, { imageOrientation: "none" })
: undefined);
const timeoutMs = dependencies.timeoutMs ?? DEFAULT_TIMEOUT_MS;
const timers = snapshotAbortTimers(
@@ -100,11 +108,15 @@ export function createBrowserImageProbe(
return browserDataFailure("UNSUPPORTED", "IMAGE_RESOLVE");
}
const scope = createProbeAbortScope(
request.signal,
// X-AUDIT-02 / TR-RR-05. The probe is owned by the shared abort
// primitive: the caller listener and the deadline are installed
// together, so a throwing scheduler closes the probe instead of
// rejecting `probe()`.
const scope = createAbortableOperation({
signal: request.signal,
timeoutMs,
timers,
);
...timers,
});
let response: Response | undefined;
try {
if (scope.signal.aborted) {
@@ -124,8 +136,8 @@ export function createBrowserImageProbe(
signal: scope.signal,
}),
);
response = await scope.await(fetchTask, (lateResponse) => {
cancelResponseBody(lateResponse);
response = await awaitOwned(scope, fetchTask, (lateResponse) => {
cancelBody(lateResponse);
});
} catch {
return signalFailure(request.signal);
@@ -140,7 +152,7 @@ export function createBrowserImageProbe(
response.url !== url.href ||
!validResponseHeaders(response, request)
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure(
"POLICY_REJECTED",
"IMAGE_RESOLVE",
@@ -152,10 +164,10 @@ export function createBrowserImageProbe(
bytes = await readBoundedBody(
response,
request.maxEncodedBytes,
scope.signal,
scope,
);
} catch (error) {
if (request.signal.aborted || scope.timedOut()) {
if (request.signal.aborted || unanswered(scope)) {
return signalFailure(request.signal);
}
return error instanceof EncodedBodyLimitError
@@ -227,18 +239,12 @@ export function createBrowserImageProbe(
type: request.expectedMediaType,
}),
);
bitmap = await scope.await(decodeTask, closeBitmap);
bitmap = await awaitOwned(scope, decodeTask, closeBitmap);
if (
!positiveSafeInteger(bitmap.width) ||
!positiveSafeInteger(bitmap.height) ||
// The header dimensions are positive and already within the
// decode budget, so an exact match is the whole check.
bitmap.width !== metadata.width ||
bitmap.height !== metadata.height ||
!withinDecodeBudget(
bitmap.width,
bitmap.height,
request.maxDecodedPixels,
request.maxDecodedBytes,
)
bitmap.height !== metadata.height
) {
return browserDataFailure(
"INTEGRITY_FAILED",
@@ -255,7 +261,7 @@ export function createBrowserImageProbe(
}),
);
} catch {
return request.signal.aborted || scope.timedOut()
return request.signal.aborted || unanswered(scope)
? signalFailure(request.signal)
: browserDataFailure(
"INTEGRITY_FAILED",
@@ -265,7 +271,7 @@ export function createBrowserImageProbe(
if (bitmap) closeBitmap(bitmap);
}
} finally {
scope.release();
scope.close();
}
},
});
@@ -474,7 +480,7 @@ class EncodedBodyLimitError extends Error {}
async function readBoundedBody(
response: Response,
maximumBytes: number,
signal: AbortSignal,
scope: AbortableOperation,
): Promise<Uint8Array> {
if (!response.body) {
throw new TypeError("Image response body is unavailable.");
@@ -484,8 +490,9 @@ async function readBoundedBody(
let total = 0;
try {
while (true) {
if (signal.aborted) throw abortException();
const next = await readOrAbort(reader.read(), signal);
if (scope.signal.aborted) throw abortException();
// A late chunk is dropped: the bytes are only accumulated below.
const next = await awaitOwned(scope, reader.read(), () => undefined);
if (next.done) break;
if (!(next.value instanceof Uint8Array)) {
throw new TypeError("Image response chunk is invalid.");
@@ -515,90 +522,28 @@ async function readBoundedBody(
return bytes;
}
type ProbeAbortScope = Readonly<{
signal: AbortSignal;
/** True once a deadline, or a deadline that could not be installed, ended it. */
timedOut(): boolean;
/**
* Awaits `task` under this scope's ownership. A late value is compensated
* exactly once; a terminal owner raises the scope's abort exception.
*/
await<Value>(
task: Promise<Value>,
onLateValue: (value: Value) => void,
): Promise<Value>;
release(): void;
}>;
/**
* X-AUDIT-02 / TR-RR-05. The probe scope is the shared abort primitive with
* this subsystem's vocabulary on top. Owning a private copy meant the caller
* listener was attached before the timer was installed, so a scheduler that
* threw rejected the public `probe()` promise and left the listener behind.
* `CLOSED` here means the deadline could never be installed, so the probe was
* never bounded: operationally the same unanswered host as a deadline.
*/
function createProbeAbortScope(
externalSignal: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
): ProbeAbortScope {
const operation = createAbortableOperation({
signal: externalSignal,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
return Object.freeze({
signal: operation.signal,
// `CLOSED` here means the deadline could never be installed, so the probe
// was never bounded: operationally the same unanswered host as a deadline.
timedOut: () =>
operation.terminal() !== "CALLER_ABORT" && operation.terminal() !== null,
async await<Value>(
task: Promise<Value>,
onLateValue: (value: Value) => void,
): Promise<Value> {
const raced = await operation.race(task, onLateValue);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
},
release: () => operation.close(),
});
function unanswered(scope: AbortableOperation): boolean {
const terminal = scope.terminal();
return terminal !== null && terminal !== "CALLER_ABORT";
}
/**
* A single read raced against the probe's ownership. A late chunk is dropped:
* the bytes are only ever accumulated by the caller below.
* Awaits `task` under the probe's ownership. A late value is compensated
* exactly once; a terminal owner raises the probe's abort exception.
*/
function readOrAbort<Value>(
async function awaitOwned<Value>(
scope: AbortableOperation,
task: Promise<Value>,
signal: AbortSignal,
onLateValue: (value: Value) => void,
): Promise<Value> {
return new Promise<Value>((resolve, reject) => {
let settled = false;
const onAbort = () => {
if (settled) return;
settled = true;
reject(abortException());
};
signal.addEventListener("abort", onAbort, { once: true });
void task.then(
(value) => {
signal.removeEventListener("abort", onAbort);
if (!settled) {
settled = true;
resolve(value);
}
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
if (!settled) {
settled = true;
reject(error);
}
},
);
});
const raced = await scope.race(task, onLateValue);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
}
function signalFailure(externalSignal: AbortSignal) {
@@ -612,25 +557,6 @@ function signalFailure(externalSignal: AbortSignal) {
});
}
function cancelResponseBody(response: Response): void {
try {
const cancellation = response.body?.cancel();
void cancellation?.catch(() => undefined);
} catch {
// Best-effort release cannot change the closed probe result.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => undefined);
} catch {
// Best-effort release cannot change the closed probe result.
}
}
function closeBitmap(bitmap: DecodedImageFacade): void {
try {
bitmap.close();
@@ -682,7 +608,3 @@ function isRasterMediaType(
"image/webp",
].includes(value);
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -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) ||
@@ -485,6 +490,10 @@ function snapshotPreset(
"strict-origin-when-cross-origin",
].includes(input.referrerPolicy) ||
!["NONE", "PRIMARY_REQUIRED"].includes(input.probeMode) ||
// Q-6.1-7 / D-12. The probe expects the exact primary pixel size, which
// only these fits produce; inside/outside keep the source ratio.
(input.probeMode === "PRIMARY_REQUIRED" &&
!["cover", "contain", "fill"].includes(input.fit)) ||
typeof input.allowUpscale !== "boolean" ||
!positiveSafeInteger(input.maxTransformedPixels) ||
input.maxTransformedPixels > hardLimits.maxTransformedPixels ||
@@ -722,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[],
@@ -744,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;
});
}
@@ -5,7 +5,6 @@ import type {
ImageCdnRuntime,
ImageOutputFormat,
ImagePresentationDescriptor,
ImagePresetReference,
ImageProbeReceipt,
ImageRasterMediaType,
ImageResourceProbePort,
@@ -20,6 +19,12 @@ import {
browserDataSuccess,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
import {
createAbortableOperation,
snapshotAbortTimers,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import { countBucket } from "../presigned/http-common.ts";
import {
IMAGE_FORMAT_MEDIA_TYPE,
type ImageCandidateGeometry,
@@ -37,6 +42,13 @@ export type ImageCdnRuntimeDependencies = Readonly<{
capabilityVerificationTimeoutMs?: number;
capabilityVerificationScheduler?: ImageCapabilityVerificationScheduler;
probe?: ImageResourceProbePort;
/**
* 01-11. Most probes in flight at once. Each downloads and decodes up to the
* preset's encoded and decoded byte budgets, so a screen of private images
* would otherwise hold all of them in memory together. Later calls wait for
* a slot. Default 4, at most 32.
*/
maxConcurrentProbes?: number;
observer?: BrowserDataObserver;
}>;
@@ -71,6 +83,7 @@ type IssuedDescriptorSnapshot = BackendIssuedImageAsset;
const OPAQUE_TOKEN = /^[A-Za-z0-9_-]{8,128}$/u;
const SIGNATURE = /^[A-Za-z0-9_-]{16,512}$/u;
const SHA256_HEX = /^[a-f0-9]{64}$/u;
const REGISTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
const PUBLIC_DESCRIPTOR_KEYS = Object.freeze([
"kind",
"originKey",
@@ -145,19 +158,18 @@ export function createImageCdnRuntime(
dependencies.capabilityVerifier,
);
if (dependencies.capabilityVerifier) {
let covered = false;
try {
if (
!verifyCapability ||
!acceptsCapabilityKey ||
[...capabilityPolicy.acceptedKeyIds].some(
(keyId) => acceptsCapabilityKey(keyId) !== true,
)
) {
throw new TypeError(
"Image capability verifier registry does not cover policy keys.",
covered =
!!verifyCapability &&
!!acceptsCapabilityKey &&
[...capabilityPolicy.acceptedKeyIds].every(
(keyId) => acceptsCapabilityKey(keyId) === true,
);
}
} catch {
// A throwing registry covers nothing.
}
if (!covered) {
throw new TypeError(
"Image capability verifier registry does not cover policy keys.",
);
@@ -176,17 +188,69 @@ export function createImageCdnRuntime(
"Image capability verification timeout is invalid.",
);
}
const capabilityVerificationScheduler =
const capabilityVerificationTimers =
snapshotCapabilityVerificationScheduler(
dependencies.capabilityVerificationScheduler ??
defaultCapabilityVerificationScheduler(),
dependencies.capabilityVerificationScheduler ?? globalThis,
);
const probe =
dependencies.probe?.probe.bind(dependencies.probe);
const maxConcurrentProbes = dependencies.maxConcurrentProbes ?? 4;
if (
!Number.isSafeInteger(maxConcurrentProbes) ||
maxConcurrentProbes < 1 ||
maxConcurrentProbes > 32
) {
throw new TypeError("Image probe concurrency is invalid.");
}
let activeProbes = 0;
const probeWaiters: (() => void)[] = [];
const acquireProbeSlot = (): Promise<void> => {
if (activeProbes < maxConcurrentProbes) {
activeProbes += 1;
return Promise.resolve();
}
return new Promise((resolve) => {
probeWaiters.push(() => {
activeProbes += 1;
resolve();
});
});
};
const releaseProbeSlot = (): void => {
activeProbes -= 1;
probeWaiters.shift()?.();
};
/**
* 01-11. Asset+preset pairs whose primary candidate already passed a probe.
* `resolve()` re-checks capability expiry on every call, so a pass is reused
* only while the capability is still valid.
*/
const passedProbes = new WeakMap<
AssetSnapshot,
Set<ResolvedImageCdnPreset>
>();
const observer = snapshotObserver(dependencies.observer);
let acceptedAssets =
new WeakMap<ImageAssetReference, AssetSnapshot>();
const lifetime = new AbortController();
// Every in-flight operation, so `close()` ends the physical work too.
const lifetime = new Set<AbortableOperation>();
const openOperation = (
signal: AbortSignal | undefined,
timeoutMs?: number,
): AbortableOperation => {
const operation = createAbortableOperation({
signal,
timeoutMs,
...capabilityVerificationTimers,
});
if (closed) operation.close();
else lifetime.add(operation);
return operation;
};
const closeOperation = (operation: AbortableOperation): void => {
lifetime.delete(operation);
operation.close();
};
let activeCapabilityVerifications = 0;
let closed = false;
@@ -333,12 +397,11 @@ export function createImageCdnRuntime(
canonicalImageCapabilityPayload(snapshot);
let bindingDigest: string;
let verified: boolean;
let deadline: ImageCapabilityVerificationDeadline;
let deadline: AbortableOperation;
try {
deadline = createCapabilityVerificationDeadline(
[options.signal, lifetime.signal],
deadline = openOperation(
options.signal,
capabilityVerificationTimeoutMs,
capabilityVerificationScheduler,
);
} catch {
return browserDataFailure("UNAVAILABLE", "IMAGE_RESOLVE", {
@@ -352,10 +415,7 @@ export function createImageCdnRuntime(
}
const digestTask = sha256Hex(digest, canonicalPayload);
rawVerificationTasks.push(digestTask);
bindingDigest = await awaitImageRuntimeAbort(
digestTask,
deadline.signal,
);
bindingDigest = await raceImageRuntime(deadline, digestTask);
if (
!constantTimeHexEqual(
bindingDigest,
@@ -377,15 +437,12 @@ export function createImageCdnRuntime(
signatureBase64Url: snapshot.signature.valueBase64Url,
});
rawVerificationTasks.push(verifyTask);
verified = await awaitImageRuntimeAbort(
verifyTask,
deadline.signal,
);
verified = await raceImageRuntime(deadline, verifyTask);
} catch {
if (closed) return imageRuntimeClosedFailure();
return capabilityVerificationFailure(options.signal);
} finally {
deadline.release();
closeOperation(deadline);
}
if (closed) return imageRuntimeClosedFailure();
if (options.signal?.aborted) {
@@ -526,19 +583,27 @@ export function createImageCdnRuntime(
return browserDataFailure("POLICY_REJECTED", "IMAGE_RESOLVE");
}
if (preset.probeMode === "PRIMARY_REQUIRED") {
if (
preset.probeMode === "PRIMARY_REQUIRED" &&
!passedProbes.get(asset)?.has(preset)
) {
if (!probe || !request.signal) {
return browserDataFailure("UNSUPPORTED", "IMAGE_RESOLVE");
}
const primary = primaryCandidate(preset);
let probeResult: BrowserDataResult<ImageProbeReceipt>;
const probeScope = combineImageRuntimeAbortSignals([
request.signal,
lifetime.signal,
]);
const probeScope = openOperation(request.signal);
try {
probeResult = await awaitImageRuntimeAbort(
probe({
const slot = await probeScope.race(
acquireProbeSlot(),
releaseProbeSlot,
);
if (slot.kind !== "VALUE") {
throw capabilityVerificationAbortException();
}
let task: Promise<BrowserDataResult<ImageProbeReceipt>>;
try {
task = Promise.resolve(probe({
absoluteUrl: descriptor.src,
expectedMediaType: descriptor.fallbackMediaType,
expectedWidth: primary.pixelWidth,
@@ -551,9 +616,14 @@ export function createImageCdnRuntime(
asset.origin.minimumPublicMaxAgeSeconds,
referrerPolicy: descriptor.referrerPolicy,
signal: probeScope.signal,
}),
probeScope.signal,
);
}));
} catch (error) {
task = Promise.reject(error);
}
// The slot belongs to the raw probe, not to this wrapper (as for
// capability verification, TR-RR-07).
void task.then(releaseProbeSlot, releaseProbeSlot);
probeResult = await raceImageRuntime(probeScope, task);
} catch {
probeResult = closed
? imageRuntimeClosedFailure()
@@ -564,7 +634,7 @@ export function createImageCdnRuntime(
recovery: "RETRY",
});
} finally {
probeScope.release();
closeOperation(probeScope);
}
if (closed) probeResult = imageRuntimeClosedFailure();
observeImageTerminal(
@@ -599,6 +669,10 @@ export function createImageCdnRuntime(
hardLimits.minCapabilityRemainingMs,
);
if (postProbeExpiry) return postProbeExpiry;
passedProbes.set(
asset,
(passedProbes.get(asset) ?? new Set()).add(preset),
);
}
if (closed) return imageRuntimeClosedFailure();
@@ -629,7 +703,8 @@ export function createImageCdnRuntime(
close(): void {
if (closed) return;
closed = true;
lifetime.abort();
for (const operation of lifetime) operation.close();
lifetime.clear();
acceptedAssets =
new WeakMap<ImageAssetReference, AssetSnapshot>();
},
@@ -943,17 +1018,11 @@ function snapshotIssuedDescriptor(
allowedPresetBindingIds.some(
(bindingId) =>
typeof bindingId !== "string" ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
bindingId,
),
!REGISTRY_ID.test(bindingId),
) ||
snapshot.signature.algorithm !== "ECDSA_P256_SHA256" ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
snapshot.issuer,
) ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
snapshot.signature.keyId,
) ||
!REGISTRY_ID.test(snapshot.issuer) ||
!REGISTRY_ID.test(snapshot.signature.keyId) ||
!SHA256_HEX.test(
snapshot.signature.capabilityBindingDigestHex,
) ||
@@ -1052,114 +1121,16 @@ function safeNow(now: () => number): number | null {
}
}
type ImageCapabilityVerificationDeadline = Readonly<{
signal: AbortSignal;
release(): void;
}>;
function createCapabilityVerificationDeadline(
signals: readonly (AbortSignal | undefined)[],
timeoutMs: number,
scheduler: ImageCapabilityVerificationScheduler,
): ImageCapabilityVerificationDeadline {
const controller = new AbortController();
let released = false;
const abortListeners = new Map<AbortSignal, () => void>();
const activeSignals = signals.filter(
(signal): signal is AbortSignal => signal !== undefined,
);
for (const signal of new Set(activeSignals)) {
const onAbort = () => controller.abort(signal.reason);
abortListeners.set(signal, onAbort);
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
}
let timeoutHandle: unknown;
try {
timeoutHandle = scheduler.setTimeout(() => {
if (released) return;
controller.abort(capabilityVerificationAbortException());
}, timeoutMs);
} catch (error) {
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
throw error;
}
return Object.freeze({
signal: controller.signal,
release() {
if (released) return;
released = true;
try {
scheduler.clearTimeout(timeoutHandle);
} catch {
// Scheduler cleanup cannot alter an already closed adapter result.
}
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
abortListeners.clear();
},
});
}
function awaitImageRuntimeAbort<Value>(
/** Settles with the task's own outcome, or rejects once the operation ends. */
async function raceImageRuntime<Value>(
operation: AbortableOperation,
task: Promise<Value>,
signal: AbortSignal,
): Promise<Value> {
return new Promise<Value>((resolve, reject) => {
let settled = false;
const onAbort = () => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
reject(capabilityVerificationAbortException());
};
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
void task.then(
(value) => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
resolve(value);
},
(error: unknown) => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function combineImageRuntimeAbortSignals(
signals: readonly AbortSignal[],
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abortListeners = new Map<AbortSignal, () => void>();
for (const signal of new Set(signals)) {
const onAbort = () => controller.abort(signal.reason);
abortListeners.set(signal, onAbort);
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
}
let released = false;
return Object.freeze({
signal: controller.signal,
release() {
if (released) return;
released = true;
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
abortListeners.clear();
},
});
const outcome = await operation.race(task);
if (outcome.kind === "VALUE") return outcome.value;
throw outcome.kind === "REJECTED"
? outcome.reason
: capabilityVerificationAbortException();
}
function capabilityVerificationFailure(
@@ -1187,35 +1158,14 @@ function capabilityVerificationAbortException(): DOMException {
function snapshotCapabilityVerificationScheduler(
scheduler: ImageCapabilityVerificationScheduler,
): ImageCapabilityVerificationScheduler {
if (
!scheduler ||
typeof scheduler.setTimeout !== "function" ||
typeof scheduler.clearTimeout !== "function"
) {
) {
try {
return snapshotAbortTimers(scheduler);
} catch {
throw new TypeError(
"Image capability verification scheduler is invalid.",
);
}
return Object.freeze({
setTimeout: scheduler.setTimeout.bind(scheduler),
clearTimeout: scheduler.clearTimeout.bind(scheduler),
});
}
function defaultCapabilityVerificationScheduler(): ImageCapabilityVerificationScheduler {
const schedule = globalThis.setTimeout.bind(globalThis);
const clear = globalThis.clearTimeout.bind(globalThis);
return Object.freeze({
setTimeout(callback: () => void, milliseconds: number) {
return schedule(callback, milliseconds);
},
clearTimeout(handle: unknown) {
clear(
handle as ReturnType<typeof globalThis.setTimeout>,
);
},
});
}
function createAssetReference(): ImageAssetReference {
@@ -1262,16 +1212,6 @@ function observeImageTerminal<Value>(
return result;
}
function countBucket(
value: number,
): "ZERO" | "ONE" | "TWO_TO_TEN" | "ELEVEN_TO_HUNDRED" | "GT_HUNDRED" {
if (value <= 0) return "ZERO";
if (value === 1) return "ONE";
if (value <= 10) return "TWO_TO_TEN";
if (value <= 100) return "ELEVEN_TO_HUNDRED";
return "GT_HUNDRED";
}
function byteBucket(
value: number,
): "ZERO" | "LT1MIB" | "1_TO_9MIB" | "10_TO_99MIB" | "GTE100MIB" {
@@ -73,8 +73,6 @@ function parsePng(
const interlace = bytes[payloadStart + 12];
if (
!dimensions ||
bitDepth === undefined ||
colorType === undefined ||
!validPngColorDepth(colorType, bitDepth) ||
compression !== 0 ||
filter !== 0 ||
@@ -144,7 +142,7 @@ function parseJpeg(
if (offset >= bytes.byteLength) return null;
const marker = bytes[offset];
offset += 1;
if (marker === undefined || marker === 0x00) return null;
if (marker === 0x00) return null;
if (marker === 0xd9) return null;
if (marker === 0xda) return dimensions;
if (
@@ -227,7 +225,6 @@ function parseWebp(
chunkIndex !== 0 ||
extendedHeaderSeen ||
length !== 10 ||
bytes[payloadStart] === undefined ||
(bytes[payloadStart] & 0xc3) !== 0
) {
return null;
@@ -260,15 +257,7 @@ function parseWebp(
const byte2 = bytes[payloadStart + 2];
const byte3 = bytes[payloadStart + 3];
const byte4 = bytes[payloadStart + 4];
if (
byte1 === undefined ||
byte2 === undefined ||
byte3 === undefined ||
byte4 === undefined ||
(byte4 & 0xe0) !== 0
) {
return null;
}
if ((byte4 & 0xe0) !== 0) return null;
candidate = validDimensions(
1 + byte1 + ((byte2 & 0x3f) << 8),
1 +
@@ -306,14 +295,8 @@ function parseAvif(
return null;
}
const fileType = boxes[0];
const fileTypeLength = fileType
? fileType.payloadEnd - fileType.payloadStart
: 0;
if (
!fileType ||
fileTypeLength < 8 ||
(fileTypeLength - 8) % 4 !== 0
) {
const fileTypeLength = fileType.payloadEnd - fileType.payloadStart;
if (fileTypeLength < 8 || (fileTypeLength - 8) % 4 !== 0) {
return null;
}
const brands: string[] = [
@@ -343,7 +326,6 @@ function parseAvif(
const metadataBox = metadataBoxes[0];
if (
metadataBoxes.length !== 1 ||
!metadataBox ||
metadataBox.payloadStart + 4 > metadataBox.payloadEnd ||
!zeroFullBoxFlags(bytes, metadataBox.payloadStart)
) {
@@ -413,9 +395,7 @@ function parseAvif(
const dimensions = state.properties.get(propertyIndex);
if (dimensions) associatedExtents.push(dimensions);
}
return associatedExtents.length === 1
? (associatedExtents[0] ?? null)
: null;
return associatedExtents.length === 1 ? associatedExtents[0] : null;
}
type IsoBox = Readonly<{
@@ -532,11 +512,7 @@ function parseAvifItemProperties(
(child) => child.type === "ipma",
);
const propertyContainer = propertyContainers[0];
if (
propertyContainers.length !== 1 ||
associationBoxes.length < 1 ||
!propertyContainer
) {
if (propertyContainers.length !== 1 || associationBoxes.length < 1) {
return false;
}
const properties = parseBoxes(
@@ -581,9 +557,7 @@ function parseAvifPropertyAssociations(
const version = bytes[start];
if (version !== 0 && version !== 1) return false;
const flags =
((bytes[start + 1] ?? 0) << 16) |
((bytes[start + 2] ?? 0) << 8) |
(bytes[start + 3] ?? 0);
(bytes[start + 1] << 16) | (bytes[start + 2] << 8) | bytes[start + 3];
if ((flags & ~1) !== 0) return false;
const wideAssociation = (flags & 1) === 1;
const view = dataView(bytes);
@@ -598,7 +572,6 @@ function parseAvifPropertyAssociations(
: view.getUint32(offset);
offset += itemIdBytes;
const associationCount = bytes[offset];
if (associationCount === undefined) return false;
offset += 1;
const propertyIndices: number[] = [];
for (
@@ -609,9 +582,7 @@ function parseAvifPropertyAssociations(
const associationBytes = wideAssociation ? 2 : 1;
if (offset + associationBytes > end) return false;
const encoded =
associationBytes === 2
? view.getUint16(offset)
: (bytes[offset] ?? 0);
associationBytes === 2 ? view.getUint16(offset) : bytes[offset];
const propertyIndex =
encoded & (wideAssociation ? 0x7fff : 0x7f);
offset += associationBytes;
@@ -694,35 +665,23 @@ function validDimensions(
: null;
}
/** Callers pass an offset whose three bytes lie inside a checked chunk. */
function readUint24LittleEndian(
bytes: Uint8Array,
offset: number,
): number {
const byte0 = bytes[offset];
const byte1 = bytes[offset + 1];
const byte2 = bytes[offset + 2];
if (
byte0 === undefined ||
byte1 === undefined ||
byte2 === undefined
) {
return Number.NaN;
}
return byte0 | (byte1 << 8) | (byte2 << 16);
return (
bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16)
);
}
/** Callers pass a range that the surrounding length checks keep in bounds. */
function ascii(
bytes: Uint8Array,
start: number,
end: number,
): string {
let value = "";
for (let offset = start; offset < end; offset += 1) {
const byte = bytes[offset];
if (byte === undefined) return "";
value += String.fromCharCode(byte);
}
return value;
return String.fromCharCode(...bytes.subarray(start, end));
}
function dataView(bytes: Uint8Array): DataView {
@@ -87,8 +87,7 @@ export function createP256ImageCapabilityVerifier(
return false;
}
try {
const signatureBytes = new Uint8Array(signature.byteLength);
signatureBytes.set(signature);
// `decodeBase64Url` already returns an owned, exactly sized buffer.
const payloadBytes = new Uint8Array(
request.canonicalPayload.byteLength,
);
@@ -96,7 +95,7 @@ export function createP256ImageCapabilityVerifier(
return await verify(
{ name: "ECDSA", hash: "SHA-256" },
key,
signatureBytes.buffer,
signature.buffer,
payloadBytes.buffer,
);
} catch {
@@ -106,7 +105,7 @@ export function createP256ImageCapabilityVerifier(
});
}
function decodeBase64Url(value: string): Uint8Array | null {
function decodeBase64Url(value: string): Uint8Array<ArrayBuffer> | null {
if (
!/^[A-Za-z0-9_-]+$/u.test(value) ||
value.length % 4 === 1
@@ -119,9 +118,8 @@ function decodeBase64Url(value: string): Uint8Array | null {
let accumulator = 0;
let bitCount = 0;
for (const character of value) {
const index = alphabet.indexOf(character);
if (index < 0) return null;
accumulator = (accumulator << 6) | index;
// The pattern above admits only alphabet characters.
accumulator = (accumulator << 6) | alphabet.indexOf(character);
bitCount += 6;
if (bitCount >= 8) {
bitCount -= 8;
@@ -0,0 +1,257 @@
import {
createAbortableOperation,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataOperation,
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,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
/**
* Q-6.1-9. HTTP mechanics shared by the presigned executor (object-store
* GET/PUT) and the capability provider (BFF issuance). They were two
* 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");
export type PresignedAbortScope = ReturnType<typeof createAbortScope>;
/**
* TR-RR-01 / TR-RR-05. A thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* `abort()` exists, so `close()` on a download can actually stop a pending
* fetch instead of only dropping listeners; and additional ownership signals —
* a consumer's stream signal — are composed into the same operation *before*
* any I/O starts, so an already-aborted consumer never causes a fetch.
*/
export function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
consumer?: AbortSignal,
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
let release = () => {};
if (consumer?.aborted) operation.close();
else if (consumer) {
const onAbort = () => operation.close();
try {
consumer.addEventListener("abort", onAbort, { once: true });
release = () => {
try {
consumer.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
};
} catch {
// A signal that refuses a listener cannot bound this operation, so the
// operation closes rather than running unbounded.
operation.close();
}
}
const end = () => {
operation.close();
release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
/** Bounds a fetch that ignores its signal; a late response is cancelled. */
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort: end,
release: end,
});
}
/**
* 01-03. `idleTimeoutMs` bounds this one read, so a stream that stops making
* progress ends there with a `TimeoutError` while a slow one keeps going.
*/
export async function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
idleTimeoutMs?: number,
timers?: AbortTimerSnapshot,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) throw new DOMException("Aborted", "AbortError");
const operation = createAbortableOperation({
signal,
timeoutMs: idleTimeoutMs,
setTimer: timers?.setTimer,
clearTimer: timers?.clearTimer,
});
const outcome = await operation.race(reader.read());
operation.close();
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
throw outcome.terminal === "DEADLINE"
? new DOMException("No progress", "TimeoutError")
: new DOMException("Aborted", "AbortError");
}
/**
* 01-03. Time a transfer of `byteLength` needs at the slowest supported
* throughput, added to a fixed base deadline.
*/
export function transferAllowanceMs(
byteLength: number,
minTransferBytesPerSecond: number,
): number {
return Math.ceil((byteLength * 1000) / minTransferBytesPerSecond);
}
/**
* A plain decimal `Content-Length`. `Number()` alone accepted `"5e0"`,
* `"0x5"`, `"+5"` and `""`. An absent header is `null` unless the caller's
* binding allows an implicit zero.
*/
export function normalizedContentLength(
value: string | null,
allowImplicitZero = false,
): number | null {
if (value === null) return allowImplicitZero ? 0 : null;
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
/**
* One status table for both HTTP exchanges. Presigned capabilities are
* single-use, so every recoverable refusal — an expired or rejected signature
* (401/403), a conflict, a gone resource or a transient 429/5xx — is recovered
* by issuing a new capability, never by replaying the same one.
*/
export function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
export function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
export function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
/**
* One terminal observation for presigned and resumable transfers. An absent or
* invalid byte length leaves `byteBucket` out rather than guessing one.
* 01-10. `attempts`, when given, is the retry count as a `countBucket`.
*/
export function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: Result<unknown, Readonly<{ code: BrowserDataFailureCode }>>,
byteLength?: number,
attempts?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
...(attempts !== undefined ? { countBucket: countBucket(attempts) } : {}),
});
}
export function countBucket(
value: number,
): "ZERO" | "ONE" | "TWO_TO_TEN" | "ELEVEN_TO_HUNDRED" | "GT_HUNDRED" {
if (value <= 0) return "ZERO";
if (value === 1) return "ONE";
if (value <= 10) return "TWO_TO_TEN";
if (value <= 100) return "ELEVEN_TO_HUNDRED";
return "GT_HUNDRED";
}
@@ -126,8 +126,8 @@ class Sha256Accumulator {
words[index] = view.getUint32(index * 4, false);
}
for (let index = 16; index < 64; index += 1) {
const previous15 = words[index - 15] ?? 0;
const previous2 = words[index - 2] ?? 0;
const previous15 = words[index - 15];
const previous2 = words[index - 2];
const sigma0 =
rotateRight(previous15, 7) ^
rotateRight(previous15, 18) ^
@@ -136,22 +136,18 @@ class Sha256Accumulator {
rotateRight(previous2, 17) ^
rotateRight(previous2, 19) ^
(previous2 >>> 10);
words[index] =
((words[index - 16] ?? 0) +
sigma0 +
(words[index - 7] ?? 0) +
sigma1) >>>
0;
// A Uint32Array store already reduces modulo 2^32.
words[index] = words[index - 16] + sigma0 + words[index - 7] + sigma1;
}
let a = this.#state[0] ?? 0;
let b = this.#state[1] ?? 0;
let c = this.#state[2] ?? 0;
let d = this.#state[3] ?? 0;
let e = this.#state[4] ?? 0;
let f = this.#state[5] ?? 0;
let g = this.#state[6] ?? 0;
let h = this.#state[7] ?? 0;
let a = this.#state[0];
let b = this.#state[1];
let c = this.#state[2];
let d = this.#state[3];
let e = this.#state[4];
let f = this.#state[5];
let g = this.#state[6];
let h = this.#state[7];
for (let index = 0; index < 64; index += 1) {
const sum1 =
@@ -161,8 +157,8 @@ class Sha256Accumulator {
(h +
sum1 +
choice +
(ROUND_CONSTANTS[index] ?? 0) +
(words[index] ?? 0)) >>>
ROUND_CONSTANTS[index] +
words[index]) >>>
0;
const sum0 =
rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
@@ -178,14 +174,15 @@ class Sha256Accumulator {
a = (temporary1 + temporary2) >>> 0;
}
this.#state[0] = ((this.#state[0] ?? 0) + a) >>> 0;
this.#state[1] = ((this.#state[1] ?? 0) + b) >>> 0;
this.#state[2] = ((this.#state[2] ?? 0) + c) >>> 0;
this.#state[3] = ((this.#state[3] ?? 0) + d) >>> 0;
this.#state[4] = ((this.#state[4] ?? 0) + e) >>> 0;
this.#state[5] = ((this.#state[5] ?? 0) + f) >>> 0;
this.#state[6] = ((this.#state[6] ?? 0) + g) >>> 0;
this.#state[7] = ((this.#state[7] ?? 0) + h) >>> 0;
const state = this.#state;
state[0] += a;
state[1] += b;
state[2] += c;
state[3] += d;
state[4] += e;
state[5] += f;
state[6] += g;
state[7] += h;
}
}
@@ -11,31 +11,40 @@ import type {
PresignedUploadPartCapabilityProvider,
} from "../../../application/ports/browser-transfer/presigned-transfer.ts";
import {
createAbortableOperation,
cancelBody,
cancelReader,
snapshotAbortTimers,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataRecovery,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
import type {
PresignedCapabilityRegistration,
PresignedCapabilityVault,
PresignedHeaderBinding,
} from "./presigned-capability-vault.ts";
import {
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
transferFailure,
} from "./http-common.ts";
import {
SAFE_TRANSFER_ID,
SHA256_HEX as SHA256,
} from "../resumable-upload/checkpoint-schema.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
const OPAQUE_ID = /^[a-z0-9][a-z0-9._:-]{0,255}$/i;
const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
const QUERY_NAME = /^[A-Za-z0-9_.~-]{1,128}$/;
const FORBIDDEN_REQUEST_HEADERS = new Set([
@@ -78,6 +87,14 @@ export type PresignedCapabilityHttpProviderOptions = Readonly<{
* with a token that is predictably going to expire in flight.
*/
minimumRemainingLifetimeMs: number;
/**
* 01-06. How far the device clock may trail the server's. A capability is
* refused as too long-lived only past `maxCapabilityTtlMs` plus this.
* Default 60 s. The lower bound is not relaxed: a server lifetime must be at
* least `minimumRemainingLifetimeMs + maxClockSkewMs` to survive a device
* clock running that far ahead.
*/
maxClockSkewMs?: number;
timeoutMs: number;
maxCapabilityResponseBytes?: number;
fetcher?: typeof fetch;
@@ -134,6 +151,10 @@ export function createPresignedCapabilityHttpProvider(
options.minimumRemainingLifetimeMs,
"Presigned capability minimum remaining lifetime",
);
const maxClockSkewMs = options.maxClockSkewMs ?? 60_000;
if (!Number.isSafeInteger(maxClockSkewMs) || maxClockSkewMs < 0) {
throw new TypeError("Presigned capability clock skew is invalid.");
}
if (minimumRemainingLifetimeMs > maxCapabilityTtlMs) {
throw new TypeError(
"Presigned capability minimum remaining lifetime exceeds its TTL.",
@@ -170,15 +191,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;
}
@@ -237,11 +255,11 @@ export function createPresignedCapabilityHttpProvider(
response.type === "opaqueredirect" ||
response.url !== endpoint
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER");
}
if (!response.ok || response.status !== 200) {
cancelResponseBody(response);
cancelBody(response);
return statusFailure(response.status);
}
const contentType = response.headers.get("content-type") ?? "";
@@ -249,7 +267,7 @@ export function createPresignedCapabilityHttpProvider(
contentType.split(";", 1)[0]?.trim().toLowerCase() !==
"application/json"
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER");
}
const payload = await readBoundedJson(
@@ -261,7 +279,7 @@ export function createPresignedCapabilityHttpProvider(
expected,
hardMaxTransferBytes,
hardMaxUploadResponseBytes,
maxCapabilityTtlMs,
maxCapabilityTtlMs: maxCapabilityTtlMs + maxClockSkewMs,
minimumRemainingLifetimeMs,
nowEpochMs: now(),
allowedDataOrigins,
@@ -762,11 +780,11 @@ async function readBoundedJson(
if (declared !== null) {
declaredLength = normalizedContentLength(declared);
if (declaredLength === null) {
cancelResponseBody(response);
cancelBody(response);
throw new ResponseIntegrityError();
}
if (declaredLength > maxBytes) {
cancelResponseBody(response);
cancelBody(response);
throw new ResponseLimitError();
}
}
@@ -797,15 +815,7 @@ async function readBoundedJson(
text += decoder.decode();
return JSON.parse(text) as unknown;
} finally {
if (!completed) {
try {
void reader.cancel().catch(() => {
// Response cancellation is best effort after classification.
});
} catch {
// Response cleanup cannot alter the closed result.
}
}
if (!completed) cancelReader(reader);
try {
reader.releaseLock();
} catch {
@@ -814,223 +824,6 @@ async function readBoundedJson(
}
}
function cancelResponseBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Cancellation is best effort after the response is classified.
});
} catch {
// Response cleanup cannot alter the closed result.
}
}
function normalizedContentLength(value: string): number | null {
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () =>
reject(new DOMException("Aborted", "AbortError"));
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "RETRY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "NONE";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-capability-scope-ended");
/**
* TR-RR-01 / TR-RR-05. The abort scope is a thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* Two things changed with the migration. `abort()` exists, so `close()` on a
* download can actually stop a pending fetch instead of only dropping
* listeners; and additional ownership signals — a consumer's stream signal —
* are composed into the same operation *before* any I/O starts, so an
* already-aborted consumer never causes a fetch.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
// A signal that refuses a listener cannot bound this operation, so the
// operation closes rather than running unbounded.
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
/** Bounds a fetch that ignores its signal. */
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(
task,
(value) => compensateLateResponseValue(value),
);
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function compensateLateResponseValue(value: unknown): void {
const body = (value as { body?: { cancel(): Promise<void> } | null } | null)
?.body;
void body?.cancel().catch(() => undefined);
}
function transferFailure(
signal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (signal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{ retryable: true, recovery: "REISSUE_CAPABILITY" },
);
}
function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
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";
}
function strictRecord(
value: unknown,
keys: readonly string[],
@@ -1116,8 +909,8 @@ function normalizedSha256(value: unknown): string {
}
function snapshotOpaqueId(value: unknown, name: string): string {
const id = requiredString(value, 256);
if (!OPAQUE_ID.test(id)) throw new TypeError(`${name} is invalid.`);
const id = requiredString(value, 512);
if (!SAFE_TRANSFER_ID.test(id)) throw new TypeError(`${name} is invalid.`);
return id;
}
@@ -275,18 +275,14 @@ export function createPresignedCapabilityVault(options: Readonly<{
const invalid = validatePresignedCapabilityRegistration(snapshot);
if (invalid) return invalid;
pruneExpired();
if (
byReceipt.has(registration.capabilityReceipt) ||
byReceipt.size >= maxActiveCapabilities
) {
// Q-6.1-11. The duplicate check reads the snapshot too; the issuer's
// object is never read again once the snapshot exists.
const duplicate = byReceipt.has(snapshot.capabilityReceipt);
if (duplicate || byReceipt.size >= maxActiveCapabilities) {
return browserDataFailure(
byReceipt.has(registration.capabilityReceipt)
? "CONFLICT"
: "LIMIT_EXCEEDED",
duplicate ? "CONFLICT" : "LIMIT_EXCEEDED",
"PRESIGNED_TRANSFER",
byReceipt.has(registration.capabilityReceipt)
? { recovery: "REISSUE_CAPABILITY" }
: undefined,
duplicate ? { recovery: "REISSUE_CAPABILITY" } : undefined,
);
}
@@ -9,15 +9,14 @@ import type {
PresignedUploadPartPort,
} from "../../../application/ports/browser-transfer/presigned-transfer.ts";
import {
createAbortableOperation,
cancelBody,
cancelReader,
snapshotAbortTimers,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataOperation,
BrowserDataRecovery,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
@@ -34,9 +33,24 @@ import type {
PresignedCapabilityBinding,
PresignedCapabilityVault,
} from "./presigned-capability-vault.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const RECEIPT_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/;
import {
byteBucket,
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
transferAllowanceMs,
transferFailure,
type PresignedAbortScope,
} from "./http-common.ts";
import {
isSafeUploadReceiptToken,
SAFE_TRANSFER_ID,
SHA256_HEX as SHA256,
} from "../resumable-upload/checkpoint-schema.ts";
type Scheduler = Readonly<{
setTimeout(callback: () => void, milliseconds: number): unknown;
@@ -50,7 +64,20 @@ export type PresignedTransferExecutorOptions = Readonly<{
hardMaxChunkBytes: number;
hardMaxUploadResponseBytes: number;
minimumRemainingLifetimeMs: number;
/**
* Base deadline of one PUT or one download. 01-03: the transfer's bytes at
* `minTransferBytesPerSecond` are added on top, so the limit grows with the
* payload instead of stranding a slow connection.
*/
timeoutMs: number;
/** 01-03. Slowest supported throughput. Default 64 KiB/s (~0.5 Mbit/s). */
minTransferBytesPerSecond?: number;
/**
* 01-03. Longest wait for the next download chunk. A stream that stops making
* progress ends here, well before the size-scaled overall deadline. Default:
* `timeoutMs`.
*/
idleTimeoutMs?: number;
fetcher?: typeof fetch;
now?: () => number;
scheduler?: Scheduler;
@@ -77,6 +104,20 @@ export function createPresignedTransferExecutor(
): PresignedTransferExecutor {
const resolve = options.vault.resolve.bind(options.vault);
const consume = options.vault.consume.bind(options.vault);
// 01-07. The capability a call was handed is retired on the way out of
// `open()` and `put()`, whichever path ends the call, so an invalid,
// pre-aborted, refused, expired or failed transfer does not hold a vault
// slot until its expiry. Idempotent after consume() and for identities the
// vault never issued.
const revokeVault = options.vault.revoke.bind(options.vault);
function release(capability: unknown): void {
if (capability === UNREADABLE_CAPABILITY) return;
try {
revokeVault(capability as PresignedTransferCapability);
} catch {
// Release is best effort; the entry still expires in the vault.
}
}
const claim = options.replayGuard.claim.bind(options.replayGuard);
const hardMaxTransferBytes = positiveSafeInteger(
options.hardMaxTransferBytes,
@@ -94,6 +135,12 @@ export function createPresignedTransferExecutor(
options.minimumRemainingLifetimeMs,
);
const timeoutMs = positiveSafeInteger(options.timeoutMs);
const minTransferBytesPerSecond = positiveSafeInteger(
options.minTransferBytesPerSecond ?? 64 * 1024,
);
const idleTimeoutMs = positiveSafeInteger(
options.idleTimeoutMs ?? timeoutMs,
);
const fetcher = (options.fetcher ?? fetch).bind(globalThis);
const now = options.now ?? Date.now;
// X-AUDIT-02. The timer callables are captured once, bound to their
@@ -122,13 +169,12 @@ export function createPresignedTransferExecutor(
async function openDownload(
input: Parameters<PresignedDownloadSourcePort["open"]>[0],
capability: PresignedDownloadCapability,
): Promise<BrowserDataResult<PresignedDownloadByteSource>> {
let resourceId: string;
let capability: PresignedDownloadCapability;
let signal: AbortSignal;
try {
resourceId = input.resourceId;
capability = input.capability;
signal = input.signal;
if (!isAbortSignal(signal)) {
throw new TypeError("Abort signal is invalid.");
@@ -183,10 +229,16 @@ export function createPresignedTransferExecutor(
createScope: (consumerSignal?: AbortSignal) =>
createAbortScope(
signal,
timeoutMs,
timeoutMs +
transferAllowanceMs(
capability.byteLength,
minTransferBytesPerSecond,
),
timers,
consumerSignal ? [consumerSignal] : [],
consumerSignal,
),
readChunk: (reader, scopeSignal) =>
readWithSignal(reader, scopeSignal, idleTimeoutMs, timers),
recheckExpiry: () =>
validateExpiry(capability, minimumRemainingLifetimeMs, now()),
binding,
@@ -201,8 +253,8 @@ export function createPresignedTransferExecutor(
async function putUploadPart(
input: Parameters<PresignedUploadPartPort["put"]>[0],
capability: PresignedUploadPartCapability,
): Promise<BrowserDataResult<PresignedUploadPartOutcome>> {
let capability: PresignedUploadPartCapability;
let bytes: Uint8Array<ArrayBuffer>;
let request: Readonly<{
sessionId: string;
@@ -216,7 +268,6 @@ export function createPresignedTransferExecutor(
signal: AbortSignal;
}>;
try {
capability = input.capability;
if (!(input.bytes instanceof Uint8Array)) {
throw new TypeError("Upload bytes are invalid.");
}
@@ -286,7 +337,12 @@ export function createPresignedTransferExecutor(
// caller signal and the deadline like every other step. Computing it before
// the scope existed meant an abort or a deadline could not reach it, and a
// hash that never settled held the whole `put` open.
const scope = createAbortScope(request.signal, timeoutMs, timers);
const scope = createAbortScope(
request.signal,
timeoutMs +
transferAllowanceMs(bytes.byteLength, minTransferBytesPerSecond),
timers,
);
try {
const digested = await scope.race(
Promise.resolve().then(async () => await digestBytes(bytes)),
@@ -377,8 +433,12 @@ export function createPresignedTransferExecutor(
input: Parameters<PresignedDownloadSourcePort["open"]>[0],
) {
let result: BrowserDataResult<PresignedDownloadByteSource>;
const capability = readCapability(input);
try {
result = await openDownload(input);
result =
capability === UNREADABLE_CAPABILITY
? browserDataFailure("INVALID_INPUT", "PRESIGNED_TRANSFER")
: await openDownload(input, capability);
} catch {
result = browserDataFailure(
"UNAVAILABLE",
@@ -388,6 +448,8 @@ export function createPresignedTransferExecutor(
recovery: "REISSUE_CAPABILITY",
},
);
} finally {
release(capability);
}
observeTransferResult(
observer,
@@ -406,8 +468,12 @@ export function createPresignedTransferExecutor(
input: Parameters<PresignedUploadPartPort["put"]>[0],
) {
let result: BrowserDataResult<PresignedUploadPartOutcome>;
const capability = readCapability(input);
try {
result = await putUploadPart(input);
result =
capability === UNREADABLE_CAPABILITY
? browserDataFailure("INVALID_INPUT", "PRESIGNED_TRANSFER")
: await putUploadPart(input, capability);
} catch {
result = browserDataFailure(
"UNAVAILABLE",
@@ -417,10 +483,14 @@ export function createPresignedTransferExecutor(
recovery: "REISSUE_CAPABILITY",
},
);
} finally {
release(capability);
}
// 01-10. One PUT attempt. The resumable runtime records the part's final
// result as UPLOAD_PART, so the two layers never count the same event.
observeTransferResult(
observer,
"UPLOAD_PART",
"PRESIGNED_TRANSFER",
result,
result.ok
? result.value.bytesWritten
@@ -435,13 +505,17 @@ export function createPresignedTransferExecutor(
function createDownloadSource(input: Readonly<{
start: (
scope: ReturnType<typeof createAbortScope>,
scope: PresignedAbortScope,
) => Promise<Response>;
validateResponse: (response: Response) => BrowserDataResult<unknown>;
createScope: (
consumerSignal?: AbortSignal,
) => ReturnType<typeof createAbortScope>;
) => PresignedAbortScope;
recheckExpiry: () => BrowserDataResult<unknown>;
readChunk: (
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
) => Promise<ReadableStreamReadResult<Uint8Array>>;
binding: PresignedCapabilityBinding;
capability: PresignedDownloadCapability;
externalSignal: AbortSignal;
@@ -453,7 +527,7 @@ function createDownloadSource(input: Readonly<{
}>): PresignedDownloadByteSource {
/** BT-PRE-01. One state machine shared by `stream()` and `close()`. */
let state: "READY" | "STREAMING" | "CLOSED" = "READY";
let activeScope: ReturnType<typeof createAbortScope> | undefined;
let activeScope: PresignedAbortScope | undefined;
let activeResponse: Response | undefined;
// TR-RR-01. Releasing the scope only dropped listeners and the timer, so a
@@ -626,10 +700,7 @@ function createDownloadSource(input: Readonly<{
});
return;
}
const result = await readWithSignal(
reader,
scope.signal,
);
const result = await input.readChunk(reader, scope.signal);
if (result.done) break;
const chunk = result.value;
if (!(chunk instanceof Uint8Array)) {
@@ -702,13 +773,16 @@ function createDownloadSource(input: Readonly<{
return;
}
completed = true;
} catch {
} catch (error) {
if (
input.externalSignal.aborted ||
consumerSignal.aborted
) {
yield fail("ABORTED");
} else if (scope.timedOut()) {
} else if (
scope.timedOut() ||
(error instanceof DOMException && error.name === "TimeoutError")
) {
yield fail("UNAVAILABLE", {
retryable: true,
recovery: "REISSUE_CAPABILITY",
@@ -783,8 +857,7 @@ function validateDownloadResponse(
const contentEncoding = response.headers.get("content-encoding");
if (
mediaType !== binding.mediaType ||
declaredLength === null ||
Number(declaredLength) !== binding.byteLength ||
normalizedContentLength(declaredLength) !== binding.byteLength ||
digestHeader === null ||
response.headers.get(digestHeader)?.trim().toLowerCase() !==
binding.expectedSha256 ||
@@ -928,17 +1001,6 @@ function validateRequiredHeaders(
);
}
function normalizedContentLength(
value: string | null,
allowImplicitZero: boolean,
): number | null {
if (value === null) return allowImplicitZero ? 0 : null;
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
function headersFor(binding: PresignedCapabilityBinding): Headers {
const headers = new Headers();
for (const header of binding.requestHeaders) {
@@ -994,189 +1056,6 @@ function validateExpiry(
);
}
function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-scope-ended");
function compensateLateResponse(task: Promise<unknown>): void {
void task
.then(async (value) => {
const body = (value as { body?: { cancel(): Promise<void> } | null })
?.body;
await body?.cancel();
})
.catch(() => undefined);
}
/**
* TR-RR-01 / TR-RR-05. A projection of the shared `createAbortableOperation`
* primitive into this subsystem's vocabulary, replacing a second hand-written
* copy of the same mechanics.
*
* `additionalSignals` lets a consumer's stream signal join the operation's
* ownership before any I/O begins, and `abort()` ends the physical work rather
* than only releasing bookkeeping.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function cancelBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// A response already classified as failure/success is not reclassified by
// best-effort body cancellation.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// Reader cancellation cannot alter the terminal closed result.
}
}
function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () => {
reject(new DOMException("Aborted", "AbortError"));
};
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function normalizeReceiptToken(value: string | null): string | null {
if (!value) return null;
const trimmed = value.trim();
@@ -1186,9 +1065,7 @@ function normalizeReceiptToken(value: string | null): string | null {
trimmed.endsWith("\"")
? trimmed.slice(1, -1)
: trimmed;
return RECEIPT_TOKEN.test(unquoted) && !unquoted.includes("://")
? unquoted
: null;
return isSafeUploadReceiptToken(unquoted) ? unquoted : null;
}
function responseUrlMatches(
@@ -1211,12 +1088,7 @@ function normalizedSha256(value: unknown): string {
}
function opaqueId(value: unknown): string {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 256 ||
!/^[a-z0-9][a-z0-9._:-]*$/i.test(value)
) {
if (typeof value !== "string" || !SAFE_TRANSFER_ID.test(value)) {
throw new TypeError("Opaque identifier is invalid.");
}
return value;
@@ -1251,21 +1123,19 @@ async function digestSha256WithWebCrypto(
).join("");
}
function isAbortSignal(value: unknown): value is AbortSignal {
/**
* 01-07. Reads the caller's capability once, so the identity released on the
* way out is the one the call resolved even if `capability` is an accessor.
*/
const UNREADABLE_CAPABILITY: unique symbol = Symbol("unreadable capability");
function readCapability<T>(
input: Readonly<{ capability: T }>,
): T | typeof UNREADABLE_CAPABILITY {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
return input.capability;
} catch {
return false;
return UNREADABLE_CAPABILITY;
}
}
@@ -1304,41 +1174,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 } : {}),
});
}
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";
}
@@ -5,12 +5,23 @@ 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;
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;
export const RECEIPT_TOKEN =
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;
@@ -60,7 +71,7 @@ export function isUploadFileFingerprint(
);
}
export function isUploadPartDescriptor(
function isUploadPartDescriptor(
value: unknown,
): value is UploadPartDescriptor {
if (!exactRecord(value, PART_KEYS)) return false;
@@ -131,7 +142,7 @@ export function isResumableUploadCheckpoint(
return true;
}
export function partMatchesFingerprint(
function partMatchesFingerprint(
part: UploadPartDescriptor,
fingerprint: UploadFileFingerprint,
): boolean {
@@ -161,7 +172,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> {
@@ -176,10 +187,17 @@ function exactRecord<const Keys extends readonly string[]>(
);
}
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
* 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",
);
}
@@ -2,23 +2,27 @@ 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,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
cancelBody,
cancelReader,
createAbortableOperation,
type AbortRace,
type AbortTerminalReason,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import { parseRetryAfterDelay } from "../../platform/retry-after.ts";
import type {
ResumableUploadControlOperation,
ResumableUploadJsonTransport,
} from "./http-control-plane-adapter.ts";
import { isAbortSignal } from "./checkpoint-schema.ts";
export type ResumableUploadEndpointMap = Readonly<
Record<ResumableUploadControlOperation, string>
@@ -33,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>>
@@ -59,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(
@@ -129,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,
@@ -182,14 +218,17 @@ export function createResumableUploadFetchJsonTransport(
"NONE",
);
}
const attempt = createFetchAttempt(
// X-AUDIT-02 / TR-RR-05. The attempt is the shared abort primitive:
// the listener and the timer are installed together, so a throwing
// scheduler closes the attempt instead of rejecting `execute()`.
const attempt = createAbortableOperation({
signal,
timeoutMs,
setTimer,
clearTimer,
);
});
try {
if (attempt.terminalKind() !== null) {
if (attempt.terminal() !== null) {
// The attempt was closed before it could be bounded, so no request is
// ever put on the wire.
return attemptFailure(attempt, operation);
@@ -210,7 +249,7 @@ export function createResumableUploadFetchJsonTransport(
const raced = await attempt.race(
Promise.resolve(fetchPromise),
(late) => {
cancelResponseBody(late);
cancelBody(late);
},
);
if (raced.kind !== "VALUE") {
@@ -222,7 +261,7 @@ export function createResumableUploadFetchJsonTransport(
response.type === "opaqueredirect" ||
!sameUrl(response.url, endpoint)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"POLICY_REJECTED",
operation,
@@ -237,11 +276,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,
@@ -261,7 +300,9 @@ export function createResumableUploadFetchJsonTransport(
} catch {
return attemptFailure(attempt, operation);
} finally {
attempt.release();
// BT-UP-01. Cleanup is best effort and never replaces the classified
// terminal result with a rejection.
attempt.close();
}
},
};
@@ -341,7 +382,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.");
}
@@ -405,7 +446,7 @@ async function readBoundedJson(
response: Response,
maxBytes: number,
operation: ResumableUploadControlOperation,
attempt: FetchAttempt,
attempt: AbortableOperation,
): Promise<UploadProviderResult<unknown>> {
const contentLength = response.headers.get("content-length");
let declaredLength: number | null = null;
@@ -414,7 +455,7 @@ async function readBoundedJson(
(!/^(0|[1-9][0-9]*)$/u.test(contentLength) ||
Number(contentLength) > maxBytes)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"LIMIT_EXCEEDED",
operation,
@@ -532,7 +573,7 @@ function statusFailure(
return failure("LIMIT_EXCEEDED", operation, false, "NONE");
}
if (response.status === 429) {
const retryAfterMs = parseRetryAfter(
const retryAfterMs = parseRetryAfterDelay(
response.headers.get("retry-after"),
nowEpochMs,
);
@@ -574,89 +615,15 @@ function failure(
return Object.freeze({ ok: false, error });
}
type FetchAttemptTerminalKind = "ABORT" | "TIMEOUT" | "CLOSED";
type FetchAttempt = Readonly<{
signal: AbortSignal;
terminalKind(): FetchAttemptTerminalKind | null;
race<Value>(
task: Promise<Value>,
compensate?: (value: Value) => void,
): Promise<AbortRace<Value>>;
release(): void;
}>;
/**
* X-AUDIT-02 / TR-RR-05. The attempt is the shared abort primitive with this
* subsystem's vocabulary on top. Owning a private copy meant the listener was
* attached before the timer was installed, so a scheduler that threw rejected
* the public `execute()` promise and left the listener on the caller's signal.
*/
function createFetchAttempt(
parent: AbortSignal,
timeoutMs: number,
setTimer: (callback: () => void, delayMs: number) => unknown,
clearTimer: (handle: unknown) => void,
): FetchAttempt {
const operation = createAbortableOperation({
signal: parent,
timeoutMs,
setTimer,
clearTimer,
});
const kindOf = (
reason: AbortTerminalReason | null,
): FetchAttemptTerminalKind | null => {
if (reason === null) return null;
if (reason === "CALLER_ABORT") return "ABORT";
return reason === "DEADLINE" ? "TIMEOUT" : "CLOSED";
};
return Object.freeze({
signal: operation.signal,
terminalKind: () => kindOf(operation.terminal()),
race: <Value,>(
task: Promise<Value>,
compensate?: (value: Value) => void,
) => operation.race(task, compensate),
release() {
// BT-UP-01. Cleanup is best effort and must never replace the already
// classified terminal result with a rejection.
operation.close();
},
});
}
function attemptFailure(
attempt: FetchAttempt,
attempt: AbortableOperation,
operation: ResumableUploadControlOperation,
): UploadProviderResult<never> {
return attempt.terminalKind() === "ABORT"
return attempt.terminal() === "CALLER_ABORT"
? failure("ABORTED", operation, false, "NONE")
: 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 {
@@ -667,29 +634,6 @@ function releaseReader(
}
}
/**
* BT-UP-02. Both the delta-seconds and the HTTP-date branch resolve against the
* same captured `now`, so a fake clock makes boundary, rollback and invalid-date
* behaviour deterministic instead of depending on the global clock.
*/
function parseRetryAfter(
value: string | null,
nowEpochMs: number,
): number | null {
if (!value) return null;
if (/^(0|[1-9][0-9]*)$/u.test(value)) {
const seconds = Number(value);
const milliseconds = seconds * 1000;
return Number.isSafeInteger(milliseconds) ? milliseconds : null;
}
const timestamp = Date.parse(value);
if (!Number.isFinite(timestamp) || !Number.isSafeInteger(nowEpochMs)) {
return null;
}
// A clock that moved backwards yields zero, never a negative delay.
return Math.max(0, timestamp - nowEpochMs);
}
function jsonContentType(value: string | null): boolean {
return Boolean(
value &&
@@ -721,21 +665,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 {
@@ -766,13 +695,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<Record<string, unknown>> {
@@ -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;
}
@@ -14,7 +14,7 @@ import { isBrowserDataFailureCode } from "../../../application/ports/browser-fil
import {
browserDataFailure,
browserDataSuccess,
mapBrowserDataException,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import { snapshotAbortTimers } from "../../platform/abortable-operation.ts";
import {
@@ -81,7 +81,7 @@ type ScopeBinding = Readonly<{
}>;
/**
* `browserDataFailure` and `mapBrowserDataException` build a `Result`, while the
* `browserDataFailure` and `mapIndexedDbException` build a `Result`, while the
* kernel's `translate` contract wants the failure on its own. Both only ever
* build the failure arm, so the branch below is a narrowing, not a claim.
*/
@@ -103,7 +103,7 @@ function checkpointFailure(
}
function mappedFailure(error: unknown): BrowserDataFailure {
return failureOf(mapBrowserDataException(error, OPERATION));
return failureOf(mapIndexedDbException(error, OPERATION));
}
/**
@@ -120,11 +120,9 @@ function admissionFailure(detail: unknown): BrowserDataFailure | null {
}
/**
* BT-UP-03. The checkpoint store keeps its own failure table rather than the
* `mapIndexedDbException` the other three IndexedDB adapters share: the same
* native error is a different answer here (a `ConstraintError` recovers by
* REOPEN, a quota failure is retryable), and unifying the four tables is a
* separate change from moving the mechanics onto the kernel.
* BT-UP-03. Native exceptions go through `mapIndexedDbException`, the one
* IndexedDB table the other IndexedDB adapters use (F-1, 05-11). Only the
* kernel causes below keep checkpoint-specific answers.
*/
const translate: IndexedDbTranslate<BrowserDataFailure> = (cause) => {
switch (cause.kind) {
@@ -285,6 +283,35 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
}),
});
/**
* Every store operation reads the row it guards inside the same transaction
* it may then write in, so the guard and the write cannot interleave with
* another context.
*/
async function withCheckpointRow<Value>(
uploadKey: string,
mode: "readonly" | "readwrite",
signal: AbortSignal | undefined,
onRow: (
row: unknown,
store: IDBObjectStore,
context: CheckpointTransactionContext<Value>,
) => void,
): Promise<BrowserDataResult<Value>> {
const opened = await connection.acquire(signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<Value>(
opened.value,
mode,
signal,
(nativeStore, context) => {
const request = nativeStore.get(uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => onRow(request.result, nativeStore, context);
},
);
}
const storeValue: ResumableUploadCheckpointStore = {
async read(
uploadKey: string,
@@ -295,32 +322,22 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
if (!SAFE_UPLOAD_KEY.test(uploadKey)) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<
ResumableUploadCheckpoint | null
>(
opened.value,
return await withCheckpointRow<ResumableUploadCheckpoint | null>(
uploadKey,
"readonly",
signal,
(nativeStore, context) => {
const request = nativeStore.get(uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
if (request.result === undefined) {
context.succeed(null);
return;
}
if (!isResumableUploadCheckpoint(request.result)) {
context.fail(
checkpointFailure("CORRUPT_DATA", { recovery: "RECONCILE" }),
);
return;
}
context.succeed(
snapshotCheckpoint(request.result),
(row, _nativeStore, context) => {
if (row === undefined) {
context.succeed(null);
return;
}
if (!isResumableUploadCheckpoint(row)) {
context.fail(
checkpointFailure("CORRUPT_DATA", { recovery: "RECONCILE" }),
);
};
return;
}
context.succeed(snapshotCheckpoint(row));
},
);
},
@@ -345,32 +362,25 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(inputValue.signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<ResumableUploadCheckpoint>(
opened.value,
return await withCheckpointRow<ResumableUploadCheckpoint>(
checkpoint.uploadKey,
"readwrite",
inputValue.signal,
(nativeStore, context) => {
const request = nativeStore.get(checkpoint.uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
const current = request.result;
if (
(expectedRevision === null && current !== undefined) ||
(expectedRevision !== null &&
(!isResumableUploadCheckpoint(current) ||
current.revision !== expectedRevision))
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const put = nativeStore.put(checkpoint);
put.onerror = () => context.fail(mappedFailure(put.error));
put.onsuccess = () => context.succeed(checkpoint);
};
(current, nativeStore, context) => {
if (
(expectedRevision === null && current !== undefined) ||
(expectedRevision !== null &&
(!isResumableUploadCheckpoint(current) ||
current.revision !== expectedRevision))
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const put = nativeStore.put(checkpoint);
put.onerror = () => context.fail(mappedFailure(put.error));
put.onsuccess = () => context.succeed(checkpoint);
},
);
},
@@ -387,30 +397,51 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(inputValue.signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<void>(
opened.value,
return await withCheckpointRow<void>(
inputValue.uploadKey,
"readwrite",
inputValue.signal,
(nativeStore, context) => {
const request = nativeStore.get(inputValue.uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
if (
!isResumableUploadCheckpoint(request.result) ||
request.result.revision !== inputValue.expectedRevision
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const deletion = nativeStore.delete(inputValue.uploadKey);
deletion.onerror = () =>
context.fail(mappedFailure(deletion.error));
deletion.onsuccess = () => context.succeed(undefined);
};
(row, nativeStore, context) => {
if (
!isResumableUploadCheckpoint(row) ||
row.revision !== inputValue.expectedRevision
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
deleteCheckpointRow(nativeStore, inputValue.uploadKey, context);
},
);
},
async removeUnreadable(
inputValue: Parameters<
NonNullable<ResumableUploadCheckpointStore["removeUnreadable"]>
>[0],
): Promise<BrowserDataResult<void>> {
if (!SAFE_UPLOAD_KEY.test(inputValue.uploadKey)) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
return await withCheckpointRow<void>(
inputValue.uploadKey,
"readwrite",
inputValue.signal,
(row, nativeStore, context) => {
// Checked in the same transaction as the delete, so a row another
// context rewrote as a valid checkpoint is never dropped.
if (row === undefined) {
context.succeed(undefined);
return;
}
if (isResumableUploadCheckpoint(row)) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
deleteCheckpointRow(nativeStore, inputValue.uploadKey, context);
},
);
},
@@ -477,6 +508,21 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
return Object.freeze({ store, admin });
}
type CheckpointTransactionContext<Value> = Readonly<{
succeed(value: Value): void;
fail(failure: BrowserDataFailure): void;
}>;
function deleteCheckpointRow(
store: IDBObjectStore,
uploadKey: string,
context: CheckpointTransactionContext<void>,
): void {
const deletion = store.delete(uploadKey);
deletion.onerror = () => context.fail(mappedFailure(deletion.error));
deletion.onsuccess = () => context.succeed(undefined);
}
/**
* `durability` is deliberately `undefined` rather than `"default"`: that opens
* the transaction with no options bag at all, which is what checkpoint writes
@@ -494,10 +540,7 @@ async function runCheckpointTransaction<Value>(
signal: AbortSignal | undefined,
execute: (
store: IDBObjectStore,
context: Readonly<{
succeed(value: Value): void;
fail(failure: BrowserDataFailure): void;
}>,
context: CheckpointTransactionContext<Value>,
) => void,
): Promise<BrowserDataResult<Value>> {
return await runIndexedDbTransaction<Value, BrowserDataFailure>({
@@ -91,7 +91,9 @@ export function createPresignedUploadPartExecutor(
byteLength: input.part.byteLength,
checksumSha256: input.part.checksumSha256,
idempotencyKey: input.idempotencyKey,
bytes: Uint8Array.from(input.bytes),
// Q-6.1-3b. The presigned port snapshots `bytes` before any await,
// so a second copy here only doubled the per-part buffer.
bytes: input.bytes,
signal: input.signal,
});
} catch {
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,378 @@
import type {
ResumableUploadCheckpointStore,
ResumableUploadControlPlane,
UploadPartExecutor,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataObserver,
BrowserDataOperation,
BrowserDataResult,
} 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 { snapshotUploadCrypto, type UploadCrypto } from "./upload-byte-source.ts";
import {
resolveResumableUploadRuntimePolicy,
type ResumableUploadRuntimePolicy,
} from "./runtime-policy.ts";
import type { UploadCancellationChannel } from "./upload-cancellation-channel.ts";
import type { UploadMutationLock } from "./upload-mutation-lock.ts";
/**
* Q-6.1-10. The resumable upload runtime's injected collaborators. Each one is
* validated and its methods captured once at composition, so replacing a
* method afterwards cannot change what an upload in flight calls.
*/
export type ResumableUploadRuntimeDependencies<Capability> = Readonly<{
controlPlane: ResumableUploadControlPlane<Capability>;
partExecutor: UploadPartExecutor<Capability>;
checkpoints: ResumableUploadCheckpointStore;
mutationLock: UploadMutationLock;
/**
* Runtime-owned ephemeral BroadcastChannel coordination. When omitted,
* explicit abort is still correct but may wait for another context's lock.
*/
crossContextCancellation?: UploadCancellationChannel;
crypto: Crypto;
policy?: Partial<ResumableUploadRuntimePolicy>;
now?: () => number;
random?: () => number;
sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>;
observer?: BrowserDataObserver;
}>;
export type RuntimeDependencies<Capability> = Readonly<{
controlPlane: ResumableUploadControlPlane<Capability>;
partExecutor: UploadPartExecutor<Capability>;
checkpoints: ResumableUploadCheckpointStore;
mutationLock: UploadMutationLock;
crossContextCancellation?: UploadCancellationChannel;
crypto: UploadCrypto;
policy: ResumableUploadRuntimePolicy;
now(): number;
random(): number;
sleep(delayMs: number, signal: AbortSignal): Promise<void>;
observer?: BrowserDataObserver;
/**
* TR-04. Every raw provider promise, from the moment the collaborator is
* called until it actually settles. The wrapper that bounds the attempt can
* settle long before the provider does, so the wrapper registry alone could
* report an empty set while physical work was still running.
*/
physicalTasks: Set<Promise<unknown>>;
}>;
export function snapshotDependencies<Capability>(
input: ResumableUploadRuntimeDependencies<Capability>,
physicalTasks: Set<Promise<unknown>>,
): RuntimeDependencies<Capability> {
const policy = resolveResumableUploadRuntimePolicy(input.policy);
const controlPlane = snapshotControlPlane(input.controlPlane);
const partExecutor = snapshotPartExecutor(input.partExecutor);
const checkpoints = snapshotCheckpointStore(input.checkpoints);
const mutationLock = snapshotMutationLock(input.mutationLock);
const crossContextCancellation = snapshotCancellationChannel(
input.crossContextCancellation,
);
const crypto = snapshotUploadCrypto(input.crypto);
const nowSource = input.now ?? Date.now;
const randomSource = input.random ?? Math.random;
const sleepSource = input.sleep ?? abortableSleep;
const observer = snapshotObserver(input.observer);
if (
typeof nowSource !== "function" ||
typeof randomSource !== "function" ||
typeof sleepSource !== "function"
) {
throw new TypeError("Upload runtime dependency is invalid.");
}
return Object.freeze({
physicalTasks,
controlPlane,
partExecutor,
checkpoints,
mutationLock,
...(crossContextCancellation
? { crossContextCancellation }
: {}),
crypto,
policy,
now: () => nowSource(),
random: () => randomSource(),
sleep: async (delayMs, signal) =>
await sleepSource(delayMs, signal),
...(observer ? { observer } : {}),
});
}
function snapshotCancellationChannel(
value: UploadCancellationChannel | undefined,
): UploadCancellationChannel | undefined {
if (!value) return undefined;
const publish = value.publish;
const subscribe = value.subscribe;
const close = value.close;
if (
typeof publish !== "function" ||
typeof subscribe !== "function" ||
typeof close !== "function"
) {
throw new TypeError(
"Upload cancellation channel is invalid.",
);
}
return Object.freeze({
publish(uploadKey: string): boolean {
try {
return publish.call(value, uploadKey) === true;
} catch {
return false;
}
},
subscribe(
listener: (uploadKey: string) => void,
): () => void {
const release = subscribe.call(value, listener);
if (typeof release !== "function") {
throw new TypeError(
"Upload cancellation subscription is invalid.",
);
}
let active = true;
return () => {
if (!active) return;
active = false;
try {
release();
} catch {
// Runtime close remains terminal.
}
};
},
close(): void {
try {
close.call(value);
} catch {
// Runtime close remains terminal.
}
},
});
}
function snapshotObserver(
value: BrowserDataObserver | undefined,
): BrowserDataObserver | undefined {
if (!value) return undefined;
const record = value.record;
if (typeof record !== "function") {
throw new TypeError("Upload observer is invalid.");
}
return Object.freeze({
record(
observation: Parameters<BrowserDataObserver["record"]>[0],
) {
record.call(value, Object.freeze({ ...observation }));
},
});
}
function snapshotControlPlane<Capability>(
value: ResumableUploadControlPlane<Capability>,
): ResumableUploadControlPlane<Capability> {
const createSession = value?.createSession;
const getStatus = value?.getStatus;
const issuePartCapability = value?.issuePartCapability;
const complete = value?.complete;
const abort = value?.abort;
if (
typeof createSession !== "function" ||
typeof getStatus !== "function" ||
typeof issuePartCapability !== "function" ||
typeof complete !== "function" ||
typeof abort !== "function"
) {
throw new TypeError("Upload control plane is invalid.");
}
const snapshot: ResumableUploadControlPlane<Capability> = {
async createSession(
input: Parameters<
ResumableUploadControlPlane<Capability>["createSession"]
>[0],
) {
return await createSession.call(value, input);
},
async getStatus(
input: Parameters<
ResumableUploadControlPlane<Capability>["getStatus"]
>[0],
) {
return await getStatus.call(value, input);
},
async issuePartCapability(
input: Parameters<
ResumableUploadControlPlane<Capability>["issuePartCapability"]
>[0],
) {
return await issuePartCapability.call(value, input);
},
async complete(
input: Parameters<
ResumableUploadControlPlane<Capability>["complete"]
>[0],
) {
return await complete.call(value, input);
},
async abort(
input: Parameters<
ResumableUploadControlPlane<Capability>["abort"]
>[0],
) {
return await abort.call(value, input);
},
};
return Object.freeze(snapshot);
}
function snapshotPartExecutor<Capability>(
value: UploadPartExecutor<Capability>,
): UploadPartExecutor<Capability> {
const uploadPart = value?.uploadPart;
if (typeof uploadPart !== "function") {
throw new TypeError("Upload part executor is invalid.");
}
const snapshot: UploadPartExecutor<Capability> = {
async uploadPart(
input: Parameters<UploadPartExecutor<Capability>["uploadPart"]>[0],
) {
return await uploadPart.call(value, input);
},
};
return Object.freeze(snapshot);
}
function snapshotCheckpointStore(
value: ResumableUploadCheckpointStore,
): ResumableUploadCheckpointStore {
const read = value?.read;
const compareAndSwap = value?.compareAndSwap;
const remove = value?.remove;
const removeUnreadable = value?.removeUnreadable;
const close = value?.close;
if (
typeof read !== "function" ||
typeof compareAndSwap !== "function" ||
typeof remove !== "function" ||
(removeUnreadable !== undefined &&
typeof removeUnreadable !== "function") ||
typeof close !== "function"
) {
throw new TypeError("Upload checkpoint store is invalid.");
}
const snapshot: ResumableUploadCheckpointStore = {
async read(
uploadKey: string,
signal?: AbortSignal,
) {
return await read.call(value, uploadKey, signal);
},
async compareAndSwap(
input: Parameters<
ResumableUploadCheckpointStore["compareAndSwap"]
>[0],
) {
return await compareAndSwap.call(value, input);
},
async remove(
input: Parameters<ResumableUploadCheckpointStore["remove"]>[0],
) {
return await remove.call(value, input);
},
...(removeUnreadable
? {
async removeUnreadable(
input: Parameters<typeof removeUnreadable>[0],
) {
return await removeUnreadable.call(value, input);
},
}
: {}),
close() {
close.call(value);
},
};
return Object.freeze(snapshot);
}
function snapshotMutationLock(value: UploadMutationLock): UploadMutationLock {
const run = value?.run;
if (typeof run !== "function") {
throw new TypeError("Upload mutation lock is invalid.");
}
return Object.freeze({
async run<Value>(
uploadKey: string,
signal: AbortSignal,
task: () => Promise<Value>,
): Promise<Value> {
return await (run.call(
value,
uploadKey,
signal,
task,
) as Promise<Value>);
},
});
}
export function safeNow<Capability>(
dependencies: RuntimeDependencies<Capability>,
operation: BrowserDataOperation,
): BrowserDataResult<number> {
try {
const value = dependencies.now();
return Number.isSafeInteger(value) && value >= 0
? browserDataSuccess(value)
: browserDataFailure("UNAVAILABLE", operation, {
recovery: "RESUME",
});
} catch {
return browserDataFailure("UNAVAILABLE", operation, {
recovery: "RESUME",
});
}
}
export function safeRandom<Capability>(
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<number> {
try {
const value = dependencies.random();
return Number.isFinite(value) && value >= 0 && value <= 1
? browserDataSuccess(value)
: browserDataFailure("UNAVAILABLE", "UPLOAD_RECONCILE", {
recovery: "RESUME",
});
} catch {
return browserDataFailure("UNAVAILABLE", "UPLOAD_RECONCILE", {
recovery: "RESUME",
});
}
}
async function abortableSleep(
delayMs: number,
signal: AbortSignal,
): Promise<void> {
// The kernel owns the timer and the abort listener; the sleep only waits
// for whichever of the two ends the operation first.
const sleep = createAbortableOperation({ signal, timeoutMs: delayMs });
const ended = await sleep.race(new Promise<never>(() => {}));
sleep.close();
if (ended.kind !== "TERMINAL" || ended.terminal !== "DEADLINE") {
throw new DOMException("The operation was aborted.", "AbortError");
}
}
@@ -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;
@@ -12,7 +17,18 @@ export type ResumableUploadRuntimePolicy = Readonly<{
maxRetryAfterMs: number;
capabilityRefreshSkewMs: number;
maxSessionLifetimeMs: number;
/**
* 01-06. How far the device clock may trail the server's. A session is
* refused only when it outlives `maxSessionLifetimeMs` by more than this.
*/
maxClockSkewMs: number;
providerAttemptTimeoutMs: number;
/**
* 01-03. The slowest uplink a part PUT must survive. Its attempt deadline is
* `providerAttemptTimeoutMs + partBytes / minTransferBytesPerSecond`, so a
* fixed deadline no longer strands a slow connection on its first part.
*/
minTransferBytesPerSecond: number;
/**
* TR-RR-06. The bound `dispose()` applies to its drain. A non-cooperative
* mutation lock or provider would otherwise make teardown unbounded, so a
@@ -37,6 +53,7 @@ const ABSOLUTE_LIMITS = Object.freeze({
maxRetryAfterMs: 60_000,
maxCapabilityRefreshSkewMs: 5 * 60_000,
maxSessionLifetimeMs: 7 * 24 * 60 * 60_000,
maxClockSkewMs: 5 * 60_000,
maxProviderAttemptTimeoutMs: 2 * 60_000,
});
@@ -44,7 +61,9 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
partSizeBytes: 5 * MIB,
maxFileBytes: 5 * GIB,
maxPartCount: 1_024,
maxConcurrency: 3,
// R-1.3. 5 MiB × 1 × copyFactor 4 fills the 20 MiB budget; raise both
// together to upload parts in parallel.
maxConcurrency: 1,
maxInFlightBytes: 20 * MIB,
partBufferCopyFactor: 4,
maxSourceChunkBytes: 8 * MIB,
@@ -54,7 +73,10 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
maxRetryAfterMs: 30_000,
capabilityRefreshSkewMs: 5_000,
maxSessionLifetimeMs: 24 * 60 * 60_000,
maxClockSkewMs: 60_000,
providerAttemptTimeoutMs: 30_000,
// 64 KiB/s (about 0.5 Mbit/s): a 5 MiB part gets 30 s + 80 s.
minTransferBytesPerSecond: 64 * 1024,
cleanupDeadlineMs: 10_000,
});
@@ -80,7 +102,9 @@ export function resolveResumableUploadRuntimePolicy(
policy.partBufferCopyFactor >
ABSOLUTE_LIMITS.maxPartBufferCopyFactor ||
policy.maxInFlightBytes <
policy.partSizeBytes * policy.partBufferCopyFactor ||
policy.partSizeBytes *
policy.maxConcurrency *
policy.partBufferCopyFactor ||
!positiveSafeInteger(policy.maxSourceChunkBytes) ||
policy.maxSourceChunkBytes >
ABSOLUTE_LIMITS.maxSourceChunkBytes ||
@@ -99,9 +123,12 @@ export function resolveResumableUploadRuntimePolicy(
!positiveSafeInteger(policy.maxSessionLifetimeMs) ||
policy.maxSessionLifetimeMs >
ABSOLUTE_LIMITS.maxSessionLifetimeMs ||
!nonNegativeSafeInteger(policy.maxClockSkewMs) ||
policy.maxClockSkewMs > ABSOLUTE_LIMITS.maxClockSkewMs ||
!positiveSafeInteger(policy.providerAttemptTimeoutMs) ||
policy.providerAttemptTimeoutMs >
ABSOLUTE_LIMITS.maxProviderAttemptTimeoutMs ||
!positiveSafeInteger(policy.minTransferBytesPerSecond) ||
!positiveSafeInteger(policy.cleanupDeadlineMs) ||
policy.cleanupDeadlineMs >
ABSOLUTE_LIMITS.maxProviderAttemptTimeoutMs * 2 ||
@@ -112,11 +139,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;
}
@@ -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<ArrayBuffer>;
@@ -594,7 +597,3 @@ function remapFailure(
}),
});
}
function positiveSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) > 0;
}
@@ -0,0 +1,307 @@
import type {
ActiveUploadStatus,
ResumableUploadCheckpoint,
UploadFileFingerprint,
UploadPartCapability,
UploadPartReceipt,
UploadSession,
UploadSessionStatus,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataOperation,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
exactRecord,
isUploadFileFingerprint,
isUploadPartReceipt,
SAFE_OPAQUE_ID,
SHA256_HEX,
} from "./checkpoint-schema.ts";
import { safeNow, type RuntimeDependencies } from "./runtime-dependencies.ts";
import {
verifyPartAgainstManifest,
type UploadPartManifest,
} from "./upload-byte-source.ts";
/**
* Q-6.1-10. Strict decoders for what the control plane returns: a session, a
* status, a part capability and the accepted receipts. Every failure is closed
* with the recovery the runtime reports unchanged.
*/
export function validatePartCapability<Capability>(
value: UploadPartCapability<Capability>,
checkpoint: ResumableUploadCheckpoint,
uploadBindingSha256: string,
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadPartCapability<Capability>> {
if (
!exactRecord(value, [
"capability",
"uploadBindingSha256",
"expiresAtEpochMs",
]) ||
value.uploadBindingSha256 !== uploadBindingSha256 ||
!SHA256_HEX.test(value.uploadBindingSha256) ||
!Number.isSafeInteger(value.expiresAtEpochMs)
) {
return browserDataFailure("CORRUPT_DATA", "UPLOAD_PART", {
recovery: "REISSUE_CAPABILITY",
});
}
const now = safeNow(dependencies, "UPLOAD_PART");
if (!now.ok) return now;
if (
value.expiresAtEpochMs <=
now.value + dependencies.policy.capabilityRefreshSkewMs
) {
return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_PART", {
retryable: true,
recovery: "REISSUE_CAPABILITY",
});
}
if (value.expiresAtEpochMs > checkpoint.sessionExpiresAtEpochMs) {
return browserDataFailure("POLICY_REJECTED", "UPLOAD_PART", {
recovery: "REISSUE_CAPABILITY",
});
}
return browserDataSuccess(value);
}
export function validateStatus<Capability>(
value: UploadSessionStatus,
checkpoint: ResumableUploadCheckpoint,
manifest: UploadPartManifest,
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadSessionStatus> {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", {
recovery: "RECONCILE",
});
}
if (value.state === "ACTIVE") {
if (!exactRecord(value, ["state", "session", "acceptedParts"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
const session = validateSession(
value.session,
checkpoint.requestBindingSha256,
manifest.fingerprint,
dependencies,
"ACTIVE",
);
if (
!session.ok ||
session.value.sessionId !== checkpoint.sessionId ||
session.value.maxConcurrency !== checkpoint.sessionMaxConcurrency ||
session.value.expiresAtEpochMs !==
checkpoint.sessionExpiresAtEpochMs
) {
return browserDataFailure(
"INTEGRITY_FAILED",
"UPLOAD_RECONCILE",
{ recovery: "RESTART" },
);
}
const receipts = validateServerReceipts(
value,
manifest,
"UPLOAD_RECONCILE",
);
if (!receipts.ok) return receipts;
return browserDataSuccess(
Object.freeze({
state: "ACTIVE" as const,
session: session.value,
acceptedParts: receipts.value,
}),
);
}
if (value.state === "QUARANTINED") {
if (!exactRecord(value, ["state", "session", "resourceId"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
const session = validateSession(
value.session,
checkpoint.requestBindingSha256,
manifest.fingerprint,
dependencies,
"COMPLETED",
);
if (
!session.ok ||
session.value.sessionId !== checkpoint.sessionId ||
session.value.maxConcurrency !== checkpoint.sessionMaxConcurrency ||
session.value.expiresAtEpochMs !==
checkpoint.sessionExpiresAtEpochMs ||
!SAFE_OPAQUE_ID.test(value.resourceId)
) {
return browserDataFailure(
"INTEGRITY_FAILED",
"UPLOAD_RECONCILE",
{ recovery: "RESTART" },
);
}
return browserDataSuccess(
Object.freeze({
state: "QUARANTINED" as const,
session: session.value,
resourceId: value.resourceId,
}),
);
}
if (
!["ABORTED", "EXPIRED", "NOT_FOUND"].includes(value.state) ||
!exactRecord(value, [
"state",
"protocol",
"sessionId",
"requestBindingSha256",
]) ||
value.protocol !== RESUMABLE_UPLOAD_PROTOCOL ||
value.sessionId !== checkpoint.sessionId ||
value.requestBindingSha256 !== checkpoint.requestBindingSha256
) {
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_RECONCILE", {
recovery: "RESTART",
});
}
return browserDataSuccess(
Object.freeze({
state: value.state,
protocol: RESUMABLE_UPLOAD_PROTOCOL,
sessionId: value.sessionId,
requestBindingSha256: value.requestBindingSha256,
}),
);
}
/**
* 01-08. Policy ceilings (concurrency, lifetime) apply only to a session being
* created. A stored session is checked against its checkpoint by the caller,
* so a build that lowers the policy still resumes uploads an older build began.
*/
export function validateSession<Capability>(
value: UploadSession,
requestBindingSha256: string,
fingerprint: UploadFileFingerprint,
dependencies: RuntimeDependencies<Capability>,
stage: "CREATE" | "ACTIVE" | "COMPLETED" = "CREATE",
): BrowserDataResult<UploadSession> {
if (
!exactRecord(value, [
"protocol",
"sessionId",
"requestBindingSha256",
"fingerprint",
"partSizeBytes",
"partCount",
"maxConcurrency",
"expiresAtEpochMs",
]) ||
value.protocol !== RESUMABLE_UPLOAD_PROTOCOL ||
!SAFE_OPAQUE_ID.test(value.sessionId) ||
value.requestBindingSha256 !== requestBindingSha256 ||
!SHA256_HEX.test(value.requestBindingSha256) ||
!isUploadFileFingerprint(value.fingerprint) ||
!sameFingerprint(value.fingerprint, fingerprint) ||
value.partSizeBytes !== fingerprint.partSizeBytes ||
value.partCount !== fingerprint.partCount ||
!Number.isSafeInteger(value.maxConcurrency) ||
value.maxConcurrency < 1 ||
(stage === "CREATE" &&
value.maxConcurrency > dependencies.policy.maxConcurrency) ||
!Number.isSafeInteger(value.expiresAtEpochMs)
) {
// 01-05. A create is replayed under the same key, so neither calling
// `upload()` again nor restarting changes what the server answers.
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", {
recovery: "NONE",
});
}
const now = safeNow(dependencies, "UPLOAD_SESSION");
if (!now.ok) return now;
if (
stage === "CREATE" &&
value.expiresAtEpochMs - now.value >
dependencies.policy.maxSessionLifetimeMs +
dependencies.policy.maxClockSkewMs
) {
return browserDataFailure("POLICY_REJECTED", "UPLOAD_SESSION");
}
if (stage !== "COMPLETED" && value.expiresAtEpochMs <= now.value) {
return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_SESSION", {
recovery: "RESTART",
});
}
return browserDataSuccess(
Object.freeze({
...value,
fingerprint: Object.freeze({ ...value.fingerprint }),
}),
);
}
function validateServerReceipts(
status: ActiveUploadStatus,
manifest: UploadPartManifest,
operation: BrowserDataOperation,
): BrowserDataResult<readonly UploadPartReceipt[]> {
if (
!Array.isArray(status.acceptedParts) ||
status.acceptedParts.length > manifest.parts.length
) {
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "RECONCILE",
});
}
let previousPart = 0;
for (const receipt of status.acceptedParts) {
if (
!isUploadPartReceipt(receipt) ||
receipt.partNumber <= previousPart ||
!verifyPartAgainstManifest(receipt, manifest)
) {
return browserDataFailure("INTEGRITY_FAILED", operation, {
recovery: "RESTART",
});
}
previousPart = receipt.partNumber;
}
return browserDataSuccess(snapshotReceipts(status.acceptedParts));
}
export function sameFingerprint(
left: UploadFileFingerprint,
right: UploadFileFingerprint,
): boolean {
return (
left.algorithm === right.algorithm &&
left.digestHex === right.digestHex &&
left.byteLength === right.byteLength &&
left.partSizeBytes === right.partSizeBytes &&
left.partCount === right.partCount
);
}
export function snapshotReceipts(
parts: readonly UploadPartReceipt[],
): readonly UploadPartReceipt[] {
return Object.freeze(
parts.map((part) => Object.freeze({ ...part })),
);
}
@@ -0,0 +1,656 @@
import type {
PublicCacheAsset,
PublicCacheHeader,
PublicCacheReleaseManifest,
} from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type {
BrowserDataFailure,
BrowserDataFailureCode,
BrowserDataOperation,
BrowserDataResult,
} from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
isAllowedPublicCacheOrigin,
type PublicCacheRuntimePolicy,
} from "./public-cache-policy.ts";
/**
* Q-6.2-11. Release manifest, marker and active-pointer codec for the public
* response cache: normalization, canonical digest input, bounded control JSON
* decoding, owned cache naming, and the mapping of a validation failure to a
* browser-data Result. Moved verbatim out of the adapter.
*/
export type PublicCacheCryptoFacade = Readonly<{
digestSha256(bytes: Uint8Array<ArrayBuffer>): Promise<ArrayBuffer>;
}>;
export type NormalizedAsset = Readonly<{
absoluteUrl: string;
expectedByteLength: number;
expectedContentType: string;
digestHex: string;
requestHeaders: readonly PublicCacheHeader[];
}>;
export type NormalizedReleaseManifest = Readonly<{
releaseRegistryId: string;
manifestDigestHex: string;
assets: readonly NormalizedAsset[];
}>;
export type ReleaseMarker = Readonly<{
schemaVersion: 1;
verified: true;
releaseRegistryId: string;
manifestDigestHex: string;
entryCount: number;
totalBytes: number;
stagedAtEpochMs: number;
assets: readonly NormalizedAsset[];
}>;
export type ActiveReleasePointer = Readonly<{
schemaVersion: 1;
releaseRegistryId: string;
manifestDigestHex: string;
candidateCacheName: string;
rollbackCandidateCacheNames: readonly string[];
activatedAtEpochMs: number;
}>;
export type BrowserFailureResult = Readonly<{
ok: false;
error: BrowserDataFailure;
}>;
export class CacheValidationFailure extends Error {
readonly code: BrowserDataFailureCode;
constructor(code: BrowserDataFailureCode) {
super("Public cache validation failed.");
this.name = "CacheValidationFailure";
this.code = code;
}
}
export async function normalizeAndVerifyManifest(
manifest: PublicCacheReleaseManifest,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
): Promise<NormalizedReleaseManifest> {
const snapshot = Object.freeze({
releaseRegistryId: manifest.releaseRegistryId,
manifestDigestHex: manifest.manifestDigestHex,
assets: normalizeAssets(manifest.assets, policy),
});
if (
!policy.isReleaseRegistryIdAllowed(snapshot.releaseRegistryId) ||
!SHA256_HEX.test(snapshot.manifestDigestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const actualDigest = await sha256Hex(
crypto,
new TextEncoder().encode(
canonicalManifest(snapshot.releaseRegistryId, snapshot.assets),
),
);
if (actualDigest !== snapshot.manifestDigestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return snapshot;
}
export function normalizeAssets(
assets: readonly PublicCacheAsset[],
policy: PublicCacheRuntimePolicy,
): readonly NormalizedAsset[] {
if (
!Array.isArray(assets) ||
assets.length < 1 ||
assets.length > policy.maxEntriesPerRelease
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const normalized = assets.map((asset) =>
normalizeAsset(asset, policy),
);
const keys = normalized.map(assetKey);
if (new Set(keys).size !== keys.length) {
throw new CacheValidationFailure("CONFLICT");
}
const declaredTotal = normalized.reduce(
(total, asset) => total + asset.expectedByteLength,
0,
);
if (
!Number.isSafeInteger(declaredTotal) ||
declaredTotal > policy.maxReleaseBytes
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
return Object.freeze(normalized);
}
export function normalizeAsset(
asset: PublicCacheAsset,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
if (
!asset ||
typeof asset !== "object" ||
!Number.isSafeInteger(asset.expectedByteLength) ||
asset.expectedByteLength < 0 ||
asset.expectedByteLength > policy.maxEntryBytes ||
asset.integrity?.algorithm !== "SHA-256" ||
!SHA256_HEX.test(asset.integrity.digestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
return Object.freeze({
absoluteUrl: normalizePublicUrl(asset.absoluteUrl, policy),
expectedByteLength: asset.expectedByteLength,
expectedContentType: normalizeContentType(
asset.expectedContentType,
policy,
),
digestHex: asset.integrity.digestHex,
requestHeaders: normalizeRequestHeaders(
asset.requestHeaders,
policy,
),
});
}
export function normalizeLookupRequest(
absoluteUrl: string,
requestHeaders: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
return {
absoluteUrl: normalizePublicUrl(absoluteUrl, policy),
expectedByteLength: 0,
expectedContentType: "",
digestHex: ZERO_SHA256,
requestHeaders: normalizeRequestHeaders(requestHeaders, policy),
};
}
export function normalizeContentType(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (
typeof input !== "string" ||
input.length < 1 ||
input.length > 256 ||
/[\r\n\0]/u.test(input) ||
!policy.isContentTypeAllowed(input)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return input
.split(";")
.map((part) => part.trim())
.filter((part) => part.length > 0)
.map((part, index) =>
index === 0 ? part.toLowerCase() : part,
)
.join("; ");
}
export function normalizePublicUrl(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (typeof input !== "string" || input.length > 2_048) {
throw new CacheValidationFailure("INVALID_INPUT");
}
let url: URL;
try {
url = new URL(input);
} catch {
throw new CacheValidationFailure("INVALID_INPUT");
}
if (
url.origin !== policy.origin ||
!isAllowedPublicCacheOrigin(url) ||
url.username.length > 0 ||
url.password.length > 0 ||
url.hash.length > 0 ||
url.href === markerRequestUrl(policy) ||
url.href === activePointerRequestUrl(policy)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const forbidden = new Set(policy.forbiddenQueryParameterNames);
const allowed = new Set(policy.allowedQueryParameterNames);
const seenNames = new Set<string>();
for (const [rawName, value] of url.searchParams.entries()) {
const name = rawName.toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
seenNames.has(name) ||
!policy.isQueryParameterValueAllowed(name, value)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
seenNames.add(name);
}
return url.href;
}
export function normalizeRequestHeaders(
input: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedRequestHeaderNames);
const forbidden = new Set([
"authorization",
"cookie",
"proxy-authorization",
"range",
]);
const headers = new Headers();
for (const pair of input ?? []) {
if (
!Array.isArray(pair) ||
pair.length !== 2 ||
typeof pair[0] !== "string" ||
typeof pair[1] !== "string"
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const name = pair[0].toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
pair[1].length > 1_024 ||
/[\r\n\0]/u.test(pair[1])
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
headers.append(name, pair[1].trim());
}
return Object.freeze(
[...headers.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(
([name, value]) =>
Object.freeze([name, value]) as PublicCacheHeader,
),
);
}
export async function readBoundedJson(
response: Response,
maximumBytes: number,
): Promise<unknown> {
const contentLength = response.headers.get("content-length");
if (
!Number.isSafeInteger(maximumBytes) ||
maximumBytes <= 0 ||
(contentLength !== null &&
(!/^\d+$/u.test(contentLength) ||
Number(contentLength) > maximumBytes))
) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
if (!response.body) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const reader = response.body.getReader();
// Q-6.2-6. Chunks are kept as read; the budget is enforced on their total,
// never by preallocating it.
const chunks: Uint8Array[] = [];
let byteLength = 0;
let completelyRead = false;
try {
while (true) {
const chunk = await reader.read();
if (chunk.done) {
completelyRead = true;
break;
}
if (chunk.value.byteLength > maximumBytes - byteLength) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
chunks.push(chunk.value);
byteLength += chunk.value.byteLength;
}
} catch (error) {
if (!completelyRead) {
cancelReaderSafely(
reader,
"Cache control JSON exceeded its read budget.",
);
}
throw error;
} finally {
reader.releaseLock();
}
const bytes = new Uint8Array(byteLength);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
let text: string;
try {
text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
try {
return JSON.parse(text);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
}
export function cancelReaderSafely(
reader: ReadableStreamDefaultReader<Uint8Array>,
reason: string,
): void {
try {
void reader.cancel(reason).catch(() => undefined);
} catch {
// Cancellation is best effort once the bounded consumer has stopped.
}
}
export function isReleaseMarker(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ReleaseMarker {
if (
!value ||
typeof value !== "object" ||
!("schemaVersion" in value) ||
value.schemaVersion !== 1 ||
!("verified" in value) ||
value.verified !== true ||
!("releaseRegistryId" in value) ||
typeof value.releaseRegistryId !== "string" ||
!policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) ||
!("manifestDigestHex" in value) ||
typeof value.manifestDigestHex !== "string" ||
!SHA256_HEX.test(value.manifestDigestHex) ||
!("entryCount" in value) ||
typeof value.entryCount !== "number" ||
!Number.isSafeInteger(value.entryCount) ||
!("totalBytes" in value) ||
typeof value.totalBytes !== "number" ||
!Number.isSafeInteger(value.totalBytes) ||
!("stagedAtEpochMs" in value) ||
typeof value.stagedAtEpochMs !== "number" ||
!Number.isSafeInteger(value.stagedAtEpochMs) ||
!("assets" in value) ||
!Array.isArray(value.assets) ||
value.assets.length > policy.maxEntriesPerRelease
) {
return false;
}
try {
const normalized = normalizeAssets(
value.assets.map((asset) => markerAssetToPublicAsset(asset)),
policy,
);
return stableJson(normalized) === stableJson(value.assets);
} catch {
return false;
}
}
export function markerAssetToPublicAsset(value: unknown): PublicCacheAsset {
if (!value || typeof value !== "object") {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const asset = value as Partial<NormalizedAsset>;
return {
absoluteUrl: asset.absoluteUrl ?? "",
expectedByteLength: asset.expectedByteLength ?? -1,
expectedContentType: asset.expectedContentType ?? "",
integrity: {
algorithm: "SHA-256",
digestHex: asset.digestHex ?? "",
},
requestHeaders: asset.requestHeaders,
};
}
export function isActivePointer(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ActiveReleasePointer {
return Boolean(
value &&
typeof value === "object" &&
"schemaVersion" in value &&
value.schemaVersion === 1 &&
"releaseRegistryId" in value &&
typeof value.releaseRegistryId === "string" &&
policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) &&
"manifestDigestHex" in value &&
typeof value.manifestDigestHex === "string" &&
SHA256_HEX.test(value.manifestDigestHex) &&
"candidateCacheName" in value &&
typeof value.candidateCacheName === "string" &&
value.candidateCacheName ===
releaseCacheName(
policy,
value.releaseRegistryId,
value.manifestDigestHex,
) &&
"rollbackCandidateCacheNames" in value &&
Array.isArray(value.rollbackCandidateCacheNames) &&
value.rollbackCandidateCacheNames.length <=
policy.retainedPreviousReleaseCount &&
new Set(value.rollbackCandidateCacheNames).size ===
value.rollbackCandidateCacheNames.length &&
value.rollbackCandidateCacheNames.every(
(name) =>
typeof name === "string" &&
name !== value.candidateCacheName &&
isOwnedReleaseCacheName(name, policy),
) &&
"activatedAtEpochMs" in value &&
typeof value.activatedAtEpochMs === "number" &&
Number.isSafeInteger(value.activatedAtEpochMs),
);
}
export function isOwnedReleaseCacheName(
name: string,
policy: PublicCacheRuntimePolicy,
): boolean {
if (!name.startsWith(`${policy.ownedCachePrefix}release:`)) {
return false;
}
const remainder = name.slice(
`${policy.ownedCachePrefix}release:`.length,
);
const separator = remainder.lastIndexOf(":");
if (separator < 1) return false;
const releaseRegistryId = remainder.slice(0, separator);
const digestHex = remainder.slice(separator + 1);
return (
policy.isReleaseRegistryIdAllowed(releaseRegistryId) &&
SHA256_HEX.test(digestHex)
);
}
export function canonicalManifest(
releaseRegistryId: string,
assets: readonly NormalizedAsset[],
): string {
return [
"ca-public-cache-manifest-v1",
`release:${releaseRegistryId}`,
...[...assets]
.sort((left, right) => assetKey(left).localeCompare(assetKey(right)))
.map(
(asset) =>
`${assetKey(asset)}:${asset.expectedByteLength}:${JSON.stringify(asset.expectedContentType)}:${asset.digestHex}`,
),
"",
].join("\n");
}
export function assetKey(
asset: Pick<NormalizedAsset, "absoluteUrl" | "requestHeaders">,
): string {
return JSON.stringify([asset.absoluteUrl, asset.requestHeaders]);
}
export function markerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(markerRequestUrl(policy), { method: "GET" });
}
export function activePointerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(activePointerRequestUrl(policy), { method: "GET" });
}
export function markerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/candidate`;
}
export function activePointerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/active`;
}
export function controlCacheName(policy: PublicCacheRuntimePolicy): string {
return `${policy.ownedCachePrefix}control`;
}
export function releaseCacheName(
policy: PublicCacheRuntimePolicy,
releaseRegistryId: string,
manifestDigestHex: string,
): string {
return `${policy.ownedCachePrefix}release:${releaseRegistryId}:${manifestDigestHex}`;
}
export function jsonResponse(value: unknown): Response {
return new Response(JSON.stringify(value), {
status: 200,
headers: {
"cache-control": "no-store",
"content-type": "application/json; charset=utf-8",
},
});
}
export function validationFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
return error instanceof CacheValidationFailure
? failureForCode(error.code, operation)
: asFailure(browserDataFailure("INVALID_INPUT", operation));
}
export function exceptionFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (error instanceof CacheValidationFailure) {
return failureForCode(error.code, operation);
}
const mapped = mapBrowserDataException(error, operation);
if (mapped.ok) {
return asFailure(
browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return mapped;
}
export function failureForCode(
code: BrowserDataFailureCode,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (code === "ABORTED") {
return asFailure(browserDataFailure(code, operation));
}
if (code === "INTEGRITY_FAILED" || code === "CORRUPT_DATA") {
return asFailure(
browserDataFailure(code, operation, { recovery: "REHYDRATE" }),
);
}
if (code === "QUOTA_EXCEEDED") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "ONLINE_ONLY",
}),
);
}
if (code === "BLOCKED" || code === "UNAVAILABLE") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return asFailure(browserDataFailure(code, operation));
}
export function asFailure(
result: BrowserDataResult<never>,
): BrowserFailureResult {
if (result.ok) {
throw new TypeError("Expected a browser data failure.");
}
return result;
}
export async function sha256Hex(
crypto: PublicCacheCryptoFacade,
bytes: Uint8Array<ArrayBuffer>,
): Promise<string> {
const digest = await crypto.digestSha256(bytes);
let hex = "";
for (const byte of new Uint8Array(digest)) {
hex += byte.toString(16).padStart(2, "0");
}
return hex;
}
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new CacheValidationFailure("CORRUPT_DATA");
}
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
export const ZERO_SHA256 = "0".repeat(64);
export const MAX_CONTROL_JSON_BYTES = 2 * 1024 * 1024;
@@ -137,6 +137,9 @@ export function assertPublicCachePolicy(
// rejected at composition instead of producing an unusable candidate.
(policy.allowedVaryHeaderNames.length > 0 &&
!policy.allowedResponseHeaderNames.includes("vary")) ||
// Activation re-validates the stored Content-Type, so stripping it would
// make every activation fail as INTEGRITY_FAILED.
!policy.allowedResponseHeaderNames.includes("content-type") ||
policy.forbiddenQueryParameterNames.some((name) => name.length === 0) ||
policy.allowedQueryParameterNames.some((name) =>
policy.forbiddenQueryParameterNames.includes(name),
@@ -0,0 +1,239 @@
import type { PublicCacheHeader } from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import { browserDataSuccess } from "../browser-file-storage/result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import {
CacheValidationFailure,
cancelReaderSafely,
exceptionFailure,
normalizeContentType,
sha256Hex,
type NormalizedAsset,
type PublicCacheCryptoFacade,
} from "./public-cache-codec.ts";
import type { PublicCacheRuntimePolicy } from "./public-cache-policy.ts";
/**
* Q-6.2-11. Admission of a network or cached response for one manifest asset:
* status, cache directives, content type, Vary, bounded body read and digest.
* Moved verbatim out of the adapter.
*/
export type CacheReadResult = Readonly<{
bytes: Uint8Array;
headers: readonly PublicCacheHeader[];
}>;
export async function readAndValidateResponse(
response: Response,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
signal: AbortSignal | undefined,
): Promise<BrowserDataResult<CacheReadResult>> {
try {
if (
response.status !== 200 ||
!response.ok ||
response.redirected ||
response.type === "opaque" ||
response.type === "opaqueredirect" ||
response.type === "error" ||
(response.url.length > 0 &&
new URL(response.url).href !== asset.absoluteUrl)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const cacheControl = response.headers.get("cache-control") ?? "";
const directives = new Set(
cacheControl
.split(",")
.map((part) => part.trim().split("=", 1)[0]?.toLowerCase())
.filter((part): part is string => Boolean(part)),
);
if (
directives.has("private") ||
directives.has("no-store") ||
directives.has("no-cache") ||
(response.headers.get("pragma") ?? "")
.toLowerCase()
.includes("no-cache") ||
response.headers.has("set-cookie") ||
response.headers.has("set-cookie2") ||
response.headers.has("www-authenticate")
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const contentType = response.headers.get("content-type");
if (!contentType || !policy.isContentTypeAllowed(contentType)) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
if (
normalizeContentType(contentType, policy) !==
asset.expectedContentType
) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
validateVary(response.headers.get("vary"), asset, policy);
const declaredLength = response.headers.get("content-length");
if (
declaredLength !== null &&
(!/^\d+$/u.test(declaredLength) ||
Number(declaredLength) > policy.maxEntryBytes)
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const bytes = await readBodyBounded(
response,
asset.expectedByteLength,
policy.maxEntryBytes,
signal,
);
const digestHex = await sha256Hex(crypto, bytes);
if (digestHex !== asset.digestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const headers = sanitizedResponseHeaders(response.headers, policy);
return browserDataSuccess({ bytes, headers });
} catch (error) {
return exceptionFailure(error, "CACHE_STAGE");
}
}
export async function readBodyBounded(
response: Response,
expectedByteLength: number,
maxEntryBytes: number,
signal: AbortSignal | undefined,
): Promise<Uint8Array<ArrayBuffer>> {
if (expectedByteLength > maxEntryBytes) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
if (!response.body) {
if (expectedByteLength === 0) return new Uint8Array();
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const output = new Uint8Array(expectedByteLength);
const reader = response.body.getReader();
let offset = 0;
// The kernel owner ends a pending read on abort instead of a listener pair.
const owner = createAbortableOperation({ signal });
const abortRead = (): CacheValidationFailure => {
cancelReaderSafely(reader, "Public cache body read was aborted.");
return new CacheValidationFailure("ABORTED");
};
try {
while (true) {
if (owner.signal.aborted) throw abortRead();
const raced = await owner.race(reader.read());
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind === "TERMINAL" || owner.signal.aborted) {
throw abortRead();
}
const part = raced.value;
if (part.done) break;
if (
!(part.value instanceof Uint8Array) ||
offset + part.value.byteLength > expectedByteLength ||
offset + part.value.byteLength > maxEntryBytes
) {
cancelReaderSafely(
reader,
"Public cache body exceeded its read budget.",
);
throw new CacheValidationFailure(
offset + part.value.byteLength > maxEntryBytes
? "LIMIT_EXCEEDED"
: "INTEGRITY_FAILED",
);
}
output.set(part.value, offset);
offset += part.value.byteLength;
}
} finally {
owner.close();
reader.releaseLock();
}
if (offset !== expectedByteLength) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return output;
}
export function validateVary(
vary: string | null,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
): void {
const expected = new Set(
asset.requestHeaders.map(([name]) => name.toLowerCase()),
);
const actual = new Set<string>();
if (!vary) {
if (expected.size > 0) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return;
}
const allowed = new Set(policy.allowedVaryHeaderNames);
for (const item of vary.split(",")) {
const name = item.trim().toLowerCase();
// Browser-managed: Accept-Encoding is a forbidden request header, so no
// script-built Request carries it. Stored and lookup requests both lack it
// and Cache.match still matches exactly. nginx `gzip_vary` and most CDNs
// send it on every compressible asset.
if (name === "accept-encoding") continue;
if (
name === "*" ||
name === "authorization" ||
name === "cookie" ||
!allowed.has(name)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
actual.add(name);
}
if (
actual.size !== expected.size ||
[...actual].some((name) => !expected.has(name))
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
}
export function sanitizedResponseHeaders(
headers: Headers,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedResponseHeaderNames);
const sanitized: PublicCacheHeader[] = [];
for (const [name, value] of headers.entries()) {
if (!allowed.has(name)) {
if (policy.unknownResponseHeaderAction === "REJECT") {
throw new CacheValidationFailure("POLICY_REJECTED");
}
continue;
}
sanitized.push(Object.freeze([name, value]));
}
return Object.freeze(sanitized);
}
export function createNativeRequest(
asset: NormalizedAsset,
signal?: AbortSignal,
): Request {
return new Request(asset.absoluteUrl, {
method: "GET",
headers: new Headers(
asset.requestHeaders.map(([name, value]) => [name, value]),
),
credentials: "omit",
cache: "no-store",
redirect: "error",
referrerPolicy: "no-referrer",
mode: "same-origin",
signal,
});
}
File diff suppressed because it is too large Load Diff
@@ -36,6 +36,20 @@ const CHANNEL_NAME = "ca-client-cache-invalidation-v1";
const STORAGE_PULSE_KEY =
STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE.physicalKey;
/**
* Q-6.2-9. A release ID may hold any character (`1.2.3+sha.abc`, `feature/x`,
* `app@1.2.3`) and any length, but a cache epoch is an opaque identifier. The
* epoch is a stable 64-bit FNV-1a digest of the ID, so every tab of one release
* agrees on it and it always passes the wire rule.
*/
export function crossContextCacheEpochForRelease(releaseId: string): string {
let hash = 0xcbf29ce484222325n;
for (const byte of new TextEncoder().encode(releaseId)) {
hash = ((hash ^ BigInt(byte)) * 0x100000001b3n) & 0xffffffffffffffffn;
}
return `release.${hash.toString(16).padStart(16, "0")}`;
}
/**
* Captures native capabilities without allowing a SecurityError getter or a
* missing random source to fail application boot.
@@ -49,17 +63,38 @@ export function createBrowserCrossContextInvalidationFromHost(
const host =
dependencies.host ??
(globalThis as unknown as Record<string, unknown>);
// Q-6.2-9. Ending inactive is reported, so cross-tab invalidation is never
// switched off without a diagnostic.
const inactive = (
reason: "INVALID_CACHE_EPOCH" | "SECURE_RANDOM_UNAVAILABLE",
): undefined => {
try {
dependencies.observe?.(
Object.freeze({
operation: "OPEN" as const,
outcome: "FAILED" as const,
transport: "NONE" as const,
reason,
}),
);
} catch {
// Diagnostics cannot change the capability decision.
}
return undefined;
};
if (
!isCacheInvalidationOpaqueIdentifier(dependencies.cacheEpoch)
) {
return undefined;
return inactive("INVALID_CACHE_EPOCH");
}
const createOpaqueId = randomIdFactory(host);
if (!createOpaqueId) return undefined;
if (!createOpaqueId) return inactive("SECURE_RANDOM_UNAVAILABLE");
const sourceId = createOpaqueId("tab");
const sourceEpoch = createOpaqueId("page");
if (!sourceId || !sourceEpoch) return undefined;
if (!sourceId || !sourceEpoch) {
return inactive("SECURE_RANDOM_UNAVAILABLE");
}
const capturedLocalStorage = captureLocalStorage(host);
@@ -13,6 +13,12 @@ import {
export type CrossContextInvalidationStatus =
| "ACTIVE_BROADCAST"
| "ACTIVE_STORAGE_FALLBACK"
/**
* The browser has BroadcastChannel but this tab could not open it. Other
* tabs publish on BroadcastChannel only, so this tab misses their events
* while its own storage pulses still reach them.
*/
| "DEGRADED_STORAGE_FALLBACK"
| "DEGRADED_LOCAL_ONLY"
| "CLOSED";
@@ -37,9 +43,11 @@ export type CrossContextInvalidationObservationReason =
| "DELIVERED"
| "DUPLICATE"
| "HANDLER_FAILED"
| "INVALID_CACHE_EPOCH"
| "OPENED"
| "PUBLISHED"
| "SELF_ECHO"
| "SECURE_RANDOM_UNAVAILABLE"
| "SEQUENCE_EXHAUSTED"
| "STALE"
| "STORAGE_CLEANUP_FAILED"
@@ -145,10 +153,9 @@ export type BrowserCrossContextInvalidation = Readonly<{
}>;
type SeenEvent = Readonly<{ expiresAt: number }>;
type SourceHighWatermark = Readonly<{
sequence: number;
expiresAt: number;
}>;
// No TTL: a watermark must outlive its last event, or the next event after a
// quiet period reads as a GAP. `sourceCapacity` LRU bounds the memory.
type SourceHighWatermark = Readonly<{ sequence: number }>;
const DEFAULT_EVENT_TTL_MS = 60_000;
const DEFAULT_DEDUPE_CAPACITY = 1_024;
@@ -177,6 +184,10 @@ export function createBrowserCrossContextInvalidation(
let closed = false;
let sequence = 0;
let broadcast: BroadcastChannelFacade | undefined;
let broadcastOpenFailed = false;
// A failed postMessage moves publishing to storage but keeps the channel
// open, because other tabs keep publishing on it.
let broadcastPublishFailed = false;
let storageListenerInstalled = false;
let status: CrossContextInvalidationStatus = "DEGRADED_LOCAL_ONLY";
@@ -250,6 +261,7 @@ export function createBrowserCrossContextInvalidation(
// Opening still falls back when provider cleanup is rejected.
}
}
broadcastOpenFailed = true;
observe({
operation: "OPEN",
outcome: "DEGRADED",
@@ -262,14 +274,16 @@ export function createBrowserCrossContextInvalidation(
function refreshStatus(): void {
if (closed) {
status = "CLOSED";
} else if (broadcast) {
} else if (broadcast && !broadcastPublishFailed) {
status = "ACTIVE_BROADCAST";
} else if (
dependencies.storage &&
dependencies.storageEvents &&
storageListenerInstalled
) {
status = "ACTIVE_STORAGE_FALLBACK";
status = broadcastOpenFailed
? "DEGRADED_STORAGE_FALLBACK"
: "ACTIVE_STORAGE_FALLBACK";
} else {
status = "DEGRADED_LOCAL_ONLY";
}
@@ -323,7 +337,7 @@ export function createBrowserCrossContextInvalidation(
sequence = candidate.sequence;
pruneTracking(emittedAt);
if (broadcast) {
if (broadcast && !broadcastPublishFailed) {
try {
broadcast.postMessage(candidate);
observe({
@@ -343,7 +357,7 @@ export function createBrowserCrossContextInvalidation(
transport: "BROADCAST",
reason: "BROADCAST_PUBLISH_FAILED",
});
closeBroadcast();
broadcastPublishFailed = true;
refreshStatus();
}
}
@@ -414,7 +428,7 @@ export function createBrowserCrossContextInvalidation(
reason: "STORAGE_CLEANUP_FAILED",
});
}
status = "ACTIVE_STORAGE_FALLBACK";
refreshStatus();
observe({
operation: "PUBLISH",
outcome: "ACCEPTED",
@@ -497,10 +511,7 @@ export function createBrowserCrossContextInvalidation(
event.sequence > previous.sequence + 1)
? "GAP"
: "NEXT";
touchSource(sourceKey, {
sequence: event.sequence,
expiresAt: event.expiresAt,
});
touchSource(sourceKey, { sequence: event.sequence });
const delivery = Object.freeze({ event, ordering, transport });
for (const listener of [...listeners]) {
@@ -546,11 +557,6 @@ export function createBrowserCrossContextInvalidation(
for (const [eventId, entry] of seenEvents) {
if (entry.expiresAt <= currentTime) seenEvents.delete(eventId);
}
for (const [sourceKey, entry] of sourceHighWatermarks) {
if (entry.expiresAt <= currentTime) {
sourceHighWatermarks.delete(sourceKey);
}
}
}
function subscribe(
@@ -19,5 +19,6 @@ export {
} from "./browser-cross-context-invalidation.ts";
export {
createBrowserCrossContextInvalidationFromHost,
crossContextCacheEpochForRelease,
type BrowserCrossContextHostDependencies,
} from "./browser-cross-context-host.ts";
+53 -29
View File
@@ -7,6 +7,7 @@ import {
} from "../../contracts/errors.ts";
import { mapOperationPayload } from "./resource-mapper.ts";
import { retryDelay, shouldRetry } from "./retry-policy.ts";
import { parseRetryAfterDelay } from "../platform/retry-after.ts";
import {
validateEnvelope,
validateOperationPayload,
@@ -40,7 +41,7 @@ import type { ClockPort } from "../../application/ports/clock-port.ts";
import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.ts";
import type { TelemetryPort } from "../../application/ports/telemetry-port.ts";
import type { ApiOperation } from "../../contracts/api-operations.ts";
import type { ApiFailure } from "../../contracts/errors.ts";
import type { ApiFailure, FailureKind } from "../../contracts/errors.ts";
import type { OperationRequestInput } from "./request-builder.ts";
import { readBoundedJson } from "./bounded-json.ts";
import { admitCredentialHeaders } from "./http-contract-bridge.ts";
@@ -48,7 +49,7 @@ import type { MappingResult } from "../../contracts/boundary-mapper.ts";
import {
createRestProviderProfile,
resolveRestSecurityProfiles,
REST_AUTH_PROFILES,
INSTALLED_REST_AUTH_PROFILES,
REST_CSRF_PROFILES,
type RestAuthProfile,
type RestCsrfProfile,
@@ -105,6 +106,11 @@ export type HttpClientDependencies = Readonly<{
payload: unknown,
) => MappingResult<unknown>;
idempotencyKeyFactory?: () => string;
/**
* Default total deadline for an operation without its own `timeoutMs`. Not a
* ceiling: an operation may set a longer one. V3 treats `REQUEST_TIMEOUT_MS`
* as a ceiling instead (03-06).
*/
timeoutMs?: number;
maxRetryAttempts?: number;
scheduler?: Scheduler;
@@ -336,12 +342,11 @@ export function createHttpClient(
);
}
// Q-6.3-11. Recovery is its own single replay, bounded by
// `recoveryUsed` and the deadline, not by the retry budget: a disabled
// or spent budget must not turn a recoverable 401 into a logout.
if (outcome.error.httpStatus === 401 && !recoveryUsed) {
recoveryUsed = true;
if (physicalAttemptCount >= maxRetryAttempts + 1) {
authSession.onUnauthenticated();
return finalize(outcome, "failed");
}
let recovered: SessionRecoveryOutcome;
// LEG-01. The recovery collaborator receives the request lifetime, and
// the transport races the same signal so a non-cooperative owner cannot
@@ -562,7 +567,7 @@ export function createHttpClient(
security = resolveRestSecurityProfiles(
operation,
provider,
dependencies.authProfiles ?? REST_AUTH_PROFILES,
dependencies.authProfiles ?? INSTALLED_REST_AUTH_PROFILES,
dependencies.csrfProfiles ?? REST_CSRF_PROFILES,
);
}
@@ -842,6 +847,17 @@ export function createHttpClient(
class LogicalDeadlineError extends Error {}
/**
* Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
* server outage, not a contract breach: it keeps its status and the normal
* SERVER_FAILURE retry rule instead of a non-retryable body error.
*/
function gatewayFailureOr(status: number, kind: FailureKind): FailureKind {
return status >= 500 || status === 408 || status === 425
? "SERVER_FAILURE"
: kind;
}
async function parseResponse(
response: Response,
operation: ApiOperation,
@@ -853,6 +869,12 @@ async function parseResponse(
) => MappingResult<unknown>,
now: number,
): Promise<HttpResult> {
// R3-1. Retry-After is read only where the retry policy honors it; 502/504
// keep the local backoff.
const retryAfterMs = [408, 425, 429, 503].includes(response.status)
? (parseRetryAfterDelay(response.headers.get("retry-after"), now) ??
undefined)
: undefined;
const contentType = mediaType(response.headers.get("content-type"));
const acceptedMedia = operation.responseMediaTypes ?? ["application/json"];
if (!contentType || !acceptedMedia.includes(contentType)) {
@@ -862,10 +884,16 @@ async function parseResponse(
void response.body?.cancel().catch(() => {});
return {
ok: false,
error: failure("CONTENT_TYPE_MISMATCH", operation.operationId, attempt, {
code: "CONTENT_TYPE_MISMATCH",
httpStatus: response.status,
}),
error: failure(
gatewayFailureOr(response.status, "CONTENT_TYPE_MISMATCH"),
operation.operationId,
attempt,
{
code: "CONTENT_TYPE_MISMATCH",
httpStatus: response.status,
retryAfterMs,
},
),
};
}
@@ -876,10 +904,12 @@ async function parseResponse(
if (!decoded.ok) {
return {
ok: false,
error: failure(decoded.code, operation.operationId, attempt, {
code: decoded.code,
httpStatus: response.status,
}),
error: failure(
gatewayFailureOr(response.status, decoded.code),
operation.operationId,
attempt,
{ code: decoded.code, httpStatus: response.status, retryAfterMs },
),
};
}
const envelope = decoded.value;
@@ -889,12 +919,15 @@ async function parseResponse(
return {
ok: false,
error: failure(
response.ok ? "ENVELOPE_MISMATCH" : statusKind(response.status),
response.ok
? "ENVELOPE_MISMATCH"
: gatewayFailureOr(response.status, statusKind(response.status)),
operation.operationId,
attempt,
{
code: response.ok ? "ENVELOPE_MISMATCH" : "HTTP_FAILURE",
httpStatus: response.status,
retryAfterMs,
},
),
};
@@ -965,8 +998,9 @@ async function parseResponse(
};
}
const kind = statusKind(response.status);
const retryAfter = response.headers.get("retry-after");
// R3-1. V2 treats a 408/425 error envelope as the same server failure as a
// gateway body; the shared status map in contracts is not changed.
const kind = gatewayFailureOr(response.status, statusKind(response.status));
const backendError =
envelopeRecord.error && typeof envelopeRecord.error === "object"
? (envelopeRecord.error as Record<string, unknown>)
@@ -978,10 +1012,7 @@ async function parseResponse(
httpStatus: response.status,
requestId: safeMeta(envelopeRecord.meta).requestId,
traceId: safeMeta(envelopeRecord.meta).traceId,
retryAfterMs:
response.status === 429 && retryAfter
? parseRetryAfterHeader(retryAfter, now)
: undefined,
retryAfterMs,
validationIssues:
response.status === 422
? safeValidationIssues(backendError.details)
@@ -1065,13 +1096,6 @@ function safeMeta(meta: unknown): Record<string, string> {
};
}
function parseRetryAfterHeader(value: string, now: number): number | undefined {
const seconds = Number(value);
if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1_000;
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
}
function safeIdentifier(
value: string,
property: "requestId" | "traceId",
+93 -4
View File
@@ -9,8 +9,10 @@ import {
type ApiFailure,
type FailureEffectCertainty,
type FailureKind,
type ValidationIssue,
} from "../../contracts/errors.ts";
import type { MutationIntent } from "../../contracts/mutation-intent.ts";
import type { ExecutionContext } from "../../platform/execution/execution-context.ts";
import type {
HttpExecutionOutcome,
SafeResponseMetadata,
@@ -64,6 +66,7 @@ export type InstalledHttpOperationExecutor = Readonly<{
routeId: string;
signal?: AbortSignal;
intent?: MutationIntent;
execution?: ExecutionContext;
}>,
): Promise<HttpExecutionOutcome<WireOutput, Problem>>;
}>;
@@ -72,6 +75,11 @@ export type FeatureHttpProblemMapping = Readonly<{
kind: FailureKind;
code: string;
detail?: string;
/**
* 03-04. Field issues read from the problem body. Only `path` and `code`
* survive; `createFailure` bounds them with `projectValidationIssues`.
*/
validationIssues?: readonly ValidationIssue[];
}>;
type FeatureHttpOperationSpec<
@@ -212,6 +220,7 @@ export type FeatureHttpBinding<
context?: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
execution?: ExecutionContext;
}>,
): Promise<Result<OperationValue<Operations[OperationId]>, ApiFailure>>;
}>;
@@ -244,6 +253,7 @@ export function createFeatureHttpBinding<
context: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
execution?: ExecutionContext;
}> = {},
): Promise<Result<OperationValue<Operations[OperationId]>, ApiFailure>> {
const operation = operations[operationId];
@@ -262,6 +272,9 @@ export function createFeatureHttpBinding<
routeId: operation.routeId,
...(context.signal === undefined ? {} : { signal: context.signal }),
...(context.intent === undefined ? {} : { intent: context.intent }),
...(context.execution === undefined
? {}
: { execution: context.execution }),
});
return projectExecutionOutcome(
operation.operationId,
@@ -278,6 +291,10 @@ export function createFeatureHttpBinding<
});
}
/**
* 03-03. A failure carries the server's echoed correlation id as `requestId`,
* so the support reference a user reports points at one server log entry.
*/
function projectExecutionOutcome<WireOutput, Problem, Value>(
operationId: string,
mapSuccess: (value: WireOutput) => MappingResult<Value>,
@@ -289,9 +306,50 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome);
const requestId =
"metadata" in outcome
? outcome.metadata?.correlationReference
: undefined;
return projected.ok || requestId === undefined
? projected
: Object.freeze({
ok: false as const,
error: Object.freeze({ ...projected.error, requestId }),
});
}
function projectOutcome<WireOutput, Problem, Value>(
operationId: string,
mapSuccess: (value: WireOutput) => MappingResult<Value>,
mapProblem:
| ((
problem: Problem,
metadata: SafeResponseMetadata,
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
// A throwing feature mapper is a mapping defect, not a transport failure: it
// must not reject and lose the effect the server already confirmed.
const mapperThrew = (
effect: FailureEffectCertainty,
httpStatus: number,
): Result<Value, ApiFailure> =>
failure(
"MAPPING_CONTRACT_VIOLATION",
operationId,
"MAPPING_CONTRACT_VIOLATION",
{ httpStatus, effect },
);
switch (outcome.kind) {
case "SUCCESS": {
const mapped = mapSuccess(outcome.value);
let mapped: MappingResult<Value>;
try {
mapped = mapSuccess(outcome.value);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return mapped.ok
? Object.freeze({ ok: true as const, value: mapped.value })
: failure(
@@ -302,7 +360,12 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
);
}
case "PROBLEM": {
const mapped = mapProblem?.(outcome.problem, outcome.metadata);
let mapped: FeatureHttpProblemMapping | undefined;
try {
mapped = mapProblem?.(outcome.problem, outcome.metadata);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return failure(
mapped?.kind ?? kindForStatus(outcome.metadata.status),
operationId,
@@ -311,6 +374,9 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
...(mapped?.detail === undefined ? {} : { detail: mapped.detail }),
httpStatus: outcome.metadata.status,
effect: outcome.effect,
...(mapped?.validationIssues === undefined
? {}
: { validationIssues: mapped.validationIssues }),
},
);
}
@@ -351,16 +417,33 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
outcome.failure.kind,
{ effect: outcome.effect },
);
case "CONTRACT_VIOLATION":
case "CONTRACT_VIOLATION": {
const httpStatus = outcome.metadata?.status;
// R-3.3. A gateway 5xx/408/425 with an HTML or empty body is a server
// outage: keep its status and retryability instead of "contact support".
if (httpStatus !== undefined && isServerFailureStatus(httpStatus)) {
return failure("SERVER_FAILURE", operationId, outcome.violation.kind, {
httpStatus,
effect: outcome.effect,
});
}
return failure(
failureKindForViolation(outcome.violation.kind),
operationId,
outcome.violation.kind,
{ effect: outcome.effect },
{
...(httpStatus === undefined ? {} : { httpStatus }),
effect: outcome.effect,
},
);
}
}
}
function isServerFailureStatus(status: number): boolean {
return status >= 500 || status === 408 || status === 425;
}
function failureKindForViolation(
violation: Extract<
HttpExecutionOutcome<unknown, unknown>,
@@ -383,6 +466,11 @@ function failureKindForViolation(
case "PROBLEM_SCHEMA_INVALID":
case "VALIDATOR_RUNTIME_FAILURE":
return "SCHEMA_MISMATCH";
// Rejected before dispatch: the request, not the server answer, was wrong.
case "FINAL_REQUEST_INVARIANT_FAILED":
case "MISSING_IDEMPOTENCY_KEY":
case "UNEXPECTED_IDEMPOTENCY_KEY":
return "VALIDATION_REJECTED";
default:
return "ENVELOPE_MISMATCH";
}
@@ -397,6 +485,7 @@ function failure(
httpStatus?: number;
retryAfterMs?: number;
effect?: FailureEffectCertainty;
validationIssues?: readonly ValidationIssue[];
}> = {},
): Result<never, ApiFailure> {
return Object.freeze({
+29 -4
View File
@@ -50,6 +50,13 @@ export type CredentialAdmissionOutcome =
const MAX_CREDENTIAL_HEADER_VALUE_BYTES = 8_192;
/**
* R-3.4. The one credential value rule for V2 and V3: a ByteString (every code
* unit one byte on the wire) with no C0/C1 control characters. Fetch rejects
* anything else only after the request counts as dispatched.
*/
const CREDENTIAL_HEADER_VALUE = /^[\x20-\x7E\xA0-\xFF]+$/;
/**
* §7.7. Admits a credential patch against the resolved profile before any
* header object is built. A rejection here guarantees `fetch()` is not called:
@@ -82,9 +89,8 @@ export function admitCredentialHeaders(
}
if (
typeof value !== "string" ||
value.length === 0 ||
/[\r\n]/.test(value) ||
encoder.encode(value).byteLength > MAX_CREDENTIAL_HEADER_VALUE_BYTES
!CREDENTIAL_HEADER_VALUE.test(value) ||
value.length > MAX_CREDENTIAL_HEADER_VALUE_BYTES
) {
return frozenAdmissionFailure("CREDENTIAL_HEADER_VALUE_INVALID");
}
@@ -109,6 +115,10 @@ const TRANSPORT_OWNED_HEADERS: ReadonlySet<string> = new Set([
"accept",
"content-type",
"idempotency-key",
// Spec §29. Interaction trace propagation is runtime-owned; a credential
// collaborator can never supply or shadow these.
"traceparent",
"x-correlation-id",
]);
const FORBIDDEN_REQUEST_HEADERS: ReadonlySet<string> = new Set([
@@ -185,7 +195,14 @@ function projectRequestChecked<Input, WireOutput, Problem>(
missing = true;
return "";
}
if (value.includes("/") || value.includes("\\")) {
// A dot segment survives encodeURIComponent and URL resolution would
// move the request to a parent path that still passes the base check.
if (
value.includes("/") ||
value.includes("\\") ||
value === "." ||
value === ".."
) {
invalid = true;
return "";
}
@@ -314,6 +331,7 @@ export type FinalInvariantFailure =
| "CREDENTIAL_HEADER_NOT_ALLOWED"
| "MISSING_REQUIRED_CREDENTIAL_HEADER"
| "FORBIDDEN_HEADER"
| "HEADER_VALUE_INVALID"
| "REQUEST_BODY_TOO_LARGE"
| "DEADLINE_EXPIRED"
| "SCOPE_FENCED";
@@ -372,6 +390,13 @@ export function checkFinalInvariants(
return "MISSING_REQUIRED_CREDENTIAL_HEADER";
}
}
// Fetch validates header values only once it is called; build them here so
// any value it would reject fails before dispatch, not as a network error.
try {
new Headers(input.headers);
} catch {
return "HEADER_VALUE_INVALID";
}
if (
input.request.bodyBytes &&
@@ -128,6 +128,28 @@ export function classifyProblemEffect<Problem>(
});
}
/**
* D-2. A dispatched command answered 401, 403 or 429 is `MAYBE_APPLIED` unless
* the package classifies that status as `NOT_APPLIED`. Any other answer, or a
* throw, fails safe to `MAYBE_APPLIED`.
*/
export function classifyStatusEffect<Problem>(
descriptor: CommandEffectDescriptor<Problem> | null,
status: 401 | 403 | 429,
abandoned: MutationEffectCertainty,
): MutationEffectCertainty {
if (abandoned !== "MAYBE_APPLIED" || !descriptor?.classifyStatus) {
return abandoned;
}
try {
return descriptor.classifyStatus(status) === "NOT_APPLIED"
? "NOT_APPLIED"
: "MAYBE_APPLIED";
} catch {
return "MAYBE_APPLIED";
}
}
/** §8.10. Certainty to UI intent. The copy itself is owned by the i18n catalog. */
export function projectCertaintyToUi(
certainty: MutationEffectCertainty,
+288 -100
View File
@@ -36,11 +36,28 @@ import {
import {
certaintyForAbandonedAttempt,
classifyProblemEffect,
classifyStatusEffect,
joinMutationEffectCertainty,
type MutationEffectCertainty,
type PhysicalAttemptState,
} from "./http-effect-certainty.ts";
import { parseRetryAfter } from "./retry-policy.ts";
import {
createExecutionContext,
MAX_INTERACTION_DEADLINE_MS,
type ExecutionContext,
} from "../../platform/execution/execution-context.ts";
import {
ConcurrencyQueueFullError,
type ConcurrencyLease,
} from "../../platform/traffic/concurrency-budget.ts";
import type { TrafficBudget } from "../../platform/traffic/traffic-budget.ts";
import { checkJsonStructure } from "../../platform/validation/bounded-json.ts";
import {
buildTraceHeaders,
CORRELATION_ID_HEADER,
} from "../../platform/telemetry/trace-context.ts";
import { responseValidationBudget } from "../../platform/validation/validation-budget.ts";
import {
canRetryTransport,
isRetryableHttpStatus,
@@ -121,20 +138,32 @@ export type HttpExecutionOutcome<Value, Problem> =
}>
| Readonly<{
kind: "UNAUTHENTICATED";
/**
* Present only when the server answered 401. Absent means no credential
* existed and nothing was sent; that is not a session verdict.
*/
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
kind: "FORBIDDEN";
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
kind: "RATE_LIMITED";
retryAfterMs?: number;
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
kind: "CONTRACT_VIOLATION";
violation: HttpContractViolation;
/**
* Present when an error status arrived without a usable problem body.
* A 5xx/408/425 here is a server outage, not a contract breach (R-3.3).
*/
metadata?: SafeResponseMetadata;
effect: HttpEffectCertainty;
}>
| Readonly<{
@@ -196,8 +225,28 @@ export interface HttpExecutionContext {
readonly signal?: AbortSignal;
readonly scope: CacheScopeSnapshot;
readonly intent?: MutationIntent;
/**
* Spec §10–§15. The interaction this execution belongs to. Every physical
* attempt consumes the interaction's shared request budget, retry budget and
* concurrency lease, and the interaction's absolute deadline caps the
* operation deadline. Absent, the executor creates a single-operation
* interaction from the operation's own traffic policy, so no execution is
* ever unbudgeted.
*/
readonly execution?: ExecutionContext;
}
/**
* Spec §11. The bounded traffic policy of an operation that declares none:
* one initial attempt plus the hard retry ceiling, strictly sequential.
*/
export const DEFAULT_OPERATION_TRAFFIC_BUDGET: TrafficBudget = Object.freeze({
maxPhysicalRequests: 1 + HTTP_EXECUTION_CEILINGS.hardRetryCount,
maxRetries: HTTP_EXECUTION_CEILINGS.hardRetryCount,
maxConcurrentRequests: 1,
maxQueuedRequests: 0,
});
export interface ContractHttpExecutor {
execute<Input, WireOutput, Problem>(
operation: InstalledHttpContract<Input, WireOutput, Problem>,
@@ -223,6 +272,11 @@ export type HttpExecutionObservation = Readonly<{
durationMs: number;
effect: HttpEffectCertainty;
cancellationOwner?: CancellationOwner;
/**
* 03-03. The server's echoed `x-correlation-id`, else the request id this
* execution sent. Diagnostics only; never telemetry.
*/
correlationId?: string;
/**
* The internal terminal-reason label recorded by the execution site. It is
* evidence for the HTTP scenario catalog only; the composition-root
@@ -267,8 +321,14 @@ function observationErrorKind(
function observationStatus(
outcome: HttpExecutionOutcome<unknown, unknown>,
): number | undefined {
return outcome.kind === "SUCCESS" || outcome.kind === "PROBLEM"
? outcome.metadata.status
return "metadata" in outcome ? outcome.metadata?.status : undefined;
}
function responseCorrelation(
outcome: HttpExecutionOutcome<unknown, unknown>,
): string | undefined {
return "metadata" in outcome
? outcome.metadata?.correlationReference
: undefined;
}
@@ -303,6 +363,8 @@ export type ContractHttpExecutorDependencies = Readonly<{
monotonicNow?: () => number;
sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
random?: () => number;
/** 03-03. One id per logical execution, sent as `x-correlation-id`. */
createRequestId?: () => string;
observe?: (observation: HttpExecutionObservation) => void;
}>;
@@ -383,6 +445,8 @@ export function createContractHttpExecutor(
dependencies.readBoundedResponseBytes ?? readBoundedBytes;
const now = dependencies.monotonicNow ?? (() => performance.now());
const random = dependencies.random ?? Math.random;
const createRequestId =
dependencies.createRequestId ?? (() => globalThis.crypto.randomUUID());
const deadlineCeilingMs = dependencies.requestDeadlineCeilingMs;
const effectiveDeadlineMs = (contractDeadlineMs: number): number =>
typeof deadlineCeilingMs === "number" &&
@@ -417,9 +481,30 @@ export function createContractHttpExecutor(
// §8.5. One monotonic deadline covers credential resolution, encoding,
// backoff, every physical attempt, body read and validation.
const startedAt = now();
const totalDeadlineMs = effectiveDeadlineMs(policy.totalDeadlineMs);
const execution =
context.execution ??
createExecutionContext({
interactionId: "implicit-operation",
deadlineMs: Math.max(
1,
Math.min(
MAX_INTERACTION_DEADLINE_MS,
Math.ceil(effectiveDeadlineMs(policy.totalDeadlineMs)),
),
),
traffic: policy.traffic ?? DEFAULT_OPERATION_TRAFFIC_BUDGET,
clock: now,
startedAt,
});
// Spec §15. A late operation only receives what is left of the
// interaction's absolute deadline; it never restarts its own full timeout.
const totalDeadlineMs = Math.max(
0,
Math.min(effectiveDeadlineMs(policy.totalDeadlineMs), execution.remainingMs()),
);
const deadlineAt = startedAt + totalDeadlineMs;
const remaining = () => deadlineAt - now();
const remaining = () =>
Math.min(deadlineAt - now(), execution.remainingMs());
let attemptState: PhysicalAttemptState = "PREPARING";
let attempts = 0;
@@ -442,6 +527,17 @@ export function createContractHttpExecutor(
kind: HttpTransportFailure["kind"],
): HttpExecutionOutcome<WireOutput, Problem> =>
transportFailure(kind, false, abandonedCertainty());
/**
* Q-6.3-7. What the attempts that were retried settled on. The logical
* accumulator above is raised at dispatch, before the attempt's own answer
* is known, so it cannot tell a rejected attempt from a lost one.
*/
let retriedCertainty: MutationEffectCertainty = "NOT_STARTED";
const rememberRetried = (settled: MutationEffectCertainty) => {
if (isCommand) {
retriedCertainty = joinMutationEffectCertainty(retriedCertainty, settled);
}
};
let terminalCancellation: CancellationOwner | null = null;
const lifetimeController = new AbortController();
const forwardCallerToLifetime = () => {
@@ -460,6 +556,15 @@ export function createContractHttpExecutor(
once: true,
});
}
// Spec §10. Cancelling the interaction cancels every child execution the
// same way the caller's own signal does.
const interactionSignal = context.execution?.cancellation.signal;
if (interactionSignal?.aborted) forwardCallerToLifetime();
else {
interactionSignal?.addEventListener("abort", forwardCallerToLifetime, {
once: true,
});
}
if (context.scope.signal.aborted) forwardScopeToLifetime();
else {
context.scope.signal.addEventListener("abort", forwardScopeToLifetime, {
@@ -476,10 +581,12 @@ export function createContractHttpExecutor(
lifetimeDisposed = true;
clearTimeout(lifetimeDeadlineTimer);
callerSignal?.removeEventListener("abort", forwardCallerToLifetime);
interactionSignal?.removeEventListener("abort", forwardCallerToLifetime);
context.scope.signal.removeEventListener("abort", forwardScopeToLifetime);
lifetimeController.abort();
};
let sentRequestId: string | undefined;
const finish = (
outcome: HttpExecutionOutcome<WireOutput, Problem>,
terminalReason: string,
@@ -487,6 +594,7 @@ export function createContractHttpExecutor(
disposeLifetime();
try {
const status = observationStatus(outcome);
const correlationId = responseCorrelation(outcome) ?? sentRequestId;
dependencies.observe?.(
Object.freeze({
routeId: context.routeId,
@@ -502,6 +610,7 @@ export function createContractHttpExecutor(
...(terminalCancellation === null
? {}
: { cancellationOwner: terminalCancellation }),
...(correlationId === undefined ? {} : { correlationId }),
}),
);
} catch {
@@ -510,6 +619,31 @@ export function createContractHttpExecutor(
return outcome;
};
/**
* Q-6.3-6. The one classifier for a wait that a terminal owner ended. The
* caller cancels and the deadline times out. A scope fence during a `WAIT`
* (credentials, lease, dispatch, backoff) aborts the transport; during
* `ADMISSION` the response headers prove the request reached the server,
* so a stale generation stays the `SCOPE_FENCED` contract violation.
*/
const terminalOutcomeFor = (
phase: "WAIT" | "ADMISSION",
): HttpExecutionOutcome<WireOutput, Problem> => {
switch (terminalCancellation) {
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return phase === "ADMISSION"
? finish(scopeFenced(abandonedCertainty()), "SCOPE_FENCED")
: finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
default:
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
}
};
try {
// §7.7. The installed registry is the only source of a profile. Composition
@@ -612,20 +746,7 @@ export function createContractHttpExecutor(
"AUTH_INTEGRATION_FAILURE",
);
}
if (patchResult === ABORTED) {
if (terminalCancellation === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
return terminalCancellation === "CALLER"
? finish(cancelled("NOT_STARTED"), "CANCELLED")
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (patchResult === ABORTED) return terminalOutcomeFor("WAIT");
// NS-01. The whole answer is decoded once, inside the auth boundary, before
// any field is used. Reading `kind` and `headers` off the raw object left
// the decode outside that boundary: a throwing getter escaped into the
@@ -688,6 +809,21 @@ export function createContractHttpExecutor(
if (intentValidation.intent?.idempotencyKey !== undefined) {
headers["Idempotency-Key"] = intentValidation.intent.idempotencyKey;
}
// Spec §29. Only an interaction that opted into tracing propagates its
// identity; every child request carries the same trace and correlation.
if (context.execution?.trace !== undefined) {
Object.assign(headers, buildTraceHeaders(context.execution));
}
// 03-03. Every other logical execution still sends its own request id,
// shared by its retries, so a failure can be found in the server log.
if (headers[CORRELATION_ID_HEADER] === undefined) {
try {
headers[CORRELATION_ID_HEADER] = createRequestId();
} catch {
// A diagnostic id never blocks the request (e.g. no secure context).
}
}
sentRequestId = headers[CORRELATION_ID_HEADER];
const retryCeiling = Math.min(
policy.retryBudget,
@@ -695,8 +831,15 @@ export function createContractHttpExecutor(
HTTP_EXECUTION_CEILINGS.hardRetryCount,
);
// Spec §13. A retry is admitted only when the interaction still has both a
// shared retry and a physical request left; the retry budget is consumed
// only for a retry that will actually be dispatched.
const admitRetry = (): boolean =>
execution.traffic.requests.remaining > 0 &&
execution.traffic.retries.tryConsume(contract.operationId);
for (let retryIndex = 0; ; retryIndex += 1) {
if (callerSignal?.aborted) {
if (callerSignal?.aborted || interactionSignal?.aborted) {
terminalCancellation ??= "CALLER";
return finish(
cancelled(abandonedCertainty()),
@@ -711,6 +854,32 @@ export function createContractHttpExecutor(
);
}
if (remaining() <= 0) {
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
}
// Spec §11 / §14. Physical request budget first, then a cancellable
// concurrency lease whose wait is bounded by the operation lifetime.
if (!execution.traffic.requests.tryConsume()) {
return finish(
abandonedTransportFailure("OVERLOADED_BEFORE_SEND"),
"TRAFFIC_BUDGET_EXCEEDED",
);
}
let lease: ConcurrencyLease;
try {
lease = await execution.traffic.concurrency.acquire(
lifetimeController.signal,
);
} catch (error) {
if (error instanceof ConcurrencyQueueFullError) {
return finish(
abandonedTransportFailure("OVERLOADED_BEFORE_SEND"),
"TRAFFIC_BUDGET_EXCEEDED",
);
}
return terminalOutcomeFor("WAIT");
}
try {
const controller = new AbortController();
const budget = remaining();
if (budget <= 0) {
@@ -800,49 +969,29 @@ export function createContractHttpExecutor(
} else {
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener("abort", forwardLifetime);
const owner = terminalCancellation;
if (owner === "CALLER") {
return finish(
cancelled(abandonedCertainty()),
"CANCELLED",
);
if (terminalCancellation !== null) {
return terminalOutcomeFor("WAIT");
}
if (owner === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
const kind = owner === "DEADLINE" ? "TIMEOUT" : "NETWORK_FAILURE";
if (
owner === null &&
canRetryTransport(contract.retrySemantics, attemptState) &&
retryIndex < retryCeiling &&
remaining() > 0
) {
const delay = jitteredDelay(retryIndex, random);
if (delay < remaining()) {
if (delay < remaining() && admitRetry()) {
lease.release();
const slept = await awaitWithAbort(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
rememberRetried(certaintyForAbandonedAttempt(attemptState, isCommand));
continue;
}
}
return finish(
abandonedTransportFailure(kind),
kind,
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
);
}
@@ -863,49 +1012,34 @@ export function createContractHttpExecutor(
controller.signal,
() => cancelResponseBody(response),
);
// LIVE-04. Once response headers are in hand the request demonstrably
// reached the server, so a terminal owner that lands during admission
// keeps the dispatched classification: a stale generation stays the
// `SCOPE_FENCED` contract violation it has always been, and only the
// deadline and the caller reclassify the outcome.
const abandonAdmission = ():
| HttpExecutionOutcome<WireOutput, Problem>
| null => {
switch (terminalCancellation) {
case "DEADLINE":
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return finish(
scopeFenced(abandonedCertainty()),
"SCOPE_FENCED",
);
default:
return null;
}
};
// LIVE-04. A terminal owner that lands during admission wins over the
// admitted answer.
if (admission.kind !== "VALUE") {
cancelResponseBody(response);
return (
abandonAdmission() ??
finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
);
return terminalCancellation === null
? finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
: terminalOutcomeFor("ADMISSION");
}
const outcome = admission.value;
attemptState = "SETTLED";
const abandoned = abandonAdmission();
if (abandoned) return abandoned;
if (terminalCancellation !== null) {
return terminalOutcomeFor("ADMISSION");
}
if (
outcome.retryHint &&
// Q-6.3-7. An answer that says the command may already be applied
// is not replayed; reconciliation owns it from here.
outcome.certainty !== "MAYBE_APPLIED" &&
outcome.certainty !== "APPLIED_CONFIRMED" &&
retryIndex < retryCeiling &&
isRetryableSemantics(contract.retrySemantics)
) {
const delay = retryDelayFor(outcome.retryAfterMs, retryIndex, random);
if (delay !== null && delay < remaining()) {
if (delay !== null && delay < remaining() && admitRetry()) {
lease.release();
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener(
"abort",
@@ -915,25 +1049,35 @@ export function createContractHttpExecutor(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
rememberRetried(outcome.result.effect as MutationEffectCertainty);
continue;
}
}
return finish(outcome.result, outcome.certainty);
// Q-6.3-7. A retry never reports less than an earlier attempt of the
// same command already established.
const effect = isCommand
? joinMutationEffectCertainty(
retriedCertainty,
outcome.result.effect as MutationEffectCertainty,
)
: outcome.result.effect;
return finish(
effect === outcome.result.effect
? outcome.result
: (Object.freeze({
...outcome.result,
effect,
}) as HttpExecutionOutcome<WireOutput, Problem>),
outcome.certainty,
);
} finally {
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener("abort", forwardLifetime);
}
} finally {
lease.release();
}
}
} catch {
return finish(
@@ -1034,22 +1178,25 @@ async function admitResponse<Input, WireOutput, Problem>(
}
const metadata = safeMetadata(response, retryAfterMs);
const statusEffect = (classified: 401 | 403 | 429) =>
classifyStatusEffect(
contract.commandEffect,
classified,
certaintyForAbandonedAttempt(attemptState, isCommand),
);
if (!contract.acceptedStatuses.includes(status)) {
if (status === 401) {
await response.body?.cancel().catch(() => {});
return settled(
unauthenticated(
certaintyForAbandonedAttempt(attemptState, isCommand),
isCommand,
),
unauthenticated(statusEffect(401), isCommand, metadata),
"UNAUTHENTICATED",
);
}
if (status === 403) {
await response.body?.cancel().catch(() => {});
return settled(
forbidden(certaintyForAbandonedAttempt(attemptState, isCommand), isCommand),
forbidden(statusEffect(403), isCommand, metadata),
"FORBIDDEN",
);
}
@@ -1059,10 +1206,8 @@ async function admitResponse<Input, WireOutput, Problem>(
result: Object.freeze({
kind: "RATE_LIMITED" as const,
...(retryAfterMs === null ? {} : { retryAfterMs }),
effect: normalizeOptionalEffect(
certaintyForAbandonedAttempt(attemptState, isCommand),
isCommand,
),
metadata,
effect: normalizeOptionalEffect(statusEffect(429), isCommand),
}),
certainty: "RATE_LIMITED",
retryHint: true,
@@ -1191,6 +1336,20 @@ async function admitResponse<Input, WireOutput, Problem>(
"CONTRACT_VIOLATION",
);
}
// Spec §21–§22. Structure before validation/mapping: the byte ceiling
// already bounded the parse; the structural budget bounds what the schema
// validator and mapper are asked to walk.
if (
!checkJsonStructure(
decoded.value,
responseValidationBudget(policy.responseByteLimit),
).ok
) {
return settled(
violation("RESPONSE_TOO_LARGE", "RESPONSE", postDispatchEffect(isCommand)),
"RESPONSE_STRUCTURE_LIMIT",
);
}
const validated = invokeValidator(contract.outputValidator, decoded.value);
if (validated.outcome === "THROWN") {
@@ -1360,6 +1519,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1372,6 +1532,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"CONTENT_TYPE_MISMATCH",
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1386,6 +1547,7 @@ async function admitProblem<Input, WireOutput, Problem>(
decoded.code,
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1393,6 +1555,25 @@ async function admitProblem<Input, WireOutput, Problem>(
});
}
if (
!checkJsonStructure(
decoded.value,
responseValidationBudget(HTTP_EXECUTION_CEILINGS.problemResponseBytes),
).ok
) {
return Object.freeze({
result: violation<WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: false,
retryAfterMs: metadata.retryAfterMs ?? null,
});
}
const validated = invokeValidator(contract.problemValidator, decoded.value);
if (validated.outcome !== "VALID") {
return Object.freeze({
@@ -1402,6 +1583,7 @@ async function admitProblem<Input, WireOutput, Problem>(
: "PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1464,10 +1646,12 @@ function violation<Value, Problem>(
kind: HttpContractViolationKind,
operation: HttpContractViolation["operation"],
effect: HttpEffectCertainty,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "CONTRACT_VIOLATION" as const,
violation: Object.freeze({ kind, operation }),
...(metadata === undefined ? {} : { metadata }),
effect,
});
}
@@ -1504,9 +1688,11 @@ function postDispatchEffect(isCommand: boolean): HttpEffectCertainty {
function unauthenticated<Value, Problem>(
effect: string,
isCommand: boolean,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "UNAUTHENTICATED" as const,
...(metadata === undefined ? {} : { metadata }),
effect: normalizeOptionalEffect(effect, isCommand),
});
}
@@ -1514,9 +1700,11 @@ function unauthenticated<Value, Problem>(
function forbidden<Value, Problem>(
effect: string,
isCommand: boolean,
metadata: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "FORBIDDEN" as const,
metadata,
effect: normalizeOptionalEffect(effect, isCommand),
});
}
+17 -8
View File
@@ -33,25 +33,34 @@ export function isRetryableSemantics(semantics: RetrySemantics): boolean {
return semantics === "SAFE" || semantics === "IDEMPOTENT";
}
function localJitterCeiling(retryIndex: number): number {
return Math.min(RETRY_MAX_LOCAL_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** retryIndex);
}
/** Full jitter over min(2000, 250 * 2^retryIndex). */
export function jitteredDelay(
retryIndex: number,
random: () => number,
): number {
const ceiling = Math.min(
RETRY_MAX_LOCAL_DELAY_MS,
RETRY_BASE_DELAY_MS * 2 ** retryIndex,
);
return Math.floor(random() * ceiling);
return Math.floor(random() * localJitterCeiling(retryIndex));
}
/**
* Spec §13.3. `Retry-After` is a floor, never an exact instant: every client
* that received the same hint would otherwise retry in one synchronized second
* spike. The cohort is spread over a bounded window that grows with the hint
* (a quarter of it) but never beyond the local 2s jitter ceiling.
*/
export function retryDelayFor(
retryAfterMs: number | null,
retryIndex: number,
random: () => number,
): number | null {
const local = jitteredDelay(retryIndex, random);
if (retryAfterMs === null) return local;
if (retryAfterMs === null) return jitteredDelay(retryIndex, random);
if (retryAfterMs > RETRY_AFTER_CEILING_MS) return null;
return Math.max(local, retryAfterMs);
const window = Math.min(
RETRY_MAX_LOCAL_DELAY_MS,
Math.max(localJitterCeiling(retryIndex), Math.ceil(retryAfterMs / 4)),
);
return retryAfterMs + Math.floor(random() * window);
}
+5 -1
View File
@@ -19,6 +19,8 @@ export {
type HttpTransportFailure,
type SafeResponseMetadata,
} from "./http-execution-v3.ts";
/** Spec §17. V3 결과를 플랫폼 오류 봉투(`AppError`)로 정규화한다. */
export { platformErrorForOutcome } from "./platform-error-mapping.ts";
export {
createFeatureHttpBinding,
defineFeatureHttpOperation,
@@ -40,7 +42,9 @@ export type { CredentialPatchOutcome } from "./http-contract-bridge.ts";
*
* 이 템플릿은 V2의 오퍼레이션 레지스트리와 payload 매퍼를 비워서 출하한다.
* 제품이 `RuntimeHttpContract`(`src/bootstrap/runtime-adapters.ts`)의 네
* 슬롯을 주입해야 동작한다 — 주입 없이 V3에서 되돌리면 모든 요청이 실패한다.
* 슬롯을 주입해야 동작한다. V3의 롤백 경로는 아니다 — V2는
* `{ success, data, meta }` 봉투를, V3는 DTO 자체를 검증하므로 V2로 되돌리려면
* 슬롯 주입과 함께 서버 응답도 V2 봉투여야 한다.
*/
export {
createHttpClient,
@@ -0,0 +1,45 @@
import type { AppError } from "../../platform/errors/app-error.ts";
import { PLATFORM_ERRORS } from "../../platform/errors/platform-errors.ts";
import type { HttpExecutionOutcome } from "./http-execution-v3.ts";
/**
* Spec §17. Adapter-boundary normalization of transport-level outcomes into
* the platform error envelope. Only failures no feature owns are mapped here;
* a `PROBLEM`, an auth verdict or a scope fence is interpreted by its owner
* (the feature binding or the session), so those return `null`.
*/
export function platformErrorForOutcome(
outcome: HttpExecutionOutcome<unknown, unknown>,
): AppError | null {
switch (outcome.kind) {
case "CANCELLED":
return PLATFORM_ERRORS.REQUEST_CANCELLED;
case "TRANSPORT_FAILURE":
switch (outcome.failure.kind) {
case "TIMEOUT":
return PLATFORM_ERRORS.REQUEST_TIMEOUT;
case "ABORTED_BY_CALLER":
return PLATFORM_ERRORS.REQUEST_CANCELLED;
case "OVERLOADED_BEFORE_SEND":
return PLATFORM_ERRORS.TRAFFIC_BUDGET_EXCEEDED;
case "ABORTED_BY_SCOPE":
return null;
default:
return PLATFORM_ERRORS.NETWORK_UNAVAILABLE;
}
case "CONTRACT_VIOLATION":
switch (outcome.violation.kind) {
case "RESPONSE_TOO_LARGE":
return PLATFORM_ERRORS.RESPONSE_TOO_LARGE;
case "SCOPE_FENCED":
case "MISSING_IDEMPOTENCY_KEY":
case "UNEXPECTED_IDEMPOTENCY_KEY":
case "FINAL_REQUEST_INVARIANT_FAILED":
return null;
default:
return PLATFORM_ERRORS.RESPONSE_INVALID;
}
default:
return null;
}
}
+3
View File
@@ -73,6 +73,9 @@ export function buildRequestTarget(
if (
serialized.length === 0 ||
serialized.length > 512 ||
// Dot segments are not encoded and pathname assignment normalizes them.
serialized === "." ||
serialized === ".." ||
[...serialized].some((character) => {
const code = character.codePointAt(0) ?? 0;
return code < 32 || code === 127;
+4 -14
View File
@@ -1,3 +1,5 @@
import { parseRetryAfterDelay } from "../platform/retry-after.ts";
const retryKinds: ReadonlySet<string> = new Set([
"NETWORK_UNREACHABLE",
"REQUEST_TIMEOUT",
@@ -18,16 +20,7 @@ export function parseRetryAfter(
value: string | null | undefined,
now = Date.now(),
): number | null {
if (!value) return null;
const seconds = Number(value);
if (Number.isFinite(seconds)) {
return seconds < 0 ? null : seconds * 1_000;
}
const timestamp = Date.parse(value);
if (!Number.isFinite(timestamp)) return null;
return Math.max(0, timestamp - now);
return parseRetryAfterDelay(value, now);
}
export type RetryOperation = Readonly<{
@@ -54,12 +47,11 @@ export function shouldRetry(
if (
failure.kind === "SERVER_FAILURE" &&
failure.httpStatus !== undefined &&
![502, 503, 504].includes(failure.httpStatus)
![408, 425, 502, 503, 504].includes(failure.httpStatus)
) {
return false;
}
if (
failure.kind === "RATE_LIMITED" &&
typeof failure.retryAfterMs === "number" &&
failure.retryAfterMs > 30_000
) {
@@ -75,8 +67,6 @@ export function retryDelay(
now = Date.now(),
): number {
const localBackoff = calculateBackoff(retryIndex, random);
if (failure.kind !== "RATE_LIMITED") return localBackoff;
const retryAfterMs =
typeof failure.retryAfterMs === "number"
? failure.retryAfterMs
+3 -5
View File
@@ -1,4 +1,5 @@
import { z } from "zod";
import { z } from "../../contracts/zod.ts";
import { projectValidationIssues } from "../../contracts/validation-issues.ts";
const metaSchema = z
.object({
@@ -104,9 +105,6 @@ function projectResult(
return {
success: false,
issues: result.error.issues.map((issue) => ({
path: issue.path.join("."),
code: issue.code,
})),
issues: projectValidationIssues(result.error.issues),
};
}
@@ -267,3 +267,49 @@ export function compensateLateHandle(
})
.catch(() => undefined);
}
/**
* Best-effort release of a response body whose result is already classified.
* Neither a synchronous throw nor a rejected cancellation can change that
* result.
*/
export function cancelBody(response: Response): void {
try {
void response.body?.cancel().catch(() => undefined);
} catch {
// The classified result wins over body cancellation.
}
}
/** `cancelBody` for a reader that already holds the body's lock. */
export function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => undefined);
} catch {
// The classified result wins over reader cancellation.
}
}
/** Aborts one signal when either input aborts; `release` only drops listeners. */
export function combineAbortSignals(
first: AbortSignal,
second: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = () => controller.abort();
if (first.aborted || second.aborted) {
controller.abort();
} else {
first.addEventListener("abort", abort, { once: true });
second.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release() {
first.removeEventListener("abort", abort);
second.removeEventListener("abort", abort);
},
});
}
+16 -4
View File
@@ -332,7 +332,9 @@ export function openIndexedDbDatabase<Failure>(
// A null `newVersion` means a delete is in progress, and no `upgrade`
// policy can be applied to a schema that is going away. It is reported
// before the callback runs so a caller never sees a half-open upgrade.
if (!transaction || newVersion === null || !input.upgrade) {
// Q-6.5-10. An open that already settled (caller abort, BLOCKED, close)
// must not commit a migration behind its caller's back either.
if (settled || !transaction || newVersion === null || !input.upgrade) {
upgradeRejection = { kind: "UPGRADE_REJECTED", oldVersion, newVersion };
abortUpgrade();
return;
@@ -425,6 +427,16 @@ export function openIndexedDbDatabase<Failure>(
settle(succeeded(database));
return;
}
// 05-13. Admission is asynchronous and nothing else answers another
// context's upgrade until the caller adopts the connection, so that
// upgrade would wait blocked until its deadline. While admission runs, a
// versionchange closes this connection and ends the open as CLOSED. An
// `admit` that installs its own handler replaces this one.
database.onversionchange = () => {
if (settled) return;
closeQuietly(database);
settleFailure({ kind: "CLOSED" });
};
let admission: IndexedDbAdmission | Promise<IndexedDbAdmission>;
try {
admission = input.admit(database);
@@ -603,9 +615,9 @@ export function createIndexedDbConnection<Failure>(
/**
* In this module because it is the same `IDBOpenDBRequest` state machine as
* `openIndexedDbDatabase`, not because three subsystems need it — only
* `indexeddb-checkpoint-store.ts` deletes a database, and nothing here asks the
* other three to start. Leaving it out would leave a third hand-written copy of
* `openIndexedDbDatabase`. Two callers delete a database:
* `indexeddb-checkpoint-store.ts`, and the IndexedDB runtime's authorized
* LOGOUT/ACCOUNT_DELETION purge when its dataset fails admission. Leaving it out would leave a third hand-written copy of
* the settle-once blocked-deadline latch eight lines away from the kernel's.
*
* There is deliberately no `signal`: the request cannot be cancelled after
@@ -26,7 +26,8 @@ export type IndexedDbDurability = "default" | "strict" | "relaxed";
*/
export type IndexedDbRequestSink<Failure> = Readonly<{
/**
* Records the failure and aborts the transaction. The first failure wins.
* Records the failure and aborts the transaction. The first failure wins,
* and it wins over an earlier `succeed`.
* This is `indexeddb-runtime.ts:1047-1054`'s `fail`.
*/
fail(failure: Failure): void;
@@ -266,7 +267,9 @@ export function runIndexedDbTransaction<Value, Failure>(
candidate ??= succeeded(value);
},
fail(failure) {
candidate ??= failed(failure);
// Q-6.5-10. A failure replaces an earlier `succeed`; only an earlier
// failure outranks it.
if (candidate?.ok !== false) candidate = failed(failure);
try {
transaction.abort();
} catch {
+38
View File
@@ -0,0 +1,38 @@
/**
* Parses an HTTP Retry-After value: delta-seconds (digits only, surrounding
* whitespace allowed) or an IMF-fixdate. Anything else — decimals, exponents,
* blank text, other date spellings — is `null`, never a guessed delay.
* No runtime ceiling is applied; callers reject a value above their budget.
*/
export function parseRetryAfterDelay(
value: string | null | undefined,
nowEpochMs: number,
): number | null {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 128 ||
!Number.isFinite(nowEpochMs)
) {
return null;
}
const normalized = value.trim();
if (/^\d+$/u.test(normalized)) {
const seconds = Number(normalized);
return Number.isSafeInteger(seconds) &&
seconds <= Math.floor(Number.MAX_SAFE_INTEGER / 1_000)
? seconds * 1_000
: null;
}
if (
!/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/u.test(
normalized,
)
) {
return null;
}
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp)
? Math.max(0, timestamp - nowEpochMs)
: null;
}
@@ -138,12 +138,11 @@ export function createConditionalValidatorStore(
function isSafeEntityTag(value: string): boolean {
if (value.length < 3 || value.length > 256) return false;
const opaque = value.startsWith('W/"')
? value.slice(3, -1)
: value.startsWith('"')
? value.slice(1, -1)
: null;
if (opaque === null || !value.endsWith('"')) return false;
const start = value.startsWith('W/"') ? 3 : value.startsWith('"') ? 1 : -1;
// Q-6.3-12. The closing quote must follow the opening one: a bare `W/"`
// ends with its opening quote and is unclosed.
if (start < 0 || value.length <= start || !value.endsWith('"')) return false;
const opaque = value.slice(start, -1);
return [...opaque].every((character) => {
const code = character.codePointAt(0) ?? 0;
return code === 0x21 || (code >= 0x23 && code <= 0x7e) ||
@@ -68,6 +68,7 @@ export function createCursorPaginationRuntime<Value>(dependencies: Readonly<{
return Object.freeze({
async loadAll(context) {
const items: Value[] = [];
let pageBytes = 0;
const cursors = new Set<string>();
let cursor: string | null = null;
let snapshot: string | null | undefined;
@@ -108,16 +109,21 @@ export function createCursorPaginationRuntime<Value>(dependencies: Readonly<{
"PAGINATION_SNAPSHOT_CHANGED",
);
}
items.push(...page.items);
// Q-6.3-12. Each page is measured once (the sum errs high by at most
// one byte per page) and appended item by item: re-serializing the
// accumulated items was O(pages × total), and `push(...items)`
// throws a RangeError for a large page.
pageBytes += estimatedBytes(page.items);
if (
items.length > profile.maxTotalItems ||
estimatedBytes(items) > profile.maxEstimatedBytes
items.length + page.items.length > profile.maxTotalItems ||
pageBytes > profile.maxEstimatedBytes
) {
return failure(
"RESULT_LIMIT_EXCEEDED",
"PAGINATION_RESULT_LIMIT",
);
}
for (const item of page.items) items.push(item);
if (!page.hasMore) return { ok: true, value: Object.freeze(items) };
const nextCursor: string | null = page.nextCursor;
if (!nextCursor || cursors.has(nextCursor)) {
@@ -1,4 +1,5 @@
import type { AuthSessionPort } from "../../application/ports/auth-session-port.ts";
import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.ts";
import type { QueryInvalidationCoordinator } from "../../contracts/query-invalidation.ts";
import {
createRuntimeIdentityRegistry,
@@ -24,8 +25,15 @@ export type ScopeResetParticipant = Readonly<{
}>;
export type ServerStateScopeDependencies = Readonly<{
session: Pick<AuthSessionPort, "subscribe">;
/**
* `getState`/`getSubject` let the runtime skip a notification that changes
* neither. Without `getState` every notification fences, as before.
*/
session: Pick<AuthSessionPort, "subscribe"> &
Partial<Pick<AuthSessionPort, "getState" | "getSubject">>;
queryInvalidation: Pick<QueryInvalidationCoordinator, "resetLocal">;
/** Hears about an authenticated session that could not name its subject. */
diagnostics?: DiagnosticsPort;
tokenFactory?: () => string;
participants?: readonly ScopeResetParticipant[];
activateNextGeneration?: () => void | Promise<void>;
@@ -49,6 +57,7 @@ export function createServerStateScopeRuntime(
let phase: ClientScopePhase = "READY";
let disposed = false;
let resetChain = Promise.resolve();
let sessionIdentity = readSessionIdentity(dependencies.session).identity;
function createSnapshot(): CacheScopeSnapshot {
const capturedGeneration = generation;
@@ -89,6 +98,21 @@ export function createServerStateScopeRuntime(
const unsubscribe = dependencies.session.subscribe(() => {
if (disposed) return;
// §10.6 is for identity-affecting changes only. A notification that keeps
// (state, subject) — a token refresh, a repeated sign-out — must not abort
// requests and clear the cache. A FAILED scope still retries its reset.
const next = readSessionIdentity(dependencies.session);
if (
next.identity !== null &&
next.identity === sessionIdentity &&
phase !== "FAILED"
) {
return;
}
// The fence below is correct but costly: an owner that cannot name its
// subject clears the cache on every token refresh. Make that visible.
if (next.subjectMissing) reportSubjectMissing(dependencies.diagnostics);
sessionIdentity = next.identity;
const previousIdentities = identities;
const previousGeneration = generation;
@@ -185,6 +209,45 @@ export function createServerStateScopeRuntime(
});
}
/**
* A `null` identity cannot be proven unchanged: no `getState`, a throwing
* owner, or an authenticated session without a non-empty subject (the last one
* is flagged `subjectMissing`). Those always fence, which keeps an account
* switch from reusing the previous cache.
*/
function readSessionIdentity(
session: ServerStateScopeDependencies["session"],
): Readonly<{ identity: string | null; subjectMissing: boolean }> {
try {
const state = session.getState?.();
if (state === undefined) return { identity: null, subjectMissing: false };
const subject = session.getSubject?.();
const knownSubject =
typeof subject === "string" && subject !== "" ? subject : null;
if (state === "authenticated" && knownSubject === null) {
return { identity: null, subjectMissing: true };
}
return {
identity: JSON.stringify([state, knownSubject]),
subjectMissing: false,
};
} catch {
return { identity: null, subjectMissing: false };
}
}
function reportSubjectMissing(diagnostics: DiagnosticsPort | undefined): void {
try {
diagnostics?.record({
level: "warn",
eventId: "cache.operation.failed",
context: { operation: "SCOPE_FENCE", reason: "SUBJECT_MISSING" },
});
} catch {
// The fence must run whether or not diagnostics works.
}
}
function newIdentityRegistry(
tokenFactory: (() => string) | undefined,
): RuntimeIdentityRegistry {
@@ -76,16 +76,19 @@ export function createTanStackCacheCoordinator(
namespaces.set(queryNamespaceIdentityKey(namespace), namespace);
}
}
for (const namespace of namespaces.values()) {
try {
await dependencies.queryClient.invalidateQueries({
// Q-6.3-8. invalidateQueries resolves only after the active refetches
// finish, so the namespaces run side by side instead of one after another.
const results = await Promise.allSettled(
[...namespaces.values()].map(async (namespace) =>
dependencies.queryClient.invalidateQueries({
queryKey: createQueryInvalidationPrefix(namespace),
exact: false,
refetchType: "active",
});
} catch {
report("invalidate");
}
}),
),
);
for (const result of results) {
if (result.status === "rejected") report("invalidate");
}
}
+58 -14
View File
@@ -17,6 +17,7 @@ import {
type RealtimeEventTypeRegistration,
type RealtimePolicyRegistry,
type RealtimeStreamRegistration,
type StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import {
validateWithRuntimeSchemaRegistry,
@@ -24,14 +25,16 @@ import {
} from "../../contracts/schema-registry.ts";
import {
hasDuplicateJsonMembers,
} from "./json-member-scanner.ts";
} from "../platform/json-member-scanner.ts";
export type ValidatedRealtimeEventDto = Readonly<{
envelope: RealtimeEventEnvelope;
wireBytes: number;
/**
* Adapter-private semantic identity used only by the bounded conflict
* detector. It must never be logged or projected into diagnostics.
* detector: a fixed-size hash of the canonical envelope, so dedupe memory
* does not grow with payload size. It must never be logged or projected
* into diagnostics.
*/
semanticFingerprint: string;
fingerprintBytes: number;
@@ -66,21 +69,41 @@ const FORBIDDEN_OBJECT_KEYS = new Set([
]);
const encoder = new TextEncoder();
const issuedDtos = new WeakSet<object>();
const failedStreams = new WeakMap<object, StreamRegistrationId>();
type DecodeProgress = { stream?: StreamRegistrationId };
export function createRealtimeEventCodec(
dependencies: RealtimeEventCodecDependencies,
): RealtimeEventCodec {
return Object.freeze({
decode(raw: string): RealtimeResult<ValidatedRealtimeEventDto> {
const progress: DecodeProgress = {};
let result: RealtimeResult<ValidatedRealtimeEventDto>;
try {
return decodeUnsafe(raw, dependencies);
result = decodeUnsafe(raw, dependencies, progress);
} catch {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
result = realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (!result.ok && progress.stream) {
failedStreams.set(result, progress.stream);
}
return result;
},
});
}
/**
* The registered stream a failed decode had already identified, so that
* stream's freshness can become UNKNOWN (design 13.1). `null` when the
* failure came before the stream lookup.
*/
export function realtimeDecodeFailureStream(
failure: RealtimeResult<unknown>,
): StreamRegistrationId | null {
return failedStreams.get(failure) ?? null;
}
export function isValidatedRealtimeEventDto(
value: unknown,
): value is ValidatedRealtimeEventDto {
@@ -95,17 +118,18 @@ export function isValidatedRealtimeEventDto(
function decodeUnsafe(
raw: string,
dependencies: RealtimeEventCodecDependencies,
progress: DecodeProgress,
): RealtimeResult<ValidatedRealtimeEventDto> {
if (typeof raw !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (
raw.length > REALTIME_HARD_LIMITS.maxEventBytes ||
encoder.encode(raw).byteLength > REALTIME_HARD_LIMITS.maxEventBytes
) {
if (raw.length > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
const wireBytes = encoder.encode(raw).byteLength;
if (wireBytes > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
let input: unknown;
if (
@@ -134,6 +158,7 @@ function decodeUnsafe(
if (!stream) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
progress.stream = stream.id;
if (wireBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
@@ -145,7 +170,9 @@ function decodeUnsafe(
input.eventType,
);
if (!eventType) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
// A type the backend added after this bundle was built: a client/server
// version mismatch (reload), not a corrupt event.
return realtimeFailure("PROTOCOL_MISMATCH", "REGISTRY");
}
if (!hasValidEnvelopeFields(input, stream)) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
@@ -186,11 +213,8 @@ function decodeUnsafe(
eventType,
payloadSnapshot,
);
const semanticFingerprint = canonicalJson(envelope);
const fingerprintBytes = encoder.encode(semanticFingerprint).byteLength;
if (fingerprintBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
const semanticFingerprint = hash64(canonicalJson(envelope));
const fingerprintBytes = semanticFingerprint.length;
const dto = Object.freeze({
envelope,
@@ -367,6 +391,26 @@ function snapshotJson(
return visit(value, 0);
}
/**
* Two differently seeded 32-bit FNV-1a hashes as 16 hex characters.
* ponytail: not collision-proof against a hostile server; a collision only
* lets a conflicting redelivery pass as a duplicate. Use SHA-256 if the
* server is not trusted to keep event IDs unique.
*/
function hash64(text: string): string {
let first = 0x811c9dc5;
let second = 0x9e3779b9;
for (let index = 0; index < text.length; index += 1) {
const unit = text.charCodeAt(index);
first = Math.imul(first ^ unit, 0x01000193);
second = Math.imul(second ^ unit, 0x01000193);
}
return (
(first >>> 0).toString(16).padStart(8, "0") +
(second >>> 0).toString(16).padStart(8, "0")
);
}
function canonicalJson(value: unknown): string {
if (
value === null ||
+15 -3
View File
@@ -15,8 +15,9 @@ import {
import type {
StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import type {
RealtimeEventCodec,
import {
realtimeDecodeFailureStream,
type RealtimeEventCodec,
} from "./event-codec.ts";
import type {
RealtimeStreamCoordinator,
@@ -63,7 +64,8 @@ export type RealtimeEventConsumer = Readonly<{
export function createRealtimeEventConsumer(
dependencies: Readonly<{
codec: RealtimeEventCodec;
coordinator: Pick<RealtimeStreamCoordinator, "accept">;
coordinator: Pick<RealtimeStreamCoordinator, "accept"> &
Partial<Pick<RealtimeStreamCoordinator, "invalidate">>;
}>,
): RealtimeEventConsumer {
async function consumeWithStream(
@@ -84,6 +86,8 @@ export function createRealtimeEventConsumer(
}
const decoded = dependencies.codec.decode(rawEnvelope);
if (!decoded.ok) {
const failedStream = realtimeDecodeFailureStream(decoded);
if (failedStream) dependencies.coordinator.invalidate?.(failedStream);
return { streamId: null, result: decoded };
}
const envelope = decoded.value.envelope;
@@ -178,6 +182,14 @@ function projectTransportOutcome(
streamId: StreamRegistrationId | null,
): RealtimeResult<RealtimeTransportEventOutcome> {
if (!accepted.ok) return accepted;
// A recovery with no barrier to confirm keeps the connection; handing it to
// the reconnect path would ask for a barrier the coordinator never set.
if (
accepted.value.outcome === "RECOVERED" &&
accepted.value.transportBarrierRequired === false
) {
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
}
if (
accepted.value.outcome === "RECOVERED" ||
accepted.value.outcome === "RECOVERY_BARRIER_REQUIRED"
+1
View File
@@ -29,6 +29,7 @@ export {
type RealtimeReconnectCoordinator,
type RealtimeReconnectCoordinatorDependencies,
type RealtimeReconnectEnvironment,
type RealtimeReconnectObservation,
type RealtimeReconnectOutcome,
type RealtimeReconnectRunInput,
type RealtimeReconnectSession,
@@ -7,6 +7,7 @@ import {
import { systemClock } from "../platform/system-clock.ts";
import {
isRealtimeResult,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "./result.ts";
@@ -132,8 +133,6 @@ type InternalProbe<Value> = {
facade: LiveProbeLease<Value>;
readonly buffer: BufferedValue<Value>[];
bufferedBytes: number;
acceptedEvents: number;
acceptedBytes: number;
};
type QuiescenceOutcome = "QUIESCED" | "TIMER_FAILED" | "TIMED_OUT";
@@ -224,8 +223,6 @@ export function createLivePollHandoffCoordinator<Value>(
lease,
buffer: [],
bufferedBytes: 0,
acceptedEvents: 0,
acceptedBytes: 0,
facade: null as unknown as LiveProbeLease<Value>,
};
selected.facade = Object.freeze({
@@ -263,11 +260,11 @@ export function createLivePollHandoffCoordinator<Value>(
value: Value,
wireBytes: number,
): RealtimeResult<LivePollWriteReceipt> {
// Bounded by what is still buffered: activation drains the buffer while
// the probe keeps receiving.
if (
selected.acceptedEvents + 1 >
limits.maxProbeBufferedEvents ||
selected.acceptedBytes + wireBytes >
limits.maxProbeBufferedBytes
selected.buffer.length + 1 > limits.maxProbeBufferedEvents ||
selected.bufferedBytes + wireBytes > limits.maxProbeBufferedBytes
) {
if (transitioning) {
failClosed();
@@ -282,8 +279,6 @@ export function createLivePollHandoffCoordinator<Value>(
}
selected.buffer.push(Object.freeze({ value, wireBytes }));
selected.bufferedBytes += wireBytes;
selected.acceptedEvents += 1;
selected.acceptedBytes += wireBytes;
return realtimeSuccess(
Object.freeze({
kind: "BUFFERED" as const,
@@ -555,24 +550,6 @@ export function createLivePollHandoffCoordinator<Value>(
from: LivePollWriterKind,
candidate: InternalWriterLease<Value>,
): Promise<RealtimeResult<void>> {
const timer = new AbortController();
let releaseAbortGate = (): void => undefined;
const aborted = new Promise<
Readonly<{ kind: "ABORTED" }>
>((resolve) => {
const onAbort = () => resolve({ kind: "ABORTED" });
candidate.controller.signal.addEventListener(
"abort",
onAbort,
{ once: true },
);
releaseAbortGate = () =>
candidate.controller.signal.removeEventListener(
"abort",
onAbort,
);
if (candidate.controller.signal.aborted) onAbort();
});
const operation = Promise.resolve()
.then(() =>
dependencies.establishAuthoritativeCheckpoint(
@@ -585,59 +562,30 @@ export function createLivePollHandoffCoordinator<Value>(
isCheckpointCandidateCurrent(candidate),
}),
),
)
.then(
(value) => ({ kind: "VALUE" as const, value }),
() => ({ kind: "REJECTED" as const }),
);
// RT-RR-04. Registered at the moment the authority is called, and removed
// only when it settles, so `close()` cannot report quiescence over it.
checkpointTasks.add(operation);
void operation.finally(() => {
checkpointTasks.delete(operation);
const settled = operation.then(
() => undefined,
() => undefined,
);
checkpointTasks.add(settled);
void settled.then(() => {
checkpointTasks.delete(settled);
});
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(
limits.quiescenceTimeoutMs,
timer.signal,
);
return { kind: "TIMED_OUT" as const };
})
.catch(() => ({
kind: timer.signal.aborted
? ("CANCELED" as const)
: ("TIMER_FAILED" as const),
}));
const selected = await Promise.race([
operation,
timeout,
aborted,
]);
timer.abort();
releaseAbortGate();
const selected = await raceRealtimeTask(
() => operation,
candidate.controller.signal,
(signal) => clock.sleep(limits.quiescenceTimeoutMs, signal),
);
if (selected.kind === "ABORTED") {
return handoffFailure("ABORTED", "RECOVER");
}
if (selected.kind === "TIMED_OUT") {
if (selected.kind === "TIMEOUT") {
candidate.controller.abort();
return handoffFailure("IDLE_TIMEOUT", "RECOVER");
}
if (
selected.kind === "TIMER_FAILED" ||
selected.kind === "REJECTED"
) {
candidate.controller.abort();
return handoffFailure(
"PROVIDER_UNAVAILABLE",
"RECOVER",
true,
);
}
if (selected.kind === "CANCELED") {
return handoffFailure("ABORTED", "RECOVER");
}
if (selected.kind !== "VALUE") {
candidate.controller.abort();
return handoffFailure(
@@ -673,50 +621,22 @@ export function createLivePollHandoffCoordinator<Value>(
async function awaitTaskQuiescence(
task: Promise<unknown>,
): Promise<QuiescenceOutcome> {
const timer = new AbortController();
const settled = task.then(
() => "QUIESCED" as const,
() => "QUIESCED" as const,
const outcome = await raceRealtimeTask(
() => task,
undefined,
(signal) => clock.sleep(limits.quiescenceTimeoutMs, signal),
);
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(limits.quiescenceTimeoutMs, timer.signal);
return "TIMED_OUT" as const;
})
.catch(() =>
timer.signal.aborted
? ("QUIESCED" as const)
: ("TIMER_FAILED" as const),
);
const outcome = await Promise.race([settled, timeout]);
timer.abort();
return outcome;
return outcome.kind === "TIMEOUT"
? "TIMED_OUT"
: outcome.kind === "CLOCK_FAILED"
? "TIMER_FAILED"
: "QUIESCED";
}
async function awaitQuiescence(
function awaitQuiescence(
lease: InternalWriterLease<Value>,
): Promise<QuiescenceOutcome> {
const timer = new AbortController();
const settled = lease.tail.then(
() => "QUIESCED" as const,
() => "QUIESCED" as const,
);
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(
limits.quiescenceTimeoutMs,
timer.signal,
);
return "TIMED_OUT" as const;
})
.catch(() =>
timer.signal.aborted
? ("QUIESCED" as const)
: ("TIMER_FAILED" as const),
);
const outcome = await Promise.race([settled, timeout]);
timer.abort();
return outcome;
return awaitTaskQuiescence(lease.tail);
}
function close(): Promise<RealtimeResult<void>> {
@@ -13,8 +13,13 @@ import {
} from "../../../application/ports/realtime/shared.ts";
import { systemClock } from "../../platform/system-clock.ts";
import {
captureRealtimeDataSnapshot,
hasExactSnapshotKeys,
observeRealtime,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
type RealtimeRace,
} from "../result.ts";
/**
@@ -79,6 +84,16 @@ export type BoundedPollCoordinator<Value> = Readonly<{
close(): void;
}>;
/**
* Closed diagnostics for design 14.1 `bounded_poll_*`. `outcome` is VALUE,
* UNCHANGED or the failure kind for ATTEMPT_FINISHED, and TERMINAL or the
* failure kind for LEASE_STOPPED.
*/
export type BoundedPollObservation = Readonly<{
kind: "LEASE_STARTED" | "ATTEMPT_FINISHED" | "LEASE_STOPPED";
outcome?: "VALUE" | "UNCHANGED" | "TERMINAL" | RealtimeFailureKind;
}>;
export type BoundedPollCoordinatorDependencies<Value> = Readonly<{
policy: PollLeasePolicy;
operation: BoundedPollOperationContract;
@@ -95,6 +110,7 @@ export type BoundedPollCoordinatorDependencies<Value> = Readonly<{
isCurrent?: () => boolean;
clock?: ClockPort;
random?: () => number;
observe?(observation: BoundedPollObservation): void;
}>;
const SAFE_STATE = /^[A-Z][A-Z0-9_]{0,63}$/u;
@@ -124,8 +140,25 @@ export function createBoundedPollCoordinator<Value>(
let activeController: AbortController | null = null;
let generation = 0;
let pendingWork = 0;
const observe = (observation: BoundedPollObservation) =>
observeRealtime(dependencies.observe, observation);
async function run(
input?: BoundedPollRunInput<Value>,
): Promise<BoundedPollResult<Value>> {
const startedGeneration = generation;
const result = await runLease(input);
// A call rejected before starting leaves the generation unchanged.
if (generation !== startedGeneration) {
observe({
kind: "LEASE_STOPPED",
outcome: result.ok ? "TERMINAL" : result.error.kind,
});
}
return result;
}
async function runLease(
input: BoundedPollRunInput<Value> = {},
): Promise<BoundedPollResult<Value>> {
if (state === "CLOSED") return pollFailure("CLOSED");
@@ -145,6 +178,7 @@ export function createBoundedPollCoordinator<Value>(
state = "RUNNING";
const runGeneration = ++generation;
observe({ kind: "LEASE_STARTED" });
const controller = new AbortController();
activeController = controller;
let stopKind: RealtimeFailureKind | null = null;
@@ -216,7 +250,7 @@ export function createBoundedPollCoordinator<Value>(
) {
return pollFailure("POLL_BUDGET_EXHAUSTED");
}
const cadenceOutcome = await awaitTaskOrAbort(
const cadenceOutcome = await raceRealtimeTask(
() => clock.sleep(nextDelayMs, controller.signal),
controller.signal,
);
@@ -231,7 +265,7 @@ export function createBoundedPollCoordinator<Value>(
);
return pollFailure(
afterSleepFailure ??
(cadenceOutcome.kind === "THREW"
(cadenceOutcome.kind === "REJECTED"
? "PROVIDER_UNAVAILABLE"
: "ABORTED"),
afterSleepFailure === "OFFLINE",
@@ -281,7 +315,7 @@ export function createBoundedPollCoordinator<Value>(
);
if (attemptOutcome.kind === "VALUE") {
result = attemptOutcome.value;
} else if (attemptOutcome.kind === "THREW") {
} else if (attemptOutcome.kind === "REJECTED") {
result = realtimeFailure(
controller.signal.aborted ? "ABORTED" : "OFFLINE",
"POLL",
@@ -340,14 +374,23 @@ export function createBoundedPollCoordinator<Value>(
return pollFailure("PROTOCOL_MISMATCH");
}
result = parsedResult;
observe({
kind: "ATTEMPT_FINISHED",
outcome: result.ok ? result.value.kind : result.error.kind,
});
if (!result.ok) {
// A missing server hint falls back to policy backoff; an executor
// that requires one reports `retryable: false` instead.
if (
!result.error.retryable ||
!isPollRetryableFailureKind(result.error.kind) ||
(isPollRetryAfterFailureKind(result.error.kind) &&
result.error.retryAfterMs === undefined)
!isPollRetryableFailureKind(result.error.kind)
) {
return pollFailure(result.error.kind);
// OFFLINE (a thrown executor included) ends this lease but stays
// retryable, like every other OFFLINE here.
return pollFailure(
result.error.kind,
result.error.kind === "OFFLINE" && result.error.retryable,
);
}
consecutiveFailures += 1;
const failureDelay = retryDelay(
@@ -411,7 +454,7 @@ export function createBoundedPollCoordinator<Value>(
controller.signal,
() => stop("POLL_BUDGET_EXHAUSTED"),
);
if (applyOutcome.kind === "THREW") {
if (applyOutcome.kind === "REJECTED") {
return applyFailure();
}
if (applyOutcome.kind !== "VALUE") {
@@ -550,156 +593,24 @@ function currentFailure(
return null;
}
type TaskOutcome<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "THREW" }>
| Readonly<{ kind: "ABORTED" }>;
type LeaseTaskOutcome<Value> =
| TaskOutcome<Value>
| Readonly<{ kind: "LEASE_EXPIRED" }>
| Readonly<{ kind: "CLOCK_FAILED" }>;
async function awaitTaskOrAbort<Value>(
task: () => Promise<Value>,
signal: AbortSignal,
): Promise<TaskOutcome<Value>> {
if (signal.aborted) return Object.freeze({ kind: "ABORTED" });
let removeAbortListener: () => void = () => undefined;
const aborted = new Promise<Readonly<{ kind: "ABORTED" }>>(
(resolve) => {
const onAbort = () => resolve(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", onAbort, { once: true });
removeAbortListener = () =>
signal.removeEventListener("abort", onAbort);
if (signal.aborted) onAbort();
},
);
if (signal.aborted) {
removeAbortListener();
return Object.freeze({ kind: "ABORTED" });
}
let taskPromise: Promise<Value>;
try {
taskPromise = task();
} catch {
removeAbortListener();
return Object.freeze({ kind: "THREW" });
}
const completed = taskPromise.then<
TaskOutcome<Value>,
TaskOutcome<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "THREW" }),
);
try {
return await Promise.race([completed, aborted]);
} finally {
removeAbortListener();
}
}
const LEASE_EXPIRED = Object.freeze({ kind: "TIMEOUT" as const });
/** Bounds work by the lease's remaining time; expiry stops the whole run. */
async function awaitWithinLease<Value>(
task: () => Promise<Value>,
remainingMs: number,
clock: ClockPort,
signal: AbortSignal,
onLeaseExpired: () => void,
): Promise<LeaseTaskOutcome<Value>> {
if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
onLeaseExpired();
return Object.freeze({ kind: "LEASE_EXPIRED" });
}
if (signal.aborted) return Object.freeze({ kind: "ABORTED" });
const deadlineController = new AbortController();
let resolveInterruption:
| ((outcome: LeaseTaskOutcome<Value>) => void)
| undefined;
let removeAbortListener: () => void = () => undefined;
let interruptionSettled = false;
const finishInterruption = (
outcome: LeaseTaskOutcome<Value>,
): boolean => {
if (interruptionSettled) return false;
interruptionSettled = true;
resolveInterruption?.(outcome);
return true;
};
const interrupted = new Promise<LeaseTaskOutcome<Value>>((resolve) => {
resolveInterruption = resolve;
const onAbort = () =>
finishInterruption(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", onAbort, { once: true });
removeAbortListener = () =>
signal.removeEventListener("abort", onAbort);
if (signal.aborted) onAbort();
});
if (signal.aborted) {
removeAbortListener();
return Object.freeze({ kind: "ABORTED" });
}
let deadlineSleep: Promise<void>;
try {
deadlineSleep = clock.sleep(
remainingMs,
deadlineController.signal,
);
} catch {
removeAbortListener();
deadlineController.abort();
return Object.freeze({ kind: "CLOCK_FAILED" });
}
const deadline = deadlineSleep.then(
() => {
if (deadlineController.signal.aborted) return;
if (
finishInterruption(
Object.freeze({ kind: "LEASE_EXPIRED" }),
): Promise<RealtimeRace<Value>> {
const outcome =
Number.isFinite(remainingMs) && remainingMs > 0
? await raceRealtimeTask(task, signal, (lease) =>
clock.sleep(remainingMs, lease),
)
) {
onLeaseExpired();
}
},
() => {
if (!deadlineController.signal.aborted) {
finishInterruption(
Object.freeze({ kind: "CLOCK_FAILED" }),
);
}
},
);
if (signal.aborted) {
removeAbortListener();
deadlineController.abort();
void deadline;
return Object.freeze({ kind: "ABORTED" });
}
let taskPromise: Promise<Value>;
try {
taskPromise = task();
} catch {
taskPromise = Promise.reject(new Error("Task failed."));
}
const completed = taskPromise.then<
LeaseTaskOutcome<Value>,
LeaseTaskOutcome<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "THREW" }),
);
try {
const outcome = await Promise.race([completed, interrupted]);
void deadline;
return outcome;
} finally {
removeAbortListener();
deadlineController.abort();
}
: LEASE_EXPIRED;
if (outcome.kind === "TIMEOUT") onLeaseExpired();
return outcome;
}
function parseAttemptResult<Value>(
@@ -790,42 +701,10 @@ function snapshotDataRecord(
value: unknown,
allowedKeySets: readonly (readonly string[])[],
): Readonly<Record<string, unknown>> | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
try {
if (Object.getPrototypeOf(value) !== Object.prototype) {
return null;
}
const keys = Reflect.ownKeys(value);
if (keys.some((key) => typeof key !== "string")) return null;
const sortedKeys = (keys as string[]).sort();
if (
!allowedKeySets.some((allowed) => {
const sortedAllowed = [...allowed].sort();
return (
sortedKeys.length === sortedAllowed.length &&
sortedKeys.every(
(key, index) => key === sortedAllowed[index],
)
);
})
) {
return null;
}
const descriptors = Object.getOwnPropertyDescriptors(value);
const snapshot: Record<string, unknown> = {};
for (const key of sortedKeys) {
const descriptor = descriptors[key];
if (!descriptor || !Object.hasOwn(descriptor, "value")) {
return null;
}
snapshot[key] = descriptor.value;
}
return Object.freeze(snapshot);
} catch {
return null;
}
const snapshot = captureRealtimeDataSnapshot(value);
return snapshot && hasExactSnapshotKeys(snapshot, ...allowedKeySets)
? snapshot.values
: null;
}
function retryDelay(
+1
View File
@@ -5,6 +5,7 @@ export {
type BoundedPollCoordinator,
type BoundedPollCoordinatorDependencies,
type BoundedPollEnvironment,
type BoundedPollObservation,
type BoundedPollResult,
type BoundedPollRunInput,
} from "./bounded-poll-coordinator.ts";
+209 -282
View File
@@ -16,9 +16,15 @@ import {
type ReconnectPolicy,
} from "./reconnect-policy.ts";
import {
captureRealtimeDataSnapshot,
hasExactSnapshotKeys,
isRealtimeResult,
isRealtimeTransportEventOutcome,
observeRealtime,
raceRealtimeTask,
realtimeFailure,
timerDeadline,
type RealtimeDataSnapshot,
} from "./result.ts";
type FailureResult = Extract<RealtimeResult<never>, { ok: false }>;
@@ -50,7 +56,9 @@ export type RealtimeReconnectAttemptContext = Readonly<{
pendingRecovery: RealtimeCommittedRecovery | null;
isCurrent(): boolean;
/**
* Call only after a protocol-valid heartbeat or event.
* Call only after a protocol-valid heartbeat or event: an applied event,
* an SSE `onComment`, or a WebSocket `HEARTBEAT_ACK` observation. A quiet
* stream that never calls it cannot earn a fresh retry budget.
*/
markValidHeartbeatOrEvent(): void;
/**
@@ -95,6 +103,10 @@ export type RealtimeReconnectSession<
close(): void;
}>;
/**
* Online is the only environment signal the coordinator follows. Visibility,
* pagehide and the registry's `hiddenPolicy` are composition code's job.
*/
export type RealtimeReconnectEnvironment = Readonly<{
online(): boolean;
subscribeOnline(listener: (online: boolean) => void): () => void;
@@ -113,6 +125,32 @@ export type RealtimeReconnectCoordinator = Readonly<{
close(): void;
}>;
/**
* Closed, low-cardinality diagnostics for design 14.1/14.2: connect attempted
* (ATTEMPT_STARTED), connect finished (SESSION_OPENED, or the RETRY_SCHEDULED
* or RUN_ENDED that follows a failed attempt), connection closed
* (SESSION_CLOSED) and reconnect delay and exhaustion.
*/
export type RealtimeReconnectObservation = Readonly<{
kind:
| "ATTEMPT_STARTED"
| "SESSION_OPENED"
| "SESSION_CLOSED"
| "RETRY_SCHEDULED"
| "RUN_ENDED";
/**
* RETRY_SCHEDULED: the failure being retried. RUN_ENDED: the returned
* failure, absent on success.
*/
failureKind?: RealtimeFailureKind;
delayBucket?: "UNDER_1S" | "1S_TO_10S" | "10S_PLUS";
/**
* RUN_ENDED. EXHAUSTED means a retryable failure outlived the attempt or
* elapsed budget; TERMINAL means the failure itself was not retryable.
*/
reason?: "COMPLETED" | "EXHAUSTED" | "TERMINAL" | "ABORTED";
}>;
export type RealtimeReconnectCoordinatorDependencies<
ClosedReceipt = RealtimeReconnectOutcome<void>,
> = Readonly<{
@@ -134,7 +172,14 @@ export type RealtimeReconnectCoordinatorDependencies<
): RealtimeResult<void>;
clock?: ClockPort;
random?: () => number;
/**
* Checked only at loop boundaries (around attempt, sleep and waitClosed),
* never while a session stays open. On logout or account switch call
* `close()`; otherwise a quiet open session stays open until its next
* event or server close.
*/
isCurrent?: () => boolean;
observe?(observation: RealtimeReconnectObservation): void;
}>;
const RETRYABLE_KINDS = Object.freeze([
@@ -226,12 +271,6 @@ type ParsedCloseClassification =
directive: ParsedRecoveryDirective;
}>;
type DataSnapshot = Readonly<{
source: object;
keys: readonly string[];
values: Readonly<Record<string, unknown>>;
}>;
type ParsedRunInput = Readonly<{
signal: AbortSignal | undefined;
initialRecovery: ParsedRecoveryDirective | null;
@@ -266,6 +305,8 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
let phaseController: AbortController | null = null;
let session: RealtimeReconnectSession<ClosedReceipt> | null = null;
let activeRecoveryGate: BarrierGate | null = null;
const observe = (observation: RealtimeReconnectObservation) =>
observeRealtime(dependencies.observe, observation);
function retainTracked<Value>(
task: Promise<Settled<Value>>,
@@ -305,6 +346,18 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
}
async function run(
input?: RealtimeReconnectRunInput,
): Promise<RealtimeResult<void>> {
const startedGeneration = generation;
const result = await runLoop(input);
// A call rejected before starting leaves the generation unchanged.
if (generation !== startedGeneration) {
observe({ kind: "RUN_ENDED", ...runEnd(result) });
}
return result;
}
async function runLoop(
input: RealtimeReconnectRunInput = {},
): Promise<RealtimeResult<void>> {
if (state === "CLOSED") return failure("CLOSED");
@@ -494,15 +547,16 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
) {
return retry.terminalResult;
}
if (
(!online || requiredOnlineVersion !== null) &&
!(await waitOnline())
) {
const offlineWait = !online || requiredOnlineVersion !== null;
if (offlineWait && !(await waitOnline())) {
return failure(currentFailure() ?? "ABORTED");
}
now = safeNow(clock);
if (now === null) return retry.terminalResult;
// Offline time is not retry time. The elapsed budget restarts when
// the network returns; maxAttempts still bounds the loop.
if (offlineWait) budgetStartedAt = now;
const delay = nextDelay(
retry,
retriesUsed,
@@ -512,6 +566,16 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
random,
);
if (delay === null) return retry.terminalResult;
observe({
kind: "RETRY_SCHEDULED",
failureKind: retry.result.error.kind,
delayBucket:
delay < 1_000
? "UNDER_1S"
: delay < 10_000
? "1S_TO_10S"
: "10S_PLUS",
});
const phase = beginPhase();
const sleeping = track(
@@ -590,6 +654,22 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
activeRecoveryGate = null;
}
};
/**
* Ends this attempt: settles its barrier gate when given a result,
* closes the opened session, and aborts and releases the phase.
*/
const endAttempt = (
gateResult: RealtimeResult<void> | null,
opened?: RealtimeReconnectSession<ClosedReceipt>,
) => {
if (gateResult) settleAttemptGate(gateResult);
if (opened) {
safelyClose(opened);
if (session === opened) session = null;
}
phase.controller.abort();
phase.dispose();
};
const isAttemptCurrent = () =>
state === "RUNNING" &&
generation === runGeneration &&
@@ -612,6 +692,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
);
},
});
observe({ kind: "ATTEMPT_STARTED" });
const attempting = track(
() => attempt(context),
);
@@ -653,24 +734,19 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
continue;
}
const interrupted = currentFailure() ?? "ABORTED";
settleAttemptGate(recoveryFailure(interrupted));
phase.dispose();
endAttempt(recoveryFailure(interrupted));
return failure(interrupted);
}
const afterAttempt = currentFailure();
if (afterAttempt) {
closeLateSession(attempted);
settleAttemptGate(recoveryFailure(afterAttempt));
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterAttempt));
return failure(afterAttempt);
}
if (attemptOffline) {
closeLateSession(attempted);
settleAttemptGate(recoveryFailure("OFFLINE"));
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure("OFFLINE"));
retry = offlineRetry(
safeNow(clock) ?? beforeAttempt,
"CONNECT",
@@ -684,9 +760,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
"CONNECT",
pendingRecovery?.terminalFailure.result,
);
settleAttemptGate(nextRetry.result);
phase.controller.abort();
phase.dispose();
endAttempt(nextRetry.result);
retry = nextRetry;
continue;
}
@@ -696,33 +770,20 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
);
if (!opened) {
const mismatch = failure("PROTOCOL_MISMATCH");
settleAttemptGate(mismatch);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch);
return mismatch;
}
const afterAttemptValidation = currentFailure();
if (afterAttemptValidation) {
if (opened.ok) safelyClose(opened.value.session);
settleAttemptGate(
recoveryFailure(afterAttemptValidation),
);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterAttemptValidation));
return failure(afterAttemptValidation);
}
if (!opened.ok) {
settleAttemptGate(opened.failure.result);
phase.controller.abort();
phase.dispose();
if (
!reconnectable(
opened.failure,
opened.serverNotBeforeMs,
)
) {
endAttempt(opened.failure.result);
if (!reconnectable(opened.failure)) {
return opened.failure.result;
}
const failedAt = safeNow(clock);
@@ -748,21 +809,13 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
const mismatch = recoveryFailure(
"PROTOCOL_MISMATCH",
);
settleAttemptGate(mismatch);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch, active);
return mismatch;
}
const beforeConfirmation = currentFailure();
if (beforeConfirmation) {
settleAttemptGate(
recoveryFailure(beforeConfirmation),
);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(beforeConfirmation), active);
return failure(beforeConfirmation);
}
@@ -778,28 +831,17 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
const mismatch = recoveryFailure(
"PROTOCOL_MISMATCH",
);
settleAttemptGate(mismatch);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch, active);
return mismatch;
}
const afterConfirmation = currentFailure();
if (afterConfirmation) {
settleAttemptGate(
recoveryFailure(afterConfirmation),
);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterConfirmation), active);
return failure(afterConfirmation);
}
if (!confirmation.ok) {
settleAttemptGate(confirmation.failure.result);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(confirmation.failure.result, active);
return confirmation.failure.result;
}
@@ -810,9 +852,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
} else {
settleAttemptGate(noPendingRecovery);
if (opened.value.hasRecoveryBarrier) {
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return noPendingRecovery;
}
}
@@ -826,9 +866,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
openedAt,
) <= 0
) {
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return (
retry?.terminalResult ??
failure("PROVIDER_UNAVAILABLE")
@@ -837,19 +875,33 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
retry = null;
session = active;
observe({ kind: "SESSION_OPENED" });
const waiting = track(() => active.waitClosed());
const closed = await race(
waiting,
phase.controller.signal,
);
const closeOffline = wentOffline(phase);
observe({ kind: "SESSION_CLOSED" });
// Every way an opened session ends, including offline and a throwing
// waitClosed, can earn a fresh budget, not only a classified close.
const endedAt = safeNow(clock);
if (
endedAt !== null &&
isReconnectAttemptResetEligible({
policy,
openedAtMs: openedAt,
nowMs: endedAt,
observedValidHeartbeatOrEvent: validSignalObserved,
})
) {
retriesUsed = 0;
budgetStartedAt = endedAt;
}
const afterWaitClosed = currentFailure();
if (afterWaitClosed) {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return failure(afterWaitClosed);
}
if (closed.kind === "INTERRUPTED") {
@@ -884,10 +936,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
}
if (closeOffline) {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
retry = offlineRetry(
safeNow(clock) ?? openedAt,
"RECEIVE",
@@ -895,10 +944,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
continue;
}
if (closed.kind === "THREW") {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
retry = providerRetry(
safeNow(clock) ?? openedAt,
"RECEIVE",
@@ -913,10 +959,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
rawClassification = null;
}
const afterClassification = currentFailure();
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
if (afterClassification) {
return failure(afterClassification);
}
@@ -934,12 +977,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
if (classified.outcome.ok) {
return classified.outcome.result as RealtimeResult<void>;
}
if (
!reconnectable(
classified.outcome.failure,
classified.outcome.serverNotBeforeMs,
)
) {
if (!reconnectable(classified.outcome.failure)) {
return classified.outcome.failure.result;
}
@@ -947,18 +985,6 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
if (closedAt === null) {
return classified.outcome.failure.result;
}
if (
isReconnectAttemptResetEligible({
policy,
openedAtMs: openedAt,
nowMs: closedAt,
observedValidHeartbeatOrEvent:
validSignalObserved,
})
) {
retriesUsed = 0;
budgetStartedAt = closedAt;
}
retry = captureRetry(
classified.outcome.failure.result,
classified.outcome.failure.result,
@@ -977,17 +1003,6 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
if (closedAt === null) {
return classified.directive.terminalFailure.result;
}
if (
isReconnectAttemptResetEligible({
policy,
openedAtMs: openedAt,
nowMs: closedAt,
observedValidHeartbeatOrEvent: validSignalObserved,
})
) {
retriesUsed = 0;
budgetStartedAt = closedAt;
}
pendingRecovery = classified.directive;
retry = captureRetry(
classified.directive.terminalFailure.result,
@@ -1033,65 +1048,31 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
});
}
const INTERRUPTED = Object.freeze({ kind: "INTERRUPTED" as const });
async function race<Value>(
task: Promise<Settled<Value>>,
signal: AbortSignal,
): Promise<AwaitedTask<Value>> {
if (signal.aborted) return Object.freeze({ kind: "INTERRUPTED" });
let cleanup: () => void = () => undefined;
const interrupted = new Promise<
Readonly<{ kind: "INTERRUPTED" }>
>((resolve) => {
const abort = () =>
resolve(Object.freeze({ kind: "INTERRUPTED" }));
signal.addEventListener("abort", abort, { once: true });
cleanup = () => signal.removeEventListener("abort", abort);
if (signal.aborted) abort();
});
try {
return await Promise.race([task, interrupted]);
} finally {
cleanup();
}
const raced = await raceRealtimeTask(() => task, signal);
return raced.kind === "VALUE" ? raced.value : INTERRUPTED;
}
async function drainWithinCeiling<Value>(
task: Promise<Settled<Value>>,
signal: AbortSignal,
): Promise<DrainedTask<Value>> {
if (signal.aborted) return Object.freeze({ kind: "INTERRUPTED" });
let timer: ReturnType<typeof setTimeout> | undefined;
let cleanup: () => void = () => undefined;
const boundary = new Promise<
| Readonly<{ kind: "INTERRUPTED" }>
| Readonly<{ kind: "TIMED_OUT" }>
>((resolve) => {
const abort = () =>
resolve(Object.freeze({ kind: "INTERRUPTED" }));
cleanup = () => safelyRemoveAbortListener(signal, abort);
try {
signal.addEventListener("abort", abort, { once: true });
timer = setTimeout(
() => resolve(Object.freeze({ kind: "TIMED_OUT" })),
REALTIME_RECONNECT_CEILINGS.drainTimeoutMs,
);
} catch {
resolve(Object.freeze({ kind: "TIMED_OUT" }));
}
if (signal.aborted) abort();
});
try {
return await Promise.race([task, boundary]);
} finally {
cleanup();
if (timer !== undefined) {
try {
clearTimeout(timer);
} catch {
// The generation remains fenced if host timer cleanup fails.
}
}
}
// A host timer, not the clock: a non-cooperative clock is one of the things
// this drain has to bound.
const raced = await raceRealtimeTask(
() => task,
signal,
timerDeadline(REALTIME_RECONNECT_CEILINGS.drainTimeoutMs),
);
if (raced.kind === "VALUE") return raced.value;
return raced.kind === "ABORTED"
? INTERRUPTED
: Object.freeze({ kind: "TIMED_OUT" });
}
function createBarrierGate(): BarrierGate {
@@ -1114,15 +1095,16 @@ function createBarrierGate(): BarrierGate {
}
function parseRunInput(value: unknown): ParsedRunInput | null {
const snapshot = captureDataSnapshot(value);
const snapshot = captureRealtimeDataSnapshot(value);
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
[],
["signal"],
["initialRecovery"],
["initialRecovery", "signal"],
])
)
) {
return null;
}
@@ -1140,7 +1122,7 @@ function parseRunInput(value: unknown): ParsedRunInput | null {
initialValue === undefined
? null
: parseRecoveryDirectiveSnapshot(
captureDataSnapshot(initialValue),
captureRealtimeDataSnapshot(initialValue),
);
if (initialValue !== undefined && !initialRecovery) return null;
return Object.freeze({
@@ -1153,28 +1135,29 @@ function parseAttemptOutcome<ClosedReceipt>(
value: unknown,
): ParsedOutcome<ParsedAttemptSuccess<ClosedReceipt>> | null {
return parseOutcomeSnapshot(
captureDataSnapshot(value),
captureRealtimeDataSnapshot(value),
(candidate) =>
parseAttemptSuccess<ClosedReceipt>(
captureDataSnapshot(candidate),
captureRealtimeDataSnapshot(candidate),
),
);
}
function parseAttemptSuccess<ClosedReceipt>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): ParsedValue<ParsedAttemptSuccess<ClosedReceipt>> | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["session"],
["establishedRecoveryBarrier", "session"],
])
)
) {
return null;
}
const session = parseSession<ClosedReceipt>(
captureDataSnapshot(snapshot.values.session),
captureRealtimeDataSnapshot(snapshot.values.session),
);
if (!session) return null;
const hasRecoveryBarrier = snapshot.keys.includes(
@@ -1191,11 +1174,11 @@ function parseAttemptSuccess<ClosedReceipt>(
}
function parseSession<ClosedReceipt>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): RealtimeReconnectSession<ClosedReceipt> | null {
if (
!snapshot ||
!hasExactKeys(snapshot, [
!hasExactSnapshotKeys(snapshot, [
"classifyClosed",
"close",
"waitClosed",
@@ -1231,7 +1214,7 @@ function parseSession<ClosedReceipt>(
function parseCloseClassification(
value: unknown,
): ParsedCloseClassification | null {
const snapshot = captureDataSnapshot(value);
const snapshot = captureRealtimeDataSnapshot(value);
if (!snapshot) return null;
if (snapshot.values.kind === "RECOVERY_RECONNECT") {
const directive = parseRecoveryDirectiveSnapshot(snapshot);
@@ -1255,11 +1238,12 @@ function parseCloseClassification(
}
function parseRecoveryDirectiveSnapshot(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): ParsedRecoveryDirective | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["kind", "recovery", "terminalResult"],
[
"kind",
@@ -1267,13 +1251,13 @@ function parseRecoveryDirectiveSnapshot(
"serverNotBeforeMs",
"terminalResult",
],
]) ||
) ||
snapshot.values.kind !== "RECOVERY_RECONNECT"
) {
return null;
}
const recovery = parseCommittedRecovery(
captureDataSnapshot(snapshot.values.recovery),
captureRealtimeDataSnapshot(snapshot.values.recovery),
);
const terminalFailure = parseFailureResult(
snapshot.values.terminalResult,
@@ -1296,32 +1280,32 @@ function parseRecoveryDirectiveSnapshot(
}
function parseCommittedRecovery(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): RealtimeCommittedRecovery | null {
if (
!snapshot ||
!hasExactKeys(snapshot, [
!hasExactSnapshotKeys(snapshot, [
"checkpoint",
"kind",
"streamId",
]) ||
snapshot.values.kind !== "RECOVERY_COMMITTED" ||
!safeFrozen(snapshot.source)
!snapshot.frozen
) {
return null;
}
const checkpoint = captureDataSnapshot(
const checkpoint = captureRealtimeDataSnapshot(
snapshot.values.checkpoint,
);
if (
!checkpoint ||
!hasExactKeys(checkpoint, [
!hasExactSnapshotKeys(checkpoint, [
"lastAppliedSequence",
"recoveryMode",
"resumeCursor",
"streamEpoch",
]) ||
!safeFrozen(checkpoint.source)
!checkpoint.frozen
) {
return null;
}
@@ -1357,22 +1341,23 @@ function parseVoidResult(
}
function parseOutcomeSnapshot<Value>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
parseValue: (candidate: unknown) => ParsedValue<Value> | null,
): ParsedOutcome<Value> | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["result"],
["result", "serverNotBeforeMs"],
])
)
) {
return null;
}
const result = parseResult(snapshot.values.result, parseValue);
if (!result) return null;
if (result.ok) {
return hasExactKeys(snapshot, ["result"])
return hasExactSnapshotKeys(snapshot, ["result"])
? Object.freeze({
ok: true,
result: result.result,
@@ -1395,11 +1380,11 @@ function parseResult<Value>(
value: unknown,
parseValue: (candidate: unknown) => ParsedValue<Value> | null,
): ParsedResult<Value> | null {
const snapshot = captureDataSnapshot(value);
if (!snapshot || !safeFrozen(snapshot.source)) return null;
const snapshot = captureRealtimeDataSnapshot(value);
if (!snapshot || !snapshot.frozen) return null;
if (snapshot.values.ok === true) {
if (!hasExactKeys(snapshot, ["ok", "value"])) return null;
if (!hasExactSnapshotKeys(snapshot, ["ok", "value"])) return null;
const parsedValue = parseValue(snapshot.values.value);
const canonical = Object.freeze({
ok: true,
@@ -1430,29 +1415,29 @@ function parseResult<Value>(
function parseFailureResult(
value: unknown,
): FailureSnapshot | null {
return parseFailureResultSnapshot(captureDataSnapshot(value));
return parseFailureResultSnapshot(captureRealtimeDataSnapshot(value));
}
function parseFailureResultSnapshot(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): FailureSnapshot | null {
if (
!snapshot ||
!hasExactKeys(snapshot, ["error", "ok"]) ||
!hasExactSnapshotKeys(snapshot, ["error", "ok"]) ||
snapshot.values.ok !== false ||
!safeFrozen(snapshot.source)
!snapshot.frozen
) {
return null;
}
const error = captureDataSnapshot(snapshot.values.error);
const error = captureRealtimeDataSnapshot(snapshot.values.error);
if (
!error ||
!hasExactKeys(error, [
!hasExactSnapshotKeys(error, [
"kind",
"operation",
"retryable",
]) ||
!safeFrozen(error.source)
!error.frozen
) {
return null;
}
@@ -1482,69 +1467,6 @@ function parseFailureResultSnapshot(
});
}
function captureDataSnapshot(value: unknown): DataSnapshot | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
try {
const prototype = Object.getPrototypeOf(value);
if (
prototype !== Object.prototype &&
prototype !== null
) {
return null;
}
const descriptors = Object.getOwnPropertyDescriptors(value);
const ownKeys = Reflect.ownKeys(descriptors);
if (ownKeys.some((key) => typeof key !== "string")) {
return null;
}
const keys = (ownKeys as string[]).sort();
const values = Object.create(null) as Record<string, unknown>;
for (const key of keys) {
const descriptor = descriptors[key];
if (
!descriptor ||
!("value" in descriptor) ||
descriptor.enumerable !== true
) {
return null;
}
Object.defineProperty(values, key, {
configurable: false,
enumerable: true,
value: descriptor.value,
writable: false,
});
}
return Object.freeze({
source: value,
keys: Object.freeze(keys),
values: Object.freeze(values),
});
} catch {
return null;
}
}
function hasOneExactKeySet(
snapshot: DataSnapshot,
expected: readonly (readonly string[])[],
): boolean {
return expected.some((keys) => hasExactKeys(snapshot, keys));
}
function hasExactKeys(
snapshot: DataSnapshot,
expected: readonly string[],
): boolean {
const sorted = [...expected].sort();
return (
snapshot.keys.length === sorted.length &&
snapshot.keys.every((key, index) => key === sorted[index])
);
}
function parseNotBefore(
value: unknown,
): number | null | undefined {
@@ -1658,17 +1580,11 @@ function providerRetry(
);
}
function reconnectable(
failureSnapshot: FailureSnapshot,
serverNotBeforeMs: number | null,
): boolean {
if (
serverNotBeforeMs === null &&
(failureSnapshot.kind === "RATE_LIMITED" ||
failureSnapshot.kind === "PROVIDER_UNAVAILABLE")
) {
return false;
}
/**
* A transport that needs a server hint and did not get one already reports
* `retryable: false`, so a missing hint alone never ends the loop.
*/
function reconnectable(failureSnapshot: FailureSnapshot): boolean {
return (
failureSnapshot.retryable &&
RETRYABLE_KINDS.includes(
@@ -1677,6 +1593,25 @@ function reconnectable(
);
}
function runEnd(
result: RealtimeResult<void>,
): Pick<RealtimeReconnectObservation, "failureKind" | "reason"> {
if (result.ok) return { reason: "COMPLETED" };
const { kind, retryable } = result.error;
return {
failureKind: kind,
reason:
kind === "ABORTED" || kind === "CLOSED" || kind === "SCOPE_FENCED"
? "ABORTED"
: retryable &&
RETRYABLE_KINDS.includes(
kind as (typeof RETRYABLE_KINDS)[number],
)
? "EXHAUSTED"
: "TERMINAL",
};
}
function closeLateSession(
outcome: Settled<unknown>,
): void {
@@ -1725,14 +1660,6 @@ function safeSignalAborted(
}
}
function safeFrozen(value: object): boolean {
try {
return Object.isFrozen(value);
} catch {
return false;
}
}
function safelyAddAbortListener(
signal: AbortSignal | undefined,
listener: () => void,
+9 -38
View File
@@ -1,3 +1,5 @@
export { parseRetryAfterDelay } from "../platform/retry-after.ts";
export const REALTIME_RECONNECT_CEILINGS = Object.freeze({
drainTimeoutMs: 2_000,
maxAttempts: 10,
@@ -126,57 +128,26 @@ export function reconnectBudgetRemaining(
return Math.max(0, policy.maxElapsedMs - (nowMs - startedAtMs));
}
/**
* A connection earns a fresh retry budget only when it both proved itself
* with a valid heartbeat/event and stayed open for `stableOpenMs`. Either
* alone lets a server that sends one comment and drops keep the budget at
* zero forever.
*/
export function isReconnectAttemptResetEligible(input: Readonly<{
policy: ReconnectPolicy;
openedAtMs: number;
nowMs: number;
observedValidHeartbeatOrEvent: boolean;
}>): boolean {
if (input.observedValidHeartbeatOrEvent) return true;
return (
input.observedValidHeartbeatOrEvent &&
Number.isFinite(input.openedAtMs) &&
Number.isFinite(input.nowMs) &&
input.nowMs - input.openedAtMs >= input.policy.stableOpenMs
);
}
/**
* Parses the HTTP Retry-After delay without applying a runtime ceiling.
* Callers must reject a value that exceeds their remaining/max-delay budget.
*/
export function parseRetryAfterDelay(
value: string | null | undefined,
nowEpochMs: number,
): number | null {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 128 ||
!Number.isFinite(nowEpochMs)
) {
return null;
}
const normalized = value.trim();
if (/^\d+$/u.test(normalized)) {
const seconds = Number(normalized);
return Number.isSafeInteger(seconds) &&
seconds <= Math.floor(Number.MAX_SAFE_INTEGER / 1_000)
? seconds * 1_000
: null;
}
if (
!/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/u.test(
normalized,
)
) {
return null;
}
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp)
? Math.max(0, timestamp - nowEpochMs)
: null;
}
function positiveInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
+123 -7
View File
@@ -16,6 +16,7 @@ import {
isRealtimeOpaqueIdentifier,
isRealtimeResumeCursor,
} from "../../contracts/realtime-events.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
export type {
RealtimeFailure,
@@ -35,6 +36,8 @@ const FAILURE_KINDS = new Set<unknown>(REALTIME_FAILURE_KINDS);
const OPERATIONS = new Set<unknown>(REALTIME_OPERATIONS);
export type RealtimeDataSnapshot = Readonly<{
/** The object that was read; never read its properties again. */
source: object;
keys: readonly string[];
values: Readonly<Record<string, unknown>>;
frozen: boolean;
@@ -67,6 +70,115 @@ export function isRealtimeFailure(
return parseRealtimeFailure(value, true) !== null;
}
export type RealtimeRace<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "REJECTED" }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "TIMEOUT" }>
| Readonly<{ kind: "CLOCK_FAILED" }>;
const REJECTED = Object.freeze({ kind: "REJECTED" as const });
const ABORTED = Object.freeze({ kind: "ABORTED" as const });
const TIMEOUT = Object.freeze({ kind: "TIMEOUT" as const });
const CLOCK_FAILED = Object.freeze({ kind: "CLOCK_FAILED" as const });
/**
* Realtime's one abort/deadline race, on the kernel abortable operation.
* Settles with whichever comes first: the task's value or rejection (a
* synchronous throw counts as one), `signal` aborting, or `deadline`
* resolving. A deadline that throws or rejects on its own is CLOCK_FAILED.
* Nothing starts when `signal` is already aborted.
*
* The task gets the operation signal, which aborts with `signal`, at the
* deadline and once the race is over. The deadline is armed before the task
* starts, so it wins a tie, but the task always starts (a cancel must not be
* skipped because the clock broke).
*/
export function raceRealtimeTask<Value>(
task: (signal: AbortSignal) => Value | PromiseLike<Value>,
signal?: AbortSignal,
deadline?: (signal: AbortSignal) => PromiseLike<unknown>,
): Promise<RealtimeRace<Value>> {
if (signal?.aborted) return Promise.resolve(ABORTED);
const timer = new AbortController();
const operation = createAbortableOperation({
signal,
...(deadline && {
timeoutMs: 0,
setTimer: (fire: () => void) =>
Promise.resolve(deadline(timer.signal)).then(fire, () =>
operation.close(),
),
clearTimer: () => timer.abort(),
}),
});
let running: Promise<Value>;
try {
running = Promise.resolve(task(operation.signal));
} catch (error) {
running = Promise.reject(error);
}
const raced = operation.race(running);
// Registered after the race, so the outcome is claimed first.
void running.then(operation.close, operation.close);
return raced.then((outcome) =>
outcome.kind === "VALUE"
? outcome
: outcome.kind === "REJECTED"
? REJECTED
: outcome.terminal === "CALLER_ABORT"
? ABORTED
: outcome.terminal === "DEADLINE"
? TIMEOUT
: CLOCK_FAILED,
);
}
/**
* Best-effort delivery to an optional observation sink. A throwing sink never
* changes realtime control flow.
*/
export function observeRealtime<Observation extends object>(
sink: ((observation: Observation) => void) | undefined,
observation: Observation,
): void {
try {
sink?.(Object.freeze(observation));
} catch {
// Diagnostics never control realtime behavior.
}
}
/**
* A `raceRealtimeTask` deadline on a host timer instead of the injected
* clock, for bounds that must hold even when the clock itself hangs.
*/
export function timerDeadline(
delayMs: number,
schedule: (callback: () => void, delayMs: number) => unknown = (
callback,
delay,
) => setTimeout(callback, delay),
cancel: (handle: unknown) => void = (handle) =>
clearTimeout(handle as ReturnType<typeof setTimeout>),
): (signal: AbortSignal) => Promise<void> {
return (signal) =>
new Promise((resolve) => {
const handle = schedule(resolve, delayMs);
signal.addEventListener(
"abort",
() => {
try {
cancel(handle);
} catch {
// A broken scheduler cannot change the race outcome.
}
},
{ once: true },
);
});
}
/**
* Captures an external result through own data descriptors exactly once and
* returns a new canonical value. Callers that need to use the validated fields
@@ -186,6 +298,7 @@ export function captureRealtimeDataSnapshot(
descriptor.writable === false;
}
return Object.freeze({
source: value,
keys: Object.freeze(keys),
values: Object.freeze(values),
frozen,
@@ -266,13 +379,16 @@ function parseRealtimeFailure(
});
}
function hasExactSnapshotKeys(
/** True when the snapshot's keys are exactly one of the given key sets. */
export function hasExactSnapshotKeys(
snapshot: RealtimeDataSnapshot,
expectedKeys: readonly string[],
...keySets: readonly (readonly string[])[]
): boolean {
const expected = [...expectedKeys].sort();
return (
snapshot.keys.length === expected.length &&
snapshot.keys.every((key, index) => key === expected[index])
);
return keySets.some((keySet) => {
const expected = [...keySet].sort();
return (
snapshot.keys.length === expected.length &&
snapshot.keys.every((key, index) => key === expected[index])
);
});
}
+91 -143
View File
@@ -12,15 +12,18 @@ import {
} from "../../../application/ports/realtime/event-authority.ts";
import { isRealtimeResumeCursor } from "../../../contracts/realtime-events.ts";
import { systemClock } from "../../platform/system-clock.ts";
import type { RealtimeReconnectOutcome } from "../reconnect-coordinator.ts";
import { parseRetryAfterDelay } from "../reconnect-policy.ts";
import {
isRealtimeResult,
isRealtimeTransportEventOutcome,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "../result.ts";
import {
createIncrementalSseParser,
SSE_PARSER_CEILINGS,
type ParsedSseEvent,
type SseParserItem,
type SseParserLimits,
@@ -100,6 +103,7 @@ const MAX_CONNECT_TIMEOUT_MS = 30_000;
const MAX_IDLE_TIMEOUT_MS = 120_000;
const MAX_CURSOR_BYTES = 1_024;
const READER_CANCEL_TIMEOUT_MS = 2_000;
const encoder = new TextEncoder();
export function createFetchSseConnection(
dependencies: FetchSseConnectionDependencies,
@@ -128,6 +132,9 @@ export function createFetchSseConnection(
// Validate immutable parser policy at factory construction, before network
// side effects. A fresh parser is still created for every physical attempt.
createIncrementalSseParser(dependencies.parserLimits);
const maxChunkBytes =
dependencies.parserLimits?.maxChunkBytes ??
SSE_PARSER_CEILINGS.maxChunkBytes;
let closed = false;
let active = false;
@@ -162,30 +169,36 @@ export function createFetchSseConnection(
once: true,
});
if (input.signal?.aborted) onCallerAbort();
const timed = <Value>(
task: () => Value | PromiseLike<Value>,
timeoutMs: number,
) =>
raceRealtimeTask(task, controller.signal, (signal) =>
clock.sleep(timeoutMs, signal),
);
try {
const request = timed(
Promise.resolve().then(() =>
fetcher(endpoint.href, {
method: "GET",
credentials: "same-origin",
redirect: "error",
cache: "no-store",
referrerPolicy: "no-referrer",
headers: {
Accept: "text/event-stream",
...(input.resumeCursor === null
? {}
: { "Last-Event-ID": input.resumeCursor }),
},
signal: controller.signal,
}),
),
const responseResult = await timed(
// The fetcher starts on the next microtask, like other collaborators.
() =>
Promise.resolve().then(() =>
fetcher(endpoint.href, {
method: "GET",
credentials: "same-origin",
redirect: "error",
cache: "no-store",
referrerPolicy: "no-referrer",
headers: {
Accept: "text/event-stream",
...(input.resumeCursor === null
? {}
: { "Last-Event-ID": input.resumeCursor }),
},
signal: controller.signal,
}),
),
connectTimeoutMs,
clock,
controller.signal,
);
const responseResult = await request;
if (responseResult.kind === "CLOCK_FAILED") {
controller.abort();
return failed("PROVIDER_UNAVAILABLE", "CONNECT", true);
@@ -241,23 +254,11 @@ export function createFetchSseConnection(
const reader = response.body.getReader();
activeReader = reader;
let retryHintMs: number | null = null;
if (input.onOpen) {
let opening: Promise<RealtimeResult<void>>;
try {
opening = Promise.resolve(input.onOpen(controller.signal));
} catch {
await cancelReader(reader, clock, controller);
return failed(
"PROVIDER_UNAVAILABLE",
"CONNECT",
false,
);
}
const onOpen = input.onOpen;
if (onOpen) {
const opened = await timed(
opening,
() => onOpen(controller.signal),
connectTimeoutMs,
clock,
controller.signal,
);
if (opened.kind !== "VALUE") {
await cancelReader(reader, clock, controller);
@@ -305,7 +306,7 @@ export function createFetchSseConnection(
(!item.hasExplicitId ||
!item.id ||
!isRealtimeResumeCursor(item.id) ||
new TextEncoder().encode(item.id).byteLength >
encoder.encode(item.id).byteLength >
maxCursorBytes)
) {
await cancelReader(reader, clock, controller);
@@ -318,22 +319,9 @@ export function createFetchSseConnection(
await cancelReader(reader, clock, controller);
return failed("PROTOCOL_MISMATCH", "DECODE", false);
}
let handler: Promise<
RealtimeResult<SseInboundEventOutcome>
>;
try {
handler = Promise.resolve(
input.onEvent(item, controller.signal),
);
} catch {
await cancelReader(reader, clock, controller);
return failed("APPLY_FAILED", "APPLY", false);
}
const handled = await timed(
handler,
() => input.onEvent(item, controller.signal),
idleTimeoutMs,
clock,
controller.signal,
);
if (handled.kind === "ABORTED") {
await cancelReader(reader, clock, controller);
@@ -384,10 +372,8 @@ export function createFetchSseConnection(
while (true) {
const readResult = await timed(
reader.read(),
() => reader.read(),
idleTimeoutMs,
clock,
controller.signal,
);
if (readResult.kind === "ABORTED") {
await cancelReader(reader, clock, controller);
@@ -434,13 +420,31 @@ export function createFetchSseConnection(
await cancelReader(reader, clock, controller);
return failed("MALFORMED_EVENT", "DECODE", false);
}
const parsed = parser.push(readResult.value.value);
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
// The browser picks the read size, so a chunk larger than the
// parser's per-push cap is fed in slices. Items past the per-call item
// cap arrive through drain().
const chunk = readResult.value.value;
for (
let offset = 0;
offset < chunk.byteLength;
offset += maxChunkBytes
) {
for (
let parsed = parser.push(
chunk.subarray(offset, offset + maxChunkBytes),
);
;
parsed = parser.drain()
) {
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
}
if (parsed.value.length === 0) break;
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
}
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
} catch {
return failed(
@@ -480,6 +484,28 @@ export function createFetchSseConnection(
return Object.freeze({ read, close });
}
/**
* Bridges one read to the reconnect coordinator's outcome shape. A validated
* Retry-After (429/503) or SSE `retry:` hint reaches only `onRetryHint`, not
* the failure, so a plain `read` result lets the coordinator retry early.
*/
export async function readSseForReconnect(
connection: FetchSseConnection,
input: FetchSseReadInput,
): Promise<RealtimeReconnectOutcome<FetchSseClosedOutcome>> {
let serverNotBeforeMs: number | null = null;
const result = await connection.read({
...input,
onRetryHint(retryMs) {
serverNotBeforeMs = retryMs;
input.onRetryHint?.(retryMs);
},
});
return Object.freeze(
result.ok ? { result } : { result, serverNotBeforeMs },
);
}
function fixedEndpoint(endpoint: string, applicationOrigin: string): URL {
let parsedEndpoint: URL;
let parsedOrigin: URL;
@@ -532,7 +558,7 @@ function validResumeCursor(
return (
typeof cursor === "string" &&
isRealtimeResumeCursor(cursor) &&
new TextEncoder().encode(cursor).byteLength <= maxCursorBytes
encoder.encode(cursor).byteLength <= maxCursorBytes
);
}
@@ -591,66 +617,6 @@ function responseFailure(
return failed("PROTOCOL_MISMATCH", "CONNECT", false);
}
type TimedResult<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "REJECTED" }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "CLOCK_FAILED" }>
| Readonly<{ kind: "TIMEOUT" }>;
async function timed<Value>(
operation: Promise<Value>,
timeoutMs: number,
clock: ClockPort,
signal: AbortSignal,
): Promise<TimedResult<Value>> {
if (signal.aborted) {
return Object.freeze({ kind: "ABORTED" });
}
const timer = new AbortController();
let abortListener: (() => void) | undefined;
const operationResult = operation.then<
TimedResult<Value>,
TimedResult<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "REJECTED" }),
);
let timeoutResult: Promise<TimedResult<Value>>;
try {
timeoutResult = clock.sleep(timeoutMs, timer.signal).then<
TimedResult<Value>,
TimedResult<Value>
>(
() => Object.freeze({ kind: "TIMEOUT" }),
() =>
Object.freeze({
kind: timer.signal.aborted
? ("ABORTED" as const)
: ("CLOCK_FAILED" as const),
}),
);
} catch {
return Object.freeze({ kind: "CLOCK_FAILED" });
}
const abortedResult = new Promise<TimedResult<Value>>((resolve) => {
abortListener = () =>
resolve(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", abortListener, { once: true });
if (signal.aborted) abortListener();
});
const result = await Promise.race([
operationResult,
timeoutResult,
abortedResult,
]);
timer.abort();
if (abortListener) {
signal.removeEventListener("abort", abortListener);
}
return result;
}
function readClockNow(clock: ClockPort): number | null {
try {
const value = clock.now();
@@ -666,29 +632,11 @@ async function cancelReader(
generation?: AbortController,
): Promise<void> {
generation?.abort();
let cancellation: Promise<void>;
try {
cancellation = Promise.resolve(reader.cancel()).then(
() => undefined,
() => undefined,
);
} catch {
return;
}
const timeout = new AbortController();
let timeoutPromise: Promise<void>;
try {
timeoutPromise = clock
.sleep(READER_CANCEL_TIMEOUT_MS, timeout.signal)
.then(
() => undefined,
() => undefined,
);
} catch {
timeoutPromise = Promise.resolve();
}
await Promise.race([cancellation, timeoutPromise]);
timeout.abort();
await raceRealtimeTask(
() => reader.cancel(),
undefined,
(signal) => clock.sleep(READER_CANCEL_TIMEOUT_MS, signal),
);
}
function safelyNotify(
+1
View File
@@ -1,5 +1,6 @@
export {
createFetchSseConnection,
readSseForReconnect,
SSE_CONTINUE,
type FetchSseClosedOutcome,
type FetchSseConnection,
+158 -77
View File
@@ -13,6 +13,11 @@ export const SSE_PARSER_CEILINGS = Object.freeze({
maxRetryMs: 60_000,
});
const NO_ITEMS: readonly SseParserItem[] = Object.freeze([]);
const COMMENT_ITEMS: readonly SseParserItem[] = Object.freeze([
Object.freeze({ kind: "COMMENT" as const }),
]);
export type SseParserLimits = Readonly<{
maxLineBytes: number;
maxEventBytes: number;
@@ -45,7 +50,13 @@ export type SseParserFinish = Readonly<{
}>;
export type IncrementalSseParser = Readonly<{
/**
* Returns at most `maxItemsPerChunk` items. Bytes past that cap are kept
* and must be taken with `drain()` until it returns no items; pushing or
* finishing before then fails with QUEUE_OVERFLOW.
*/
push(chunk: Uint8Array): RealtimeResult<readonly SseParserItem[]>;
drain(): RealtimeResult<readonly SseParserItem[]>;
finish(): RealtimeResult<SseParserFinish>;
}>;
@@ -53,17 +64,23 @@ export function createIncrementalSseParser(
limits: Partial<SseParserLimits> = {},
): IncrementalSseParser {
const resolved = resolveLimits(limits);
// The decoder keeps U+FEFF; `append` drops the one leading BOM the stream
// grammar allows, so a BOM at the start of a later line stays text.
const decoder = new TextDecoder("utf-8", {
fatal: true,
ignoreBOM: false,
ignoreBOM: true,
});
const encoder = new TextEncoder();
let state: "OPEN" | "FAILED" | "FINISHED" = "OPEN";
let atStart = true;
let pendingCarriageReturn = false;
let atStreamStart = true;
let line = "";
// UTF-8 bytes of the decoded `line`. The bytes of a character the decoder
// still holds across reads (`held` of `heldNeed`) count once it completes.
let lineBytes = 0;
let held = 0;
let heldNeed = 0;
let undrained: Uint8Array | null = null;
let blockBytes = 0;
let dataLines: string[] = [];
let eventType = "";
@@ -82,35 +99,36 @@ export function createIncrementalSseParser(
if (chunk.byteLength > resolved.maxChunkBytes) {
return fail("EVENT_TOO_LARGE");
}
let text: string;
try {
text = decoder.decode(chunk, { stream: true });
} catch {
return fail("MALFORMED_EVENT");
if (undrained !== null) return fail("QUEUE_OVERFLOW");
return consumeBytes(chunk);
}
function drain(): RealtimeResult<readonly SseParserItem[]> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
return consumeText(text);
const bytes = undrained ?? new Uint8Array();
undrained = null;
return consumeBytes(bytes);
}
function finish(): RealtimeResult<SseParserFinish> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
let tail: string;
if (undrained !== null) return fail("QUEUE_OVERFLOW");
// Throws when the stream ends inside a character.
try {
tail = decoder.decode();
decoder.decode();
} catch {
return fail("MALFORMED_EVENT");
}
const consumed = consumeText(tail);
if (!consumed.ok) return consumed;
const items = [...consumed.value];
let items = NO_ITEMS;
if (pendingCarriageReturn) {
pendingCarriageReturn = false;
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
items = processed.value;
}
const incompleteEventDiscarded =
lineBytes > 0 ||
@@ -124,60 +142,132 @@ export function createIncrementalSseParser(
state = "FINISHED";
return success(
Object.freeze({
items: Object.freeze(items),
items,
incompleteEventDiscarded,
}),
);
}
function consumeText(
text: string,
/**
* Finds CR/LF on the raw bytes, so a line's byte length is known without
* re-encoding, and decodes each line once. CR and LF bytes never occur
* inside a multibyte UTF-8 character. Byte counts only grow within a line,
* so checking the limits per segment fails exactly where a per-character
* check would. Stops at `maxItemsPerChunk` items and keeps the rest for
* `drain()`.
*/
function consumeBytes(
bytes: Uint8Array,
): RealtimeResult<readonly SseParserItem[]> {
const items: SseParserItem[] = [];
for (const character of text) {
if (atStart) {
atStart = false;
if (character === "\uFEFF") continue;
}
let index = 0;
let nextLineFeed = -1;
let nextCarriageReturn = -1;
while (index < bytes.length) {
// Only part of a character is left: the decoder holds it, and a
// pending CR or the item cap waits for the character to complete.
const rest = bytes.length - index;
if (rest < 4 && heldAfter(bytes.subarray(index)) === held + rest) {
const appended = append(bytes.subarray(index), true);
if (!appended.ok) return appended;
break;
}
if (items.length >= resolved.maxItemsPerChunk) {
// A copy, so a caller reusing its buffer cannot change kept bytes.
undrained = bytes.slice(index);
break;
}
if (pendingCarriageReturn) {
pendingCarriageReturn = false;
const processed = processLine(character === "\n" ? 2 : 1);
const lineFeed = bytes[index] === 0x0a;
const processed = processLine(lineFeed ? 2 : 1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
if (character === "\n") continue;
items.push(...processed.value);
if (lineFeed) index += 1;
continue;
}
if (character === "\r") {
if (nextLineFeed < index) {
nextLineFeed = indexOrEnd(bytes, 0x0a, index);
}
if (nextCarriageReturn < index) {
nextCarriageReturn = indexOrEnd(bytes, 0x0d, index);
}
const lineBreak = Math.min(nextLineFeed, nextCarriageReturn);
const appended = append(
bytes.subarray(index, lineBreak),
lineBreak === bytes.length,
);
if (!appended.ok) return appended;
if (lineBreak === bytes.length) break;
index = lineBreak + 1;
if (bytes[lineBreak] === 0x0d) {
pendingCarriageReturn = true;
continue;
}
if (character === "\n") {
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
continue;
}
line += character;
lineBytes += encoder.encode(character).byteLength;
if (lineBytes > resolved.maxLineBytes) {
return fail("EVENT_TOO_LARGE");
}
if (
lineBytes + blockBytes >
resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
}
const processed = processLine(1);
if (!processed.ok) return processed;
items.push(...processed.value);
}
return success(Object.freeze(items));
}
/**
* Decodes one line segment. `open` means the line continues in a later
* read, so the decoder may hold the bytes of an unfinished character.
*/
function append(
segment: Uint8Array,
open: boolean,
): RealtimeResult<null> {
let text = "";
if (segment.length > 0 || held > 0) {
try {
text = decoder.decode(segment, { stream: open });
} catch {
return fail("MALFORMED_EVENT");
}
}
const heldBefore = held;
held = open ? heldAfter(segment) : 0;
lineBytes += heldBefore + segment.length - held;
if (atStreamStart && (text.length > 0 || !open)) {
atStreamStart = false;
if (text.charCodeAt(0) === 0xfeff) {
text = text.slice(1);
lineBytes -= 3;
}
}
line += text;
if (
lineBytes > resolved.maxLineBytes ||
lineBytes + blockBytes > resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
}
return success(null);
}
/**
* Bytes of the unfinished character at the end of a segment the decoder
* accepted in stream mode, so they form a valid UTF-8 prefix.
*/
function heldAfter(segment: Uint8Array): number {
const end = segment.length;
for (let index = end - 1; index >= 0 && index >= end - 4; index -= 1) {
const byte = segment[index]!;
if (byte < 0x80) return 0;
if (byte >= 0xc0) {
heldNeed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : 2;
return end - index < heldNeed ? end - index : 0;
}
}
// Only continuation bytes: they extend the character already held.
return held + end < heldNeed ? held + end : 0;
}
function processLine(
terminatorBytes: number,
): RealtimeResult<readonly SseParserItem[]> {
@@ -203,13 +293,7 @@ export function createIncrementalSseParser(
return success(Object.freeze(items));
}
if (currentLine.startsWith(":")) {
return success(
Object.freeze([
Object.freeze({ kind: "COMMENT" as const }),
]),
);
}
if (currentLine.startsWith(":")) return success(COMMENT_ITEMS);
blockBytes += currentLineBytes + terminatorBytes;
if (blockBytes > resolved.maxEventBytes) {
@@ -230,18 +314,18 @@ export function createIncrementalSseParser(
if (field === "data") {
dataLines.push(value);
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "event") {
eventType = value;
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "id") {
if (!value.includes("\0")) {
lastEventId = value;
hasExplicitId = true;
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "retry" && /^\d+$/u.test(value)) {
const retryMs = Number(value);
@@ -256,7 +340,7 @@ export function createIncrementalSseParser(
);
}
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
function clearBlock(): void {
@@ -275,25 +359,13 @@ export function createIncrementalSseParser(
state = "FAILED";
line = "";
lineBytes = 0;
held = 0;
undrained = null;
clearBlock();
return realtimeFailure(kind, "DECODE");
}
function appendItems(
target: SseParserItem[],
additions: readonly SseParserItem[],
): boolean {
if (
target.length + additions.length >
resolved.maxItemsPerChunk
) {
return false;
}
target.push(...additions);
return true;
}
return Object.freeze({ push, finish });
return Object.freeze({ push, drain, finish });
}
function resolveLimits(
@@ -341,6 +413,15 @@ function success<Value>(value: Value): RealtimeResult<Value> {
return realtimeSuccess(value);
}
function indexOrEnd(
bytes: Uint8Array,
byte: number,
from: number,
): number {
const index = bytes.indexOf(byte, from);
return index === -1 ? bytes.length : index;
}
function positiveInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
+78 -107
View File
@@ -35,6 +35,9 @@ import {
} from "./event-codec.ts";
import {
captureRealtimeDataSnapshot,
hasExactSnapshotKeys,
raceRealtimeTask,
timerDeadline,
realtimeFailure,
realtimeSuccess,
snapshotRealtimeResult,
@@ -90,6 +93,11 @@ export type RealtimeStreamCoordinator = Readonly<{
checkpoint: RealtimeRecoveryCheckpoint,
): RealtimeResult<void>;
getResumeState(streamId: StreamRegistrationId): RealtimeResumeState | null;
/**
* An event for this stream failed to decode (design 13.1): freshness
* becomes UNKNOWN, so the next admitted event recovers first.
*/
invalidate(streamId: StreamRegistrationId): void;
inspect(streamId: StreamRegistrationId): RealtimeStreamInspection;
lifecycle(streamId: StreamRegistrationId): RealtimeStreamLifecycle;
/**
@@ -184,15 +192,8 @@ export function createRealtimeStreamCoordinator(
});
const states = new Map<StreamRegistrationId, StreamState>();
let closed = false;
/** RT-02. Releasing a timer is best effort and never a public failure. */
const clearTimerSafely = (handle: unknown): void => {
try {
clearScheduledTimeout(handle);
} catch {
// A broken scheduler cannot change an already classified outcome.
}
};
const deadline = (delayMs: number) =>
timerDeadline(delayMs, scheduleTimeout, clearScheduledTimeout);
const TASK_TIMED_OUT = Symbol("REALTIME_TASK_TIMED_OUT");
@@ -227,26 +228,18 @@ export function createRealtimeStreamCoordinator(
if (!state.closed) state.freshness = "STALE";
}
});
// RT-02. A scheduler that cannot install the deadline leaves the wait
// unbounded. Letting the exception escape turned a typed realtime result
// into a native rejection and — through the caller's own catch — started a
// recovery that overlapped the effect still running, so an install failure
// fails closed as an expired deadline instead.
let handle: unknown;
let installed = false;
const timeout = new Promise<typeof TASK_TIMED_OUT>((resolve) => {
try {
handle = scheduleTimeout(() => resolve(TASK_TIMED_OUT), timeoutMs);
installed = true;
} catch {
resolve(TASK_TIMED_OUT);
}
});
const outcome = await Promise.race([task, timeout]);
if (installed) clearTimerSafely(handle);
if (outcome !== TASK_TIMED_OUT) return outcome;
// The commit capability is revoked immediately; the work itself is not.
const outcome = await raceRealtimeTask(
() => task,
undefined,
deadline(timeoutMs),
);
if (outcome.kind === "VALUE") return outcome.value;
// The collaborator's own rejection reaches the caller unchanged.
if (outcome.kind === "REJECTED") return await task;
// Expired, or (RT-02) a scheduler that could not install the deadline and
// left the wait unbounded: both fail closed as an expired deadline, not a
// native rejection that would start an overlapping recovery. The commit
// capability is revoked immediately; the work itself is not.
revokeAndAbort();
state.lifecycle = "DRAINING";
state.timedOutTasks.add(task);
@@ -487,20 +480,6 @@ export function createRealtimeStreamCoordinator(
signal,
);
}
if (
state.eventIds.size + 1 >
state.registration.limits.maxDedupeEntries ||
state.dedupeBytes + event.fingerprintBytes >
state.registration.limits.maxDedupeBytes
) {
return recoverForAccept(
state,
"DEDUPE_OVERFLOW",
true,
signal,
);
}
const eventType = dependencies.registry.findStreamEventType(
state.registration.id,
event.envelope.eventType,
@@ -626,6 +605,17 @@ export function createRealtimeStreamCoordinator(
fingerprintBytes: event.fingerprintBytes,
appliedAt: safeNow(state),
});
// The dedupe window is the newest entries: drop the oldest to make room.
for (const [eventId, oldest] of state.eventIds) {
if (
state.eventIds.size < state.registration.limits.maxDedupeEntries &&
state.dedupeBytes + entry.fingerprintBytes <=
state.registration.limits.maxDedupeBytes
) {
break;
}
forgetDedupe(state, eventId, oldest);
}
state.eventIds.set(entry.eventId, entry);
state.sequences.set(entry.sequence, entry);
state.dedupeBytes += entry.fingerprintBytes;
@@ -707,7 +697,9 @@ export function createRealtimeStreamCoordinator(
if (!calledFromCurrentJob) {
await quiescence;
}
if (closed || state.closed) {
// RT-RR-01. The effect this recovery waited on can time out and keep
// running; recovering beside it would let its late write win.
if (closed || state.closed || state.lifecycle === "DRAINING") {
state.freshness = "UNKNOWN";
return realtimeFailure("CLOSED", "RECOVER");
}
@@ -907,6 +899,9 @@ export function createRealtimeStreamCoordinator(
outcome: "RECOVERED" as const,
reason,
resumeState: result.value,
transportBarrierRequired: recoveryRequiresTransportBarrier(
state.registration,
),
}),
);
}
@@ -918,38 +913,22 @@ export function createRealtimeStreamCoordinator(
const active = state.recoveryPromise;
const reason = state.activeRecoveryReason ?? "INITIALIZE";
if (!active) return dropped("RECOVERY_IN_PROGRESS");
if (signal?.aborted) {
return realtimeFailure("ABORTED", "RECEIVE");
}
let removeAbortListener: () => void = () => undefined;
const aborted = new Promise<Readonly<{ kind: "ABORTED" }>>(
(resolve) => {
if (!signal) return;
const onAbort = () => resolve({ kind: "ABORTED" });
signal.addEventListener("abort", onAbort, { once: true });
removeAbortListener = () =>
signal.removeEventListener("abort", onAbort);
if (signal.aborted) onAbort();
},
);
const settled = await Promise.race([
active.then((result) => ({
kind: "RESULT" as const,
result,
})),
aborted,
]);
removeAbortListener();
const settled = await raceRealtimeTask(() => active, signal);
if (settled.kind === "ABORTED") {
return realtimeFailure("ABORTED", "RECEIVE");
}
const result = settled.result;
// Only VALUE or REJECTED remain; a rejection propagates as before.
const result =
settled.kind === "VALUE" ? settled.value : await active;
if (!result.ok) return result;
return realtimeSuccess(
Object.freeze({
outcome: "RECOVERED" as const,
reason,
resumeState: result.value,
transportBarrierRequired: recoveryRequiresTransportBarrier(
state.registration,
),
}),
);
}
@@ -1016,6 +995,11 @@ export function createRealtimeStreamCoordinator(
});
}
function invalidate(streamId: StreamRegistrationId): void {
const state = states.get(streamId);
if (state) state.freshness = "UNKNOWN";
}
function lifecycleOf(streamId: StreamRegistrationId): RealtimeStreamLifecycle {
const state = states.get(streamId);
if (!state) return "CLOSED";
@@ -1035,26 +1019,14 @@ export function createRealtimeStreamCoordinator(
for (const state of states.values()) state.lifecycle = "CLOSED";
return realtimeSuccess(undefined);
}
let handle: unknown;
let installed = false;
const drained = await Promise.race([
Promise.allSettled(retained).then(() => true),
new Promise<false>((resolve) => {
try {
handle = scheduleTimeout(
() => resolve(false),
limits.drainTimeoutMs,
);
installed = true;
} catch {
// RT-02. Without a drain bound this call cannot prove quiescence, so
// it reports the honest failure rather than rejecting natively.
resolve(false);
}
}),
]);
if (installed) clearTimerSafely(handle);
if (!drained) {
// RT-02. Without a drain bound (CLOCK_FAILED) this call cannot prove
// quiescence, so it reports the honest failure rather than rejecting.
const drained = await raceRealtimeTask(
() => Promise.allSettled(retained),
undefined,
deadline(limits.drainTimeoutMs),
);
if (drained.kind !== "VALUE") {
// Still DRAINING: the caller must not treat this as quiescence.
return realtimeFailure("IDLE_TIMEOUT", "CLOSE", false);
}
@@ -1105,6 +1077,7 @@ export function createRealtimeStreamCoordinator(
return candidate;
}
/** Entries are kept in apply order and `appliedAt` never decreases. */
function pruneDedupe(state: StreamState): void {
const selectedNow = safeNow(state);
for (const [eventId, entry] of state.eventIds) {
@@ -1112,19 +1085,27 @@ export function createRealtimeStreamCoordinator(
selectedNow - entry.appliedAt <
state.registration.limits.dedupeTtlMs
) {
continue;
break;
}
state.eventIds.delete(eventId);
if (state.sequences.get(entry.sequence) === entry) {
state.sequences.delete(entry.sequence);
}
state.dedupeBytes = Math.max(
0,
state.dedupeBytes - entry.fingerprintBytes,
);
forgetDedupe(state, eventId, entry);
}
}
function forgetDedupe(
state: StreamState,
eventId: string,
entry: DedupeEntry,
): void {
state.eventIds.delete(eventId);
if (state.sequences.get(entry.sequence) === entry) {
state.sequences.delete(entry.sequence);
}
state.dedupeBytes = Math.max(
0,
state.dedupeBytes - entry.fingerprintBytes,
);
}
function fenceState(state: StreamState): void {
state.processingGeneration += 1;
state.activeEffectAbort?.abort();
@@ -1168,6 +1149,7 @@ export function createRealtimeStreamCoordinator(
recover,
confirmTransportBarrier,
getResumeState,
invalidate,
inspect,
lifecycle: lifecycleOf,
close,
@@ -1400,14 +1382,3 @@ function captureSnapshotCheckpoint(
? checkpoint
: null;
}
function hasExactSnapshotKeys(
snapshot: RealtimeDataSnapshot,
expected: readonly string[],
): boolean {
const selected = [...expected].sort();
return (
snapshot.keys.length === selected.length &&
snapshot.keys.every((key, index) => key === selected[index])
);
}
@@ -11,6 +11,7 @@ import type {
import {
isRealtimeResult,
isRealtimeTransportEventOutcome,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "../result.ts";
@@ -70,6 +71,7 @@ export type WebSocketConnectionObservation = Readonly<{
kind:
| "CONNECTED"
| "SUBSCRIBED"
| "HEARTBEAT_ACK"
| "FRAME_REJECTED"
| "RECOVERY_REQUIRED"
| "CLOSED";
@@ -306,7 +308,6 @@ export function createWebSocketConnection(
"PROTOCOL_MISMATCH",
"CONNECT",
false,
"NONE",
),
"PROTOCOL_MISMATCH",
{
@@ -348,12 +349,7 @@ export function createWebSocketConnection(
failureKind: code,
});
terminate(
failure(
code,
"RECEIVE",
false,
code === "EVENT_TOO_LARGE" ? "SNAPSHOT" : "NONE",
),
failure(code, "RECEIVE", false),
"PROTOCOL_MISMATCH",
{
subscriptionId: null,
@@ -377,6 +373,9 @@ export function createWebSocketConnection(
if (decoded.value.nonce === retiredHeartbeat) {
retiredHeartbeat = null;
}
// A quiet stream's only liveness proof; composition can forward it to
// the reconnect coordinator's markValidHeartbeatOrEvent.
observe({ kind: "HEARTBEAT_ACK" });
return;
}
const queueLimits = effectiveLimits ?? ceilings;
@@ -390,7 +389,6 @@ export function createWebSocketConnection(
"QUEUE_OVERFLOW",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
{
@@ -435,7 +433,6 @@ export function createWebSocketConnection(
? "CONNECT"
: "RECEIVE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -450,7 +447,6 @@ export function createWebSocketConnection(
"CLOSED",
"CONNECT",
false,
"NONE",
);
}
if (connectPromise) return connectPromise;
@@ -459,7 +455,6 @@ export function createWebSocketConnection(
"CLOSED",
"CONNECT",
false,
"NONE",
);
}
if (signal?.aborted) {
@@ -467,7 +462,6 @@ export function createWebSocketConnection(
"ABORTED",
"CONNECT",
false,
"NONE",
);
terminate(
aborted.error,
@@ -497,7 +491,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"CONNECT",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -512,7 +505,6 @@ export function createWebSocketConnection(
"ABORTED",
"CONNECT",
false,
"NONE",
),
"NORMAL",
undefined,
@@ -543,7 +535,6 @@ export function createWebSocketConnection(
status === "OPEN" ? "PROTOCOL_MISMATCH" : "CLOSED",
"SUBSCRIBE",
false,
"NONE",
);
}
const eventWindowStartedAt = readClockNow(dependencies.clock);
@@ -552,7 +543,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"SUBSCRIBE",
true,
"RECONNECT",
);
terminate(
unavailable.error,
@@ -595,7 +585,6 @@ export function createWebSocketConnection(
status === "OPEN" ? "PROTOCOL_MISMATCH" : "CLOSED",
"SUBSCRIBE",
false,
"NONE",
);
}
const sent = sendCritical(
@@ -637,7 +626,7 @@ export function createWebSocketConnection(
if (sent.ok) drainOutboundQueue();
}
terminate(
failure("CLOSED", "CLOSE", false, "NONE"),
failure("CLOSED", "CLOSE", false),
category,
undefined,
);
@@ -664,7 +653,6 @@ export function createWebSocketConnection(
"CONNECT_TIMEOUT",
"CONNECT",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -680,7 +668,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"CONNECT",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -761,7 +748,6 @@ export function createWebSocketConnection(
resetFailureCode(frame.reason),
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
@@ -868,7 +854,6 @@ export function createWebSocketConnection(
"SEQUENCE_GAP",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
@@ -882,91 +867,63 @@ export function createWebSocketConnection(
terminateProtocol();
return;
}
if (dependencies.onSubscribed) {
const barrierController = new AbortController();
const abortBarrier = () => barrierController.abort();
generation.signal.addEventListener("abort", abortBarrier, {
once: true,
});
if (generation.signal.aborted) abortBarrier();
try {
const outcome = await Promise.race([
Promise.resolve()
.then(() =>
dependencies.onSubscribed!(
Object.freeze({
subscriptionId: frame.subscriptionId,
streamId: subscription.request.streamId,
streamEpoch: frame.streamEpoch,
acceptedCursor: frame.acceptedCursor,
nextExpectedSequence: frame.nextExpectedSequence,
}),
barrierController.signal,
),
)
.then((value) =>
const onSubscribed = dependencies.onSubscribed;
if (onSubscribed) {
const outcome = await raceRealtimeTask(
(signal) =>
Promise.resolve().then(() =>
onSubscribed(
Object.freeze({
kind: "HANDLED" as const,
value,
subscriptionId: frame.subscriptionId,
streamId: subscription.request.streamId,
streamEpoch: frame.streamEpoch,
acceptedCursor: frame.acceptedCursor,
nextExpectedSequence: frame.nextExpectedSequence,
}),
signal,
),
dependencies.clock
.sleep(
ceilings.maxApplyMs,
barrierController.signal,
)
.then(() =>
Object.freeze({ kind: "TIMED_OUT" as const }),
),
]);
if (
outcome.kind === "TIMED_OUT" &&
status !== "CLOSED"
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
terminate(
failure(
"APPLY_FAILED",
),
generation.signal,
(signal) => dependencies.clock.sleep(ceilings.maxApplyMs, signal),
);
if (outcome.kind === "TIMEOUT" && status !== "CLOSED") {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
terminate(
failure(
"APPLY_FAILED",
"RECOVER",
false,
),
"CURSOR_RESET",
undefined,
);
return;
}
if (outcome.kind === "VALUE" && status !== "CLOSED") {
if (!isRealtimeResult(outcome.value, isUndefined)) {
terminateInboundFailure(
realtimeFailure(
"PROTOCOL_MISMATCH",
"RECOVER",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
).error,
frame.subscriptionId,
);
return;
}
if (
outcome.kind === "HANDLED" &&
status !== "CLOSED"
) {
if (!isRealtimeResult(outcome.value, isUndefined)) {
terminateInboundFailure(
realtimeFailure(
"PROTOCOL_MISMATCH",
"RECOVER",
false,
).error,
frame.subscriptionId,
);
return;
}
if (!outcome.value.ok) {
terminateInboundFailure(
outcome.value.error,
frame.subscriptionId,
);
return;
}
if (!outcome.value.ok) {
terminateInboundFailure(
outcome.value.error,
frame.subscriptionId,
);
return;
}
} catch {
if (
status !== "CLOSED" &&
!generation.signal.aborted
) {
}
if (outcome.kind !== "TIMEOUT" && outcome.kind !== "VALUE") {
if (status !== "CLOSED" && !generation.signal.aborted) {
terminateInboundFailure(
realtimeFailure(
"PROVIDER_UNAVAILABLE",
@@ -977,12 +934,6 @@ export function createWebSocketConnection(
);
}
return;
} finally {
generation.signal.removeEventListener(
"abort",
abortBarrier,
);
barrierController.abort();
}
}
if (
@@ -1023,7 +974,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1049,7 +999,6 @@ export function createWebSocketConnection(
"QUEUE_OVERFLOW",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
@@ -1057,28 +1006,24 @@ export function createWebSocketConnection(
return;
}
const applyController = new AbortController();
const abortApply = () => applyController.abort();
generation.signal.addEventListener("abort", abortApply, {
once: true,
});
try {
const outcome = await Promise.race([
dependencies
.onEvent(frame, applyController.signal)
.then((value) =>
Object.freeze({
kind: "HANDLED" as const,
value,
}),
),
dependencies.clock
.sleep(ceilings.maxApplyMs, applyController.signal)
.then(() =>
Object.freeze({ kind: "TIMED_OUT" as const }),
),
]);
if (outcome.kind === "TIMED_OUT" && status !== "CLOSED") {
const outcome = await raceRealtimeTask(
(signal) => dependencies.onEvent(frame, signal),
generation.signal,
(signal) => dependencies.clock.sleep(ceilings.maxApplyMs, signal),
);
const handled =
outcome.kind === "VALUE" &&
isRealtimeResult(outcome.value, isRealtimeTransportEventOutcome)
? outcome.value
: null;
if (!handled) {
// Timed out, returned no valid result, or failed while still current.
if (
status !== "CLOSED" &&
(outcome.kind === "TIMEOUT" ||
outcome.kind === "VALUE" ||
!generation.signal.aborted)
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
@@ -1088,74 +1033,27 @@ export function createWebSocketConnection(
"APPLY_FAILED",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
);
} else if (outcome.kind === "HANDLED" && status !== "CLOSED") {
if (
!isRealtimeResult(
outcome.value,
isRealtimeTransportEventOutcome,
)
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
terminate(
failure(
"APPLY_FAILED",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
);
} else if (!outcome.value.ok) {
terminateInboundFailure(
outcome.value.error,
frame.subscriptionId,
);
} else if (
outcome.value.value.kind === "RECOVERY_COMMITTED"
) {
terminate(
failure(
"CURSOR_EXPIRED",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
true,
outcome.value.value,
);
}
}
} catch {
if (status !== "CLOSED" && !generation.signal.aborted) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
} else if (status !== "CLOSED") {
if (!handled.ok) {
terminateInboundFailure(handled.error, frame.subscriptionId);
} else if (handled.value.kind === "RECOVERY_COMMITTED") {
terminate(
failure(
"APPLY_FAILED",
"CURSOR_EXPIRED",
"RECEIVE",
false,
"SNAPSHOT",
),
"CURSOR_RESET",
undefined,
true,
handled.value,
);
}
} finally {
generation.signal.removeEventListener("abort", abortApply);
applyController.abort();
}
}
@@ -1256,7 +1154,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1269,7 +1166,6 @@ export function createWebSocketConnection(
"IDLE_TIMEOUT",
"RECEIVE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1286,7 +1182,6 @@ export function createWebSocketConnection(
"PROTOCOL_MISMATCH",
"RECEIVE",
false,
"NONE",
),
"PROTOCOL_MISMATCH",
undefined,
@@ -1303,7 +1198,7 @@ export function createWebSocketConnection(
socket.readyState !== NATIVE_OPEN ||
!effectiveLimits
) {
return connectionFailure("CLOSED", operation, false, "NONE");
return connectionFailure("CLOSED", operation, false);
}
const encoded = encodeWebSocketClientFrame(
frame,
@@ -1316,7 +1211,6 @@ export function createWebSocketConnection(
: "PROTOCOL_MISMATCH",
operation,
false,
"NONE",
);
}
if (
@@ -1333,7 +1227,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
operation,
true,
"RECONNECT",
);
terminate(result.error, "NETWORK_LOST", undefined);
return result;
@@ -1384,7 +1277,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
queued.operation,
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1408,7 +1300,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
queued.operation,
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1428,7 +1319,6 @@ export function createWebSocketConnection(
"QUEUE_OVERFLOW",
operation,
false,
"NONE",
);
terminate(result.error, "OVERLOADED", {
subscriptionId: null,
@@ -1543,7 +1433,6 @@ export function createWebSocketConnection(
"IDLE_TIMEOUT",
"SUBSCRIBE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1562,7 +1451,6 @@ export function createWebSocketConnection(
"PROVIDER_UNAVAILABLE",
"SUBSCRIBE",
true,
"RECONNECT",
),
"NETWORK_LOST",
undefined,
@@ -1919,49 +1807,43 @@ function closeFailure(
): RealtimeFailure {
switch (category) {
case "NORMAL":
return failure("CLOSED", "CLOSE", false, "NONE");
return failure("CLOSED", "CLOSE", false);
case "RESTART":
case "NETWORK_LOST":
return failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
"RECONNECT",
);
case "OVERLOADED":
return failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
false,
"NONE",
);
case "AUTH_REQUIRED":
return failure(
"AUTH_REQUIRED",
"RECEIVE",
false,
"SESSION_REVALIDATE",
);
case "FORBIDDEN":
return failure(
"FORBIDDEN",
"RECEIVE",
false,
"NONE",
);
case "PROTOCOL_MISMATCH":
return failure(
"PROTOCOL_MISMATCH",
"RECEIVE",
false,
"NONE",
);
case "CURSOR_RESET":
return failure(
"CURSOR_EXPIRED",
"RECEIVE",
false,
"SNAPSHOT",
);
}
}
@@ -1988,7 +1870,6 @@ function failure(
kind: RealtimeFailureKind,
operation: RealtimeOperation,
retryable: boolean,
_recovery: "NONE" | "RECONNECT" | "SNAPSHOT" | "SESSION_REVALIDATE",
): RealtimeFailure {
return realtimeFailure(kind, operation, retryable).error;
}
@@ -1997,7 +1878,6 @@ function connectionFailure(
kind: RealtimeFailureKind,
operation: RealtimeOperation,
retryable: boolean,
_recovery: "NONE" | "RECONNECT" | "SNAPSHOT" | "SESSION_REVALIDATE",
): Extract<RealtimeResult<never>, { ok: false }> {
return realtimeFailure(kind, operation, retryable);
}
@@ -1,6 +1,6 @@
import {
hasDuplicateJsonMembers,
} from "../json-member-scanner.ts";
} from "../../platform/json-member-scanner.ts";
export const REALTIME_WEBSOCKET_PROTOCOL = "realtime.v1" as const;
@@ -469,6 +469,12 @@ function isUnsignedSequence(input: unknown): input is string {
}
}
const encoder = new TextEncoder();
function utf8ByteLength(input: string): number {
return encoder.encode(input).byteLength;
}
/**
* R-05. Admission before allocation.
*
@@ -479,10 +485,6 @@ function isUnsignedSequence(input: unknown): input is string {
* bytes and a lone surrogate as the three-byte replacement sequence, exactly
* like `TextEncoder`.
*/
function utf8ByteLength(input: string): number {
return new TextEncoder().encode(input).byteLength;
}
function exceedsUtf8ByteLimit(input: string, maxBytes: number): boolean {
if (input.length > maxBytes) return true;
let bytes = 0;
@@ -89,18 +89,26 @@ self.addEventListener("activate", (event) => {
event.waitUntil(runtime.onActivate());
});
self.addEventListener("fetch", (event) => {
const request = event.request;
event.respondWith(
runtime
.onFetch({
method: request.method,
url: request.url,
mode: request.mode,
})
.then((cached) => cached ?? fetch(request)),
);
});
// R-6.6. Without the static asset handler there is nothing to answer, and
// no fetch listener means the browser never boots this worker for a fetch.
if (handlers.includes("PWA_STATIC_ASSETS")) {
self.addEventListener("fetch", (event) => {
const request = event.request;
const described = {
method: request.method,
url: request.url,
mode: request.mode,
};
// R-6.6 / Q-6.6-6b. Decided synchronously: only a same-origin GET for a
// verified asset of this release or a content-hashed old-build chunk is
// answered. Navigations, API calls, cross-origin and unhashed requests are
// left to the browser untouched. Every cache miss goes to the network.
if (!runtime.intercepts(described)) return;
event.respondWith(
runtime.onFetch(described).then((cached) => cached ?? fetch(request)),
);
});
}
self.addEventListener("message", (event) => {
const parsed = parseServiceWorkerMessage(event.data);
@@ -1,4 +1,5 @@
import {
HASHED_STATIC_ASSET_NAME,
SERVICE_WORKER_BOUNDS,
isOwnedStaticCacheName,
staticCacheName,
@@ -118,11 +119,12 @@ export function createServiceWorkerRuntime(
),
);
const consumedNonces = new Set<string>();
/** 06-07. Why a drain ended, so the requester is told the real reason. */
type DrainOutcome = "DRAINED" | "REJECTED" | "TIMED_OUT";
type PendingActivation = Readonly<{
requesterBuildId: string;
expectedClientIds: ReadonlySet<string>;
acknowledgedClientIds: Set<string>;
resolve(drained: boolean): void;
resolve(outcome: DrainOutcome): void;
timer: ReturnType<typeof setTimeout>;
}>;
const pendingActivations = new Map<string, PendingActivation>();
@@ -154,20 +156,17 @@ export function createServiceWorkerRuntime(
const owned = names.filter(isOwnedStaticCacheName);
const currentCache = await scope.caches.open(current);
const oldCaches = owned.filter((name) => name !== current);
const markers: ActivationMarker[] = [];
for (const name of oldCaches) {
const marker = await readActivationMarker(await scope.caches.open(name), name);
if (marker) markers.push(marker);
}
const highestOld = await highestMarkedCache(names, current);
const currentMarker = await readActivationMarker(currentCache, current);
const highestOld = markers.reduce<ActivationMarker | null>(
(highest, marker) =>
!highest || marker.activationSequence >= highest.activationSequence
? marker
: highest,
null,
);
const previous = highestOld?.cacheName ?? oldCaches.at(-1) ?? null;
// Q-6.6-9. Stale caches go first: when storage is full the marker write
// below is what fails, and deleting is the only way space comes back.
const stale = selectCachesToDelete(names, current, previous);
let deleted = 0;
for (const name of stale) {
if (await scope.caches.delete(name).catch(() => false)) deleted += 1;
}
void SERVICE_WORKER_BOUNDS.retainedPreviousCaches;
if (
!currentMarker ||
currentMarker.activationSequence < (highestOld?.activationSequence ?? 0)
@@ -176,54 +175,127 @@ export function createServiceWorkerRuntime(
if (!Number.isSafeInteger(nextSequence)) {
throw new Error("SERVICE_WORKER_ACTIVATION_SEQUENCE_EXHAUSTED");
}
await currentCache.put(
ACTIVATION_MARKER_URL,
new Response(
JSON.stringify({
schemaVersion: 1,
cacheName: current,
activationSequence: nextSequence,
}),
{
status: 200,
headers: { "content-type": "application/json" },
},
),
);
try {
await currentCache.put(
ACTIVATION_MARKER_URL,
new Response(
JSON.stringify({
schemaVersion: 1,
cacheName: current,
activationSequence: nextSequence,
}),
{
status: 200,
headers: { "content-type": "application/json" },
},
),
);
} catch {
// Q-6.6-9. Activation stands without a marker; the next release just
// cannot find this cache as its previous one for the hashed fallback.
}
}
const stale = selectCachesToDelete(names, current, previous);
let deleted = 0;
for (const name of stale) {
if (await scope.caches.delete(name)) deleted += 1;
}
void SERVICE_WORKER_BOUNDS.retainedPreviousCaches;
return deleted;
}
/** The owned non-current cache with the highest activation marker. */
async function highestMarkedCache(
names: readonly string[],
current: string,
): Promise<ActivationMarker | null> {
let highest: ActivationMarker | null = null;
for (const name of names) {
if (!isOwnedStaticCacheName(name) || name === current) continue;
const marker = await readActivationMarker(
await scope.caches.open(name),
name,
);
if (
marker &&
(!highest || marker.activationSequence >= highest.activationSequence)
) {
highest = marker;
}
}
return highest;
}
/**
* §18.5–§18.7. A verified cache hit is returned; anything else goes to the
* network and is never written back into the active cache at runtime.
* R-6.3 / D-7. A hashed URL names immutable bytes, so the copy kept in the
* previous release cache (found by its activation marker) is the same
* response. Any other URL is never answered from a previous release.
*/
async function onFetch(
request: Readonly<{ method: string; url: string; mode?: string }>,
async function matchPreviousRelease(
url: string,
current: string,
): Promise<Response | null> {
const classification = classifyFetch({
try {
if (!HASHED_STATIC_ASSET_NAME.test(new URL(url).pathname)) return null;
const previous = await highestMarkedCache(
await scope.caches.keys(),
current,
);
if (!previous) return null;
const cached = await (
await scope.caches.open(previous.cacheName)
).match(url);
return cached?.status === 200 && cached.type !== "opaque"
? cached
: null;
} catch {
return null;
}
}
type FetchRequest = Readonly<{ method: string; url: string; mode?: string }>;
function classify(request: FetchRequest) {
if (!staticEnabled) return "NETWORK_PASSTHROUGH";
return classifyFetch({
method: request.method,
requestUrl: request.url,
isNavigation: request.mode === "navigate",
runtimeConfigUrl: config.runtimeConfigUrl,
releaseManifestUrl: config.releaseManifestUrl,
manifestUrls,
scopeUrl: scope.registrationScope,
});
if (classification !== "VERIFIED_CACHE_FIRST") return null;
}
// SW-01. Only the current release cache may answer. A CacheStorage-wide
// match could return a previous release's response for the same URL, and
// the subsequent delete would then target a cache that was never read.
/**
* R-6.6 / Q-6.6-6b. Synchronous, so the fetch listener decides before it
* calls `respondWith`. Only a manifest asset of this release or a
* content-hashed URL under the build asset directory (an old build's chunk,
* 06-08) is answered;
* navigations, API calls, cross-origin and unhashed URLs are left alone.
*/
function intercepts(request: FetchRequest): boolean {
const classification = classify(request);
return (
classification === "VERIFIED_CACHE_FIRST" ||
classification === "PREVIOUS_RELEASE_FALLBACK"
);
}
/**
* §18.5–§18.7. A verified cache hit is returned; anything else goes to the
* network and is never written back into the active cache at runtime.
*/
async function onFetch(request: FetchRequest): Promise<Response | null> {
const classification = classify(request);
// SW-01. Only the current release cache may answer a manifest URL. A
// CacheStorage-wide match could return a previous release's response for
// the same URL, and the subsequent delete would then target a cache that
// was never read.
const currentCacheName = config.manifest
? staticCacheName(config.manifest.setDigest)
: null;
if (!currentCacheName) return null;
if (classification === "PREVIOUS_RELEASE_FALLBACK") {
// Q-6.6-6b. Not listed by this release, so not in the current cache.
return matchPreviousRelease(request.url, currentCacheName);
}
if (classification !== "VERIFIED_CACHE_FIRST") return null;
// SW-RR-04. Both `open` and `match` are storage calls that can throw
// synchronously or reject. Either one escaping here rejects `respondWith`
// itself, so the entry never reaches its network fallback and the page
@@ -236,7 +308,7 @@ export function createServiceWorkerRuntime(
} catch {
return null;
}
if (!cached) return null;
if (!cached) return matchPreviousRelease(request.url, currentCacheName);
if (cached.status !== 200 || cached.type === "opaque") {
// §18.6. An invalid hit is deleted from the cache it was read from and
// treated as a release mismatch.
@@ -276,13 +348,13 @@ export function createServiceWorkerRuntime(
const clients = candidates.filter((client) =>
isClientWithinRegistrationScope(client.url, scope.registrationScope),
);
const drained = await drainClients(
clients,
nonce,
parsed.message.sourceBuildId,
);
if (!drained) {
notifyClients(clients, "ACTIVATE_REJECTED", parsed.message.sourceBuildId, nonce);
const drained = await drainClients(clients, nonce);
if (drained !== "DRAINED") {
notifyClients(
clients,
drained === "REJECTED" ? "ACTIVATE_REJECTED" : "ACTIVATE_DRAIN_TIMEOUT",
nonce,
);
return "REJECTED";
}
@@ -292,28 +364,30 @@ export function createServiceWorkerRuntime(
try {
await scope.skipWaiting();
} catch {
notifyClients(clients, "ACTIVATE_REJECTED", parsed.message.sourceBuildId, nonce);
notifyClients(clients, "ACTIVATE_COMMIT_FAILED", nonce);
return "REJECTED";
}
// Post-commit notifications are per-client best effort.
notifyClients(clients, "ACTIVATE_ACCEPTED", parsed.message.sourceBuildId, nonce);
notifyClients(
clients,
"ACTIVATED_RELOAD_REQUIRED",
parsed.message.sourceBuildId,
nonce,
);
notifyClients(clients, "ACTIVATE_ACCEPTED", nonce);
notifyClients(clients, "ACTIVATED_RELOAD_REQUIRED", nonce);
return "ACCEPTED";
}
/**
* SW-08. One client's `postMessage()` throwing must not break the whole
* activation event; delivery is isolated per client.
*
* R-6.3. Untargeted: every tab, whatever build it runs, has to see
* ACTIVATED_RELOAD_REQUIRED. The requester pairs its reply by nonce.
*/
function notifyClients(
clients: readonly WorkerClientLike[],
kind: "ACTIVATE_REJECTED" | "ACTIVATE_ACCEPTED" | "ACTIVATED_RELOAD_REQUIRED",
targetBuildId: string,
kind:
| "ACTIVATE_REJECTED"
| "ACTIVATE_DRAIN_TIMEOUT"
| "ACTIVATE_COMMIT_FAILED"
| "ACTIVATE_ACCEPTED"
| "ACTIVATED_RELOAD_REQUIRED",
nonce: string,
): void {
for (const client of clients) {
@@ -322,7 +396,6 @@ export function createServiceWorkerRuntime(
createServiceWorkerMessage({
kind,
sourceBuildId: config.identity.buildId,
targetBuildId,
nonce,
}),
);
@@ -335,20 +408,18 @@ export function createServiceWorkerRuntime(
async function drainClients(
clients: readonly WorkerClientLike[],
nonce: string,
requesterBuildId: string,
): Promise<boolean> {
): Promise<DrainOutcome> {
// SW-07. No in-scope client means nothing dirty to drain, so the set is
// vacuously drained. A `clients.matchAll()` failure still rejects upstream.
if (clients.length === 0) return true;
const drained = new Promise<boolean>((resolve) => {
if (clients.length === 0) return "DRAINED";
const drained = new Promise<DrainOutcome>((resolve) => {
const timer = setTimeout(() => {
pendingActivations.delete(nonce);
resolve(false);
resolve("TIMED_OUT");
}, SERVICE_WORKER_BOUNDS.clientDrainMs);
pendingActivations.set(
nonce,
Object.freeze({
requesterBuildId,
expectedClientIds: new Set(clients.map((client) => client.id)),
acknowledgedClientIds: new Set<string>(),
resolve,
@@ -358,20 +429,22 @@ export function createServiceWorkerRuntime(
});
// SW-08. A client that cannot receive the drain request can never
// acknowledge it, so it fails immediately instead of holding the pending
// state until the timeout.
// state until the timeout. Like a silent client it did not refuse (06-07).
// R-6.2. Clients run whatever build they loaded, which is usually not the
// requester's. The request is untargeted; replies are paired by this
// worker's buildId, the nonce and the exact client id.
for (const client of clients) {
try {
client.postMessage(
createServiceWorkerMessage({
kind: "CLIENT_DRAIN_REQUEST",
sourceBuildId: config.identity.buildId,
targetBuildId: requesterBuildId,
nonce,
}),
);
} catch {
const pending = pendingActivations.get(nonce);
if (pending) settlePendingActivation(nonce, pending, false);
if (pending) settlePendingActivation(nonce, pending, "TIMED_OUT");
return await drained;
}
}
@@ -389,22 +462,18 @@ export function createServiceWorkerRuntime(
return;
}
const pending = pendingActivations.get(parsed.message.nonce);
if (
!pending ||
parsed.message.sourceBuildId !== pending.requesterBuildId ||
!pending.expectedClientIds.has(sourceClientId)
) {
if (!pending || !pending.expectedClientIds.has(sourceClientId)) {
return;
}
if (parsed.message.kind === "ACTIVATE_REJECTED") {
settlePendingActivation(parsed.message.nonce, pending, false);
settlePendingActivation(parsed.message.nonce, pending, "REJECTED");
return;
}
pending.acknowledgedClientIds.add(sourceClientId);
if (
pending.acknowledgedClientIds.size === pending.expectedClientIds.size
) {
settlePendingActivation(parsed.message.nonce, pending, true);
settlePendingActivation(parsed.message.nonce, pending, "DRAINED");
}
}
@@ -449,6 +518,7 @@ export function createServiceWorkerRuntime(
onInstall,
onActivate,
onFetch,
intercepts,
onActivateRequest,
onClientMessage,
onCacheResetRequest,
@@ -458,11 +528,11 @@ export function createServiceWorkerRuntime(
function settlePendingActivation(
nonce: string,
pending: PendingActivation,
drained: boolean,
outcome: DrainOutcome,
): void {
clearTimeout(pending.timer);
pendingActivations.delete(nonce);
pending.resolve(drained);
pending.resolve(outcome);
}
}
@@ -38,6 +38,8 @@ export type PageControllerDependencies = Readonly<{
buildId: string;
container?: ServiceWorkerContainer;
caches?: CacheStorage;
/** Q-6.6-12. The host page; without it the global `document`, if any. */
document?: Pick<Document, "visibilityState">;
/** §17.10. Any blocker returning true rejects automatic activation. */
blockers?: readonly ActivationBlocker[];
now?: () => number;
@@ -63,6 +65,9 @@ export function createServiceWorkerPageController(
let resetInFlight: Promise<ServiceWorkerResetOutcome> | null = null;
let stopped = false;
const pendingStops = new Set<() => void>();
let updateFoundListener: (() => void) | null = null;
const reloadRequiredListeners = new Set<() => void>();
const updateWaitingListeners = new Set<() => void>();
const observe = (event: string, outcome: string) =>
dependencies.observe?.({ event, outcome });
@@ -178,12 +183,26 @@ export function createServiceWorkerPageController(
}
attachMessageListener(container);
watchForUpdates(registration);
scheduleUpdateChecks();
if (registration.waiting) {
observe("register", "UPDATE_WAITING");
return Object.freeze({ kind: "UPDATE_WAITING" as const });
}
// R-6.4. On a first visit `register()` resolves while the only worker is
// still installing, and that install can fail. Nothing is ACTIVE until it
// settles.
if (!registration.active) {
const settled = registration.installing
? await installSettled(registration.installing)
: "INSTALL_FAILED";
if (stopped) return failed("STOPPED");
if (settled !== "ACTIVATED" || !registration.active) {
observe("register", settled);
return failed(settled);
}
}
// §17.13. Without `clients.claim()` the first install leaves this page
// uncontrolled. That is reported, never silently reloaded.
if (registration.active && !container.controller) {
@@ -197,6 +216,38 @@ export function createServiceWorkerPageController(
});
}
/**
* R-6.4. Waits for a first-install worker to become `activated` or
* `redundant`, bounded by the worker's own install deadline and by stop().
*/
function installSettled(
worker: ServiceWorker,
): Promise<"ACTIVATED" | "INSTALL_FAILED" | "INSTALL_TIMEOUT" | "STOPPED"> {
return new Promise((resolve) => {
const finish = (
outcome: "ACTIVATED" | "INSTALL_FAILED" | "INSTALL_TIMEOUT" | "STOPPED",
) => {
clearTimeout(timer);
worker.removeEventListener("statechange", onStateChange);
pendingStops.delete(onStop);
resolve(outcome);
};
const onStateChange = () => {
if (worker.state === "activated") finish("ACTIVATED");
else if (worker.state === "redundant") finish("INSTALL_FAILED");
};
const onStop = () => finish("STOPPED");
const timer = setTimeout(
() => finish("INSTALL_TIMEOUT"),
SERVICE_WORKER_BOUNDS.installDeadlineMs,
);
pendingStops.add(onStop);
worker.addEventListener("statechange", onStateChange);
// The worker may have settled before this listener existed.
onStateChange();
});
}
function attachMessageListener(container: ServiceWorkerContainer): void {
if (messageListener) return;
messageListener = (event: MessageEvent) => {
@@ -239,6 +290,13 @@ export function createServiceWorkerPageController(
observe("client_drain", rejected ? "BLOCKED" : "DRAINED");
return;
}
// R-6.3. Sent to every tab once any tab's activation committed.
if (
parsed.message.kind === "ACTIVATED_RELOAD_REQUIRED" &&
isExpectedWorkerSource(event.source)
) {
notify(reloadRequiredListeners);
}
observe("message", parsed.message.kind);
};
container.addEventListener("message", messageListener);
@@ -261,13 +319,43 @@ export function createServiceWorkerPageController(
);
}
/**
* R-6.3. An update found by the periodic check (or by another tab) reaches
* `waiting` without any message, so the registration's own events are
* watched. A first install has no active worker and activates on its own,
* so it is never announced as waiting.
*/
function watchForUpdates(watched: ServiceWorkerRegistration): void {
if (updateFoundListener) return;
let lastWatched: ServiceWorker | null = null;
const watchInstalling = () => {
const worker = watched.installing;
if (!worker || worker === lastWatched) return;
lastWatched = worker;
worker.addEventListener("statechange", () => {
if (
worker.state === "installed" &&
watched.waiting === worker &&
watched.active
) {
notify(updateWaitingListeners);
}
});
};
updateFoundListener = watchInstalling;
watched.addEventListener("updatefound", updateFoundListener);
// The update may have been found before this listener existed.
watchInstalling();
}
function scheduleUpdateChecks(): void {
// §17.14. At most one check per 6 hours, and none while the page is hidden.
if (updateTimer) return;
const page =
dependencies.document ??
(typeof document === "undefined" ? undefined : document);
updateTimer = setInterval(() => {
if (typeof document !== "undefined" && document.visibilityState === "hidden") {
return;
}
if (page?.visibilityState === "hidden") return;
void registration?.update().catch(() => {
// A failed update check never fails a product flow.
});
@@ -296,7 +384,12 @@ export function createServiceWorkerPageController(
}
const nonce = nonces.issue();
const deadline = now() + SERVICE_WORKER_BOUNDS.clientDrainMs;
// Q-6.6-10b. With equal deadlines a tab draining at 29s left this page at
// TIMEOUT while the worker still committed skipWaiting().
const deadline =
now() +
SERVICE_WORKER_BOUNDS.clientDrainMs +
SERVICE_WORKER_BOUNDS.activationReplySlackMs;
const accepted = await new Promise<ServiceWorkerActivationOutcome>(
(resolve) => {
const container = dependencies.container;
@@ -317,6 +410,20 @@ export function createServiceWorkerPageController(
const onMessage = (event: MessageEvent) => {
const parsed = parseServiceWorkerMessage(event.data);
if (!parsed.ok) return;
const kind = parsed.message.kind;
// R-6.1. Only this request's replies are considered. Any other
// message (SYNC_WAKE_OBSERVED, a drain request, another command's
// result) is not a reply and must not end the activation.
if (
parsed.message.nonce !== nonce ||
(kind !== "ACTIVATE_REJECTED" &&
kind !== "ACTIVATE_DRAIN_TIMEOUT" &&
kind !== "ACTIVATE_COMMIT_FAILED" &&
kind !== "ACTIVATE_ACCEPTED" &&
kind !== "ACTIVATED_RELOAD_REQUIRED")
) {
return;
}
if (
parsed.message.targetBuildId !== undefined &&
parsed.message.targetBuildId !== dependencies.buildId
@@ -331,25 +438,31 @@ export function createServiceWorkerPageController(
finish(Object.freeze({ kind: "PROTOCOL_MISMATCH" as const }));
return;
}
if (registration?.waiting !== waiting) {
// R-6.1. ACCEPTED and RELOAD_REQUIRED are sent after skipWaiting(),
// so the registration may already show this worker as active.
const committed =
kind === "ACTIVATE_ACCEPTED" ||
kind === "ACTIVATED_RELOAD_REQUIRED";
if (
registration?.waiting !== waiting &&
!(committed && registration?.active === waiting)
) {
finish(Object.freeze({ kind: "PROTOCOL_MISMATCH" as const }));
return;
}
if (
parsed.message.kind === "ACTIVATE_REJECTED" &&
parsed.message.nonce === nonce
) {
finish(Object.freeze({ kind: "BLOCKED_DIRTY_CLIENT" as const }));
return;
}
if (
parsed.message.kind === "ACTIVATED_RELOAD_REQUIRED" &&
parsed.message.nonce === nonce
) {
finish(
Object.freeze({ kind: "ACTIVATED_RELOAD_REQUIRED" as const }),
);
}
// 06-07. Only a client's explicit refusal is a dirty client.
finish(
committed
? Object.freeze({ kind: "ACTIVATED_RELOAD_REQUIRED" as const })
: kind === "ACTIVATE_DRAIN_TIMEOUT"
? Object.freeze({ kind: "CLIENT_DRAIN_TIMEOUT" as const })
: kind === "ACTIVATE_COMMIT_FAILED"
? Object.freeze({
kind: "FAILED" as const,
code: "ACTIVATION_COMMIT_FAILED",
})
: Object.freeze({ kind: "BLOCKED_DIRTY_CLIENT" as const }),
);
};
const onStop = () =>
finish(Object.freeze({ kind: "FAILED" as const, code: "STOPPED" }));
@@ -477,10 +590,45 @@ export function createServiceWorkerPageController(
dependencies.container.removeEventListener("message", messageListener);
messageListener = null;
}
if (updateFoundListener && registration) {
registration.removeEventListener("updatefound", updateFoundListener);
updateFoundListener = null;
}
reloadRequiredListeners.clear();
updateWaitingListeners.clear();
nonces.clear();
}
return Object.freeze({ start, requestActivation, resetOwnedCaches, stop });
return Object.freeze({
start,
requestActivation,
resetOwnedCaches,
stop,
onReloadRequired: (listener: () => void) =>
subscribe(reloadRequiredListeners, listener),
onUpdateWaiting: (listener: () => void) =>
subscribe(updateWaitingListeners, listener),
});
}
function subscribe(
listeners: Set<() => void>,
listener: () => void,
): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
}
function notify(listeners: ReadonlySet<() => void>): void {
for (const listener of [...listeners]) {
try {
listener();
} catch {
// A failing subscriber cannot break the message or event handler.
}
}
}
function canPostMessage(
@@ -19,6 +19,8 @@ const MESSAGE_KINDS: ReadonlySet<string> = new Set<ServiceWorkerMessageKind>([
"ACTIVATE_REQUEST",
"ACTIVATE_ACCEPTED",
"ACTIVATE_REJECTED",
"ACTIVATE_DRAIN_TIMEOUT",
"ACTIVATE_COMMIT_FAILED",
"CLIENT_DRAIN_REQUEST",
"CLIENT_DRAINED",
"ACTIVATED_RELOAD_REQUIRED",
@@ -1,4 +1,5 @@
import {
HASHED_STATIC_ASSET_NAME,
isOwnedStaticCacheName,
SERVICE_WORKER_BOUNDS,
staticCacheName,
@@ -17,7 +18,14 @@ import {
export type FetchClassification =
| "NETWORK_PASSTHROUGH"
| "NETWORK_ONLY"
| "VERIFIED_CACHE_FIRST";
| "VERIFIED_CACHE_FIRST"
/**
* Q-6.6-6b. A content-hashed URL under the build asset directory that this
* release does not list, typically a lazy chunk of the build a tab still
* runs. Only the previous release cache may answer it; otherwise it goes to
* the network.
*/
| "PREVIOUS_RELEASE_FALLBACK";
export type ClassificationInput = Readonly<{
method: string;
@@ -26,6 +34,8 @@ export type ClassificationInput = Readonly<{
runtimeConfigUrl: string;
releaseManifestUrl: string;
manifestUrls: ReadonlySet<string>;
/** The registration scope; a hashed URL outside its origin is never cached. */
scopeUrl: string;
}>;
/**
@@ -42,9 +52,31 @@ export function classifyFetch(input: ClassificationInput): FetchClassification {
return "NETWORK_ONLY";
}
if (input.manifestUrls.has(input.requestUrl)) return "VERIFIED_CACHE_FIRST";
if (isSameOriginHashedAsset(input.requestUrl, input.scopeUrl)) {
return "PREVIOUS_RELEASE_FALLBACK";
}
return "NETWORK_PASSTHROUGH";
}
/**
* 06-08. Vite's default `build.assetsDir`, under the app base that is also the
* registration scope. A hashed-looking API or download name elsewhere is not an
* old build chunk and is left to the browser.
*/
const BUILD_ASSET_DIRECTORY = "assets/";
function isSameOriginHashedAsset(requestUrl: string, scopeUrl: string): boolean {
try {
const request = new URL(requestUrl);
return (
request.href.startsWith(new URL(BUILD_ASSET_DIRECTORY, scopeUrl).href) &&
HASHED_STATIC_ASSET_NAME.test(request.pathname)
);
} catch {
return false;
}
}
function sameResource(left: string, right: string): boolean {
try {
const a = new URL(left);
@@ -77,6 +109,8 @@ export type InstallDependencies = Readonly<{
caches: Readonly<{
open(cacheName: string): Promise<Cache>;
delete(cacheName: string): Promise<boolean>;
/** Q-6.6-8. Without it every failed candidate is treated as new. */
keys?(): Promise<readonly string[]>;
}>;
fetcher: typeof fetch;
digest(bytes: Uint8Array): Promise<string>;
@@ -114,7 +148,8 @@ export function validateStaticAssetManifest(
/**
* §17.9. A partial candidate is never used: any failure deletes the candidate
* cache and rejects install, leaving the previous verified revision in place.
* cache this install created and rejects install, leaving the previous
* verified revision in place.
*/
export async function installStaticAssets(
manifest: StaticAssetManifestV1,
@@ -124,6 +159,12 @@ export async function installStaticAssets(
if (invalid) return invalid;
const cacheName = staticCacheName(manifest.setDigest);
// Q-6.6-8. The name is the asset-set digest, so a worker whose assets did
// not change installs into the cache the active (or retained previous)
// worker serves from. Rewriting it only puts identical verified bytes, but
// deleting it on failure would take the serving cache and its marker away.
// Only a cache this install created is rolled back.
const rollBack = !(await cacheExists(dependencies.caches, cacheName));
const abortController = new AbortController();
let deadlineExceeded = false;
let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
@@ -147,7 +188,7 @@ export async function installStaticAssets(
? rejected("INSTALL_DEADLINE_EXCEEDED")
: raced;
if (outcome.kind === "REJECTED") {
if (outcome.kind === "REJECTED" && rollBack) {
await dependencies.caches.delete(cacheName).catch(() => false);
// SW-09. A non-cooperative fetch, digest or `cache.put` started before the
// deadline cannot be cancelled, so it may recreate the candidate cache
@@ -166,6 +207,17 @@ export async function installStaticAssets(
return outcome;
}
async function cacheExists(
caches: InstallDependencies["caches"],
cacheName: string,
): Promise<boolean> {
try {
return (await caches.keys?.())?.includes(cacheName) ?? false;
} catch {
return false;
}
}
async function installCandidate(
manifest: StaticAssetManifestV1,
cacheName: string,
@@ -247,10 +299,17 @@ async function storeAsset(
if (response.status !== 200 || response.type === "opaque") {
return rejected("STATUS_INVALID");
}
const contentType = response.headers.get("content-type") ?? "";
const contentType =
response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ??
"";
const expectedType = asset.contentType.toLowerCase();
if (
contentType.split(";", 1)[0]?.trim().toLowerCase() !==
asset.contentType.toLowerCase()
contentType !== expectedType &&
// R-6.5. Servers still send `application/javascript` for `.js`.
!(
JAVASCRIPT_MIME_TYPES.has(contentType) &&
JAVASCRIPT_MIME_TYPES.has(expectedType)
)
) {
return rejected("CONTENT_TYPE_INVALID");
}
@@ -289,6 +348,26 @@ async function storeAsset(
return null;
}
/** WHATWG MIME Sniffing: every essence that denotes a JavaScript MIME type. */
const JAVASCRIPT_MIME_TYPES: ReadonlySet<string> = new Set([
"application/ecmascript",
"application/javascript",
"application/x-ecmascript",
"application/x-javascript",
"text/ecmascript",
"text/javascript",
"text/javascript1.0",
"text/javascript1.1",
"text/javascript1.2",
"text/javascript1.3",
"text/javascript1.4",
"text/javascript1.5",
"text/jscript",
"text/livescript",
"text/x-ecmascript",
"text/x-javascript",
]);
const ABORTED = Symbol("service-worker-install-aborted");
async function abortable<Value>(
@@ -317,8 +396,12 @@ async function readBoundedBody(
| Readonly<{ ok: false; code: "BYTES_MISMATCH" | "FETCH_FAILED" }>
> {
const declaredLength = response.headers.get("content-length");
// R-6.5. With a content-encoding the declared length is the encoded size,
// while the stream yields decoded bytes. The decoded count and sha256 below
// are the real checks.
if (
declaredLength !== null &&
!response.headers.has("content-encoding") &&
/^\d+$/u.test(declaredLength) &&
Number(declaredLength) !== expectedBytes
) {
+5 -3
View File
@@ -2,9 +2,11 @@
* 최상위 storage 배럴은 Web Storage 어댑터만 내보낸다.
*
* `./indexeddb/index.ts`와 `./opfs/index.ts`를 여기서 재수출하지 말 것.
* `scripts/test-browser-file-storage-runtime-removal.ts:23-34`가 그 두 폴더만
* 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면 제거 드릴이 죽는다.
* 두 서브배럴이 각자 제거 가능한 런타임의 경계다.
* `scripts/test-browser-file-storage-runtime-removal.ts`의 `runtimePaths`는 이 두
* 폴더를 browser-file-storage 번들 전체(ports, browser-files, browser-transfer,
* cache-storage 등)와 함께 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면
* 제거 드릴이 죽는다. 드릴은 번들을 통째로만 지운다. 두 폴더 중 하나만 지우는
* 경우는 드릴이 검증하지 않는다.
*/
export {
createBrowserStorageAdapter,
@@ -1,72 +0,0 @@
import type {
BrowserDataOperation,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { browserDataFailure } from "../../browser-file-storage/result.ts";
function exceptionName(error: unknown): string {
if (
error &&
typeof error === "object" &&
"name" in error &&
typeof error.name === "string"
) {
return error.name;
}
return "";
}
/**
* Maps the closed DOMException vocabulary without exposing an exception
* object, message, key or stored value across the adapter boundary.
*/
export function mapIndexedDbException(
error: unknown,
operation: BrowserDataOperation,
): BrowserDataResult<never> {
switch (exceptionName(error)) {
case "AbortError":
return browserDataFailure("ABORTED", operation);
case "ConstraintError":
return browserDataFailure("CONFLICT", operation);
case "DataCloneError":
case "DataError":
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "READ_ONLY",
});
case "InvalidAccessError":
case "InvalidStateError":
case "NotFoundError":
case "ReadOnlyError":
case "TransactionInactiveError":
case "VersionError":
return browserDataFailure("MIGRATION_FAILED", operation, {
recovery: "READ_ONLY",
});
case "NotAllowedError":
case "SecurityError":
return browserDataFailure("PERMISSION_DENIED", operation, {
recovery: "ONLINE_ONLY",
});
case "NotReadableError":
return browserDataFailure("NOT_READABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
case "QuotaExceededError":
case "NS_ERROR_DOM_QUOTA_REACHED":
return browserDataFailure("QUOTA_EXCEEDED", operation, {
recovery: "READ_ONLY",
});
case "UnknownError":
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
default:
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
});
}
}
@@ -3,9 +3,16 @@ import {
assertValidStoragePolicy,
type BrowserStoragePolicy,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
onIndexedDbRequest,
runIndexedDbTransaction,
} from "../../platform/indexeddb-transaction.ts";
import {
INDEXEDDB_DATASET_BUDGET_KEY,
isStoredDatasetBudget,
} from "./indexeddb-records.ts";
export const INDEXEDDB_DATASET_BINDING_KEY = "dataset-binding";
export const INDEXEDDB_DATASET_BUDGET_KEY = "dataset-budget";
const OPAQUE_SCOPE_TOKEN = /^[A-Za-z0-9_-]{16,48}$/u;
@@ -216,124 +223,72 @@ export function queueIndexedDbUpgradeBinding(
/**
* Post-open verification protects non-upgrade opens and maintenance callers.
* 05-12. It runs on the kernel transaction, so settle-once, caller abort and
* the abort-after-commit rule (CP-4) are the kernel's, not a local copy's.
*/
export function verifyIndexedDbDatasetBinding(
export async function verifyIndexedDbDatasetBinding(
database: IDBDatabase,
governanceStore: string,
expected: StoredDatasetBinding,
signal?: AbortSignal,
): Promise<IndexedDbBindingVerification> {
if (signal?.aborted) {
return Promise.resolve({ ok: false, reason: "ABORTED" });
}
let transaction: IDBTransaction;
try {
transaction = database.transaction(governanceStore, "readonly");
} catch (error) {
return Promise.resolve({
ok: false,
reason: "NATIVE_ERROR",
error,
});
}
return new Promise((resolve) => {
let settled = false;
let observed: unknown;
let observedBudget: unknown;
let requestError: unknown;
let callerAborted = false;
const finish = (result: IndexedDbBindingVerification) => {
if (settled) return;
settled = true;
signal?.removeEventListener("abort", onAbort);
resolve(result);
};
function onAbort(): void {
callerAborted = true;
try {
transaction.abort();
} catch {
// Completion determines the race.
}
}
signal?.addEventListener("abort", onAbort, { once: true });
transaction.onerror = () => {
requestError ??= transaction.error;
};
transaction.onabort = () =>
finish(
callerAborted
? { ok: false, reason: "ABORTED" }
: {
ok: false,
reason: "NATIVE_ERROR",
error: requestError ?? transaction.error,
},
const outcome = await runIndexedDbTransaction<
IndexedDbBindingVerification,
BindingFailure
>({
database,
stores: [governanceStore],
mode: "readonly",
signal,
translate: (cause) =>
cause.kind === "CALLER_ABORT"
? { ok: false, reason: "ABORTED" }
: {
ok: false,
reason: "NATIVE_ERROR",
error: cause.kind === "NATIVE_EXCEPTION" ? cause.error : undefined,
},
queue: (transaction, context) => {
const store = transaction.objectStore(governanceStore);
let observed: unknown;
onIndexedDbRequest<unknown, BindingFailure>(
store.get(INDEXEDDB_DATASET_BINDING_KEY),
context,
(value) => {
observed = value;
},
);
transaction.oncomplete = () => {
if (observed === undefined) {
finish({ ok: false, reason: "MISSING" });
} else if (!isStoredDatasetBinding(observed)) {
finish({ ok: false, reason: "CORRUPT" });
} else if (!sameIndexedDbDatasetBinding(observed, expected)) {
finish({ ok: false, reason: "MISMATCH" });
} else if (
!observedBudget ||
typeof observedBudget !== "object" ||
(observedBudget as { bindingKey?: unknown }).bindingKey !==
INDEXEDDB_DATASET_BUDGET_KEY ||
(observedBudget as { budgetVersion?: unknown }).budgetVersion !==
1 ||
!Number.isSafeInteger(
(observedBudget as { usedBytes?: unknown }).usedBytes,
) ||
typeof (observedBudget as { usedBytes?: unknown }).usedBytes !==
"number" ||
(observedBudget as { usedBytes: number }).usedBytes < 0 ||
(observedBudget as { usedBytes: number }).usedBytes >
expected.storagePolicy.hardBudgetBytes
||
!Number.isSafeInteger(
(observedBudget as { receiptCount?: unknown }).receiptCount,
) ||
typeof (observedBudget as { receiptCount?: unknown })
.receiptCount !== "number" ||
(observedBudget as { receiptCount: number }).receiptCount < 0
) {
finish({ ok: false, reason: "CORRUPT" });
} else {
finish({ ok: true });
}
};
try {
const request = transaction
.objectStore(governanceStore)
.get(INDEXEDDB_DATASET_BINDING_KEY);
request.onerror = () => {
requestError ??= request.error;
};
request.onsuccess = () => {
observed = request.result;
};
const budgetRequest = transaction
.objectStore(governanceStore)
.get(INDEXEDDB_DATASET_BUDGET_KEY);
budgetRequest.onerror = () => {
requestError ??= budgetRequest.error;
};
budgetRequest.onsuccess = () => {
observedBudget = budgetRequest.result;
};
} catch (error) {
requestError = error;
try {
transaction.abort();
} catch {
finish({ ok: false, reason: "NATIVE_ERROR", error });
}
}
onIndexedDbRequest<unknown, BindingFailure>(
store.get(INDEXEDDB_DATASET_BUDGET_KEY),
context,
(budget) => {
context.succeed(bindingVerdict(observed, budget, expected));
},
);
},
});
return outcome.ok ? outcome.value : outcome.error;
}
type BindingFailure = Extract<IndexedDbBindingVerification, { ok: false }>;
function bindingVerdict(
observed: unknown,
budget: unknown,
expected: StoredDatasetBinding,
): IndexedDbBindingVerification {
if (observed === undefined) return { ok: false, reason: "MISSING" };
if (!isStoredDatasetBinding(observed)) {
return { ok: false, reason: "CORRUPT" };
}
if (!sameIndexedDbDatasetBinding(observed, expected)) {
return { ok: false, reason: "MISMATCH" };
}
if (
!isStoredDatasetBudget(budget) ||
budget.usedBytes > expected.storagePolicy.hardBudgetBytes
) {
return { ok: false, reason: "CORRUPT" };
}
return { ok: true };
}
@@ -12,6 +12,7 @@ import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import {
openIndexedDbDatabase,
@@ -24,26 +25,31 @@ import {
type IndexedDbBudget,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "./indexeddb-failure.ts";
import {
createIndexedDbDatasetBinding,
INDEXEDDB_DATASET_BUDGET_KEY,
indexedDbPhysicalDatabaseName,
verifyIndexedDbDatasetBinding,
} from "./indexeddb-governance.ts";
import {
countBucket,
failureOf,
INDEXEDDB_DATASET_BUDGET_KEY,
isPositiveInteger,
isStoredDatasetBudget,
isStoredReceipt,
isStoredRecord,
isStoredRetentionRecord,
isValidBoundaryIdentifier,
measureRecordBytes,
type StoredDatasetBudget,
type StoredRecord,
type StoredRetentionRecord,
} from "./indexeddb-records.ts";
import type {
IndexedDbCountBucket,
IndexedDbMaintenanceDependencies,
IndexedDbObservation,
} from "./indexeddb-types.ts";
type StoredRecord = Readonly<{
key: string;
codecVersion: number;
revision: number;
payload: unknown;
}>;
type StoredCheckpoint = Readonly<{
checkpointKey: string;
migrationId: string;
@@ -52,32 +58,6 @@ type StoredCheckpoint = Readonly<{
state: "MORE" | "COMPLETE";
}>;
type StoredIdempotencyReceipt = Readonly<{
idempotencyKey: string;
operation: "PUT" | "DELETE";
recordKey: string;
expectedRevision: number | null;
fingerprint: string;
synchronization: "NONE" | "PENDING" | "CONFIRMED";
revision: number;
expiresAtEpochMs: number;
}>;
type StoredRetentionRecord = Readonly<{
recordKey: string;
writtenAtEpochMs: number;
synchronization: "NONE" | "PENDING" | "CONFIRMED";
measuredBytes: number;
eligibleAtEpochMs?: number;
}>;
type StoredDatasetBudget = Readonly<{
bindingKey: typeof INDEXEDDB_DATASET_BUDGET_KEY;
budgetVersion: 1;
usedBytes: number;
receiptCount: number;
}>;
type CheckpointState = Readonly<{
persisted: StoredCheckpoint | null;
effective: Readonly<{
@@ -86,57 +66,22 @@ type CheckpointState = Readonly<{
}>;
}>;
type ScannedRecord = Readonly<{
key: string;
codecVersion: number;
revision: number;
payload: unknown;
}>;
type ScanBatch = Readonly<{
rows: readonly ScannedRecord[];
rows: readonly StoredRecord[];
reachedEnd: boolean;
budgetExhausted: boolean;
}>;
type PreparedRecord<WireValue> = Readonly<{
source: ScannedRecord;
source: StoredRecord;
needsMigration: boolean;
migratedPayload: WireValue | undefined;
measuredBytes: number | undefined;
}>;
const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
const OPAQUE_SHA256_FINGERPRINT = /^[a-f0-9]{64}$/u;
const MAX_BATCH_ROWS = 500;
const MAX_BATCH_DURATION_MS = 30_000;
const RECORD_ENVELOPE_RESERVATION_BYTES = 512;
const MAX_MEASURED_RECORD_BYTES = 2_147_483_647;
function isPositiveInteger(value: unknown): value is number {
return (
typeof value === "number" &&
Number.isSafeInteger(value) &&
value >= 1
);
}
function isStoredRecord(
value: unknown,
expectedKey?: string,
): value is StoredRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRecord>;
return (
typeof record.key === "string" &&
record.key.length > 0 &&
record.key.length <= 200 &&
(expectedKey === undefined || record.key === expectedKey) &&
isPositiveInteger(record.codecVersion) &&
isPositiveInteger(record.revision) &&
Object.hasOwn(record, "payload")
);
}
function isStoredCheckpoint(
value: unknown,
@@ -150,84 +95,12 @@ function isStoredCheckpoint(
SAFE_IDENTIFIER.test(checkpoint.migrationId) &&
isPositiveInteger(checkpoint.targetCodecVersion) &&
(checkpoint.lastKey === null ||
(typeof checkpoint.lastKey === "string" &&
checkpoint.lastKey.length > 0 &&
checkpoint.lastKey.length <= 200)) &&
isValidBoundaryIdentifier(checkpoint.lastKey)) &&
(checkpoint.state === "MORE" ||
checkpoint.state === "COMPLETE")
);
}
function isStoredReceipt(
value: unknown,
): value is StoredIdempotencyReceipt {
if (!value || typeof value !== "object") return false;
const receipt = value as Partial<StoredIdempotencyReceipt>;
return (
typeof receipt.idempotencyKey === "string" &&
receipt.idempotencyKey.length > 0 &&
receipt.idempotencyKey.length <= 200 &&
(receipt.operation === "PUT" ||
receipt.operation === "DELETE") &&
typeof receipt.recordKey === "string" &&
receipt.recordKey.length > 0 &&
receipt.recordKey.length <= 200 &&
(receipt.expectedRevision === null ||
isPositiveInteger(receipt.expectedRevision)) &&
typeof receipt.fingerprint === "string" &&
OPAQUE_SHA256_FINGERPRINT.test(receipt.fingerprint) &&
(receipt.synchronization === "NONE" ||
receipt.synchronization === "PENDING" ||
receipt.synchronization === "CONFIRMED") &&
isPositiveInteger(receipt.revision) &&
typeof receipt.expiresAtEpochMs === "number" &&
Number.isSafeInteger(receipt.expiresAtEpochMs) &&
receipt.expiresAtEpochMs >= 0
);
}
function isStoredRetentionRecord(
value: unknown,
expectedKey: string,
): value is StoredRetentionRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRetentionRecord>;
return (
record.recordKey === expectedKey &&
typeof record.writtenAtEpochMs === "number" &&
Number.isSafeInteger(record.writtenAtEpochMs) &&
record.writtenAtEpochMs >= 0 &&
(record.synchronization === "NONE" ||
record.synchronization === "PENDING" ||
record.synchronization === "CONFIRMED") &&
typeof record.measuredBytes === "number" &&
Number.isSafeInteger(record.measuredBytes) &&
record.measuredBytes >= 1 &&
record.measuredBytes <= MAX_MEASURED_RECORD_BYTES &&
(record.eligibleAtEpochMs === undefined ||
(typeof record.eligibleAtEpochMs === "number" &&
Number.isSafeInteger(record.eligibleAtEpochMs) &&
record.eligibleAtEpochMs >= record.writtenAtEpochMs))
);
}
function isStoredDatasetBudget(
value: unknown,
): value is StoredDatasetBudget {
if (!value || typeof value !== "object") return false;
const budget = value as Partial<StoredDatasetBudget>;
return (
budget.bindingKey === INDEXEDDB_DATASET_BUDGET_KEY &&
budget.budgetVersion === 1 &&
typeof budget.usedBytes === "number" &&
Number.isSafeInteger(budget.usedBytes) &&
budget.usedBytes >= 0 &&
typeof budget.receiptCount === "number" &&
Number.isSafeInteger(budget.receiptCount) &&
budget.receiptCount >= 0
);
}
function sameCheckpoint(
left: StoredCheckpoint | null,
right: StoredCheckpoint | null,
@@ -242,14 +115,6 @@ function sameCheckpoint(
);
}
function countBucket(count: number): IndexedDbCountBucket {
if (count <= 0) return "0";
if (count === 1) return "1";
if (count <= 10) return "2-10";
if (count <= 100) return "11-100";
return "101+";
}
function invalidInput(): BrowserDataResult<never> {
return browserDataFailure("INVALID_INPUT", "INDEXEDDB_MIGRATE");
}
@@ -273,19 +138,6 @@ function unsupported(): BrowserDataResult<never> {
});
}
/**
* `browserDataFailure` and `mapIndexedDbException` build a `Result`, while the
* kernel's `translate` and `context.fail` want the failure on its own. Both
* only ever build the failure arm, so the branch below is a narrowing rather
* than a claim.
*/
function failureOf(result: BrowserDataResult<never>): BrowserDataFailure {
if (result.ok) {
throw new TypeError("A browser data failure was expected.");
}
return result.error;
}
function invalidInputFailure(): BrowserDataFailure {
return failureOf(invalidInput());
}
@@ -294,6 +146,14 @@ function migrationFailure(): BrowserDataFailure {
return failureOf(migrationFailed());
}
function corruptFailure(): BrowserDataFailure {
return failureOf(
browserDataFailure("CORRUPT_DATA", "INDEXEDDB_MIGRATE", {
recovery: "READ_ONLY",
}),
);
}
function unsupportedFailure(): BrowserDataFailure {
return failureOf(unsupported());
}
@@ -462,10 +322,9 @@ export function createIndexedDbMaintenance<WireValue>(
}
/**
* STO-06. Maintenance keeps `mapIndexedDbException`, which the runtime and
* the OPFS journal share, rather than the checkpoint store's own table: the
* same native error is a different answer in the two families, and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-06. Maintenance uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that the runtime and the OPFS journal
* share (05-11).
*
* One translator covers the whole adapter because the operation label is the
* constant `INDEXEDDB_MIGRATE` here — the runtime needs one per operation.
@@ -705,7 +564,7 @@ export function createIndexedDbMaintenance<WireValue>(
return;
}
const rows: ScannedRecord[] = [];
const rows: StoredRecord[] = [];
// The scan bounds on rows it read, so the counter the kernel offers is
// the right one here. The time check comes first so a batch that ran
// out of both answers `budgetExhausted` the way it does today.
@@ -830,28 +689,10 @@ export function createIndexedDbMaintenance<WireValue>(
} catch {
return migrationFailed();
}
let measuredPayloadBytes: number;
try {
measuredPayloadBytes =
dependencies.migrationPolicy.measureStoredBytes(
migratedPayload,
);
} catch {
return migrationFailed();
}
const measuredBytes =
measuredPayloadBytes +
RECORD_ENVELOPE_RESERVATION_BYTES +
source.key.length * 2;
if (
!Number.isSafeInteger(measuredPayloadBytes) ||
measuredPayloadBytes < 0 ||
!Number.isSafeInteger(measuredBytes) ||
measuredBytes < 1 ||
measuredBytes > MAX_MEASURED_RECORD_BYTES
) {
return migrationFailed();
}
const measuredBytes = measureRecordBytes(source.key, () =>
dependencies.migrationPolicy.measureStoredBytes(migratedPayload),
);
if (measuredBytes === null) return migrationFailed();
const afterMigration = clock();
if (!afterMigration.ok) return afterMigration;
if (afterMigration.value >= deadline) {
@@ -1290,6 +1131,11 @@ export function createIndexedDbMaintenance<WireValue>(
const opened = await openExactVersion(input.signal);
if (!opened.ok) return observeResult(opened);
const database = opened.value;
// 05-05. A corrupt receipt is left in place and counted, not a stop: one
// bad row used to end every later prune, so receipts piled up until every
// write failed with LIMIT_EXCEEDED. A receipt count already at zero stays
// there. Both are reported as one CORRUPT_DATA observation.
let corruptRows = 0;
try {
const pruned = await runTransaction<
@@ -1354,8 +1200,8 @@ export function createIndexedDbMaintenance<WireValue>(
String(cursor.primaryKey) ||
cursor.value.expiresAtEpochMs > cutoff.value
) {
context.fail(migrationFailure());
return { kind: "SUSPEND" };
corruptRows += 1;
return { kind: "CONTINUE" };
}
let deleteRequest: IDBRequest<undefined>;
try {
@@ -1373,11 +1219,14 @@ export function createIndexedDbMaintenance<WireValue>(
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.receiptCount < 1
) {
context.fail(migrationFailure());
if (!isStoredDatasetBudget(budgetRequest.result)) {
context.fail(corruptFailure());
return;
}
if (budgetRequest.result.receiptCount < 1) {
corruptRows += 1;
deletedRows += 1;
resume({ kind: "CONTINUE" });
return;
}
const budgetWrite = governance.put({
@@ -1414,6 +1263,15 @@ export function createIndexedDbMaintenance<WireValue>(
});
},
);
if (corruptRows > 0) {
observe({
operation: "INDEXEDDB_MIGRATE",
outcome: "FAILED",
schemaVersion: dependencies.schemaVersion,
countBucket: countBucket(corruptRows),
failureCode: "CORRUPT_DATA",
});
}
return observeResult(
pruned,
pruned.ok ? pruned.value.deletedRows : 0,
@@ -0,0 +1,188 @@
import type { IndexedDbSynchronizationState } from "../../../application/ports/browser-file-storage/indexeddb-port.ts";
import type {
BrowserDataFailure,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import type { IndexedDbCountBucket } from "./indexeddb-types.ts";
/**
* Q-6.5-7. The one definition of the rows the runtime and maintenance store:
* their shapes, their validators and how a record is charged against the
* dataset budget. Each call site used to carry its own copy, so a field added
* to one copy made the other judge a healthy row corrupt.
*/
export const INDEXEDDB_DATASET_BUDGET_KEY = "dataset-budget";
export const OPAQUE_SHA256_FINGERPRINT = /^[a-f0-9]{64}$/u;
const RECORD_ENVELOPE_RESERVATION_BYTES = 512;
const MAX_MEASURED_RECORD_BYTES = 2_147_483_647;
type StoredSynchronization = IndexedDbSynchronizationState | "NONE";
export type StoredRecord = Readonly<{
key: string;
codecVersion: number;
revision: number;
payload: unknown;
}>;
export type StoredIdempotencyReceipt = Readonly<{
idempotencyKey: string;
operation: "PUT" | "DELETE";
recordKey: string;
expectedRevision: number | null;
fingerprint: string;
synchronization: StoredSynchronization;
revision: number;
expiresAtEpochMs: number;
}>;
export type StoredRetentionRecord = Readonly<{
recordKey: string;
writtenAtEpochMs: number;
synchronization: StoredSynchronization;
measuredBytes: number;
eligibleAtEpochMs?: number;
}>;
export type StoredDatasetBudget = Readonly<{
bindingKey: typeof INDEXEDDB_DATASET_BUDGET_KEY;
budgetVersion: 1;
usedBytes: number;
receiptCount: number;
}>;
export function isPositiveInteger(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
}
export function isValidBoundaryIdentifier(value: unknown): value is string {
return typeof value === "string" && value.length > 0 && value.length <= 200;
}
function isNonNegativeInteger(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
}
function isStoredSynchronization(value: unknown): boolean {
return value === "NONE" || value === "PENDING" || value === "CONFIRMED";
}
export function isStoredRecord(
value: unknown,
expectedKey?: string,
): value is StoredRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRecord>;
return (
isValidBoundaryIdentifier(record.key) &&
(expectedKey === undefined || record.key === expectedKey) &&
isPositiveInteger(record.codecVersion) &&
isPositiveInteger(record.revision) &&
Object.hasOwn(record, "payload")
);
}
export function isStoredReceipt(
value: unknown,
): value is StoredIdempotencyReceipt {
if (!value || typeof value !== "object") return false;
const receipt = value as Partial<StoredIdempotencyReceipt>;
return (
isValidBoundaryIdentifier(receipt.idempotencyKey) &&
(receipt.operation === "PUT" || receipt.operation === "DELETE") &&
isValidBoundaryIdentifier(receipt.recordKey) &&
(receipt.expectedRevision === null ||
isPositiveInteger(receipt.expectedRevision)) &&
typeof receipt.fingerprint === "string" &&
OPAQUE_SHA256_FINGERPRINT.test(receipt.fingerprint) &&
isStoredSynchronization(receipt.synchronization) &&
isPositiveInteger(receipt.revision) &&
isNonNegativeInteger(receipt.expiresAtEpochMs)
);
}
export function isStoredRetentionRecord(
value: unknown,
expectedKey?: string,
): value is StoredRetentionRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRetentionRecord>;
return (
isValidBoundaryIdentifier(record.recordKey) &&
(expectedKey === undefined || record.recordKey === expectedKey) &&
isNonNegativeInteger(record.writtenAtEpochMs) &&
isStoredSynchronization(record.synchronization) &&
isPositiveInteger(record.measuredBytes) &&
record.measuredBytes <= MAX_MEASURED_RECORD_BYTES &&
(record.eligibleAtEpochMs === undefined ||
(Number.isSafeInteger(record.eligibleAtEpochMs) &&
record.eligibleAtEpochMs >= record.writtenAtEpochMs))
);
}
/**
* A budget row's own shape. The dataset binding check additionally bounds
* `usedBytes` by the policy's `hardBudgetBytes`; transactions check the bytes
* they are about to add instead.
*/
export function isStoredDatasetBudget(
value: unknown,
): value is StoredDatasetBudget {
if (!value || typeof value !== "object") return false;
const budget = value as Partial<StoredDatasetBudget>;
return (
budget.bindingKey === INDEXEDDB_DATASET_BUDGET_KEY &&
budget.budgetVersion === 1 &&
isNonNegativeInteger(budget.usedBytes) &&
isNonNegativeInteger(budget.receiptCount)
);
}
/**
* The bytes a record is charged: the codec's payload size, a fixed envelope
* reservation and the key as UTF-16. `null` when the codec throws or the size
* is out of range; each caller maps that to its own failure code.
*/
export function measureRecordBytes(
key: string,
measurePayload: () => number,
): number | null {
let payloadBytes: number;
try {
payloadBytes = measurePayload();
} catch {
return null;
}
const measuredBytes =
payloadBytes + RECORD_ENVELOPE_RESERVATION_BYTES + key.length * 2;
return isNonNegativeInteger(payloadBytes) &&
isPositiveInteger(measuredBytes) &&
measuredBytes <= MAX_MEASURED_RECORD_BYTES
? measuredBytes
: null;
}
export function countBucket(count: number): IndexedDbCountBucket {
if (count <= 0) return "0";
if (count === 1) return "1";
if (count <= 10) return "2-10";
if (count <= 100) return "11-100";
return "101+";
}
/**
* `browserDataFailure` and `mapIndexedDbException` build a `Result`, while the
* kernel's `translate` and `context.fail` want the failure on its own. Both
* only ever build the failure arm, so the branch below is a narrowing rather
* than a claim.
*/
export function failureOf(
result: BrowserDataResult<never>,
): BrowserDataFailure {
if (result.ok) {
throw new TypeError("A browser data failure was expected.");
}
return result.error;
}
@@ -20,10 +20,12 @@ import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import { snapshotAbortTimers } from "../../platform/abortable-operation.ts";
import {
createIndexedDbConnection,
deleteIndexedDbDatabase,
openIndexedDbDatabase,
type IndexedDbTranslate,
} from "../../platform/indexeddb-connection.ts";
@@ -35,10 +37,8 @@ import {
type IndexedDbCursorVisit,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "./indexeddb-failure.ts";
import {
createIndexedDbDatasetBinding,
INDEXEDDB_DATASET_BUDGET_KEY,
indexedDbPhysicalDatabaseName,
queueIndexedDbUpgradeBinding,
verifyIndexedDbDatasetBinding,
@@ -48,47 +48,30 @@ import {
assertIndexedDbRuntimeStores,
validateIndexedDbMigrations,
} from "./indexeddb-migrations.ts";
import {
countBucket,
failureOf,
INDEXEDDB_DATASET_BUDGET_KEY,
isPositiveInteger,
isStoredDatasetBudget,
isStoredReceipt,
isStoredRecord,
isStoredRetentionRecord,
isValidBoundaryIdentifier,
measureRecordBytes,
OPAQUE_SHA256_FINGERPRINT,
type StoredDatasetBudget,
type StoredIdempotencyReceipt,
type StoredRecord,
type StoredRetentionRecord,
} from "./indexeddb-records.ts";
import type {
IndexedDbCountBucket,
IndexedDbKeyRangePlan,
IndexedDbObservation,
IndexedDbQueryPlan,
IndexedDbRuntimeDependencies,
} from "./indexeddb-types.ts";
type StoredRecord = Readonly<{
key: string;
codecVersion: number;
revision: number;
payload: unknown;
}>;
type StoredIdempotencyReceipt = Readonly<{
idempotencyKey: string;
operation: "PUT" | "DELETE";
recordKey: string;
expectedRevision: number | null;
fingerprint: string;
synchronization: IndexedDbSynchronizationState | "NONE";
revision: number;
expiresAtEpochMs: number;
}>;
type StoredRetentionRecord = Readonly<{
recordKey: string;
writtenAtEpochMs: number;
synchronization: IndexedDbSynchronizationState | "NONE";
measuredBytes: number;
eligibleAtEpochMs?: number;
}>;
type StoredDatasetBudget = Readonly<{
bindingKey: typeof INDEXEDDB_DATASET_BUDGET_KEY;
budgetVersion: 1;
usedBytes: number;
receiptCount: number;
}>;
type ReceiptLookup =
| Readonly<{ kind: "MISSING" | "EXPIRED" }>
| Readonly<{
@@ -102,7 +85,6 @@ type TransactionContext<Value> = IndexedDbTransactionContext<
>;
const SAFE_DATABASE_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;
const OPAQUE_SHA256_FINGERPRINT = /^[a-f0-9]{64}$/u;
const DELETE_OPERATION_FINGERPRINT =
"65daeb378bdec35d90224389f6e10917bcc0b94c90c489014ba156dd6cbf9350";
const MAX_QUERY_LIMIT = 1_000;
@@ -113,31 +95,9 @@ const MAX_RECEIPT_RETENTION_MS = 31 * 24 * 60 * 60 * 1_000;
const MAX_LIFECYCLE_ROWS = 500;
const MAX_LIFECYCLE_DURATION_MS = 30_000;
const OPAQUE_AUTHORITY_PROOF = /^[A-Za-z0-9_-]{16,128}$/u;
const RECORD_ENVELOPE_RESERVATION_BYTES = 512;
const MAX_MEASURED_RECORD_BYTES = 2_147_483_647;
const MAX_QUERY_SCANNED_ROWS = 5_000;
const MAX_IDEMPOTENCY_RECEIPTS = 1_000_000;
function countBucket(count: number): IndexedDbCountBucket {
if (count <= 0) return "0";
if (count === 1) return "1";
if (count <= 10) return "2-10";
if (count <= 100) return "11-100";
return "101+";
}
function isValidBoundaryIdentifier(value: string): boolean {
return (
typeof value === "string" &&
value.length > 0 &&
value.length <= 200
);
}
function isRevision(value: unknown): value is number {
return Number.isSafeInteger(value) && typeof value === "number" && value >= 1;
}
function isBoundedCursorKey(value: unknown): value is IDBValidKey {
const pending: Array<Readonly<{ value: unknown; depth: number }>> = [
{ value, depth: 0 },
@@ -222,86 +182,6 @@ function isBoundedRangePlan(
}
}
function isStoredRecord(value: unknown, expectedKey?: string): value is StoredRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRecord>;
return (
typeof record.key === "string" &&
isValidBoundaryIdentifier(record.key) &&
(expectedKey === undefined || record.key === expectedKey) &&
isRevision(record.codecVersion) &&
isRevision(record.revision) &&
Object.hasOwn(record, "payload")
);
}
function isStoredReceipt(value: unknown): value is StoredIdempotencyReceipt {
if (!value || typeof value !== "object") return false;
const receipt = value as Partial<StoredIdempotencyReceipt>;
return (
typeof receipt.idempotencyKey === "string" &&
isValidBoundaryIdentifier(receipt.idempotencyKey) &&
(receipt.operation === "PUT" || receipt.operation === "DELETE") &&
typeof receipt.recordKey === "string" &&
isValidBoundaryIdentifier(receipt.recordKey) &&
(receipt.expectedRevision === null ||
isRevision(receipt.expectedRevision)) &&
typeof receipt.fingerprint === "string" &&
OPAQUE_SHA256_FINGERPRINT.test(receipt.fingerprint) &&
(receipt.synchronization === "NONE" ||
receipt.synchronization === "PENDING" ||
receipt.synchronization === "CONFIRMED") &&
isRevision(receipt.revision) &&
typeof receipt.expiresAtEpochMs === "number" &&
Number.isSafeInteger(receipt.expiresAtEpochMs) &&
receipt.expiresAtEpochMs >= 0
);
}
function isStoredRetentionRecord(
value: unknown,
expectedKey?: string,
): value is StoredRetentionRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<StoredRetentionRecord>;
return (
typeof record.recordKey === "string" &&
isValidBoundaryIdentifier(record.recordKey) &&
(expectedKey === undefined || record.recordKey === expectedKey) &&
typeof record.writtenAtEpochMs === "number" &&
Number.isSafeInteger(record.writtenAtEpochMs) &&
record.writtenAtEpochMs >= 0 &&
(record.synchronization === "NONE" ||
record.synchronization === "PENDING" ||
record.synchronization === "CONFIRMED") &&
typeof record.measuredBytes === "number" &&
Number.isSafeInteger(record.measuredBytes) &&
record.measuredBytes >= 1 &&
record.measuredBytes <= MAX_MEASURED_RECORD_BYTES &&
(record.eligibleAtEpochMs === undefined ||
(typeof record.eligibleAtEpochMs === "number" &&
Number.isSafeInteger(record.eligibleAtEpochMs) &&
record.eligibleAtEpochMs >= record.writtenAtEpochMs))
);
}
function isStoredDatasetBudget(
value: unknown,
): value is StoredDatasetBudget {
if (!value || typeof value !== "object") return false;
const budget = value as Partial<StoredDatasetBudget>;
return (
budget.bindingKey === INDEXEDDB_DATASET_BUDGET_KEY &&
budget.budgetVersion === 1 &&
typeof budget.usedBytes === "number" &&
Number.isSafeInteger(budget.usedBytes) &&
budget.usedBytes >= 0 &&
typeof budget.receiptCount === "number" &&
Number.isSafeInteger(budget.receiptCount) &&
budget.receiptCount >= 0
);
}
function normalizeCursorKey(value: IDBValidKey): IndexedDbCursorKey {
if (Array.isArray(value)) {
return Object.freeze(value.map((entry) => normalizeCursorKey(entry)));
@@ -405,16 +285,12 @@ function unavailable(
});
}
/**
* The kernel's `translate` and `context.fail` take the failure on its own while
* every helper above builds a whole `Result`. All of them only ever build the
* failure arm, so the branch below is a narrowing rather than a claim.
*/
function failureOf(result: BrowserDataResult<never>): BrowserDataFailure {
if (result.ok) {
throw new TypeError("A browser data failure was expected.");
}
return result.error;
function incompatible(
operation: BrowserDataOperation,
): BrowserDataResult<never> {
return browserDataFailure("UNSUPPORTED", operation, {
recovery: "ONLINE_ONLY",
});
}
function mappedFailure(
@@ -683,10 +559,9 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
}
/**
* STO-06. The runtime keeps `mapIndexedDbException`, which maintenance and
* the OPFS journal share, rather than the checkpoint store's own table: the
* same native error is a different answer in the two families, and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-06. The runtime uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that maintenance and the OPFS journal
* share (05-11).
*
* A translator per operation, because a read, a write and an open carry
* different labels. `CLOSED` is mapped explicitly: closing the handle while
@@ -775,6 +650,7 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
// so the migration count and the binding verdict belong to the attempt.
let appliedMigrations = 0;
let policyBindingRejected = false;
let futureSchema = false;
updateStatus({
kind: "OPENING",
targetVersion: dependencies.schemaVersion,
@@ -783,7 +659,20 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
factory,
databaseName,
version: dependencies.schemaVersion,
translate: translateFor(operation),
translate: (cause) => {
// 05-06. A VersionError on open means a newer release already
// upgraded this database. That is not a failed migration: this
// bundle can only work online until it is reloaded.
if (
cause.kind === "NATIVE_EXCEPTION" &&
(cause.error as { name?: unknown } | null)?.name ===
"VersionError"
) {
futureSchema = true;
return failureOf(incompatible(operation));
}
return translateFor(operation)(cause);
},
signal,
blockedTimeoutMs,
timers,
@@ -876,7 +765,14 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
: opened;
if (disposed) return result;
if (!result.ok) {
updateStatus({ kind: "CLOSED", reason: "NOT_OPENED" });
updateStatus(
futureSchema
? {
kind: "INCOMPATIBLE",
schemaVersion: dependencies.schemaVersion,
}
: { kind: "CLOSED", reason: "NOT_OPENED" },
);
// A failed migration is observed against INDEXEDDB_MIGRATE as well
// as against the open the caller asked for.
if (result.error.operation === "INDEXEDDB_MIGRATE") {
@@ -966,6 +862,9 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
const cancelled = abortedResult(signal, operation);
if (cancelled) return Promise.resolve(cancelled);
const db = connection.current();
if (!db && !disposed && status.kind === "INCOMPATIBLE") {
return Promise.resolve(incompatible(operation));
}
if (!db || disposed) return Promise.resolve(unavailable(operation));
return runIndexedDbTransaction<ResultValue, BrowserDataFailure>({
@@ -1475,7 +1374,7 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
!isValidBoundaryIdentifier(input.key) ||
!isValidBoundaryIdentifier(input.idempotencyKey) ||
(input.expectedRevision !== null &&
!isRevision(input.expectedRevision)) ||
!isPositiveInteger(input.expectedRevision)) ||
(storagePolicySnapshot.retention.kind === "UNTIL_SYNCED"
? input.synchronization !== "PENDING" &&
input.synchronization !== "CONFIRMED"
@@ -1499,26 +1398,10 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
} catch (error) {
return mapIndexedDbException(error, operation);
}
let measuredPayloadBytes: number;
try {
measuredPayloadBytes =
dependencies.codec.measureStoredBytes(wireValue);
} catch {
return invalidInput(operation);
}
const measuredBytes =
measuredPayloadBytes +
RECORD_ENVELOPE_RESERVATION_BYTES +
input.key.length * 2;
if (
!Number.isSafeInteger(measuredPayloadBytes) ||
measuredPayloadBytes < 0 ||
!Number.isSafeInteger(measuredBytes) ||
measuredBytes < 1 ||
measuredBytes > MAX_MEASURED_RECORD_BYTES
) {
return invalidInput(operation);
}
const measuredBytes = measureRecordBytes(input.key, () =>
dependencies.codec.measureStoredBytes(wireValue),
);
if (measuredBytes === null) return invalidInput(operation);
const cancelled = abortedResult(input.signal, operation);
if (cancelled) return cancelled;
@@ -1887,7 +1770,7 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
if (
!isValidBoundaryIdentifier(sourceInput.key) ||
!isValidBoundaryIdentifier(sourceInput.idempotencyKey) ||
!isRevision(sourceInput.expectedRevision)
!isPositiveInteger(sourceInput.expectedRevision)
) {
return observeResult(operation, invalidInput(operation));
}
@@ -2193,12 +2076,21 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
return browserDataSuccess(undefined);
}
function purgeEligibleRecords(
/**
* 05-05. Like the partition purge (R-5.4), the sweep never stops on a row it
* cannot read: failing closed left every later expired row on the device and
* failed the next sweep the same way. A corrupt sidecar is left in place,
* counted and reported as one CORRUPT_DATA observation per batch. A budget
* that cannot account for a deleted row's bytes is left as it is: it can
* only read high, which blocks writes and never admits one.
*/
async function purgeEligibleRecords(
input: IndexedDbLifecycleBatchInput,
deadline: number,
cutoffEpochMs: number,
): Promise<BrowserDataResult<IndexedDbLifecycleBatchReceipt>> {
return runTransaction(
let corruptRows = 0;
const result = await runTransaction<IndexedDbLifecycleBatchReceipt>(
[
dependencies.recordStore,
dependencies.governanceStore,
@@ -2289,11 +2181,9 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
"UNTIL_SYNCED" &&
cursor.value.synchronization !== "CONFIRMED")
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
// `fail` aborts, so the pump has nowhere to go. Suspending
// without ever resuming says that without claiming a summary
// the sweep never reached.
return { kind: "SUSPEND" };
scannedRows += 1;
corruptRows += 1;
return { kind: "CONTINUE" };
}
scannedRows += 1;
const measuredBytes = cursor.value.measuredBytes;
@@ -2325,13 +2215,16 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.usedBytes < measuredBytes
) {
if (!isStoredDatasetBudget(budgetRequest.result)) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
if (budgetRequest.result.usedBytes < measuredBytes) {
corruptRows += 1;
deletedRows += 1;
resume({ kind: "CONTINUE" });
return;
}
const storedBudgetRequest = governance.put({
bindingKey: INDEXEDDB_DATASET_BUDGET_KEY,
budgetVersion: 1,
@@ -2364,13 +2257,33 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
});
},
);
if (corruptRows > 0) {
observe({
operation: "INDEXEDDB_WRITE",
outcome: "FAILED",
schemaVersion: dependencies.schemaVersion,
countBucket: countBucket(corruptRows),
failureCode: "CORRUPT_DATA",
});
}
return result;
}
function purgePartitionRecords(
/**
* R-5.4. A partition purge (session end, logout, account deletion) exists to
* remove everything, so it deletes by key and never stops on a row it cannot
* read: failing closed here left personal data on the device for good. Rows
* that fail validation are counted and reported as one CORRUPT_DATA
* observation per batch. Per-row budget arithmetic is dropped too; the
* budget is reset to zero in the transaction that finds every store empty.
* Between batches it can only read high, which blocks writes, never admits.
*/
async function purgePartitionRecords(
input: IndexedDbLifecycleBatchInput,
deadline: number,
): Promise<BrowserDataResult<IndexedDbLifecycleBatchReceipt>> {
return runTransaction(
let corruptRows = 0;
const result = await runTransaction<IndexedDbLifecycleBatchReceipt>(
[
dependencies.recordStore,
dependencies.governanceStore,
@@ -2486,47 +2399,30 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
receipts.openCursor(),
({ cursor, resume }) => {
if (!isStoredReceipt(cursor.value)) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
// `fail` aborts, so the pump has nowhere to go.
return { kind: "SUSPEND" };
}
scannedRows += 1;
if (!isStoredReceipt(cursor.value)) corruptRows += 1;
const deletion = receipts.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.receiptCount < 1
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const storedBudgetRequest = governance.put({
...budgetRequest.result,
receiptCount:
budgetRequest.result.receiptCount - 1,
} satisfies StoredDatasetBudget);
storedBudgetRequest.onerror = () =>
context.requestFailed(
storedBudgetRequest.error,
);
storedBudgetRequest.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
return { kind: "SUSPEND" };
},
() => succeed("COMPLETE", false),
() => {
// Every store above is empty in this same transaction, so zero
// is exact, and a budget row that had drifted is healed.
const budgetReset = governance.put({
bindingKey: INDEXEDDB_DATASET_BUDGET_KEY,
budgetVersion: 1,
usedBytes: 0,
receiptCount: 0,
} satisfies StoredDatasetBudget);
budgetReset.onerror = () =>
context.requestFailed(budgetReset.error);
budgetReset.onsuccess = () => succeed("COMPLETE", false);
},
);
};
@@ -2534,46 +2430,21 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
retention.openCursor(),
({ cursor, resume }) => {
scannedRows += 1;
if (
!isStoredRetentionRecord(
cursor.value,
String(cursor.primaryKey),
)
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return { kind: "SUSPEND" };
corruptRows += 1;
}
scannedRows += 1;
const measuredBytes = cursor.value.measuredBytes;
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.usedBytes < measuredBytes
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const deletion = retention.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
const budgetWrite = governance.put({
...budgetRequest.result,
usedBytes:
budgetRequest.result.usedBytes - measuredBytes,
} satisfies StoredDatasetBudget);
budgetWrite.onerror = () =>
context.requestFailed(budgetWrite.error);
budgetWrite.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
const deletion = retention.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
return { kind: "SUSPEND" };
},
@@ -2584,66 +2455,32 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
records.openCursor(),
({ cursor, resume }) => {
if (!isStoredRecord(cursor.value)) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return { kind: "SUSPEND" };
}
scannedRows += 1;
const key = cursor.value.key;
const key = cursor.primaryKey;
const recordCorrupt = !isStoredRecord(cursor.value);
const sidecarRequest = retention.get(key);
sidecarRequest.onerror = () =>
context.requestFailed(sidecarRequest.error);
sidecarRequest.onsuccess = () => {
if (
recordCorrupt ||
!isStoredRetentionRecord(
sidecarRequest.result,
key,
String(key),
)
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
corruptRows += 1;
}
const measuredBytes =
sidecarRequest.result.measuredBytes;
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.usedBytes < measuredBytes
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const recordDelete = records.delete(key);
recordDelete.onerror = () =>
context.requestFailed(recordDelete.error);
recordDelete.onsuccess = () => {
const sidecarDelete = retention.delete(key);
sidecarDelete.onerror = () =>
context.requestFailed(sidecarDelete.error);
sidecarDelete.onsuccess = () => {
const storedBudgetRequest = governance.put({
bindingKey: INDEXEDDB_DATASET_BUDGET_KEY,
budgetVersion: 1,
usedBytes:
budgetRequest.result.usedBytes -
measuredBytes,
receiptCount:
budgetRequest.result.receiptCount,
} satisfies StoredDatasetBudget);
storedBudgetRequest.onerror = () =>
context.requestFailed(
storedBudgetRequest.error,
);
storedBudgetRequest.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
const recordDelete = records.delete(key);
recordDelete.onerror = () =>
context.requestFailed(recordDelete.error);
recordDelete.onsuccess = () => {
const sidecarDelete = retention.delete(key);
sidecarDelete.onerror = () =>
context.requestFailed(sidecarDelete.error);
sidecarDelete.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
};
@@ -2653,6 +2490,16 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
);
},
);
if (corruptRows > 0) {
observe({
operation: "INDEXEDDB_WRITE",
outcome: "FAILED",
schemaVersion: dependencies.schemaVersion,
countBucket: countBucket(corruptRows),
failureCode: "CORRUPT_DATA",
});
}
return result;
}
async function enforceLifecycleBatch(
@@ -2705,7 +2552,9 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
cutoffEpochMs,
);
} else {
result = await purgePartitionRecords(input, deadline);
result =
(await deleteUnadmittedDataset(input.signal)) ??
(await purgePartitionRecords(input, deadline));
}
return observeResult(
operation,
@@ -2714,6 +2563,54 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
);
}
/**
* 05-03. A LOGOUT or ACCOUNT_DELETION purge must not depend on the dataset
* passing admission: a corrupt governance row rejects every open, so no row
* could ever be purged one by one. The authority has already approved this
* purge, and the database name comes from this partition's own tokens, so
* deleting the whole database touches no other partition. Returns `null`
* when a connection is ready for the row-by-row purge.
*/
async function deleteUnadmittedDataset(
signal: AbortSignal | undefined,
): Promise<BrowserDataResult<IndexedDbLifecycleBatchReceipt> | null> {
if (connection.current()) return null;
const opened = await open(signal);
if (opened.ok) return null;
if (
(opened.error.code !== "POLICY_REJECTED" &&
opened.error.code !== "CORRUPT_DATA") ||
disposed ||
typeof factory?.deleteDatabase !== "function"
) {
return opened;
}
const deleted = await deleteIndexedDbDatabase<BrowserDataFailure>({
factory,
databaseName,
translate: translateFor("INDEXEDDB_WRITE"),
blockedTimeoutMs,
timers,
});
if (!deleted.ok) return deleted;
if (deleted.value.kind === "BLOCKED_DEADLINE") {
// The request is still live and may yet land; the next call finds out.
return browserDataFailure("BLOCKED", "INDEXEDDB_WRITE", {
retryable: true,
recovery: "RELOAD_OTHER_CONTEXTS",
});
}
return browserDataSuccess(
Object.freeze({
state: "COMPLETE" as const,
scannedRows: 0,
deletedRows: 0,
budgetExhausted: false,
datasetDeleted: true as const,
}),
);
}
function close(): void {
if (disposed) return;
disposed = true;
@@ -1,7 +1,5 @@
import type {
BeginOpfsJournalTransaction,
OpfsCommittedObjectPage,
OpfsJournalPage,
OpfsJournalPort,
OpfsJournalTransaction,
OpfsPreparedObject,
@@ -16,7 +14,7 @@ import {
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import { snapshotAbortTimers } from "../../platform/abortable-operation.ts";
import {
@@ -31,8 +29,8 @@ import {
type IndexedDbRequestSink,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "../indexeddb/indexeddb-failure.ts";
import { isValidOpfsStorageScope } from "./opfs-policy.ts";
import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts";
export type IndexedDbOpfsJournalDependencies = Readonly<{
authorityToken: string;
@@ -1607,140 +1605,6 @@ function isChunkReference(
);
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function isPreparedObject(value: unknown): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!SAFE_BOUNDARY_ID.test(descriptor.objectId) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(descriptor.scope as OpfsStorageScope) ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
typeof descriptor.mediaType !== "string" ||
descriptor.mediaType.length < 1 ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
typeof integrity.chunkSizeBytes !== "number" ||
!Number.isSafeInteger(integrity.chunkSizeBytes) ||
integrity.chunkSizeBytes < 1 ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object"
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
if (
(descriptor.scope as OpfsStorageScope).namespace !==
(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"]
).namespace
) {
return false;
}
let totalBytes = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > integrity.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (
index < value.chunks.length - 1 &&
chunk.byteLength !== integrity.chunkSizeBytes
) {
return false;
}
totalBytes += chunk.byteLength;
}
return (
totalBytes === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / integrity.chunkSizeBytes)
);
}
function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new TypeError("Journal value is not JSON-safe.");
}
/**
* `browserDataFailure` and `mapIndexedDbException` build a `Result`, while the
* kernel's `translate` and `context.fail` want the failure on its own. Both
@@ -1809,10 +1673,9 @@ function limitExceeded(
}
/**
* STO-01. The journal keeps `mapIndexedDbException`, which the IndexedDB
* runtime and maintenance share, rather than the checkpoint store's own table:
* the same native error is a different answer in the two families and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-01. The journal uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that the IndexedDB runtime and
* maintenance share (05-11). It imports nothing from `storage/indexeddb/`.
*
* A translator per operation, because the journal labels a read and a write
* differently. The connection always translates as `INDEXEDDB_OPEN`: an open
@@ -1825,6 +1688,17 @@ function translateFor(
return (cause) => {
switch (cause.kind) {
case "NATIVE_EXCEPTION":
// 05-06. A journal a newer release upgraded is not a failed
// migration; this bundle cannot use it and works online instead.
if (
(cause.error as { name?: unknown } | null)?.name === "VersionError"
) {
return failureOf(
browserDataFailure("UNSUPPORTED", operation, {
recovery: "ONLINE_ONLY",
}),
);
}
return failureOf(mapIndexedDbException(cause.error, operation));
case "BLOCKED":
case "BLOCKED_DEADLINE":
@@ -96,6 +96,13 @@ export type OpfsByteStoreDependencies = Readonly<{
* deliberately separate from any caller signal.
*/
compensationSignal?: AbortSignal;
/**
* 05-01 (D-3). Web Locks, `navigator.locks` by default. A put or delete
* holds an exclusive per-transaction lock from journal `begin` until it
* returns; reconcile only touches rows whose lock it can take at once, so a
* live transaction in any tab is never cleaned up underneath its owner.
*/
lockManager?: Pick<LockManager, "request">;
now?: () => number;
observer?: OpfsSafeObserver;
/**
@@ -152,6 +159,12 @@ export function createOpfsByteStoreAdapter(
*/
const compensationSignal = dependencies.compensationSignal;
const now = dependencies.now ?? Date.now;
const lockManager =
dependencies.lockManager ?? globalThis.navigator?.locks;
if (!lockManager || typeof lockManager.request !== "function") {
throw new TypeError("OPFS byte store requires Web Locks.");
}
const requestLock = lockManager.request.bind(lockManager);
const objects: DurableObjectStorePort = Object.freeze({
async capabilities() {
@@ -203,160 +216,152 @@ export function createOpfsByteStoreAdapter(
}
const targetGeneration = (current?.descriptor.generation ?? 0) + 1;
const transactionId = createTransactionId();
// STO-01. The logical generation is reused across transactions; this
// token makes the physical target unique so a late compensation can never
// delete a newer transaction's directory.
const physicalGenerationId = createPhysicalGenerationId();
notifyProgress(request, "PREPARING", 0);
const begun = await dependencies.journal.begin({
return await withTransactionLock(
transactionId,
mutation: "PUT",
scope: dependencies.scope,
objectId: request.objectId,
expectedGeneration: request.expectedGeneration,
targetGeneration,
targetByteLength: request.source.byteLength!,
targetStoragePolicy: dependencies.storagePolicy,
startedAtEpochMs: now(),
});
if (!begun.ok) {
return observeFailure(
rebaseFailure(begun.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
"OBJECT_WRITE",
async () => {
// STO-01. The logical generation is reused across transactions; this
// token makes the physical target unique so a late compensation can never
// delete a newer transaction's directory.
const physicalGenerationId = createPhysicalGenerationId();
notifyProgress(request, "PREPARING", 0);
const begun = await dependencies.journal.begin({
transactionId,
mutation: "PUT",
scope: dependencies.scope,
objectId: request.objectId,
expectedGeneration: request.expectedGeneration,
targetGeneration,
targetByteLength: request.source.byteLength!,
targetStoragePolicy: dependencies.storagePolicy,
startedAtEpochMs: now(),
});
if (!begun.ok) {
return observeFailure(
rebaseFailure(begun.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
const descriptor: Omit<DurableObjectDescriptor, "integrity"> =
Object.freeze({
objectId: request.objectId,
scope: dependencies.scope,
generation: targetGeneration,
byteLength: request.source.byteLength!,
mediaType: request.mediaType,
createdAtEpochMs: now(),
storagePolicy: dependencies.storagePolicy,
});
const prepared = await dependencies.worker.preparePut({
transactionId,
physicalGenerationId,
descriptor,
source: request.source,
signal: request.signal,
onProgress: request.onProgress,
});
if (!prepared.ok) {
const compensated = await compensatePreparedPut(
begun.value,
physicalGenerationId,
);
if (!compensated.ok) {
return observeFailure(
compensated,
dependencies.observer,
request.source.byteLength!,
const descriptor: Omit<DurableObjectDescriptor, "integrity"> =
Object.freeze({
objectId: request.objectId,
scope: dependencies.scope,
generation: targetGeneration,
byteLength: request.source.byteLength!,
mediaType: request.mediaType,
createdAtEpochMs: now(),
storagePolicy: dependencies.storagePolicy,
});
const prepared = await dependencies.worker.preparePut({
transactionId,
physicalGenerationId,
descriptor,
source: request.source,
signal: request.signal,
onProgress: request.onProgress,
});
if (!prepared.ok) {
return observeFailure(
await compensatePreparedPut(
begun.value,
physicalGenerationId,
prepared.error,
),
dependencies.observer,
request.source.byteLength!,
);
}
const filesReady = await dependencies.journal.markFilesReady(
transactionId,
begun.value.fencingToken,
prepared.value,
);
}
return observeFailure(
prepared,
dependencies.observer,
request.source.byteLength!,
);
}
if (!filesReady.ok) {
return observeFailure(
await compensatePreparedPut(
begun.value,
physicalGenerationId,
filesReady.error,
),
dependencies.observer,
request.source.byteLength!,
);
}
const filesReady = await dependencies.journal.markFilesReady(
transactionId,
begun.value.fencingToken,
prepared.value,
);
if (!filesReady.ok) {
const compensated = await compensatePreparedPut(
begun.value,
physicalGenerationId,
);
if (!compensated.ok) {
return observeFailure(
compensated,
dependencies.observer,
request.source.byteLength!,
const committed = await dependencies.journal.commitPut(
transactionId,
begun.value.fencingToken,
);
}
return observeFailure(
rebaseFailure(filesReady.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
if (!committed.ok) {
// The commit response can be lost after IndexedDB commits. Reconciliation
// decides from the durable journal; rolling back here would be unsafe.
return observeFailure(
rebaseFailure(committed.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
const committed = await dependencies.journal.commitPut(
transactionId,
begun.value.fencingToken,
notifyProgress(
request,
"FINALIZING",
prepared.value.descriptor.byteLength,
);
const finalized = await dependencies.worker.finalizePut(
transactionId,
prepared.value,
request.signal,
);
if (!finalized.ok) {
// STO-RR-01. The commit fence already passed, so the payload is durable
// and the journal keeps its COMMITTED record for reconciliation to
// settle. What did not happen is finalization: the previous generation
// and the staging directory are still present. Reporting a plain
// success here would claim a settled state nobody observed, so the
// worker's own failure is surfaced and the record is left recoverable.
return observeFailure(
rebaseFailure(finalized.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
const completed = await dependencies.journal.complete(
transactionId,
begun.value.fencingToken,
);
if (!completed.ok) {
// NS-04. The payload is durable and finalized, so nothing is rolled
// back and the `COMMITTED` row stays the reconciler's authority. What
// did not happen is settling the transaction, and reporting a plain
// success for it claimed a state nobody observed while the reconcile
// backlog and its quota pressure grew unseen.
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_WRITE",
outcome: "DEGRADED",
failureCode: completed.error.code,
byteBucket: byteBucket(prepared.value.descriptor.byteLength),
});
return {
ok: false as const,
error: Object.freeze({
...completed.error,
operation: "OBJECT_WRITE" as const,
retryable: true,
recovery: "RECONCILE" as const,
}),
};
}
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_WRITE",
outcome: "SUCCEEDED",
byteBucket: byteBucket(prepared.value.descriptor.byteLength),
});
return browserDataSuccess(prepared.value.descriptor);
},
);
if (!committed.ok) {
// The commit response can be lost after IndexedDB commits. Reconciliation
// decides from the durable journal; rolling back here would be unsafe.
return observeFailure(
rebaseFailure(committed.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
notifyProgress(
request,
"FINALIZING",
prepared.value.descriptor.byteLength,
);
const finalized = await dependencies.worker.finalizePut(
transactionId,
prepared.value,
request.signal,
);
if (!finalized.ok) {
// STO-RR-01. The commit fence already passed, so the payload is durable
// and the journal keeps its COMMITTED record for reconciliation to
// settle. What did not happen is finalization: the previous generation
// and the staging directory are still present. Reporting a plain
// success here would claim a settled state nobody observed, so the
// worker's own failure is surfaced and the record is left recoverable.
return observeFailure(
rebaseFailure(finalized.error, "OBJECT_WRITE"),
dependencies.observer,
request.source.byteLength!,
);
}
const completed = await dependencies.journal.complete(
transactionId,
begun.value.fencingToken,
);
if (!completed.ok) {
// NS-04. The payload is durable and finalized, so nothing is rolled
// back and the `COMMITTED` row stays the reconciler's authority. What
// did not happen is settling the transaction, and reporting a plain
// success for it claimed a state nobody observed while the reconcile
// backlog and its quota pressure grew unseen.
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_WRITE",
outcome: "DEGRADED",
failureCode: completed.error.code,
byteBucket: byteBucket(prepared.value.descriptor.byteLength),
});
return {
ok: false as const,
error: Object.freeze({
...completed.error,
operation: "OBJECT_WRITE" as const,
retryable: true,
recovery: "RECONCILE" as const,
}),
};
}
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_WRITE",
outcome: "SUCCEEDED",
byteBucket: byteBucket(prepared.value.descriptor.byteLength),
});
return browserDataSuccess(prepared.value.descriptor);
},
async open(
@@ -483,63 +488,70 @@ export function createOpfsByteStoreAdapter(
);
}
const targetStoragePolicy = current.value.descriptor.storagePolicy;
const transactionId = createTransactionId();
const begun = await dependencies.journal.begin({
return await withTransactionLock(
transactionId,
mutation: "DELETE",
scope: dependencies.scope,
objectId: request.objectId,
expectedGeneration: request.expectedGeneration,
targetGeneration: request.expectedGeneration + 1,
targetByteLength: 0,
targetStoragePolicy: current.value.descriptor.storagePolicy,
startedAtEpochMs: now(),
});
if (!begun.ok) {
return observeFailure(
rebaseFailure(begun.error, "OBJECT_DELETE"),
dependencies.observer,
);
}
const committed = await dependencies.journal.commitDelete(
transactionId,
begun.value.fencingToken,
);
if (!committed.ok) {
return observeFailure(
rebaseFailure(committed.error, "OBJECT_DELETE"),
dependencies.observer,
);
}
const removed = await dependencies.worker.removeObject(
dependencies.scope,
request.objectId,
request.expectedGeneration,
request.signal,
);
const completed = removed.ok
? await dependencies.journal.complete(
"OBJECT_DELETE",
async () => {
const begun = await dependencies.journal.begin({
transactionId,
mutation: "DELETE",
scope: dependencies.scope,
objectId: request.objectId,
expectedGeneration: request.expectedGeneration,
targetGeneration: request.expectedGeneration + 1,
targetByteLength: 0,
targetStoragePolicy,
startedAtEpochMs: now(),
});
if (!begun.ok) {
return observeFailure(
rebaseFailure(begun.error, "OBJECT_DELETE"),
dependencies.observer,
);
}
const committed = await dependencies.journal.commitDelete(
transactionId,
begun.value.fencingToken,
)
: null;
// Logical deletion is already committed. Physical cleanup is retryable
// maintenance and must not make the caller repeat a non-idempotent delete.
// NS-04. It is still not a settled state: an unfinished physical removal
// or an unsettled journal row is maintenance debt the reconciler owns, so
// it is observed as such instead of as a clean success.
const settled = removed.ok && completed !== null && completed.ok;
const debtCode = removed.ok
? completed !== null && !completed.ok
? completed.error.code
: undefined
: removed.error.code;
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_DELETE",
outcome: settled ? "SUCCEEDED" : "DEGRADED",
...(debtCode ? { failureCode: debtCode } : {}),
});
return browserDataSuccess(undefined);
);
if (!committed.ok) {
return observeFailure(
rebaseFailure(committed.error, "OBJECT_DELETE"),
dependencies.observer,
);
}
const removed = await dependencies.worker.removeObject(
dependencies.scope,
request.objectId,
request.expectedGeneration,
request.signal,
);
const completed = removed.ok
? await dependencies.journal.complete(
transactionId,
begun.value.fencingToken,
)
: null;
// Logical deletion is already committed. Physical cleanup is retryable
// maintenance and must not make the caller repeat a non-idempotent delete.
// NS-04. It is still not a settled state: an unfinished physical removal
// or an unsettled journal row is maintenance debt the reconciler owns, so
// it is observed as such instead of as a clean success.
const settled = removed.ok && completed !== null && completed.ok;
const debtCode = removed.ok
? completed !== null && !completed.ok
? completed.error.code
: undefined
: removed.error.code;
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_DELETE",
outcome: settled ? "SUCCEEDED" : "DEGRADED",
...(debtCode ? { failureCode: debtCode } : {}),
});
return browserDataSuccess(undefined);
},
);
},
});
@@ -577,14 +589,14 @@ export function createOpfsByteStoreAdapter(
const maxTransactions =
request.maxTransactions ?? policy.reconciliationBatchSize;
const deadline = now() + budgetMs;
const page = await dependencies.journal.listIncomplete(maxTransactions);
if (!page.ok) {
return rebaseFailure(page.error, "OBJECT_RECONCILE");
const listed = await dependencies.journal.listIncomplete(maxTransactions);
if (!listed.ok) {
return rebaseFailure(listed.error, "OBJECT_RECONCILE");
}
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_RECONCILE",
outcome: "STARTED",
transactionBucket: transactionBucket(page.value.transactions.length),
transactionBucket: transactionBucket(listed.value.transactions.length),
});
const report: {
@@ -600,6 +612,8 @@ export function createOpfsByteStoreAdapter(
| "STAGING_STATE_UNREADABLE";
moreTransactionsAvailable: boolean;
deadlineReached: boolean;
skippedLiveTransactions: number;
failedTransactions: number;
} = {
inspectedTransactions: 0,
committedTransactions: 0,
@@ -608,26 +622,63 @@ export function createOpfsByteStoreAdapter(
inspectedOrphanChunks: 0,
deletedOrphanChunks: 0,
orphanGcStatus: "COMPLETED",
moreTransactionsAvailable: page.value.moreAvailable,
moreTransactionsAvailable: listed.value.moreAvailable,
deadlineReached: false,
skippedLiveTransactions: 0,
failedTransactions: 0,
};
for (const transaction of page.value.transactions) {
if (request.signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
// 05-01 (D-3). A row is reconciled only while this call holds its
// per-transaction lock, so a put or delete still running in any tab is
// skipped. The page is read again under those locks: a row listed while
// its owner still ran may have moved on before the owner let go.
const held = new Map<string, () => void>();
try {
for (const transaction of listed.value.transactions) {
let release: (() => void) | null;
try {
release = await holdTransactionLock(transaction.transactionId);
} catch {
return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE", {
retryable: true,
recovery: "RETRY",
});
}
if (release) held.set(transaction.transactionId, release);
else report.skippedLiveTransactions += 1;
}
if (now() >= deadline) {
report.deadlineReached = true;
report.moreTransactionsAvailable = true;
break;
const page =
held.size === 0
? listed
: await dependencies.journal.listIncomplete(maxTransactions);
if (!page.ok) {
return rebaseFailure(page.error, "OBJECT_RECONCILE");
}
report.inspectedTransactions += 1;
const reconciled = await reconcileTransaction(transaction, request.signal);
if (!reconciled.ok) {
return observeFailure(reconciled, dependencies.observer);
report.moreTransactionsAvailable = page.value.moreAvailable;
for (const transaction of page.value.transactions) {
if (!held.has(transaction.transactionId)) continue;
if (request.signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
}
if (now() >= deadline) {
report.deadlineReached = true;
report.moreTransactionsAvailable = true;
break;
}
report.inspectedTransactions += 1;
const reconciled = await reconcileTransaction(transaction, request.signal);
if (!reconciled.ok) {
// 05-02. A row that cannot be settled now stays for a later run;
// it must not stop the rest of the page or orphan GC.
observeFailure(reconciled, dependencies.observer);
report.failedTransactions += 1;
continue;
}
report.committedTransactions += reconciled.value.committed;
report.rolledBackTransactions += reconciled.value.rolledBack;
report.cleanedTransactions += reconciled.value.cleaned;
}
report.committedTransactions += reconciled.value.committed;
report.rolledBackTransactions += reconciled.value.rolledBack;
report.cleanedTransactions += reconciled.value.cleaned;
} finally {
for (const release of held.values()) release();
}
if (now() >= deadline) {
report.deadlineReached = true;
@@ -795,12 +846,38 @@ export function createOpfsByteStoreAdapter(
afterObjectId = page.value.nextObjectId;
moreObjectsAvailable = page.value.moreAvailable;
}
// 05-04. Removing an object leaves its chunks, and GC only takes a
// chunk 24 h after it was written, so a purged user's bytes stayed on
// the device. Once every object is gone the partition's chunks are swept
// without that grace. The sweep still skips any chunk the journal or a
// staged put references.
let chunkSweep: OpfsPolicyMaintenanceReport["chunkSweep"];
if (
(request.reason === "LOGOUT" ||
request.reason === "ACCOUNT_DELETION") &&
!moreObjectsAvailable &&
!deadlineReached &&
!request.signal?.aborted
) {
const swept = await reconcileOrphanChunks(
deadline,
request.signal,
now(),
);
if (!swept.ok) return rebaseFailure(swept.error, "OBJECT_RECONCILE");
chunkSweep = swept.value.status;
if (chunkSweep === "DEADLINE_REACHED") {
deadlineReached = true;
moreObjectsAvailable = true;
}
}
const report: OpfsPolicyMaintenanceReport = Object.freeze({
inspectedObjects,
removedObjects,
releasedBytes,
moreObjectsAvailable,
deadlineReached,
...(chunkSweep ? { chunkSweep } : {}),
});
return browserDataSuccess(report);
},
@@ -919,38 +996,94 @@ export function createOpfsByteStoreAdapter(
return Object.freeze({ objects, maintenance });
/**
* Takes the exclusive per-transaction Web Lock only if nobody holds it.
* Resolves with its release, or `null` while another context holds it.
*/
async function holdTransactionLock(
transactionId: string,
): Promise<(() => void) | null> {
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
return await new Promise((resolve, reject) => {
requestLock(
`${policy.mutationLockName}:transaction:${scope.authorityToken}:${transactionId}`,
{ mode: "exclusive", ifAvailable: true },
async (lock) => {
if (!lock) {
resolve(null);
return;
}
resolve(release);
await held;
},
).catch(reject);
});
}
async function withTransactionLock<Value>(
transactionId: string,
operation: "OBJECT_WRITE" | "OBJECT_DELETE",
run: () => Promise<BrowserDataResult<Value>>,
): Promise<BrowserDataResult<Value>> {
let release: (() => void) | null;
try {
release = await holdTransactionLock(transactionId);
} catch {
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
});
}
// A fresh transaction id is never held; a holder means a duplicate id.
if (!release) return browserDataFailure("CONFLICT", operation);
try {
return await run();
} finally {
release();
}
}
/**
* STO-01. The compensating half of the put saga.
*
* The journal row and its budget reservation are the only durable evidence
* that a physical staging generation may still exist, so they are released
* exactly when the physical effect is confirmed `CLEANED` or
* `ALREADY_CLEAN`. A timeout, crash, malformed response or `EFFECT_UNKNOWN`
* `ALREADY_CLEAN`. A timeout, crash, malformed response or worker failure
* keeps `PREPARING`/`FILES_READY` in place and asks for reconciliation.
*/
/**
* Compensates a put that failed before commit and returns that failure.
* Q-6.5-9. When the cleanup or the journal rollback does not complete, the
* journal row stays for reconciliation: the put keeps its own code and only
* its recovery becomes RECONCILE.
*/
async function compensatePreparedPut(
transaction: OpfsJournalTransaction,
physicalGenerationId: OpfsPhysicalGenerationId,
): Promise<BrowserDataResult<void>> {
failure: BrowserDataFailure,
): Promise<BrowserFailureResult> {
const cleanup = await dependencies.worker.abortPreparedPut({
scope: transaction.scope,
transactionId: transaction.transactionId,
physicalGenerationId,
...(compensationSignal ? { signal: compensationSignal } : {}),
});
if (!cleanup.ok || cleanup.value.kind === "EFFECT_UNKNOWN") {
return browserDataFailure("CONFLICT", "OBJECT_RECONCILE", {
recovery: "RETRY",
});
}
const rolledBack = await dependencies.journal.rollback(
transaction.transactionId,
transaction.fencingToken,
const compensated =
cleanup.ok &&
(
await dependencies.journal.rollback(
transaction.transactionId,
transaction.fencingToken,
)
).ok;
return rebaseFailure(
compensated ? failure : { ...failure, recovery: "RECONCILE" },
"OBJECT_WRITE",
);
if (!rolledBack.ok) {
return rebaseFailure(rolledBack.error, "OBJECT_RECONCILE");
}
return browserDataSuccess(undefined);
}
async function reconcileTransaction(
@@ -968,11 +1101,6 @@ export function createOpfsByteStoreAdapter(
signal,
);
if (!cleaned.ok) return cleaned;
if (cleaned.value.kind === "EFFECT_UNKNOWN") {
return browserDataFailure("CONFLICT", "OBJECT_RECONCILE", {
recovery: "RETRY",
});
}
const rolledBack = await dependencies.journal.rollback(
transaction.transactionId,
transaction.fencingToken,
@@ -1080,6 +1208,7 @@ export function createOpfsByteStoreAdapter(
async function reconcileOrphanChunks(
deadline: number,
signal: AbortSignal | undefined,
olderThanEpochMs = Math.max(0, now() - policy.orphanGracePeriodMs),
): Promise<
BrowserDataResult<
Readonly<{
@@ -1092,29 +1221,69 @@ export function createOpfsByteStoreAdapter(
}>
>
> {
const olderThanEpochMs = Math.max(
0,
now() - policy.orphanGracePeriodMs,
);
const candidates = await dependencies.worker.listOrphanCandidates(
dependencies.scope,
olderThanEpochMs,
policy.orphanGcBatchSize,
signal,
);
if (!candidates.ok) return candidates;
if (!candidates.value.safeToSweep) {
return browserDataSuccess({
inspected: 0,
deleted: 0,
status: "STAGING_STATE_UNREADABLE",
});
}
let inspected = 0;
let deleted = 0;
for (const digestHex of candidates.value.digests) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
// R-5.1. Candidates include committed chunks, so a page can be all
// referenced. The scan pages on by digest cursor until it runs out or the
// deadline stops it.
// ponytail: every reconcile restarts at the lowest digest; if checking the
// referenced chunks alone outlasts the budget, keep the cursor across calls.
let afterDigest: string | undefined;
for (;;) {
const candidates = await dependencies.worker.listOrphanCandidates(
dependencies.scope,
olderThanEpochMs,
policy.orphanGcBatchSize,
signal,
afterDigest,
);
if (!candidates.ok) return candidates;
if (!candidates.value.safeToSweep) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
for (const digestHex of candidates.value.digests) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
}
if (now() >= deadline) {
return browserDataSuccess({
inspected,
deleted,
status: "DEADLINE_REACHED",
});
}
inspected += 1;
const referenced = await dependencies.journal.isChunkReferenced(
dependencies.scope,
digestHex,
);
if (!referenced.ok) {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
}
if (referenced.value) continue;
const removal = await dependencies.worker.deleteOrphanChunk(
dependencies.scope,
digestHex,
olderThanEpochMs,
signal,
);
if (!removal.ok) return removal;
if (removal.value.skippedUnsafe) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
if (removal.value.deleted) deleted += 1;
}
afterDigest = candidates.value.digests.at(-1);
if (!candidates.value.moreAvailable || afterDigest === undefined) {
return browserDataSuccess({ inspected, deleted, status: "COMPLETED" });
}
if (now() >= deadline) {
return browserDataSuccess({
@@ -1123,39 +1292,7 @@ export function createOpfsByteStoreAdapter(
status: "DEADLINE_REACHED",
});
}
inspected += 1;
const referenced = await dependencies.journal.isChunkReferenced(
dependencies.scope,
digestHex,
);
if (!referenced.ok) {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
}
if (referenced.value) continue;
const removal = await dependencies.worker.deleteOrphanChunk(
dependencies.scope,
digestHex,
olderThanEpochMs,
signal,
);
if (!removal.ok) return removal;
if (removal.value.skippedUnsafe) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
if (removal.value.deleted) deleted += 1;
}
return browserDataSuccess({
inspected,
deleted,
status:
candidates.value.moreAvailable
? "DEADLINE_REACHED"
: "COMPLETED",
});
}
}
+69 -2
View File
@@ -14,6 +14,19 @@ export type OpfsRuntimePolicy = Readonly<{
maxObjectBytes: number;
maxChunkCount: number;
rpcTimeoutMs: number;
/**
* R-5.3 (D-3). How long a request may queue for the origin mutation lock.
* Another context's put holds that lock for its whole upload, so this wait
* is bounded on its own and never counted against `rpcTimeoutMs`.
*/
mutationLockWaitTimeoutMs: number;
/**
* 05-07. How long a put may wait for its source's next bytes. The put holds
* the origin mutation lock from BEGIN to FINISH, so a stalled source would
* otherwise stop every tab's writes until their lock wait ran out. Keep it
* below `mutationLockWaitTimeoutMs` so a queued writer outlasts it.
*/
putIdleTimeoutMs: number;
reconciliationBudgetMs: number;
reconciliationBatchSize: number;
orphanGracePeriodMs: number;
@@ -49,6 +62,8 @@ export const DEFAULT_OPFS_RUNTIME_POLICY: OpfsRuntimePolicy = Object.freeze({
maxObjectBytes: 2 * 1024 * 1024 * 1024,
maxChunkCount: 512,
rpcTimeoutMs: 60_000,
mutationLockWaitTimeoutMs: 10 * 60_000,
putIdleTimeoutMs: 2 * 60_000,
reconciliationBudgetMs: 5_000,
reconciliationBatchSize: 100,
orphanGracePeriodMs: 24 * 60 * 60 * 1_000,
@@ -84,6 +99,12 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void {
policy.maxObjectBytes > policy.chunkSizeBytes * policy.maxChunkCount ||
!Number.isSafeInteger(policy.rpcTimeoutMs) ||
policy.rpcTimeoutMs < 1_000 ||
!Number.isSafeInteger(policy.mutationLockWaitTimeoutMs) ||
policy.mutationLockWaitTimeoutMs < 1_000 ||
policy.mutationLockWaitTimeoutMs > 60 * 60_000 ||
!Number.isSafeInteger(policy.putIdleTimeoutMs) ||
policy.putIdleTimeoutMs < 1_000 ||
policy.putIdleTimeoutMs > 60 * 60_000 ||
!Number.isSafeInteger(policy.reconciliationBudgetMs) ||
policy.reconciliationBudgetMs < 1 ||
policy.reconciliationBudgetMs > 60_000 ||
@@ -99,12 +120,58 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void {
policy.maxCancellationTombstones < 16 ||
policy.maxCancellationTombstones > 10_000 ||
typeof policy.isObjectIdAllowed !== "function" ||
typeof policy.isMediaTypeAllowed !== "function"
typeof policy.isMediaTypeAllowed !== "function" ||
widensObjectIdGrammar(policy.isObjectIdAllowed)
) {
throw new TypeError("OPFS runtime policy is invalid.");
}
}
/**
* 05-10. Stored prepared objects, journal rows and physical paths all use the
* opaque id grammar, so a policy may narrow it but never widen it: a wider
* policy let BEGIN through and failed every put at its last step. Ids just
* outside the grammar catch the usual widenings when the policy is resolved;
* writes also check the grammar itself (isWritableObjectId), so a widening no
* sample finds is refused at BEGIN instead.
*/
const OBJECT_IDS_OUTSIDE_GRAMMAR = Object.freeze([
"",
"short_7",
"a".repeat(129),
"object 12345",
"object.12345",
"object/12345",
"object~12345",
"object:12345",
"object@12345",
"objekt_\u00e4\u00f6\u00fc12",
]);
function widensObjectIdGrammar(
isObjectIdAllowed: (objectId: string) => boolean,
): boolean {
try {
return OBJECT_IDS_OUTSIDE_GRAMMAR.some((objectId) =>
isObjectIdAllowed(objectId),
);
} catch {
return true;
}
}
export function isOpaqueObjectId(value: string): boolean {
return OPAQUE_OBJECT_ID.test(value);
}
/** 05-10. The policy may narrow the id grammar for writes, never widen it. */
export function isWritableObjectId(
policy: OpfsRuntimePolicy,
objectId: string,
): boolean {
return OPAQUE_OBJECT_ID.test(objectId) && policy.isObjectIdAllowed(objectId);
}
export function validateObjectWriteInput(
input: Readonly<{
scope: OpfsStorageScope;
@@ -125,7 +192,7 @@ export function validateObjectWriteInput(
return (
isValidOpfsStorageScope(input.scope) &&
input.scope.namespace === input.storagePolicy.namespace &&
policy.isObjectIdAllowed(input.objectId) &&
isWritableObjectId(policy, input.objectId) &&
policy.isMediaTypeAllowed(input.mediaType) &&
(input.expectedGeneration === null ||
(Number.isSafeInteger(input.expectedGeneration) &&
@@ -0,0 +1,163 @@
import type {
OpfsPreparedObject,
OpfsStorageScope,
} from "../../../application/ports/browser-file-storage/opfs-ports.ts";
import { assertValidStoragePolicy } from "../../../application/ports/browser-file-storage/shared.ts";
import { isOpaqueObjectId, isValidOpfsStorageScope } from "./opfs-policy.ts";
const SHA256_HEX = /^[a-f0-9]{64}$/u;
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
/**
* R-5.5. The one prepared-object validator for the page, the journal and the
* worker. An object is checked against itself, including its own
* `chunkSizeBytes`, never against the current runtime policy: the policy
* governs new writes only (validateObjectWriteInput, BEGIN_PUT, APPEND_CHUNK),
* so changing the chunk size or another limit cannot make stored objects
* unreadable or unreconcilable.
*/
export function isPreparedObject(
value: unknown,
): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!isOpaqueObjectId(descriptor.objectId) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(descriptor.scope as OpfsStorageScope) ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
typeof descriptor.mediaType !== "string" ||
descriptor.mediaType.length < 1 ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
typeof integrity.chunkSizeBytes !== "number" ||
!Number.isSafeInteger(integrity.chunkSizeBytes) ||
integrity.chunkSizeBytes < 1 ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object"
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
if (
(descriptor.scope as OpfsStorageScope).namespace !==
(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"]
).namespace
) {
return false;
}
let totalBytes = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > integrity.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (
index < value.chunks.length - 1 &&
chunk.byteLength !== integrity.chunkSizeBytes
) {
return false;
}
totalBytes += chunk.byteLength;
}
return (
totalBytes === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / integrity.chunkSizeBytes)
);
}
/**
* 05-10. The one canonical JSON for comparing OPFS records, used by the
* worker and the journal alike. A value JSON cannot carry exactly (a
* non-finite number, `undefined`, a function) throws instead of being
* written as something else, so two different values never compare equal.
*/
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean"
) {
return JSON.stringify(value);
}
if (typeof value === "number") {
if (!Number.isFinite(value)) {
throw new TypeError("OPFS value is not JSON-safe.");
}
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new TypeError("OPFS value is not JSON-safe.");
}
+45 -38
View File
@@ -14,8 +14,11 @@ import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import type { OpfsRuntimePolicy } from "./opfs-policy.ts";
import { isPreparedObject } from "./opfs-prepared-object.ts";
import {
OPFS_LOCK_WAITING_REQUEST_KINDS,
OPFS_WORKER_PROTOCOL_VERSION,
} from "./opfs-worker-protocol.ts";
import type {
@@ -167,13 +170,19 @@ export function createOpfsWorkerGateway(
reject(new OpfsRpcError("ABORTED"));
};
signal?.addEventListener("abort", abort, { once: true });
// R-5.3. Time queued behind another context's lock holder is the
// worker's to bound; it must not eat this request's own RPC budget.
const timeoutMs = OPFS_LOCK_WAITING_REQUEST_KINDS.has(request.kind)
? dependencies.policy.rpcTimeoutMs +
dependencies.policy.mutationLockWaitTimeoutMs
: dependencies.policy.rpcTimeoutMs;
const timeout = setTimeout(() => {
const item = pending.get(requestId);
if (!item) return;
pending.delete(requestId);
item.removeAbortListener();
reject(new OpfsRpcError("UNAVAILABLE"));
}, dependencies.policy.rpcTimeoutMs);
}, timeoutMs);
pending.set(requestId, {
// STO-07. The expected kind is stored so a reply for a different
// operation can never satisfy this request.
@@ -264,13 +273,36 @@ export function createOpfsWorkerGateway(
let sequence = 0;
let transferredBytes = 0;
notifyProgress(request, "TRANSFERRING", 0);
// 05-07. BEGIN took the origin mutation lock, so every wait for the
// source is bounded by `putIdleTimeoutMs`. A source that stops fails the
// put, and the coordinator's compensation releases the lock.
const sourceStop = new AbortController();
const stopSource = () => sourceStop.abort();
request.signal?.addEventListener("abort", stopSource, { once: true });
if (request.signal?.aborted) stopSource();
const chunks = rechunk(
request.source.stream(sourceStop.signal),
dependencies.policy.chunkSizeBytes,
dependencies.policy.maxObjectBytes,
request.signal,
);
try {
for await (const chunk of rechunk(
request.source.stream(requiredSignal(request.signal)),
dependencies.policy.chunkSizeBytes,
dependencies.policy.maxObjectBytes,
request.signal,
)) {
for (;;) {
const idle = createAbortableOperation({
signal: request.signal,
timeoutMs: dependencies.policy.putIdleTimeoutMs,
});
const next = await idle.race(chunks.next());
idle.close();
if (next.kind === "REJECTED") throw next.reason;
if (next.kind === "TERMINAL") {
stopSource();
throw new OpfsRpcError(
next.terminal === "DEADLINE" ? "NOT_READABLE" : "ABORTED",
);
}
if (next.value.done) break;
const chunk = next.value.value;
const chunkByteLength = chunk.byteLength;
const append = await invoke<void>(
"OBJECT_WRITE",
@@ -312,6 +344,8 @@ export function createOpfsWorkerGateway(
error instanceof OpfsRpcError ? error.code : "NOT_READABLE",
"OBJECT_WRITE",
);
} finally {
request.signal?.removeEventListener("abort", stopSource);
}
},
@@ -334,7 +368,7 @@ export function createOpfsWorkerGateway(
) {
const verified = await invoke(
"OBJECT_READ",
{ kind: "VERIFY_OBJECT", preparedObject },
{ kind: "VERIFY_OBJECT", preparedObject, manifestOnly: true },
signal,
[],
(value) => (typeof value === "boolean" ? value : null),
@@ -440,6 +474,7 @@ export function createOpfsWorkerGateway(
olderThanEpochMs: number,
maxEntries: number,
signal?: AbortSignal,
afterDigest?: string,
) {
return await invoke(
"OBJECT_RECONCILE",
@@ -448,6 +483,7 @@ export function createOpfsWorkerGateway(
scope,
olderThanEpochMs,
maxEntries,
...(afterDigest === undefined ? {} : { afterDigest }),
},
signal,
[],
@@ -575,10 +611,6 @@ async function* rechunk(
}
}
function requiredSignal(signal: AbortSignal | undefined): AbortSignal {
return signal ?? new AbortController().signal;
}
function notifyProgress(
request: PreparePhysicalObjectRequest,
phase: "TRANSFERRING" | "VERIFYING",
@@ -639,20 +671,6 @@ function parseCapabilities(value: unknown): OpfsCapabilities | null {
return value as OpfsCapabilities;
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function parseCleanupEffect(value: unknown): OpfsCleanupEffect | null {
if (!value || typeof value !== "object") return null;
const kind = (value as Record<string, unknown>).kind;
@@ -662,18 +680,7 @@ function parseCleanupEffect(value: unknown): OpfsCleanupEffect | null {
}
function parsePreparedObject(value: unknown): OpfsPreparedObject | null {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return null;
}
return value as OpfsPreparedObject;
return isPreparedObject(value) ? value : null;
}
function parseOrphanCandidateBatch(
@@ -77,6 +77,12 @@ export type OpfsWorkerRequest =
protocolVersion: typeof OPFS_WORKER_PROTOCOL_VERSION;
kind: "VERIFY_OBJECT";
preparedObject: OpfsPreparedObject;
/**
* Q-6.5-6. Compare the stored manifest only. `openObject` sends it: the
* stream then verifies each chunk as it reads it and the root digest
* before it releases the last chunk, so an object is not read twice.
*/
manifestOnly?: true;
}>
| Readonly<{
requestId: string;
@@ -120,6 +126,12 @@ export type OpfsWorkerRequest =
scope: OpfsStorageScope;
olderThanEpochMs: number;
maxEntries: number;
/**
* R-5.1. Candidates come back in ascending digest order. The next page
* starts strictly after this digest (the last one of the previous page),
* so a batch of still-referenced chunks cannot hide the rest forever.
*/
afterDigest?: string;
}>
| Readonly<{
requestId: string;
@@ -130,6 +142,23 @@ export type OpfsWorkerRequest =
olderThanEpochMs: number;
}>;
/**
* R-5.3 (D-3). Requests the worker may park on the origin mutation lock. The
* worker bounds that wait by `mutationLockWaitTimeoutMs`; the page adds the
* same bound to these requests' RPC timer.
*/
export const OPFS_LOCK_WAITING_REQUEST_KINDS: ReadonlySet<
OpfsWorkerRequest["kind"]
> = new Set([
"BEGIN_PUT",
"ABORT_PUT",
"REMOVE_OBJECT",
"CLEANUP_TRANSACTION",
"FINALIZE_PUT",
"LIST_ORPHAN_CANDIDATES",
"DELETE_ORPHAN_CHUNK",
]);
export type OpfsWorkerRequestBody =
OpfsWorkerRequest extends infer Request
? Request extends OpfsWorkerRequest
@@ -239,6 +268,7 @@ export interface OpfsWorkerGateway {
olderThanEpochMs: number,
maxEntries: number,
signal?: AbortSignal,
afterDigest?: string,
): Promise<BrowserDataResult<OpfsOrphanCandidateBatch>>;
deleteOrphanChunk(
scope: OpfsStorageScope,
+139 -181
View File
@@ -10,11 +10,14 @@ import {
assertValidStoragePolicy,
type BrowserDataFailureCode,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import {
resolveOpfsRuntimePolicy,
isValidOpfsStorageScope,
isWritableObjectId,
type OpfsRuntimePolicy,
} from "./opfs-policy.ts";
import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts";
import {
OPFS_WORKER_PROTOCOL_VERSION,
} from "./opfs-worker-protocol.ts";
@@ -246,7 +249,10 @@ export function createOpfsWorkerRuntime(
return success(
request.requestId,
request.kind,
await verifyObject(request.preparedObject),
await verifyObject(
request.preparedObject,
request.manifestOnly === true,
),
);
case "READ_CHUNK":
return success(
@@ -289,6 +295,7 @@ export function createOpfsWorkerRuntime(
request.scope,
request.olderThanEpochMs,
request.maxEntries,
request.afterDigest,
),
);
case "DELETE_ORPHAN_CHUNK":
@@ -322,7 +329,7 @@ export function createOpfsWorkerRuntime(
if (
!SAFE_TRANSACTION_ID.test(request.transactionId) ||
!isValidOpfsStorageScope(request.scope) ||
!dependencies.policy.isObjectIdAllowed(request.objectId) ||
!isWritableObjectId(dependencies.policy, request.objectId) ||
!Number.isSafeInteger(request.generation) ||
request.generation < 1 ||
!isPhysicalGenerationId(request.physicalGenerationId) ||
@@ -359,7 +366,7 @@ export function createOpfsWorkerRuntime(
pendingBegins.set(transactionKey, beginAbort);
let lease: OpfsMutationLease;
try {
lease = await dependencies.leaseManager!.acquire(beginAbort.signal);
lease = await acquireLease(beginAbort.signal);
} finally {
pendingBegins.delete(transactionKey);
}
@@ -690,8 +697,9 @@ export function createOpfsWorkerRuntime(
async function verifyObject(
expected: OpfsPreparedObject,
manifestOnly: boolean,
): Promise<boolean> {
if (!isPreparedObjectSafe(expected, dependencies.policy)) return false;
if (!isPreparedObject(expected)) return false;
let stored: unknown;
try {
stored = await readJson(manifestPath(expected));
@@ -700,20 +708,15 @@ export function createOpfsWorkerRuntime(
throw error;
}
if (
!isPreparedObjectSafe(stored, dependencies.policy) ||
!isPreparedObject(stored) ||
stableJson(stored) !== stableJson(expected)
) {
return false;
}
const rootDigestHex = await treeDigestHex(
dependencies.crypto,
expected.descriptor.integrity.chunkSizeBytes,
expected.descriptor.byteLength,
expected.chunks,
);
if (rootDigestHex !== expected.descriptor.integrity.rootDigestHex) {
return false;
}
// Q-6.5-6. READ_CHUNK checks the root digest at the last chunk; an empty
// object has no chunk to read, so its stream ends here.
if (manifestOnly && expected.chunks.length > 0) return true;
if (!(await rootDigestMatches(expected))) return false;
for (const chunk of expected.chunks) {
let bytes: Uint8Array;
try {
@@ -734,12 +737,25 @@ export function createOpfsWorkerRuntime(
return true;
}
async function rootDigestMatches(
expected: OpfsPreparedObject,
): Promise<boolean> {
return (
(await treeDigestHex(
dependencies.crypto,
expected.descriptor.integrity.chunkSizeBytes,
expected.descriptor.byteLength,
expected.chunks,
)) === expected.descriptor.integrity.rootDigestHex
);
}
async function readVerifiedChunk(
expected: OpfsPreparedObject,
sequence: number,
): Promise<ArrayBuffer> {
if (
!isPreparedObjectSafe(expected, dependencies.policy) ||
!isPreparedObject(expected) ||
!Number.isSafeInteger(sequence) ||
sequence < 0
) {
@@ -754,7 +770,12 @@ export function createOpfsWorkerRuntime(
);
if (
bytes.byteLength !== reference.byteLength ||
(await sha256Hex(dependencies.crypto, bytes)) !== reference.digestHex
(await sha256Hex(dependencies.crypto, bytes)) !== reference.digestHex ||
// Q-6.5-6. The last chunk is not released until the chunk list is
// proven against the root digest, so a stream never ends as a success
// on an unverified object.
(sequence === expected.chunks.length - 1 &&
!(await rootDigestMatches(expected)))
) {
throw new OpfsRuntimeFailure("INTEGRITY_FAILED");
}
@@ -776,7 +797,7 @@ export function createOpfsWorkerRuntime(
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const prefixDirectory = await getDirectory(
dependencies.root,
@@ -826,7 +847,7 @@ export function createOpfsWorkerRuntime(
throw error;
}
// Every destructive step below runs while the lease is held.
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
return await cleanupTransactionLocked(
scope,
@@ -870,16 +891,11 @@ export function createOpfsWorkerRuntime(
}
{
if (removePreparedGeneration) {
let receipt: unknown;
try {
receipt = await readJson(receiptPath(scope, transactionId));
} catch (error) {
if (isNotFound(error)) {
await removeEntryIfPresent(staging, transactionId, true);
return CLEANUP_ALREADY_CLEAN;
}
// Keep unreadable staging in place so orphan GC fails closed.
throw error;
// Keep unreadable staging in place so orphan GC fails closed.
const receipt = await readReceipt(scope, transactionId);
if (receipt === undefined) {
await removeEntryIfPresent(staging, transactionId, true);
return CLEANUP_ALREADY_CLEAN;
}
const target = extractReceiptPhysicalTarget(receipt, scope);
if (!target) {
@@ -906,11 +922,11 @@ export function createOpfsWorkerRuntime(
assertWorkerAvailable();
if (
!SAFE_TRANSACTION_ID.test(transactionId) ||
!isPreparedObjectSafe(preparedObject, dependencies.policy)
!isPreparedObject(preparedObject)
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const descriptor = preparedObject.descriptor;
const objectDirectory = await getDirectory(
@@ -952,6 +968,7 @@ export function createOpfsWorkerRuntime(
scope: OpfsPreparedObject["descriptor"]["scope"],
olderThanEpochMs: number,
maxEntries: number,
afterDigest: string | undefined,
): Promise<OpfsOrphanCandidateBatch> {
assertWorkerAvailable();
if (
@@ -960,11 +977,13 @@ export function createOpfsWorkerRuntime(
olderThanEpochMs < 0 ||
!Number.isSafeInteger(maxEntries) ||
maxEntries < 1 ||
maxEntries > dependencies.policy.orphanGcBatchSize
maxEntries > dependencies.policy.orphanGcBatchSize ||
(afterDigest !== undefined &&
(typeof afterDigest !== "string" || !SHA256_HEX.test(afterDigest)))
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const staged = await stagedChunkDigests(scope);
if (!staged.safeToSweep) {
@@ -991,25 +1010,33 @@ export function createOpfsWorkerRuntime(
}
throw error;
}
// R-5.1. Directory order is unspecified, so the scan walks prefixes and
// names in ascending order; that is what makes `afterDigest` a cursor.
const cursor = afterDigest ?? "";
const prefixes = new Map<string, FileSystemDirectoryHandle>();
for await (const [name, handle] of shaRoot.entries()) {
if (handle.kind !== "directory" || name < cursor.slice(0, 2)) continue;
prefixes.set(name, handle as FileSystemDirectoryHandle);
}
const candidates: string[] = [];
outer: for await (const [, prefixHandle] of shaRoot.entries()) {
if (prefixHandle.kind !== "directory") continue;
const prefixDirectory =
prefixHandle as FileSystemDirectoryHandle;
for await (const [name, handle] of prefixDirectory.entries()) {
outer: for (const prefix of [...prefixes.keys()].sort()) {
const files = new Map<string, FileSystemFileHandle>();
for await (const [name, handle] of prefixes.get(prefix)!.entries()) {
if (handle.kind !== "file") continue;
const digestHex = name.endsWith(".bin")
? name.slice(0, -4)
: "";
if (
!SHA256_HEX.test(digestHex) ||
digestHex <= cursor ||
staged.digests.has(digestHex)
) {
continue;
}
const file = await (
handle as FileSystemFileHandle
).getFile();
files.set(digestHex, handle as FileSystemFileHandle);
}
for (const digestHex of [...files.keys()].sort()) {
const file = await files.get(digestHex)!.getFile();
if (file.lastModified > olderThanEpochMs) continue;
candidates.push(digestHex);
if (candidates.length > maxEntries) break outer;
@@ -1039,7 +1066,7 @@ export function createOpfsWorkerRuntime(
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const staged = await stagedChunkDigests(scope);
if (!staged.safeToSweep) {
@@ -1102,10 +1129,11 @@ export function createOpfsWorkerRuntime(
}
let receipt: unknown;
try {
receipt = await readJson(receiptPath(scope, transactionId));
receipt = await readReceipt(scope, transactionId);
} catch {
return { safeToSweep: false, digests };
}
if (receipt === undefined) continue;
if (!receiptBelongsToScope(receipt, scope)) {
return { safeToSweep: false, digests };
}
@@ -1147,7 +1175,7 @@ export function createOpfsWorkerRuntime(
}
if (
record.phase === "FILES_READY" &&
isPreparedObjectSafe(record.preparedObject, dependencies.policy) &&
isPreparedObject(record.preparedObject) &&
sameScope(record.preparedObject.descriptor.scope, scope)
) {
const prepared = record.preparedObject;
@@ -1207,6 +1235,21 @@ export function createOpfsWorkerRuntime(
);
await directory.removeEntry(fileName);
} else {
// R-5.2. A dedup hit must restart the chunk's grace period. Orphan GC
// reads "not referenced" from the page journal and deletes in the
// worker, so another tab's GC can hold a stale answer for a chunk that
// this put is about to reference once staging is gone. An atomic
// rewrite of the identical bytes refreshes lastModified, and readers of
// the committed chunk see either copy, never a partial file.
const { directory, fileName } = await resolveFileParent(
dependencies.root,
path,
false,
);
await writeWithAtomicWritable(
await directory.getFileHandle(fileName),
bytes,
);
return;
}
} catch (error) {
@@ -1257,8 +1300,31 @@ export function createOpfsWorkerRuntime(
await writeWithAtomicWritable(handle, bytes);
}
/**
* 05-02. `writeJsonAtomic` creates the file before its first write lands,
* so a first receipt write that hit the quota or a crash leaves a zero-byte
* file. BEGIN writes that receipt before any chunk or generation directory,
* so an empty receipt, like a missing one, has nothing to clean up.
*/
async function readReceipt(
scope: OpfsStorageScope,
transactionId: string,
): Promise<unknown> {
let bytes: Uint8Array;
try {
bytes = await readFile(receiptPath(scope, transactionId));
} catch (error) {
if (isNotFound(error)) return undefined;
throw error;
}
return bytes.byteLength === 0 ? undefined : parseJson(bytes);
}
async function readJson(path: readonly string[]): Promise<unknown> {
const bytes = await readFile(path);
return parseJson(await readFile(path));
}
function parseJson(bytes: Uint8Array): unknown {
if (bytes.byteLength > MAX_MANIFEST_BYTES) {
throw new OpfsRuntimeFailure("CORRUPT_DATA");
}
@@ -1285,6 +1351,35 @@ export function createOpfsWorkerRuntime(
throw new OpfsRuntimeFailure("UNSUPPORTED");
}
}
/**
* R-5.3 (D-3). The lock stays origin-wide so GC and dedup keep seeing one
* writer; only the wait is bounded. A request still queued after
* `mutationLockWaitTimeoutMs` leaves the queue and fails BLOCKED (retryable).
*/
async function acquireLease(
signal?: AbortSignal,
): Promise<OpfsMutationLease> {
const wait = createAbortableOperation({
signal,
timeoutMs: dependencies.policy.mutationLockWaitTimeoutMs,
});
// A lease granted after the wait already ended is handed straight back.
const outcome = await wait.race(
dependencies.leaseManager!.acquire(wait.signal),
(lease) => lease.release(),
);
wait.close();
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
if (outcome.terminal === "DEADLINE") {
throw new OpfsRuntimeFailure("BLOCKED", true);
}
throw new OpfsRuntimeFailure(
outcome.terminal === "CALLER_ABORT" ? "ABORTED" : "UNAVAILABLE",
outcome.terminal !== "CALLER_ABORT",
);
}
}
export function installOpfsWorkerMessageHandler(
@@ -1645,143 +1740,6 @@ function bytesToHex(bytes: Uint8Array): string {
return hex;
}
function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean"
) {
return JSON.stringify(value);
}
if (typeof value === "number") {
if (!Number.isFinite(value)) throw new OpfsRuntimeFailure("CORRUPT_DATA");
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new OpfsRuntimeFailure("CORRUPT_DATA");
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function isPreparedObjectSafe(
value: unknown,
policy: OpfsRuntimePolicy,
): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!policy.isObjectIdAllowed(descriptor.objectId) ||
!("scope" in descriptor) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(
descriptor.scope as OpfsPreparedObject["descriptor"]["scope"],
) ||
(descriptor.scope as OpfsPreparedObject["descriptor"]["scope"])
.namespace !==
(descriptor.storagePolicy as
| OpfsPreparedObject["descriptor"]["storagePolicy"]
| undefined)?.namespace ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
descriptor.byteLength > policy.maxObjectBytes ||
typeof descriptor.mediaType !== "string" ||
!policy.isMediaTypeAllowed(descriptor.mediaType) ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
integrity.chunkSizeBytes !== policy.chunkSizeBytes ||
!("storagePolicy" in descriptor) ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object" ||
value.chunks.length > policy.maxChunkCount
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
let total = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > policy.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (index < value.chunks.length - 1 && chunk.byteLength !== policy.chunkSizeBytes) {
return false;
}
total += chunk.byteLength;
}
return (
total === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / policy.chunkSizeBytes)
);
}
function success(
requestId: string,
kind: OpfsWorkerRequest["kind"],
+61 -25
View File
@@ -6,6 +6,10 @@ import type {
} from "../../contracts/telemetry.ts";
import type { TelemetryPort } from "../../application/ports/telemetry-port.ts";
import { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
import {
createTelemetryCollector,
type TelemetryCollector,
} from "./telemetry-collector.ts";
export type TelemetryAdapter = TelemetryPort &
Readonly<{
@@ -26,8 +30,25 @@ export type TelemetryAdapterOptions = Readonly<{
now?: () => number;
onDrop?: (event: TelemetryEvent) => void;
lifecycle?: Pick<EventTarget, "addEventListener" | "removeEventListener">;
/**
* Spec §27. Sink sends allowed per rolling minute (default 20). Beyond it
* events wait in the bounded queue until the window reopens; a sustained
* failure storm therefore cannot turn into one collector POST per failure.
*/
maxSendsPerMinute?: number;
/** Monotonic clock for the send-rate window (default `performance.now`). */
monotonicNow?: () => number;
setTimer?: (callback: () => void, ms: number) => unknown;
clearTimer?: (handle: unknown) => void;
/**
* Q-6.9-4. The collector transport shared with feature telemetry. When set,
* it owns `fetcher`, `lifecycle`, `maxSendsPerMinute` and `monotonicNow`.
*/
collector?: TelemetryCollector;
}>;
export { DEFAULT_TELEMETRY_SENDS_PER_MINUTE } from "./telemetry-collector.ts";
export const noOpTelemetry: TelemetryAdapter = Object.freeze({
emit: () => {},
flush: async () => {},
@@ -54,14 +75,29 @@ export function createTelemetryAdapter(
return noOpTelemetry;
}
const endpoint = options.endpoint;
const fetcher = options.fetcher ?? fetch;
const maxQueue = assertBoundedCapacity(
options.maxQueue ?? 100,
MAX_TELEMETRY_QUEUE,
"telemetry maxQueue",
);
const schedule = options.schedule ?? queueMicrotask;
const collector =
options.collector ??
createTelemetryCollector({
endpoint: options.endpoint,
...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
...(options.maxSendsPerMinute === undefined
? {}
: { maxSendsPerMinute: options.maxSendsPerMinute }),
...(options.monotonicNow === undefined ? {} : { now: options.monotonicNow }),
...(options.lifecycle === undefined ? {} : { lifecycle: options.lifecycle }),
});
const setTimer =
options.setTimer ?? ((callback: () => void, ms: number) => setTimeout(callback, ms));
const clearTimer =
options.clearTimer ??
((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
let rateTimer: unknown = null;
const queue: TelemetryEvent[] = [];
let lifecycleState: TelemetryLifecycle = "ACTIVE";
/** Scheduled callbacks captured before disposal must not run afterwards. */
@@ -72,12 +108,6 @@ export function createTelemetryAdapter(
let dropped = 0;
const dropReasons = new Map<string, number>();
let lastDeliveryEvidence: TelemetryEvent | null = null;
const lifecycle =
options.lifecycle ??
(typeof globalThis.addEventListener === "function" &&
typeof globalThis.removeEventListener === "function"
? globalThis
: undefined);
function recordDrop(reason: string, count = 1): void {
const safeReason =
@@ -146,31 +176,35 @@ export function createTelemetryAdapter(
scheduleFlush();
}
function armRateTimer(reopenIn: number): void {
if (rateTimer !== null || lifecycleState === "DISPOSED") return;
rateTimer = setTimer(() => {
rateTimer = null;
void flush();
}, reopenIn);
}
/**
* `flush()` joins the active delivery instead of resolving immediately, so an
* awaited flush really means "the in-flight batch has settled".
*/
function flush(): Promise<void> {
function flush(bypassRate = false): Promise<void> {
if (activeFlush) return activeFlush;
if (lifecycleState === "DISPOSED" || queue.length === 0) {
return Promise.resolve();
}
const reopenIn = collector.sendRate.take(bypassRate);
if (reopenIn > 0) {
armRateTimer(reopenIn);
return Promise.resolve();
}
const generation = scheduleGeneration;
const run = async () => {
const batch = queue.splice(0, queue.length);
const controller = new AbortController();
activeSink = controller;
try {
const response = await fetcher(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ events: batch }),
keepalive: true,
signal: controller.signal,
});
// A sink that ignored the abort must not update post-dispose state.
if (generation !== scheduleGeneration) return;
if (!response.ok) recordDrop("sink-failure", batch.length);
await collector.post(batch, controller.signal);
} catch {
if (generation !== scheduleGeneration) return;
recordDrop("sink-failure", batch.length);
@@ -186,10 +220,10 @@ export function createTelemetryAdapter(
return activeFlush;
}
const flushBeforePageExit = () => {
void flush();
};
lifecycle?.addEventListener("pagehide", flushBeforePageExit);
// Page exit is the last chance to deliver: it may exceed the window once.
const stopPageExitFlush = collector.onPageExit(() => {
void flush(true);
});
/**
* N-04. Terminal disposal: one state transition, no further admission, no
@@ -200,7 +234,9 @@ export function createTelemetryAdapter(
lifecycleState = "DISPOSED";
scheduleGeneration += 1;
scheduled = false;
lifecycle?.removeEventListener("pagehide", flushBeforePageExit);
stopPageExitFlush();
if (rateTimer !== null) clearTimer(rateTimer);
rateTimer = null;
queue.length = 0;
activeSink?.abort();
activeSink = null;
@@ -209,7 +245,7 @@ export function createTelemetryAdapter(
return Object.freeze({
emit,
flush,
flush: () => flush(),
pendingCount: () => queue.length,
droppedCount: () => dropped,
dropReasons: () => Object.freeze(Object.fromEntries(dropReasons)),
+115
View File
@@ -0,0 +1,115 @@
import {
createTelemetryPipeline,
DEFAULT_TELEMETRY_PIPELINE_BUDGET,
type TelemetryBatchItem,
type TelemetryPipeline,
type TelemetryPipelineBudget,
type TelemetryTransport,
} from "../../platform/telemetry/telemetry-pipeline.ts";
import {
createTelemetryCollector,
type TelemetryCollector,
} from "./telemetry-collector.ts";
/**
* Spec §24–§27. Adapter side of the provider-neutral feature telemetry port.
*
* Features emit through the platform `TelemetryPort`; only this adapter knows
* the collector protocol. A vendor SDK, if a product installs one, belongs in a
* transport here, never in feature code.
*/
export function createFetchTelemetryTransport(
options: Readonly<{
endpoint: string;
fetcher?: typeof fetch;
/** Q-6.9-4. Posts through this shared collector instead of a private one. */
collector?: TelemetryCollector;
/** Aborts in-flight batches (feature telemetry disposal). */
signal?: AbortSignal;
}>,
): TelemetryTransport {
const collector =
options.collector ??
createTelemetryCollector({
endpoint: options.endpoint,
...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
});
return Object.freeze({
send(batch: readonly TelemetryBatchItem[]): Promise<void> {
return collector.post(
batch.map((item) => ({
...item.event,
fingerprint: item.fingerprint,
occurrences: item.occurrences,
})),
options.signal,
);
},
});
}
const DISABLED_FEATURE_TELEMETRY: TelemetryPipeline = Object.freeze({
emit: () => Promise.resolve(),
flush: () => Promise.resolve(),
stats: () =>
Object.freeze({
accepted: 0,
invalid: 0,
deduplicated: 0,
sampledOut: 0,
dropped: 0,
sends: 0,
failedSends: 0,
buffered: 0,
bufferedBytes: 0,
peakBuffered: 0,
fingerprints: 0,
}),
dispose: () => {},
});
export function createFeatureTelemetry(
options: Readonly<{
enabled: boolean;
endpoint?: string;
fetcher?: typeof fetch;
budget?: TelemetryPipelineBudget;
/**
* Q-6.9-4. The collector shared with the application telemetry port: one
* send-rate window and one page-exit flush for the endpoint. When set, it
* owns `fetcher` and the send rate.
*/
collector?: TelemetryCollector;
}>,
): TelemetryPipeline {
if (!options.enabled || !options.endpoint) return DISABLED_FEATURE_TELEMETRY;
const budget = options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET;
const collector =
options.collector ??
createTelemetryCollector({
endpoint: options.endpoint,
...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
maxSendsPerMinute: budget.maxSendsPerMinute,
});
const lifetime = new AbortController();
const pipeline = createTelemetryPipeline({
transport: createFetchTelemetryTransport({
endpoint: options.endpoint,
collector,
signal: lifetime.signal,
}),
budget,
sendRate: collector.sendRate,
});
const stopPageExitFlush = collector.onPageExit(() => {
void pipeline.flush();
});
return Object.freeze({
...pipeline,
dispose(): void {
stopPageExitFlush();
lifetime.abort();
pipeline.dispose();
},
});
}
+11
View File
@@ -5,3 +5,14 @@ export {
type TelemetryAdapter,
type TelemetryAdapterOptions,
} from "./best-effort-telemetry.ts";
/** Spec §24–§27. 기능 소유 텔레메트리의 수집기 전송(공급자 중립 포트 뒤). */
export {
createFeatureTelemetry,
createFetchTelemetryTransport,
} from "./feature-telemetry.ts";
/** Q-6.9-4. 두 텔레메트리 포트가 공유하는 수집기 전송(rate·타임아웃·pagehide). */
export {
createTelemetryCollector,
type TelemetryCollector,
type TelemetryCollectorOptions,
} from "./telemetry-collector.ts";
@@ -0,0 +1,178 @@
import {
createTelemetrySendRate,
type TelemetrySendRate,
} from "../../platform/telemetry/telemetry-pipeline.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
/**
* Q-6.9-4. The one transport layer behind both telemetry ports.
*
* The application port (`best-effort-telemetry.ts`) and the feature port
* (`feature-telemetry.ts`) keep their own queue and body projection, but every
* POST to the collector goes through here: one send-rate window for the
* endpoint, no cookies, no HTTP cache, a deadline on every request, and one
* `pagehide` listener that flushes every queue.
*/
export type TelemetryCollector = Readonly<{
/** Spec §27. Shared by every queue posting to this collector. */
sendRate: TelemetrySendRate;
/**
* POSTs `{ events }`, split into bodies under the keepalive limit. Rejects
* when the collector refuses any part, the deadline passes, or `signal`
* aborts — a hung collector never stalls the caller's next flush.
*/
post(events: readonly unknown[], signal?: AbortSignal): Promise<void>;
/** Runs `flush` on `pagehide`. Returns the unsubscribe. */
onPageExit(flush: () => void): () => void;
}>;
export type TelemetryCollectorOptions = Readonly<{
endpoint: string;
fetcher?: typeof fetch;
/** Sends per rolling minute across every queue (default 20). */
maxSendsPerMinute?: number;
/** Per-request deadline (default 10s). */
timeoutMs?: number;
/** Monotonic clock for the send-rate window (default `performance.now`). */
now?: () => number;
lifecycle?: Pick<EventTarget, "addEventListener" | "removeEventListener">;
/**
* 13-11. Stamped on every event as `build_id` and `release_id`, so a
* failure rate can be split by release while old and new tabs coexist.
*/
release?: Readonly<{ buildId: string; releaseId: string }>;
}>;
export const DEFAULT_TELEMETRY_SENDS_PER_MINUTE = 20;
export const DEFAULT_TELEMETRY_TIMEOUT_MS = 10_000;
/** Also bounds the send-time window the rate keeps in memory. */
const MAX_SENDS_PER_MINUTE = 10_000;
const MAX_TIMEOUT_MS = 60_000;
/**
* 03-05. Fetch fails every keepalive request once the keepalive bodies in
* flight pass 64KiB. Bodies are split below that, and a body that would push
* this collector's in-flight keepalive total over the quota is sent without
* keepalive. A split batch still counts as one send against the rate.
*/
const KEEPALIVE_QUOTA_BYTES = 64 * 1024;
const MAX_BODY_BYTES = 60 * 1024;
const utf8 = new TextEncoder();
/** Same bytes as `JSON.stringify({ events })`, cut into bounded bodies. */
function splitBodies(events: readonly unknown[]): string[] {
const envelopeBytes = '{"events":[]}'.length;
const bodies: string[] = [];
let items: string[] = [];
let itemBytes = 0;
const cut = () => {
bodies.push(`{"events":[${items.join(",")}]}`);
items = [];
itemBytes = 0;
};
for (const event of events) {
const item = JSON.stringify(event) ?? "null";
const bytes = utf8.encode(item).byteLength + 1;
if (items.length > 0 && envelopeBytes + itemBytes + bytes > MAX_BODY_BYTES) {
cut();
}
items.push(item);
itemBytes += bytes;
}
if (items.length > 0 || bodies.length === 0) cut();
return bodies;
}
export function createTelemetryCollector(
options: TelemetryCollectorOptions,
): TelemetryCollector {
const { endpoint, release } = options;
const fetcher = options.fetcher ?? fetch;
const stamp = (event: unknown): unknown =>
release && event !== null && typeof event === "object" && !Array.isArray(event)
? { ...event, build_id: release.buildId, release_id: release.releaseId }
: event;
const timeoutMs = assertBoundedCapacity(
options.timeoutMs ?? DEFAULT_TELEMETRY_TIMEOUT_MS,
MAX_TIMEOUT_MS,
"telemetry timeoutMs",
);
const sendRate = createTelemetrySendRate(
assertBoundedCapacity(
options.maxSendsPerMinute ?? DEFAULT_TELEMETRY_SENDS_PER_MINUTE,
MAX_SENDS_PER_MINUTE,
"telemetry maxSendsPerMinute",
),
options.now,
);
const lifecycle =
options.lifecycle ??
(typeof globalThis.addEventListener === "function" &&
typeof globalThis.removeEventListener === "function"
? globalThis
: undefined);
const exitFlushes = new Set<() => void>();
const onPageHide = () => {
for (const flush of [...exitFlushes]) flush();
};
let inflightKeepaliveBytes = 0;
async function send(body: string, signal?: AbortSignal): Promise<void> {
const bytes = utf8.encode(body).byteLength;
const keepalive = inflightKeepaliveBytes + bytes <= KEEPALIVE_QUOTA_BYTES;
if (keepalive) inflightKeepaliveBytes += bytes;
const operation = createAbortableOperation({
...(signal === undefined ? {} : { signal }),
timeoutMs,
});
try {
const outcome = await operation.race(
Promise.resolve(
fetcher(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body,
keepalive,
credentials: "omit",
cache: "no-store",
signal: operation.signal,
}),
),
);
if (outcome.kind !== "VALUE" || !outcome.value.ok) {
throw new Error("telemetry collector did not accept the batch");
}
} finally {
operation.close();
if (keepalive) inflightKeepaliveBytes -= bytes;
}
}
async function post(
events: readonly unknown[],
signal?: AbortSignal,
): Promise<void> {
// Sent together so a page-exit flush dispatches every part at once.
await Promise.all(
splitBodies(events.map(stamp)).map((body) => send(body, signal)),
);
}
return Object.freeze({
sendRate,
post,
onPageExit(flush: () => void): () => void {
// The listener exists only while some queue wants a page-exit flush.
if (exitFlushes.size === 0) {
lifecycle?.addEventListener("pagehide", onPageHide);
}
exitFlushes.add(flush);
return () => {
if (exitFlushes.delete(flush) && exitFlushes.size === 0) {
lifecycle?.removeEventListener("pagehide", onPageHide);
}
};
},
});
}
+101
View File
@@ -0,0 +1,101 @@
import type { PushAuthoritySnapshot } from "../../contracts/web-push.ts";
/**
* Q-6.6-12. The validation primitives every web-push codec shares. Each file
* used to carry its own copy, and the copies had drifted: one authority check
* threw on `null`, one base64url decoder accepted a lone trailing character.
* Where they differed, the stricter behavior is the one kept here.
*/
/** Opaque ids: bounded, ASCII, starting with an alphanumeric. */
export const OPAQUE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
export function validOpaqueId(value: unknown): value is string {
return typeof value === "string" && OPAQUE_ID.test(value);
}
export function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
/** `expected` must be sorted; the record's own keys must equal it exactly. */
export function hasExactKeys(
value: Record<string, unknown>,
expected: readonly string[],
): boolean {
const actual = Object.keys(value).sort();
return (
actual.length === expected.length &&
actual.every((key, index) => key === expected[index])
);
}
export function exactRecord(
value: unknown,
expected: readonly string[],
): value is Record<string, unknown> {
return isRecord(value) && hasExactKeys(value, expected);
}
/** A missing or non-object authority is invalid input, never a TypeError. */
export function validAuthority(value: unknown): value is PushAuthoritySnapshot {
return (
isRecord(value) &&
validOpaqueId(value.fenceGeneration) &&
validOpaqueId(value.sessionBindingEpoch) &&
validOpaqueId(value.releaseEpoch)
);
}
const BASE64URL_ALPHABET =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
/**
* Unpadded base64url. Rejects non-strings, characters outside the alphabet,
* a lone trailing character (6 bits cannot finish a byte) and non-zero spare
* bits, so every accepted string has exactly one decoding.
*/
export function base64UrlDecode(value: unknown): Uint8Array<ArrayBuffer> | null {
if (typeof value !== "string") return null;
const output = new Uint8Array(
new ArrayBuffer(Math.floor((value.length * 6) / 8)),
);
let accumulator = 0;
let bitCount = 0;
let outputIndex = 0;
for (const character of value) {
const digit = BASE64URL_ALPHABET.indexOf(character);
if (digit < 0) return null;
accumulator = (accumulator << 6) | digit;
bitCount += 6;
if (bitCount >= 8) {
bitCount -= 8;
output[outputIndex] = (accumulator >>> bitCount) & 0xff;
outputIndex += 1;
}
}
return bitCount < 6 &&
outputIndex === output.length &&
(accumulator & ((1 << bitCount) - 1)) === 0
? output
: null;
}
/** Unpadded base64url with zero spare bits: the inverse of the decoder. */
export function base64UrlEncode(bytes: Uint8Array): string {
let output = "";
let accumulator = 0;
let bitCount = 0;
for (const byte of bytes) {
accumulator = (accumulator << 8) | byte;
bitCount += 8;
while (bitCount >= 6) {
bitCount -= 6;
output += BASE64URL_ALPHABET[(accumulator >>> bitCount) & 63];
}
}
if (bitCount > 0) {
output += BASE64URL_ALPHABET[(accumulator << (6 - bitCount)) & 63];
}
return output;
}
@@ -84,6 +84,11 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
fenceStore: PushAssociationFenceStore;
clients: WorkerClientsFacade;
origin: string;
/**
* 06-09. Where a refused click opens: the registration scope, which is the
* router base path. Defaults to the origin root; must be same-origin.
*/
appRootUrl?: string;
now?: () => number;
handlerDeadlineMs?: number;
scheduler?: TimeoutScheduler;
@@ -104,6 +109,11 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
throw new TypeError("Web Push click adapter configuration is invalid.");
}
const origin: string = parsedOrigin;
const parsedAppRootUrl = safeTarget(origin, dependencies.appRootUrl ?? "/");
if (!parsedAppRootUrl) {
throw new TypeError("Web Push click adapter configuration is invalid.");
}
const appRootUrl: string = parsedAppRootUrl;
return Object.freeze({
handle(event) {
@@ -125,7 +135,12 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
tails: [],
};
const processing = withAbortableDeadline(
(signal) => process(event.notification.data, signal, effect),
async (signal) =>
openAppRootIfRejected(
await process(event.notification.data, signal, effect),
signal,
effect,
),
{
deadlineMs: handlerDeadlineMs,
operation: "NOTIFICATION_CLICK",
@@ -206,49 +221,6 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
expiresAt: decoded.value.expiresAt,
path,
});
// WP-RR-01. `focus` and `openWindow` are user-visible native effects, so
// they carry the same certainty phase `showNotification` already does:
// NOT_APPLIED before the call, MAYBE_APPLIED while the promise is pending,
// CONFIRMED on fulfilment. An effect that lands after this handler's
// deadline is still observed exactly once — as evidence only, never as
// authorization to retry.
const observeLateEffect = (
pending: Promise<unknown>,
appliedWhen: (value: unknown) => boolean,
): void => {
let observed = false;
// WP-01. The tail is tracked so `waitUntil` owns it. Certainty is
// monotone: once the native call has been made the effect can only be
// confirmed or stay uncertain. A rejection says the call did not report
// success, not that it never happened, so downgrading it to NOT_APPLIED
// told operators the click had definitely not been applied.
effect.tails.push(
pending.then(
(value) => {
if (observed) return;
observed = true;
const applied = appliedWhen(value);
effect.certainty = applied ? "CONFIRMED" : "NOT_APPLIED";
observeWebPush(dependencies.observer, {
event: "web_push_click_dispatched",
outcome: applied ? "DEGRADED" : "FAILED",
reason: "ABORTED",
nativeEffect: effect.certainty,
});
},
() => {
if (observed) return;
observed = true;
observeWebPush(dependencies.observer, {
event: "web_push_click_dispatched",
outcome: "DEGRADED",
reason: "ABORTED",
nativeEffect: "MAYBE_APPLIED",
});
},
),
);
};
try {
if (signal.aborted) {
return webPushFailure("ABORTED", "NOTIFICATION_CLICK");
@@ -259,26 +231,16 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
effect.certainty = "MAYBE_APPLIED";
const raced = await raceAbort(focused, signal);
if (raced === ABORT_OWNED) {
observeLateEffect(focused, () => true);
observeLateEffect(effect, focused, () => true);
return webPushFailure("ABORTED", "NOTIFICATION_CLICK");
}
effect.certainty = "CONFIRMED";
} else {
const opening = Promise.resolve(
dependencies.clients.openWindow(target),
);
effect.certainty = "MAYBE_APPLIED";
const raced = await raceAbort(opening, signal);
if (raced === ABORT_OWNED) {
observeLateEffect(opening, (value) => value !== null);
const opened = await openWindowBounded(target, signal, effect);
if (opened === ABORT_OWNED) {
return webPushFailure("ABORTED", "NOTIFICATION_CLICK");
}
if (!raced) {
// An explicit null is the one answer that confirms no window opened.
effect.certainty = "NOT_APPLIED";
return nativeFailure("NOTIFICATION_CLICK", true);
}
effect.certainty = "CONFIRMED";
if (!opened) return nativeFailure("NOTIFICATION_CLICK", true);
}
if (signal.aborted) {
return webPushFailure("ABORTED", "NOTIFICATION_CLICK");
@@ -291,6 +253,103 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
return webPushSuccess(undefined);
}
/**
* Q-6.6-11 / D-14. A click whose data or authority was refused (expired,
* fence or release mismatch, unreadable fence, unknown route) still opens
* the app at its root (06-09: the router base path) with no handoff data,
* so the user's tap is never silently dropped. The refusal stays the
* result. Native failures (the browser refused a window) and aborts are not
* retried.
*/
async function openAppRootIfRejected(
result: WebPushResult<void>,
signal: AbortSignal,
effect: ClickEffectState,
): Promise<WebPushResult<void>> {
// Every failure after a native window call is ABORTED or NATIVE_FAILURE,
// so the rest are refusals made before any window was touched.
if (
result.ok ||
result.error.code === "NATIVE_FAILURE" ||
result.error.code === "ABORTED" ||
signal.aborted
) {
return result;
}
await openWindowBounded(appRootUrl, signal, effect).catch(() => {
// The native call threw: whether a window opened is unknown.
});
return result;
}
/**
* WP-RR-01. `openWindow` bounded by the handler signal: MAYBE_APPLIED while
* pending, then CONFIRMED, or NOT_APPLIED for an explicit null (the one
* answer that confirms no window opened). A late result is still observed.
*/
async function openWindowBounded(
url: string,
signal: AbortSignal,
effect: ClickEffectState,
): Promise<boolean | typeof ABORT_OWNED> {
const opening = Promise.resolve(dependencies.clients.openWindow(url));
effect.certainty = "MAYBE_APPLIED";
const raced = await raceAbort(opening, signal);
if (raced === ABORT_OWNED) {
observeLateEffect(effect, opening, (value) => value !== null);
return ABORT_OWNED;
}
effect.certainty = raced ? "CONFIRMED" : "NOT_APPLIED";
return raced !== null;
}
/**
* WP-RR-01. `focus` and `openWindow` are user-visible native effects, so
* they carry the same certainty phase `showNotification` already does:
* NOT_APPLIED before the call, MAYBE_APPLIED while the promise is pending,
* CONFIRMED on fulfilment. An effect that lands after this handler's
* deadline is still observed exactly once — as evidence only, never as
* authorization to retry.
*/
function observeLateEffect(
effect: ClickEffectState,
pending: Promise<unknown>,
appliedWhen: (value: unknown) => boolean,
): void {
let observed = false;
// WP-01. The tail is tracked so `waitUntil` owns it. Certainty is
// monotone: once the native call has been made the effect can only be
// confirmed or stay uncertain. A rejection says the call did not report
// success, not that it never happened, so downgrading it to NOT_APPLIED
// told operators the click had definitely not been applied.
effect.tails.push(
pending.then(
(value) => {
if (observed) return;
observed = true;
const applied = appliedWhen(value);
effect.certainty = applied ? "CONFIRMED" : "NOT_APPLIED";
observeWebPush(dependencies.observer, {
event: "web_push_click_dispatched",
outcome: applied ? "DEGRADED" : "FAILED",
reason: "ABORTED",
nativeEffect: effect.certainty,
});
},
() => {
if (observed) return;
observed = true;
observeWebPush(dependencies.observer, {
event: "web_push_click_dispatched",
outcome: "DEGRADED",
reason: "ABORTED",
nativeEffect: "MAYBE_APPLIED",
});
},
),
);
}
async function validateActiveFence(
associationEpoch: string,
releaseEpoch: string,

Some files were not shown because too many files have changed in this diff Show More