donghyeon.kang/clean-architecture-frontend-template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

fix: make OPFS finalization and public cache repair failure-atomic

Browse Source 
STO-RR-01. finalizePut re-acquired the origin mutation lease it was already
holding. A Web Lock is not reentrant, so an ordinary PUT stopped for good at
FINALIZE; it now calls the locked cleanup directly. A strict non-reentrant fake
lease manager pins one acquire and one release per finalization. The adapter no
longer reports a failed finalization as a plain write success either: the
journal row stays COMMITTED for reconciliation, but the caller is told the
write did not settle.

STO-RR-02. A failure raised while serving a validated request now carries that
request's kind. Defaulting every catch to CAPABILITIES made the client's own
expected-kind check reject genuine quota, integrity and abort failures as
protocol breaches and report them as UNSUPPORTED. Only an envelope the runtime
could not read still answers at protocol level.

STO-RR-03. The worker client decodes a response instead of adopting it: exact
own-data descriptors, the negotiated protocol version, the exact awaited kind,
a code inside the closed BrowserDataFailure set and a boolean retryable. An
accessor, a proxy trap, an inherited or extra field and an unknown code all
close the call as UNSUPPORTED rather than leaving it to time out.

STO-RR-04. A marker read that fails transiently is unknown, not damaged, so it
no longer deletes the candidate that may be serving traffic. Only a confirmed
corrupt or missing marker enters the repair path.

STO-RR-05. Staging never deletes a candidate it did not create. A repair
replaces exact entries in place, so a failed fetch leaves every healthy asset
and the active release usable; a candidate this call created is still removed
on failure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-08-14 14:00:41 +09:00
co-authored by Claude Opus 5
parent ca210d3bc5
commit 6a8281a941
8 changed files with 785 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/adapters/cache-storage/public-response-cache-adapter.ts
+18 -5
View File
@@ -419,13 +419,23 @@ export function createPublicResponseCacheAdapter(
normalized.manifestDigestHex,
);
const existingNames = await dependencies.cacheStorage!.keys();
if (existingNames.includes(cacheName)) {
// STO-RR-05. A candidate this call did not create may be the one
// currently serving traffic, so nothing about it is deleted before
// a replacement has been fetched and verified.
const preExistingCandidate = existingNames.includes(cacheName);
if (preExistingCandidate) {
const existing = await dependencies.cacheStorage!.open(cacheName);
const marker = await readMarker(
existing,
policy,
dependencies.crypto,
);
if (!marker.ok && marker.error.code !== "CORRUPT_DATA") {
// STO-RR-04. A marker that could not be read is unknown, not
// damaged. Treating a transient storage error as proof of
// corruption would delete a healthy active release.
return rebaseFailure(marker.error, "CACHE_STAGE");
}
if (
marker.ok &&
marker.value &&
@@ -455,9 +465,6 @@ export function createPublicResponseCacheAdapter(
return verified.failure;
}
}
// Only this owned candidate is removed; the network restage below
// repairs it.
await dependencies.cacheStorage!.delete(cacheName);
}
const cache = await dependencies.cacheStorage!.open(cacheName);
@@ -513,7 +520,13 @@ export function createPublicResponseCacheAdapter(
);
return browserDataSuccess(summaryFromMarker(marker));
} catch (error) {
await dependencies.cacheStorage!.delete(cacheName);
// STO-RR-05. Only a candidate this call created is removed. A
// repair that failed part-way leaves every entry it did replace
// and every entry it never touched in place, so the release that
// was serving traffic before still is.
if (!preExistingCandidate) {
await dependencies.cacheStorage!.delete(cacheName);
}
throw error;
}
},
src/adapters/storage/opfs/opfs-byte-store-adapter.ts
+15 -4
View File
@@ -312,12 +312,23 @@ export function createOpfsByteStoreAdapter(
prepared.value,
request.signal,
);
if (finalized.ok) {
await dependencies.journal.complete(
transactionId,
begun.value.fencingToken,
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!,
);
}
await dependencies.journal.complete(
transactionId,
begun.value.fencingToken,
);
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_WRITE",
outcome: "SUCCEEDED",
src/adapters/storage/opfs/opfs-worker-client.ts
+120 -41
View File
@@ -3,11 +3,12 @@ import type {
OpfsCleanupEffect,
OpfsPreparedObject,
} from "../../../application/ports/browser-file-storage/opfs-ports.ts";
import type {
BrowserDataFailureCode,
BrowserDataOperation,
BrowserDataResult,
ByteSource,
import {
isBrowserDataFailureCode,
type BrowserDataFailureCode,
type BrowserDataOperation,
type BrowserDataResult,
type ByteSource,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
@@ -91,21 +92,25 @@ export function createOpfsWorkerGateway(
const onMessage = (event: MessageEvent<unknown>): void => {
if (disposed) return;
if (!isWorkerResponse(event.data)) return;
const request = pending.get(event.data.requestId);
const requestId = ownStringField(event.data, "requestId");
if (requestId === null) return;
const request = pending.get(requestId);
if (!request) return;
pending.delete(event.data.requestId);
pending.delete(requestId);
clearTimeout(request.timeout);
request.removeAbortListener();
if (event.data.kind !== request.expectedKind) {
// STO-07. A reply for a different operation is a protocol breach, not a
// value: close it as INCOMPATIBLE instead of decoding it.
// UNSUPPORTED is the closed-taxonomy code for "this runtime
// cannot serve this"; no new failure code is invented.
// STO-07 / STO-RR-03. A reply is decoded, never adopted. A different
// operation, an unknown kind, an unknown failure code, an inherited or
// extra field and a hostile accessor are all protocol breaches, and each
// closes the request rather than leaving it to time out.
// UNSUPPORTED is the closed-taxonomy code for "this runtime cannot serve
// this"; no new failure code is invented.
const decoded = decodeWorkerResponse(event.data, request.expectedKind);
if (decoded === null) {
request.reject(new OpfsRpcError("UNSUPPORTED"));
return;
}
request.resolve(event.data);
request.resolve(decoded);
};
const onWorkerFailure = (): void => {
if (disposed) return;
@@ -697,34 +702,108 @@ function parseOrphanDeleteResult(
}
/**
* STO-07. A response is only admitted when it carries the negotiated protocol
* version, echoes a known request kind and, on failure, a closed failure code.
* Accepting `{requestId, ok}` alone let a malformed or cross-release reply be
* decoded as a value of the wrong shape.
* STO-07 / STO-RR-03. A response is admitted only when every field survives an
* exact own-data decode: the negotiated protocol version, the exact request
* kind this call is waiting for and, on failure, a code inside the closed
* `BrowserDataFailure` taxonomy with a boolean `retryable`.
*
* The decoder returns a fresh frozen value, so a worker that mutates its own
* message object after posting it cannot change what the caller already read.
*/
function isWorkerResponse(value: unknown): value is OpfsWorkerResponse {
if (
!value ||
typeof value !== "object" ||
!("requestId" in value) ||
typeof value.requestId !== "string" ||
!("ok" in value) ||
typeof value.ok !== "boolean" ||
!("protocolVersion" in value) ||
value.protocolVersion !== OPFS_WORKER_PROTOCOL_VERSION ||
!("kind" in value) ||
typeof value.kind !== "string"
) {
const WORKER_RESPONSE_KEYS: ReadonlySet<string> = new Set([
"requestId",
"protocolVersion",
"kind",
"ok",
"value",
"failure",
]);
const WORKER_FAILURE_KEYS: ReadonlySet<string> = new Set(["code", "retryable"]);
/** Reads one own data property, treating an accessor or a trap as absent. */
function ownField(source: unknown, key: string): unknown {
if (source === null || typeof source !== "object") return undefined;
try {
const descriptor = Object.getOwnPropertyDescriptor(source, key);
if (!descriptor || !("value" in descriptor)) return undefined;
return descriptor.value;
} catch {
return undefined;
}
}
function ownStringField(source: unknown, key: string): string | null {
const value = ownField(source, key);
return typeof value === "string" && value.length > 0 ? value : null;
}
function hasOnlyOwnDataKeys(
source: object,
allowed: ReadonlySet<string>,
): boolean {
try {
if (Object.getOwnPropertySymbols(source).length > 0) return false;
for (const key of Object.getOwnPropertyNames(source)) {
if (!allowed.has(key)) return false;
const descriptor = Object.getOwnPropertyDescriptor(source, key);
if (!descriptor || !("value" in descriptor)) return false;
}
return true;
} catch {
return false;
}
if (value.ok) return true;
const failure = (value as { failure?: unknown }).failure;
return Boolean(
failure &&
typeof failure === "object" &&
"code" in failure &&
typeof (failure as { code?: unknown }).code === "string" &&
"retryable" in failure &&
typeof (failure as { retryable?: unknown }).retryable === "boolean",
);
}
function decodeWorkerResponse(
value: unknown,
expectedKind: OpfsWorkerRequest["kind"],
): OpfsWorkerResponse | null {
if (value === null || typeof value !== "object") return null;
if (!hasOnlyOwnDataKeys(value, WORKER_RESPONSE_KEYS)) return null;
const requestId = ownStringField(value, "requestId");
if (requestId === null || requestId.length > 128) return null;
if (ownField(value, "protocolVersion") !== OPFS_WORKER_PROTOCOL_VERSION) {
return null;
}
if (ownField(value, "kind") !== expectedKind) return null;
const ok = ownField(value, "ok");
if (typeof ok !== "boolean") return null;
if (ok) {
if (Object.hasOwn(value, "failure")) return null;
return Object.freeze(
Object.hasOwn(value, "value")
? {
requestId,
protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
kind: expectedKind,
ok: true,
value: ownField(value, "value"),
}
: {
requestId,
protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
kind: expectedKind,
ok: true,
},
) as OpfsWorkerResponse;
}
if (Object.hasOwn(value, "value")) return null;
const failure = ownField(value, "failure");
if (failure === null || typeof failure !== "object") return null;
if (!hasOnlyOwnDataKeys(failure, WORKER_FAILURE_KEYS)) return null;
const code = ownField(failure, "code");
const retryable = ownField(failure, "retryable");
if (!isBrowserDataFailureCode(code) || typeof retryable !== "boolean") {
return null;
}
return Object.freeze({
requestId,
protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
kind: expectedKind,
ok: false,
failure: Object.freeze({ code, retryable }),
}) as OpfsWorkerResponse;
}
src/adapters/storage/opfs/opfs-worker-runtime.ts
+21 -6
View File
@@ -199,10 +199,15 @@ export function createOpfsWorkerRuntime(
return Object.freeze({
async handleRequest(request: unknown) {
if (!hasRequestId(request)) return null;
if (!isWorkerRequest(request)) {
// STO-RR-02. Only an envelope this runtime could not read produces a
// protocol-level failure. Everything below answers its own request.
return failure(
request.requestId,
mapRuntimeFailure(new OpfsRuntimeFailure("INVALID_INPUT")),
);
}
try {
if (!isWorkerRequest(request)) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
switch (request.kind) {
case "CAPABILITIES":
return success(request.requestId, request.kind, capabilities);
@@ -289,7 +294,14 @@ export function createOpfsWorkerRuntime(
);
}
} catch (error) {
return failure(request.requestId, mapRuntimeFailure(error));
// STO-RR-02. The kind travels with the failure so the client's
// expected-kind check cannot mistake a quota, integrity or abort
// failure for a protocol breach.
return failure(
request.requestId,
mapRuntimeFailure(error),
request.kind,
);
}
},
});
@@ -911,10 +923,13 @@ export function createOpfsWorkerRuntime(
await objectDirectory.removeEntry(name, { recursive: true });
}
}
await cleanupTransaction(descriptor.scope, transactionId, false);
// STO-RR-01. This path already holds the origin mutation lease, and a
// Web Lock is not reentrant: asking for it again here never returns, so
// an ordinary PUT would stop for good at FINALIZE.
await cleanupTransactionLocked(descriptor.scope, transactionId, false);
} catch (error) {
if (!isNotFound(error)) throw error;
await cleanupTransaction(
await cleanupTransactionLocked(
preparedObject.descriptor.scope,
transactionId,
false,
src/application/ports/browser-file-storage/shared.ts
+36 -18
View File
@@ -1,24 +1,42 @@
import type { Result } from "../../result.ts";
/**
* STO-RR-03. The runtime membership set behind the closed failure taxonomy. A
* boundary decoder needs to test a value against it, and a type alone cannot
* stop an arbitrary string from reaching application code.
*/
export const BROWSER_DATA_FAILURE_CODES = Object.freeze([
"ABORTED",
"BLOCKED",
"CONFLICT",
"CORRUPT_DATA",
"EXPIRED_RESOURCE",
"INTEGRITY_FAILED",
"INVALID_INPUT",
"LIMIT_EXCEEDED",
"MIGRATION_FAILED",
"NOT_FOUND",
"NOT_READABLE",
"PERMISSION_DENIED",
"POLICY_REJECTED",
"QUOTA_EXCEEDED",
"STALE_RESULT",
"STORAGE_EVICTED",
"UNAVAILABLE",
"UNSUPPORTED",
] as const);
export function isBrowserDataFailureCode(
value: unknown,
): value is BrowserDataFailureCode {
return (
typeof value === "string" &&
(BROWSER_DATA_FAILURE_CODES as readonly string[]).includes(value)
);
}
export type BrowserDataFailureCode =
| "ABORTED"
| "BLOCKED"
| "CONFLICT"
| "CORRUPT_DATA"
| "EXPIRED_RESOURCE"
| "INTEGRITY_FAILED"
| "INVALID_INPUT"
| "LIMIT_EXCEEDED"
| "MIGRATION_FAILED"
| "NOT_FOUND"
| "NOT_READABLE"
| "PERMISSION_DENIED"
| "POLICY_REJECTED"
| "QUOTA_EXCEEDED"
| "STALE_RESULT"
| "STORAGE_EVICTED"
| "UNAVAILABLE"
| "UNSUPPORTED";
(typeof BROWSER_DATA_FAILURE_CODES)[number];
export type BrowserDataOperation =
| "CACHE_ACTIVATE"