diff --git a/config/recipes/frontend-capability-recipes.json b/config/recipes/frontend-capability-recipes.json index e73456c9..352d35bb 100644 --- a/config/recipes/frontend-capability-recipes.json +++ b/config/recipes/frontend-capability-recipes.json @@ -104,7 +104,7 @@ "forbiddenWhen": ["The data contains credentials.", "The browser would connect directly to a server database or object store.", "A normal HTTP cache is sufficient.", "Partition, retention, quota and recovery ownership are undefined."], "boundary": "feature-specific async repository with registry-issued opaque dataset scope and immutable full-policy binding, plus an OPFS large-object sidecar whose logical commit authority and bidirectional scope binding are owned by an IndexedDB journal", "port": "IndexedDbRepositoryPort / IndexedDbMaintenancePort / DurableObjectStorePort / DurableObjectMaintenancePort / StorageDurabilityPort", - "fake": "MemoryStructuredOfflineStore / MemoryDurableObjectStore / MemoryStorageDurabilityAdapter", + "fake": "MemoryDurableObjectStore / MemoryStorageDurabilityAdapter (no recipe fake implements IndexedDbRepositoryPort; run the reference runtime on tests/helpers/memory-indexeddb.ts)", "failureKinds": ["open-blocked", "versionchange", "quota", "corruption", "migration-rollback", "revision-conflict", "storage-eviction", "partial-object-write", "dataset-binding-mismatch", "dataset-budget-exceeded", "lifecycle-authorization-denied", "expired-resource"], "lifecycleMethods": ["close", "cancel-via-AbortSignal", "enforce-bounded-lifecycle-batch", "prune-expired-receipts", "reconcile", "enforcePolicies-with-composition-authority"], "owner": "project-owner-required", diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 7dd307ac..eeeff3f0 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -19,8 +19,8 @@ production readiness를 뜻하지 않는다. | TypeScript port | `recipes/frontend-capabilities/contracts.ts` | 아니오 | | fake/unavailable | `recipes/frontend-capabilities/fake-adapters.ts` | 아니오 | | contract test | `tests/recipes/optional-capability-contracts.test.ts` | 아니오 | -| file/IndexedDB/OPFS/Cache 심층 계약 | `recipes/frontend-capabilities/browser-file-storage-contracts.ts` | 아니오 | -| 심층 deterministic fake | `recipes/frontend-capabilities/browser-file-storage-fakes.ts` | 아니오 | +| file/IndexedDB/OPFS/Cache 심층 계약. reference runtime이 있는 port는 복사하지 않고 `src/application/ports`의 port를 다시 내보낸다([0929] 05-03) | `recipes/frontend-capabilities/browser-file-storage-contracts.ts` | 아니오 | +| 심층 deterministic fake. file·storage durability·OPFS fake는 `src` port를 `implements`한다 | `recipes/frontend-capabilities/browser-file-storage-fakes.ts` | 아니오 | | 심층 contract test | `tests/recipes/browser-file-storage-contracts.test.ts` | 아니오 | | browser data current-status ledger | `docs/architecture/browser-data-capability-completion-ledger.md` | 문서만 | | 심층 설계/ADR | `docs/architecture/browser-file-and-origin-storage.md`, `decisions/VD-11-browser-file-and-origin-storage.md` | 문서만 | diff --git a/recipes/frontend-capabilities/browser-file-storage-contracts.ts b/recipes/frontend-capabilities/browser-file-storage-contracts.ts index c3df3694..8f05603b 100644 --- a/recipes/frontend-capabilities/browser-file-storage-contracts.ts +++ b/recipes/frontend-capabilities/browser-file-storage-contracts.ts @@ -1,8 +1,17 @@ +import type { CapabilityResult } from "./contracts.ts"; import type { - CapabilityResult, - Cleanup, - TransferProgress, -} from "./contracts.ts"; + DownloadDeliveryPort, + DownloadStrategy, + DurableObjectMaintenancePort, + DurableObjectStorePort, + FileContentPort, + FilePickerPort, + FilePolicyReference, + PersistableDataClass, + PublicCacheInspection, + StorageDurabilityPort, + TransientPreviewPort, +} from "../../src/application/ports/browser-file-storage/index.ts"; /** * Deep opt-in contracts for browser file and origin-storage capabilities. @@ -12,14 +21,54 @@ import type { * copies and narrows only the ports that its product actually owns. */ +/** + * [0929] 05-03. A port that has a reference runtime under `src/` is not + * copied here. The copies kept their July shape while the runtime ports moved + * on, so a fake written against a recipe copy promised behaviour the runtime + * does not have. These names are the `src/application/ports` types themselves. + * Removing that runtime removes this file and its fakes with it + * (`scripts/test-browser-file-storage-runtime-removal.ts`). + */ +export type { + BrowserManagedDownloadCapability, + BrowserManagedDownloadCapabilityReceipt, + BrowserManagedDownloadCapabilityResolver, + DownloadDeliveryPort, + DownloadOutcome, + DownloadSource, + DownloadStrategy, + DurableObjectDescriptor, + DurableObjectMaintenancePort, + DurableObjectStorePort, + FileByteSource, + FileCandidate, + FileContentPort, + FileInspection, + FilePickerPort, + FilePickerSupport, + FilePolicyIntention, + FilePolicyKey, + FilePolicyReference, + FileSelectionLimitReduction, + FileSelectionOutcome, + FileSelectionSource, + FileSignatureResult, + FileVerificationReceipt, + LocalFileRef, + PersistableDataClass, + PreviewLease, + PublicCacheInspection, + StorageDurabilityPort, + StorageEstimate, + TransferProgress, + TransientPreviewPort, +} from "../../src/application/ports/browser-file-storage/index.ts"; +export type { + AuthorizedDownloadCapability, + AuthorizedDownloadCapabilityReceipt, +} from "../../src/application/ports/browser-transfer/index.ts"; + declare const byteCountBrand: unique symbol; -declare const localFileRefBrand: unique symbol; -declare const fileVerificationReceiptBrand: unique symbol; -declare const filePolicyKeyBrand: unique symbol; -declare const filePolicyIntentionBrand: unique symbol; -declare const browserManagedCapabilityReceiptBrand: unique symbol; -declare const authorizedDownloadCapabilityBrand: unique symbol; -declare const authorizedDownloadCapabilityReceiptBrand: unique symbol; declare const objectIdBrand: unique symbol; declare const objectGenerationBrand: unique symbol; @@ -27,62 +76,10 @@ export type ByteCount = number & { readonly [byteCountBrand]: "ByteCount"; }; -export type LocalFileRef = string & { - readonly [localFileRefBrand]: "LocalFileRef"; -}; - -export type FileVerificationReceipt = string & { - readonly [fileVerificationReceiptBrand]: "FileVerificationReceipt"; -}; - -export type FilePolicyKey = string & { - readonly [filePolicyKeyBrand]: "FilePolicyKey"; -}; - -export type FilePolicyIntention = string & { - readonly [filePolicyIntentionBrand]: "FilePolicyIntention"; -}; - /** - * Composition-issued capability selector. Implementations must resolve the - * exact registered object identity, not merely an equal string pair. + * Recipe-only brands for a durable object's id and generation. The runtime + * port takes plain values; a branded one is still accepted there. */ -export type FilePolicyReference = Readonly<{ - policyKey: FilePolicyKey; - intention: FilePolicyIntention; -}>; - -export type BrowserManagedDownloadCapabilityReceipt = string & { - readonly [browserManagedCapabilityReceiptBrand]: - "BrowserManagedDownloadCapabilityReceipt"; -}; - -export type AuthorizedDownloadCapabilityReceipt = string & { - readonly [authorizedDownloadCapabilityReceiptBrand]: - "AuthorizedDownloadCapabilityReceipt"; -}; - -/** - * GET-only provider-issued handle. The corresponding URL, signed query and - * headers stay inside the selected transfer adapter's in-memory identity - * vault; a feature cannot replace them or supply its own digest. - */ -export type AuthorizedDownloadCapability = Readonly<{ - capabilityReceipt: AuthorizedDownloadCapabilityReceipt; - method: "GET"; - binding: Readonly<{ - kind: "DOWNLOAD"; - resourceId: string; - }>; - mediaType: string; - byteLength: ByteCount; - maxBytes: ByteCount; - expectedSha256: string; - expiresAtEpochMs: number; - readonly [authorizedDownloadCapabilityBrand]: - "AuthorizedDownloadCapability"; -}>; - export type DurableObjectId = string & { readonly [objectIdBrand]: "DurableObjectId"; }; @@ -91,17 +88,6 @@ export type ObjectGeneration = number & { readonly [objectGenerationBrand]: "ObjectGeneration"; }; -export type PersistableDataClass = - | "PUBLIC" - | "INTERNAL" - | "PERSONAL" - | "CONFIDENTIAL"; - -export type FileSelectionSource = - | "NATIVE_INPUT" - | "SYSTEM_PICKER" - | "DROP"; - export type FileAcceptRule = Readonly<{ mediaType: string; extensions: ReadonlyArray; @@ -119,51 +105,6 @@ export type FileSelectionPolicy = Readonly<{ accept: ReadonlyArray; }>; -export type FileSelectionLimitReduction = Readonly<{ - maxCount?: number; - maxFileBytes?: ByteCount; - maxTotalBytes?: ByteCount; -}>; - -export type FileCandidate = Readonly<{ - ref: LocalFileRef; - displayName: string; - sizeBytes: ByteCount; - reportedMediaType: string | null; - lastModifiedEpochMs: number | null; - source: FileSelectionSource; -}>; - -export type FileSelectionOutcome = - | Readonly<{ - kind: "SELECTED"; - files: ReadonlyArray; - }> - | Readonly<{ kind: "DISMISSED" }>; - -export type FilePickerSupport = Readonly<{ - nativeInput: true; - systemOpenPicker: boolean; - systemSavePicker: boolean; -}>; - -export interface FilePickerPort { - readonly support: FilePickerSupport; - - select(input: { - policy: FilePolicyReference; - limits?: FileSelectionLimitReduction; - signal?: AbortSignal; - }): Promise>; - - release(ref: LocalFileRef): void; -} - -export type FileSignatureResult = - | "MATCHED" - | "MISMATCHED" - | "UNKNOWN"; - export type FileBytePattern = Readonly<{ offset: ByteCount; bytes: ReadonlyArray; @@ -182,67 +123,6 @@ export type FileInspectionPolicy = Readonly<{ acceptedSignatures: ReadonlyArray; }>; -export type FileInspection = Readonly<{ - byteLength: ByteCount; - reportedMediaType: string | null; - detectedMediaType: string | null; - normalizedExtension: string | null; - signature: FileSignatureResult; - verificationReceipt: FileVerificationReceipt | null; -}>; - -export type FileByteSource = Readonly<{ - byteLength: ByteCount | null; - stream( - signal: AbortSignal, - ): AsyncIterable>; -}>; - -export interface FileContentPort { - inspect(input: { - ref: LocalFileRef; - policy: FilePolicyReference; - maxInspectionBytes?: ByteCount; - signal: AbortSignal; - }): Promise>; - - readRange(input: { - ref: LocalFileRef; - offset: ByteCount; - length: ByteCount; - signal: AbortSignal; - }): Promise>; - - openSource(input: { - ref: LocalFileRef; - signal: AbortSignal; - }): Promise>; - - release(ref: LocalFileRef): void; -} - -export type PreviewLease = Readonly<{ - url: string; - mediaType: string; - release: Cleanup; -}>; - -/** - * Presentation-local capability. The implementation owns object URL creation - * and must revoke each lease on replacement, load failure and unmount. - */ -export interface TransientPreviewPort { - create(input: { - ref: LocalFileRef; - verificationReceipt: FileVerificationReceipt; - policy: FilePolicyReference; - maxPreviewBytes?: ByteCount; - signal: AbortSignal; - }): Promise>; - - dispose(): void; -} - /** * Feature/backend workflow example, not a browser capability dependency. * Copy it only when the backend owns authorization, resumable-session expiry, @@ -297,71 +177,6 @@ export interface ExampleQuarantinedUploadPort { ): Promise>; } -export type DownloadSource = - | Readonly<{ - kind: "BROWSER_MANAGED_RESOURCE"; - resourceId: string; - capabilityReceipt: BrowserManagedDownloadCapabilityReceipt; - }> - | Readonly<{ - kind: "AUTHORIZED_STREAM_RESOURCE"; - resourceId: string; - capability: AuthorizedDownloadCapability; - }> - | Readonly<{ - kind: "GENERATED"; - bytes: FileByteSource; - expectedSha256?: string; - }>; - -export type DownloadStrategy = - | "BROWSER_MANAGED" - | "PROMPT_AND_STREAM" - | "BOUNDED_OBJECT_URL"; - -export type DownloadOutcome = - | Readonly<{ - kind: "BROWSER_HANDOFF"; - transferId: string; - }> - | Readonly<{ - kind: "SAVED"; - transferId: string; - bytesWritten: ByteCount; - integrity: "VERIFIED" | "NOT_PROVIDED"; - }> - | Readonly<{ kind: "DISMISSED" }>; - -export interface DownloadDeliveryPort { - deliver(input: { - policy: FilePolicyReference; - source: DownloadSource; - suggestedFileName: string; - maxTransferBytes?: ByteCount; - maxBufferedBytes?: ByteCount; - signal: AbortSignal; - onProgress(progress: TransferProgress): void; - }): Promise>; -} - -export type BrowserManagedDownloadCapability = Readonly<{ - capabilityReceipt: BrowserManagedDownloadCapabilityReceipt; - href: string; - resourceId: string; - mediaType: string; - safeExtension: string; - maxBytes: ByteCount; - expectedSha256?: string; - expiresAtEpochMs: number; -}>; - -export interface BrowserManagedDownloadCapabilityResolver { - resolve(input: Readonly<{ - resourceId: string; - capabilityReceipt: BrowserManagedDownloadCapabilityReceipt; - }>): CapabilityResult; -} - export type RegisteredPreviewPolicy = Readonly<{ allowedMediaTypes: ReadonlyArray; maxPreviewBytes: ByteCount; @@ -543,101 +358,6 @@ export interface OfflineStoreMaintenancePort { }): Promise>>; } -export type StorageEstimate = Readonly<{ - usageBytes: number | null; - quotaBytes: number | null; - persisted: boolean | null; - pressure: "UNKNOWN" | "NORMAL" | "PRESSURE" | "CRITICAL"; -}>; - -export interface StorageDurabilityPort { - inspect(signal?: AbortSignal): Promise>; - - requestPersistence(input: { - reason: "PROTECT_UNSYNCED_USER_DATA"; - userInitiated: true; - signal?: AbortSignal; - }): Promise>; -} - -export type DurableObjectDataClass = - | "RECONSTRUCTABLE" - | "USER_CREATED_PRIVATE"; - -export type DurableObjectIntegrity = Readonly<{ - algorithm: "SHA-256-TREE-V1"; - rootDigest: string; - chunkSizeBytes: ByteCount; -}>; - -export type DurableObjectDescriptor = Readonly<{ - id: DurableObjectId; - generation: ObjectGeneration; - byteLength: ByteCount; - mediaType: string | null; - integrity: DurableObjectIntegrity; - dataClass: DurableObjectDataClass; - retention: - | Readonly<{ kind: "EXPLICIT_DELETE" }> - | Readonly<{ kind: "EXPIRES"; expiresAt: string }>; -}>; - -export type DurableObjectRead = Readonly<{ - descriptor: DurableObjectDescriptor; - chunks: AsyncIterable>; -}>; - -export interface DurableObjectStorePort { - capabilities(signal?: AbortSignal): Promise< - CapabilityResult< - Readonly<{ - backend: "OPFS" | "INDEXEDDB_BLOB" | "NONE"; - persistence: "BEST_EFFORT" | "PERSISTENT"; - maxObjectBytes: ByteCount; - }> - > - >; - - put(input: { - id: DurableObjectId; - expectedGeneration: ObjectGeneration | null; - source: AsyncIterable>; - declaredByteLength: ByteCount; - mediaType: string | null; - dataClass: DurableObjectDataClass; - retention: DurableObjectDescriptor["retention"]; - signal: AbortSignal; - onProgress(progress: TransferProgress): void; - }): Promise>; - - open( - id: DurableObjectId, - signal?: AbortSignal, - ): Promise>; - - remove(input: { - id: DurableObjectId; - expectedGeneration: ObjectGeneration; - signal?: AbortSignal; - }): Promise>; -} - -export type ObjectStoreRecoverySummary = Readonly<{ - resumedCount: number; - purgedCount: number; - quarantinedCount: number; - nextCursor: string | null; -}>; - -export interface DurableObjectMaintenancePort { - reconcile(input: { - timeBudgetMs: number; - maxEntries: number; - cursor?: string; - signal?: AbortSignal; - }): Promise>; -} - export type PublicAssetEntry = Readonly<{ url: string; byteLength: ByteCount; @@ -662,13 +382,6 @@ export type PublicCacheLookup = | "POLICY_REJECTED"; }>; -export type PublicCacheInspection = Readonly<{ - activeReleaseId: string | null; - previousReleaseId: string | null; - candidateReleaseIds: ReadonlyArray; - ownedBytes: number | null; -}>; - /** * Platform-local Cache Storage policy facade. Raw Request/Response/Cache * objects remain inside the adapter, and no application repository imports it. @@ -695,6 +408,10 @@ export interface PublicResponseCacheAdmin { signal?: AbortSignal; }): Promise>; + /** + * [0929] 05-03. Reports in the runtime's `PublicCacheInspection` shape; + * the recipe kept a same-named copy with other fields. + */ inspect(signal?: AbortSignal): Promise< CapabilityResult >; diff --git a/recipes/frontend-capabilities/browser-file-storage-fakes.ts b/recipes/frontend-capabilities/browser-file-storage-fakes.ts index 7734e730..19baa3fc 100644 --- a/recipes/frontend-capabilities/browser-file-storage-fakes.ts +++ b/recipes/frontend-capabilities/browser-file-storage-fakes.ts @@ -6,9 +6,7 @@ import type { DownloadDeliveryPort, DownloadOutcome, DurableObjectDescriptor, - DurableObjectId, DurableObjectMaintenancePort, - DurableObjectRead, DurableObjectStorePort, ExampleQuarantinedUpload, ExampleQuarantinedUploadPort, @@ -28,13 +26,13 @@ import type { FileVerificationReceipt, LocalFileRef, MigrationProgress, - ObjectGeneration, - ObjectStoreRecoverySummary, OfflineCommitReceipt, OfflinePage, OfflineStoreLifecycleEvent, OfflineStoreMaintenancePort, OfflineStoreStatus, + DurableObjectId, + ObjectGeneration, PublicAssetEntry, PublicCacheInspection, PublicCacheLookup, @@ -48,9 +46,50 @@ import type { RegisteredDownloadPolicy, RegisteredPreviewPolicy, } from "./browser-file-storage-contracts.ts"; +import type { + BrowserDataFailureCode, + BrowserDataOperation, + BrowserDataRecovery, + BrowserDataResult, + BrowserStoragePolicy, + ByteSource, + OpfsPolicyMaintenanceReport, + OpfsReconciliationReport, + OpfsStorageScope, +} from "../../src/application/ports/browser-file-storage/index.ts"; import type { CapabilityResult } from "./contracts.ts"; import { failure, success } from "./fake-adapters.ts"; +/** + * [0929] 05-03. The file, storage-durability and OPFS fakes implement the + * `src` ports, so they answer in that result shape: `error` with a closed + * failure code and the operation it belongs to. The recipe-only fakes below + * (upload example, structured offline store, public cache admin) keep the + * recipe `CapabilityResult`. + */ +function dataSuccess(value: T): BrowserDataResult { + return Object.freeze({ ok: true as const, value }); +} + +function dataFailure( + code: BrowserDataFailureCode, + operation: BrowserDataOperation, + retryable = false, + recovery: BrowserDataRecovery = retryable ? "RETRY" : "NONE", +): BrowserDataResult { + return Object.freeze({ + ok: false as const, + error: Object.freeze({ code, operation, retryable, recovery }), + }); +} + +function dataCancelled( + signal: AbortSignal | undefined, + operation: BrowserDataOperation, +): BrowserDataResult | null { + return signal?.aborted ? dataFailure("ABORTED", operation) : null; +} + export function asByteCount(value: number): ByteCount { if (!Number.isSafeInteger(value) || value < 0) { throw new TypeError("Byte counts must be non-negative safe integers."); @@ -175,9 +214,9 @@ export class MemoryBrowserFilePolicyRegistry { selection( reference: FilePolicyReference, reductions?: FileSelectionLimitReduction, - ): CapabilityResult { + ): BrowserDataResult { const profile = this.#profiles.get(reference); - if (!profile?.selection) return rejectedPolicy(); + if (!profile?.selection) return rejectedPolicy("FILE_SELECT"); const maxCount = reduceLimit( reductions?.maxCount, profile.selection.maxCount, @@ -195,13 +234,9 @@ export class MemoryBrowserFilePolicyRegistry { maxFileBytes === null || maxTotalBytes === null ) { - return failure( - "LIMIT_EXCEEDED", - false, - "A caller may only reduce registered file limits.", - ); + return dataFailure("LIMIT_EXCEEDED", "FILE_SELECT"); } - return success( + return dataSuccess( Object.freeze({ ...profile.selection, maxCount, @@ -213,27 +248,23 @@ export class MemoryBrowserFilePolicyRegistry { inspection( reference: FilePolicyReference, - reduction?: ByteCount, - ): CapabilityResult< + reduction?: number, + ): BrowserDataResult< Readonly<{ policy: FileInspectionPolicy; bindingId: string; }> > { const profile = this.#profiles.get(reference); - if (!profile?.inspection) return rejectedPolicy(); + if (!profile?.inspection) return rejectedPolicy("FILE_INSPECT"); const maxInspectionBytes = reduceLimit( reduction, profile.inspection.maxInspectionBytes, ); if (maxInspectionBytes === null) { - return failure( - "LIMIT_EXCEEDED", - false, - "A caller may only reduce registered inspection limits.", - ); + return dataFailure("LIMIT_EXCEEDED", "FILE_INSPECT"); } - return success( + return dataSuccess( Object.freeze({ bindingId: profile.bindingId, policy: Object.freeze({ @@ -246,8 +277,8 @@ export class MemoryBrowserFilePolicyRegistry { preview( reference: FilePolicyReference, - reduction?: ByteCount, - ): CapabilityResult< + reduction?: number, + ): BrowserDataResult< Readonly<{ bindingId: string; allowedMediaTypes: ReadonlySet; @@ -256,20 +287,16 @@ export class MemoryBrowserFilePolicyRegistry { > { const profile = this.#profiles.get(reference); if (!profile?.preview || !profile.inspection) { - return rejectedPolicy(); + return rejectedPolicy("PREVIEW"); } const maxPreviewBytes = reduceLimit( reduction, profile.preview.maxPreviewBytes, ); if (maxPreviewBytes === null) { - return failure( - "LIMIT_EXCEEDED", - false, - "A caller may only reduce registered preview limits.", - ); + return dataFailure("LIMIT_EXCEEDED", "PREVIEW"); } - return success( + return dataSuccess( Object.freeze({ bindingId: profile.bindingId, allowedMediaTypes: new Set( @@ -283,12 +310,12 @@ export class MemoryBrowserFilePolicyRegistry { download( reference: FilePolicyReference, reductions: Readonly<{ - maxTransferBytes?: ByteCount; - maxBufferedBytes?: ByteCount; + maxTransferBytes?: number; + maxBufferedBytes?: number; }>, - ): CapabilityResult { + ): BrowserDataResult { const profile = this.#profiles.get(reference); - if (!profile?.download) return rejectedPolicy(); + if (!profile?.download) return rejectedPolicy("DOWNLOAD"); const maxTransferBytes = reduceLimit( reductions.maxTransferBytes, profile.download.maxTransferBytes, @@ -304,13 +331,9 @@ export class MemoryBrowserFilePolicyRegistry { maxTransferBytes === null || maxBufferedBytes === null ) { - return failure( - "LIMIT_EXCEEDED", - false, - "A caller may only reduce registered download limits.", - ); + return dataFailure("LIMIT_EXCEEDED", "DOWNLOAD"); } - return success( + return dataSuccess( Object.freeze({ ...profile.download, maxTransferBytes: asByteCount(maxTransferBytes), @@ -320,12 +343,11 @@ export class MemoryBrowserFilePolicyRegistry { } } -function rejectedPolicy(): CapabilityResult { - return failure( - "POLICY_REJECTED", - false, - "The composition-issued file policy is not available.", - ); +/** The composition-issued file policy is not available. */ +function rejectedPolicy( + operation: BrowserDataOperation, +): BrowserDataResult { + return dataFailure("POLICY_REJECTED", operation); } function reduceLimit( @@ -537,20 +559,16 @@ export class MemoryFileSelectionAdapter policy: FilePolicyReference; limits?: FileSelectionLimitReduction; signal?: AbortSignal; - }): Promise> { - const aborted = cancelled(input.signal); + }): Promise> { + const aborted = dataCancelled(input.signal, "FILE_SELECT"); if (aborted) return aborted; const outcome = this.#nextOutcome; this.#nextOutcome = "SELECTED"; if (outcome === "DISMISSED") { - return success({ kind: "DISMISSED" }); + return dataSuccess({ kind: "DISMISSED" }); } if (outcome === "PERMISSION_DENIED") { - return failure( - "PERMISSION_DENIED", - false, - "File access permission was denied.", - ); + return dataFailure("PERMISSION_DENIED", "FILE_SELECT"); } const resolvedPolicy = this.#policies.selection( input.policy, @@ -583,33 +601,25 @@ export class MemoryFileSelectionAdapter ) || total > policy.maxTotalBytes ) { - return failure( - "LIMIT_EXCEEDED", - false, - "The selected files exceed the approved count or byte budget.", - ); + return dataFailure("LIMIT_EXCEEDED", "FILE_SELECT"); } if ( candidates.some( (candidate) => !acceptsCandidate(policy, candidate), ) ) { - return failure( - "POLICY_REJECTED", - false, - "A selected file does not match the intake policy.", - ); + return dataFailure("POLICY_REJECTED", "FILE_SELECT"); } - return success({ kind: "SELECTED", files: candidates }); + return dataSuccess({ kind: "SELECTED", files: candidates }); } async inspect(input: { ref: LocalFileRef; policy: FilePolicyReference; - maxInspectionBytes?: ByteCount; + maxInspectionBytes?: number; signal: AbortSignal; - }): Promise> { - const aborted = cancelled(input.signal); + }): Promise> { + const aborted = dataCancelled(input.signal, "FILE_INSPECT"); if (aborted) return aborted; const resolvedPolicy = this.#policies.inspection( input.policy, @@ -619,7 +629,7 @@ export class MemoryFileSelectionAdapter const { policy, bindingId } = resolvedPolicy.value; const file = this.#files.get(input.ref); if (!file) { - return failure("NOT_FOUND", false, "The selected file is no longer available."); + return dataFailure("NOT_FOUND", "FILE_INSPECT"); } this.#invalidateVerifications(input.ref); const inspectedBytes = file.bytes.slice( @@ -659,7 +669,7 @@ export class MemoryFileSelectionAdapter }), ); } - return success({ + return dataSuccess({ byteLength: asByteCount(file.bytes.byteLength), reportedMediaType: file.reportedMediaType, detectedMediaType, @@ -671,15 +681,15 @@ export class MemoryFileSelectionAdapter async readRange(input: { ref: LocalFileRef; - offset: ByteCount; - length: ByteCount; + offset: number; + length: number; signal: AbortSignal; - }): Promise> { - const aborted = cancelled(input.signal); + }): Promise> { + const aborted = dataCancelled(input.signal, "FILE_READ"); if (aborted) return aborted; const file = this.#files.get(input.ref); if (!file) { - return failure("NOT_FOUND", false, "The selected file is no longer available."); + return dataFailure("NOT_FOUND", "FILE_READ"); } const end = input.offset + input.length; if ( @@ -687,36 +697,32 @@ export class MemoryFileSelectionAdapter input.offset > file.bytes.byteLength || end > file.bytes.byteLength ) { - return failure("INVALID_INPUT", false, "The requested byte range is invalid."); + return dataFailure("INVALID_INPUT", "FILE_READ"); } - return success(file.bytes.slice(input.offset, end)); + return dataSuccess(file.bytes.slice(input.offset, end)); } async openSource(input: { ref: LocalFileRef; signal: AbortSignal; - }): Promise> { - const aborted = cancelled(input.signal); + }): Promise> { + const aborted = dataCancelled(input.signal, "FILE_READ"); if (aborted) return aborted; const file = this.#files.get(input.ref); if (!file) { - return failure( - "NOT_FOUND", - false, - "The selected file is no longer available.", - ); + return dataFailure("NOT_FOUND", "FILE_READ"); } const bytes = cloneBytes(file.bytes); - return success( + return dataSuccess( Object.freeze({ byteLength: asByteCount(bytes.byteLength), async *stream(signal: AbortSignal) { - const streamAbort = cancelled(signal); + const streamAbort = dataCancelled(signal, "FILE_READ"); if (streamAbort) { yield streamAbort; return; } - yield success(cloneBytes(bytes)); + yield dataSuccess(cloneBytes(bytes)); }, }), ); @@ -781,13 +787,9 @@ export class MemoryTransientPreviewAdapter implements TransientPreviewPort { input: Parameters[0], ): ReturnType { if (this.#disposed) { - return failure( - "PROVIDER_UNAVAILABLE", - false, - "The preview adapter has been disposed.", - ); + return dataFailure("UNAVAILABLE", "PREVIEW"); } - const aborted = cancelled(input.signal); + const aborted = dataCancelled(input.signal, "PREVIEW"); if (aborted) return aborted; const verification = this.#files.verification( input.verificationReceipt, @@ -803,20 +805,12 @@ export class MemoryTransientPreviewAdapter implements TransientPreviewPort { verification.ref !== input.ref || verification.policyBindingId !== policy.bindingId ) { - return failure( - "POLICY_REJECTED", - false, - "The preview verification receipt is invalid.", - ); + return dataFailure("POLICY_REJECTED", "PREVIEW"); } if ( verification.byteLength > policy.maxPreviewBytes ) { - return failure( - "LIMIT_EXCEEDED", - false, - "The preview exceeds its byte budget.", - ); + return dataFailure("LIMIT_EXCEEDED", "PREVIEW"); } if ( !policy.allowedMediaTypes.has(verification.mediaType) || @@ -824,16 +818,12 @@ export class MemoryTransientPreviewAdapter implements TransientPreviewPort { verification.mediaType.toLowerCase(), ) ) { - return failure( - "POLICY_REJECTED", - false, - "The file type is not approved for inline preview.", - ); + return dataFailure("POLICY_REJECTED", "PREVIEW"); } const url = `blob:memory-preview-${++this.#sequence}`; this.#active.add(url); let released = false; - return success( + return dataSuccess( Object.freeze({ url, mediaType: verification.mediaType, @@ -1135,8 +1125,8 @@ export class RecordingDownloadDeliveryAdapter async deliver( input: Parameters[0], - ): Promise> { - const aborted = cancelled(input.signal); + ): Promise> { + const aborted = dataCancelled(input.signal, "DOWNLOAD"); if (aborted) return aborted; const resolvedPolicy = this.#policies.download(input.policy, { maxTransferBytes: input.maxTransferBytes, @@ -1156,11 +1146,7 @@ export class RecordingDownloadDeliveryAdapter (policy.strategy !== "BROWSER_MANAGED" && input.source.kind === "BROWSER_MANAGED_RESOURCE") ) { - return failure( - "POLICY_REJECTED", - false, - "The source is incompatible with the registered strategy.", - ); + return dataFailure("POLICY_REJECTED", "DOWNLOAD"); } if ( policy.strategy === "BROWSER_MANAGED" && @@ -1182,12 +1168,11 @@ export class RecordingDownloadDeliveryAdapter (policy.integrity === "REQUIRED" && !capability.value.expectedSha256) ) { - return failure( + return dataFailure( capability.value.expiresAtEpochMs <= this.#now() ? "EXPIRED_RESOURCE" : "POLICY_REJECTED", - false, - "The server-bound download capability is invalid.", + "DOWNLOAD", ); } this.receipts.push({ @@ -1195,40 +1180,24 @@ export class RecordingDownloadDeliveryAdapter strategy: policy.strategy, bytesWritten: 0, }); - return success({ kind: "BROWSER_HANDOFF", transferId }); + return dataSuccess({ kind: "BROWSER_HANDOFF", transferId }); } if (input.source.kind === "AUTHORIZED_STREAM_RESOURCE") { - return failure( - "UNSUPPORTED", - false, - "This fake cannot stream an authorized server resource.", - ); + return dataFailure("UNSUPPORTED", "DOWNLOAD"); } if (input.source.kind !== "GENERATED") { - return failure( - "POLICY_REJECTED", - false, - "The download source is incompatible with this fake.", - ); + return dataFailure("POLICY_REJECTED", "DOWNLOAD"); } const expectedSha256 = input.source.expectedSha256; if (policy.integrity === "REQUIRED" && !expectedSha256) { - return failure( - "POLICY_REJECTED", - false, - "The registered download policy requires integrity.", - ); + return dataFailure("POLICY_REJECTED", "DOWNLOAD"); } if ( policy.strategy === "BOUNDED_OBJECT_URL" && input.source.bytes.byteLength !== null && input.source.bytes.byteLength > policy.maxBufferedBytes ) { - return failure( - "LIMIT_EXCEEDED", - false, - "The generated download exceeds the buffering budget.", - ); + return dataFailure("LIMIT_EXCEEDED", "DOWNLOAD"); } let bytesWritten = 0; const integrityChunks: Uint8Array[] = []; @@ -1237,25 +1206,17 @@ export class RecordingDownloadDeliveryAdapter )) { if (!chunkResult.ok) return chunkResult; const chunk = chunkResult.value; - const duringTransfer = cancelled(input.signal); + const duringTransfer = dataCancelled(input.signal, "DOWNLOAD"); if (duringTransfer) return duringTransfer; bytesWritten += chunk.byteLength; if (bytesWritten > policy.maxTransferBytes) { - return failure( - "LIMIT_EXCEEDED", - false, - "The generated download exceeds the transfer budget.", - ); + return dataFailure("LIMIT_EXCEEDED", "DOWNLOAD"); } if ( input.source.bytes.byteLength !== null && bytesWritten > input.source.bytes.byteLength ) { - return failure( - "INTEGRITY_FAILED", - false, - "The generated download exceeded its declared size.", - ); + return dataFailure("INTEGRITY_FAILED", "DOWNLOAD"); } if (expectedSha256) integrityChunks.push(cloneBytes(chunk)); input.onProgress({ @@ -1268,14 +1229,10 @@ export class RecordingDownloadDeliveryAdapter input.source.bytes.byteLength !== null && bytesWritten !== input.source.bytes.byteLength ) { - return failure( - "INTEGRITY_FAILED", - false, - "The generated download did not match its declared size.", - ); + return dataFailure("INTEGRITY_FAILED", "DOWNLOAD"); } if (expectedSha256) { - const beforeVerification = cancelled(input.signal); + const beforeVerification = dataCancelled(input.signal, "DOWNLOAD"); if (beforeVerification) return beforeVerification; input.onProgress({ phase: "VERIFYING", @@ -1284,11 +1241,7 @@ export class RecordingDownloadDeliveryAdapter }); const actualSha256 = await sha256Hex(concatenateBytes(integrityChunks)); if (actualSha256 !== expectedSha256.toLowerCase()) { - return failure( - "INTEGRITY_FAILED", - false, - "The generated download failed integrity verification.", - ); + return dataFailure("INTEGRITY_FAILED", "DOWNLOAD"); } } this.receipts.push({ @@ -1296,7 +1249,7 @@ export class RecordingDownloadDeliveryAdapter strategy: policy.strategy, bytesWritten, }); - return success({ + return dataSuccess({ kind: "SAVED", transferId, bytesWritten: asByteCount(bytesWritten), @@ -1631,10 +1584,10 @@ export class MemoryStorageDurabilityAdapter implements StorageDurabilityPort { async inspect( signal?: AbortSignal, - ): Promise> { + ): Promise> { return ( - cancelled(signal) ?? - success({ + dataCancelled(signal, "STORAGE_ESTIMATE") ?? + dataSuccess({ usageBytes: this.usageBytes, quotaBytes: this.quotaBytes, persisted: this.#persisted, @@ -1650,11 +1603,11 @@ export class MemoryStorageDurabilityAdapter implements StorageDurabilityPort { reason: "PROTECT_UNSYNCED_USER_DATA"; userInitiated: true; signal?: AbortSignal; - }): Promise> { - const aborted = cancelled(input.signal); + }): Promise> { + const aborted = dataCancelled(input.signal, "STORAGE_PERSIST"); if (aborted) return aborted; this.#persisted = this.persistenceDecision === "GRANTED"; - return success(this.persistenceDecision); + return dataSuccess(this.persistenceDecision); } } @@ -1683,127 +1636,128 @@ type MemoryObject = Readonly<{ chunks: ReadonlyArray; }>; -type PendingObject = Readonly<{ - id: DurableObjectId; - phase: "PREPARING" | "FILES_READY"; +type MemoryDurableObjectStoreOptions = Readonly<{ + scope: OpfsStorageScope; + storagePolicy: BrowserStoragePolicy; + maxObjectBytes: number; + now?: () => number; }>; +/** + * [0929] 05-03. Deterministic stand-in for the OPFS reference runtime + * (`src/adapters/storage/opfs`). It implements the same ports, so a feature + * test written against it compiles against the runtime too. It keeps the + * runtime's visible rules: a put is invisible until its logical commit, a + * stale `expectedGeneration` is `CONFLICT`, a put that stopped mid-way leaves + * a journal row that `reconcile` rolls back (never resumes), and a LOGOUT or + * ACCOUNT_DELETION the policy allows leaves the partition empty. + * + * It does not model the worker, Web Locks, the composition authority, chunk + * dedup, orphan GC or the other maintenance reasons (`UNSUPPORTED`). Its + * integrity digest is not the runtime's tree digest; compare digests only + * within one store. + */ export class MemoryDurableObjectStore implements DurableObjectStorePort, DurableObjectMaintenancePort { - readonly #objects = new Map(); - readonly #pending = new Map(); - #failurePhase: PendingObject["phase"] | null = null; + readonly #objects = new Map(); + /** Journal rows of puts that stopped before they committed or rolled back. */ + readonly #pending = new Set(); + readonly #scope: OpfsStorageScope; + readonly #storagePolicy: BrowserStoragePolicy; + readonly #maxObjectBytes: number; + readonly #now: () => number; + #sequence = 0; + #failurePhase: "PREPARING" | "FILES_READY" | null = null; - constructor( - private readonly maxObjectBytes: ByteCount, - private readonly backend: "OPFS" | "INDEXEDDB_BLOB" | "NONE" = "OPFS", - ) {} + constructor(options: MemoryDurableObjectStoreOptions) { + this.#scope = Object.freeze({ ...options.scope }); + this.#storagePolicy = options.storagePolicy; + this.#maxObjectBytes = options.maxObjectBytes; + this.#now = options.now ?? Date.now; + } - failNextPutAfter(phase: PendingObject["phase"]): void { + /** The next put stops after this phase, the way a closed tab would. */ + failNextPutAfter(phase: "PREPARING" | "FILES_READY"): void { this.#failurePhase = phase; } - async capabilities(signal?: AbortSignal) { - return ( - cancelled(signal) ?? - success({ - backend: this.backend, - persistence: "BEST_EFFORT" as const, - maxObjectBytes: this.maxObjectBytes, - }) + async capabilities() { + return dataSuccess( + Object.freeze({ + available: true, + dedicatedWorkerRequired: true as const, + crossContextMutationLockAvailable: true, + synchronousAccessHandleAvailable: false, + }), ); } async put( - input: Parameters[0], - ): Promise> { - const aborted = cancelled(input.signal); + request: Parameters[0], + ): Promise> { + const aborted = dataCancelled(request.signal, "OBJECT_WRITE"); if (aborted) return aborted; - if (this.backend === "NONE") { - return failure("UNSUPPORTED", false, "Durable object storage is unsupported."); + const declared = request.source.byteLength; + if (declared !== null && declared > this.#maxObjectBytes) { + return dataFailure("LIMIT_EXCEEDED", "OBJECT_WRITE"); } - if (input.declaredByteLength > this.maxObjectBytes) { - return failure("LIMIT_EXCEEDED", false, "The object exceeds its byte budget."); - } - const current = this.#objects.get(input.id); + const current = this.#objects.get(request.objectId); if ( - (input.expectedGeneration === null && current !== undefined) || - (input.expectedGeneration !== null && - current?.descriptor.generation !== input.expectedGeneration) + (request.expectedGeneration === null && current !== undefined) || + (request.expectedGeneration !== null && + current?.descriptor.generation !== request.expectedGeneration) ) { - return failure("CONFLICT", false, "The object generation changed."); + return dataFailure("CONFLICT", "OBJECT_WRITE", false, "REOPEN"); } - this.#pending.set(input.id, { id: input.id, phase: "PREPARING" }); - if (this.#failurePhase === "PREPARING") { + const row = ++this.#sequence; + this.#pending.add(row); + const stopped = (phase: "PREPARING" | "FILES_READY") => { + if (this.#failurePhase !== phase) return null; this.#failurePhase = null; - return failure( - "PROVIDER_UNAVAILABLE", - true, - "The object writer stopped after journal preparation.", - ); - } + // The row stays: only reconcile can settle it. + return dataFailure("UNAVAILABLE", "OBJECT_WRITE", true, "RECONCILE"); + }; + const afterPreparing = stopped("PREPARING"); + if (afterPreparing) return afterPreparing; const chunks: Uint8Array[] = []; let totalBytes = 0; - try { - for await (const chunkResult of input.source) { - if (!chunkResult.ok) return chunkResult; - const chunk = chunkResult.value; - const duringWrite = cancelled(input.signal); - if (duringWrite) return duringWrite; - if (!(chunk instanceof Uint8Array)) { - return failure( - "CORRUPT_DATA", - false, - "The object source emitted an invalid byte chunk.", - ); - } - totalBytes += chunk.byteLength; - if ( - totalBytes > input.declaredByteLength || - totalBytes > this.maxObjectBytes - ) { - return failure( - "INTEGRITY_FAILED", - false, - "The object exceeded its declared size.", - ); - } - chunks.push(cloneBytes(chunk)); - input.onProgress({ - phase: "TRANSFERRING", - transferredBytes: totalBytes, - totalBytes: input.declaredByteLength, - }); + const settle = (result: BrowserDataResult) => { + // A put that fails on its own compensates: its row is rolled back. + this.#pending.delete(row); + return result; + }; + for await (const chunk of request.source.stream( + request.signal ?? new AbortController().signal, + )) { + if (!chunk.ok) { + return settle( + dataFailure(chunk.error.code, "OBJECT_WRITE", chunk.error.retryable), + ); } - } catch { - return failure( - "NOT_READABLE", - true, - "The object byte source could not be read.", - ); + const duringWrite = dataCancelled(request.signal, "OBJECT_WRITE"); + if (duringWrite) return settle(duringWrite); + totalBytes += chunk.value.byteLength; + if (totalBytes > this.#maxObjectBytes) { + return settle(dataFailure("LIMIT_EXCEEDED", "OBJECT_WRITE")); + } + if (declared !== null && totalBytes > declared) { + return settle(dataFailure("INTEGRITY_FAILED", "OBJECT_WRITE")); + } + chunks.push(cloneBytes(chunk.value)); + request.onProgress?.({ + phase: "TRANSFERRING", + transferredBytes: totalBytes, + totalBytes: declared, + }); } - if (totalBytes !== input.declaredByteLength) { - return failure( - "INTEGRITY_FAILED", - false, - "The object did not match its declared size.", - ); - } - this.#pending.set(input.id, { id: input.id, phase: "FILES_READY" }); - if (this.#failurePhase === "FILES_READY") { - this.#failurePhase = null; - return failure( - "PROVIDER_UNAVAILABLE", - true, - "The object writer stopped before logical commit.", - ); + if (declared !== null && totalBytes !== declared) { + return settle(dataFailure("INTEGRITY_FAILED", "OBJECT_WRITE")); } + const afterFilesReady = stopped("FILES_READY"); + if (afterFilesReady) return afterFilesReady; - const generation = asObjectGeneration( - (current?.descriptor.generation ?? 0) + 1, - ); const chunkDigests = await Promise.all(chunks.map(sha256Hex)); const chunkSizeBytes = Math.max( 0, @@ -1820,72 +1774,137 @@ export class MemoryDurableObjectStore ].join(":"), ); const descriptor: DurableObjectDescriptor = Object.freeze({ - id: input.id, - generation, - byteLength: asByteCount(totalBytes), - mediaType: input.mediaType, + objectId: request.objectId, + scope: this.#scope, + generation: (current?.descriptor.generation ?? 0) + 1, + byteLength: totalBytes, + mediaType: request.mediaType, + createdAtEpochMs: this.#now(), integrity: Object.freeze({ - algorithm: "SHA-256-TREE-V1", - rootDigest: await sha256Hex(canonicalTree), - chunkSizeBytes: asByteCount(chunkSizeBytes), + algorithm: "SHA-256-TREE-V1" as const, + rootDigestHex: await sha256Hex(canonicalTree), + chunkSizeBytes, }), - dataClass: input.dataClass, - retention: input.retention, + storagePolicy: this.#storagePolicy, }); - this.#objects.set(input.id, { descriptor, chunks }); - this.#pending.delete(input.id); - return success(descriptor); + this.#objects.set(request.objectId, { descriptor, chunks }); + this.#pending.delete(row); + return dataSuccess(descriptor); } async open( - id: DurableObjectId, - signal?: AbortSignal, - ): Promise> { - const aborted = cancelled(signal); + request: Parameters[0], + ): ReturnType { + const aborted = dataCancelled(request.signal, "OBJECT_READ"); if (aborted) return aborted; - const object = this.#objects.get(id); - if (!object) { - return failure("NOT_FOUND", false, "The durable object does not exist."); + const object = this.#objects.get(request.objectId); + if ( + !object || + (request.generation !== undefined && + request.generation !== object.descriptor.generation) + ) { + return dataFailure("NOT_FOUND", "OBJECT_READ", false, "REHYDRATE"); } const chunks = object.chunks.map(cloneBytes); - return success({ - descriptor: object.descriptor, - chunks: chunksFrom(chunks), + const source: ByteSource = Object.freeze({ + byteLength: object.descriptor.byteLength, + async *stream(signal: AbortSignal) { + for (const chunk of chunks) { + const stopped = dataCancelled(signal, "OBJECT_READ"); + if (stopped) { + yield stopped; + return; + } + yield dataSuccess(cloneBytes(chunk)); + } + }, }); + return dataSuccess( + Object.freeze({ descriptor: object.descriptor, source }), + ); } async remove( - input: Parameters[0], - ): Promise> { - const aborted = cancelled(input.signal); + request: Parameters[0], + ): Promise> { + const aborted = dataCancelled(request.signal, "OBJECT_DELETE"); if (aborted) return aborted; - const current = this.#objects.get(input.id); - if (!current) { - return failure("NOT_FOUND", false, "The durable object does not exist."); + const current = this.#objects.get(request.objectId); + if (!current) return dataFailure("NOT_FOUND", "OBJECT_DELETE"); + if (current.descriptor.generation !== request.expectedGeneration) { + return dataFailure("CONFLICT", "OBJECT_DELETE", false, "REOPEN"); } - if (current.descriptor.generation !== input.expectedGeneration) { - return failure("CONFLICT", false, "The object generation changed."); - } - this.#objects.delete(input.id); - return success(undefined); + this.#objects.delete(request.objectId); + return dataSuccess(undefined); } async reconcile( - input: Parameters[0], - ): Promise> { - const aborted = cancelled(input.signal); + request: Parameters[0] = {}, + ): Promise> { + const aborted = dataCancelled(request.signal, "OBJECT_RECONCILE"); if (aborted) return aborted; - if (input.maxEntries < 1 || input.timeBudgetMs < 1) { - return failure("INVALID_INPUT", false, "The recovery budget is invalid."); + const maxTransactions = request.maxTransactions ?? 100; + if ( + !Number.isSafeInteger(maxTransactions) || + maxTransactions < 1 || + (request.budgetMs !== undefined && + (!Number.isSafeInteger(request.budgetMs) || request.budgetMs < 1)) + ) { + return dataFailure("INVALID_INPUT", "OBJECT_RECONCILE"); } - const pending = Array.from(this.#pending.keys()).slice(0, input.maxEntries); - for (const id of pending) this.#pending.delete(id); - return success({ - resumedCount: 0, - purgedCount: pending.length, - quarantinedCount: 0, - nextCursor: this.#pending.size > 0 ? String(pending.length) : null, - }); + const rows = [...this.#pending].slice(0, maxTransactions); + for (const row of rows) this.#pending.delete(row); + return dataSuccess( + Object.freeze({ + inspectedTransactions: rows.length, + committedTransactions: 0, + rolledBackTransactions: rows.length, + cleanedTransactions: 0, + inspectedOrphanChunks: 0, + deletedOrphanChunks: 0, + orphanGcStatus: "COMPLETED" as const, + moreTransactionsAvailable: this.#pending.size > 0, + deadlineReached: false, + skippedLiveTransactions: 0, + failedTransactions: 0, + corruptTransactions: 0, + }), + ); + } + + async enforcePolicies( + request: Parameters[0], + ): Promise> { + const aborted = dataCancelled(request.signal, "OBJECT_RECONCILE"); + if (aborted) return aborted; + if (request.reason !== "LOGOUT" && request.reason !== "ACCOUNT_DELETION") { + return dataFailure("UNSUPPORTED", "OBJECT_RECONCILE"); + } + const policy = this.#storagePolicy; + if ( + policy.accountScope !== "OPAQUE_PARTITION" || + (request.reason === "LOGOUT" + ? policy.logoutAction === "KEEP_ORIGIN_SHARED" + : policy.accountDeletionAction !== "PURGE_PARTITION") + ) { + return dataFailure("POLICY_REJECTED", "OBJECT_RECONCILE", false, "READ_ONLY"); + } + let releasedBytes = 0; + for (const object of this.#objects.values()) { + releasedBytes += object.descriptor.byteLength; + } + const removedObjects = this.#objects.size; + this.#objects.clear(); + return dataSuccess( + Object.freeze({ + inspectedObjects: removedObjects, + removedObjects, + releasedBytes, + moreObjectsAvailable: false, + deadlineReached: false, + chunkSweep: "COMPLETED" as const, + }), + ); } } @@ -1898,12 +1917,6 @@ async function sha256Hex(bytes: Uint8Array): Promise { ).join(""); } -async function* chunksFrom( - chunks: ReadonlyArray, -): AsyncIterable> { - for (const chunk of chunks) yield success(cloneBytes(chunk)); -} - type MemoryCacheRelease = Readonly<{ manifestDigest: string; entries: ReadonlyMap; @@ -2035,25 +2048,23 @@ export class MemoryPublicResponseCache ): Promise> { const aborted = cancelled(signal); if (aborted) return aborted; - const candidateReleaseIds = Array.from(this.#releases.keys()).filter( - (releaseId) => - releaseId !== this.#activeReleaseId && - releaseId !== this.#previousReleaseId, - ); - const ownedBytes = Array.from(this.#releases.values()).reduce( - (total, release) => - total + - Array.from(release.entries.values()).reduce( - (releaseTotal, entry) => releaseTotal + entry.byteLength, - 0, - ), - 0, - ); + // Every release here was staged after its entries passed policy, so each + // owned cache is readable and each candidate is verified. return success({ - activeReleaseId: this.#activeReleaseId, - previousReleaseId: this.#previousReleaseId, - candidateReleaseIds, - ownedBytes, + activeReleaseRegistryId: this.#activeReleaseId, + ownedCacheCount: this.#releases.size, + unreadableOwnedCacheCount: 0, + releaseCandidates: Array.from(this.#releases) + .filter( + ([releaseId]) => + releaseId !== this.#activeReleaseId && + releaseId !== this.#previousReleaseId, + ) + .map(([releaseRegistryId, release]) => ({ + releaseRegistryId, + verified: true, + entryCount: release.entries.size, + })), }); } diff --git a/recipes/frontend-capabilities/contracts.ts b/recipes/frontend-capabilities/contracts.ts index e6603ad6..238921c6 100644 --- a/recipes/frontend-capabilities/contracts.ts +++ b/recipes/frontend-capabilities/contracts.ts @@ -90,7 +90,13 @@ export interface ServiceWorkerUpdatePort { unregister(): Promise>; } -export type TransferProgress = Readonly<{ +/** + * [0929] 05-03. Progress of the recipe-only `FileTransferPort`. It is not the + * browser-file runtime's `TransferProgress` (whose `phase` is required), so it + * no longer shares that name; the runtime's type is re-exported from + * `browser-file-storage-contracts.ts`. + */ +export type FileTransferProgress = Readonly<{ phase?: | "VALIDATING" | "PREPARING" @@ -115,12 +121,12 @@ export interface FileTransferPort { content: TransferByteSource; }>; signal: AbortSignal; - onProgress(progress: TransferProgress): void; + onProgress(progress: FileTransferProgress): void; }): Promise>>; download(input: { resourceId: string; signal: AbortSignal; - onProgress(progress: TransferProgress): void; + onProgress(progress: FileTransferProgress): void; }): Promise< CapabilityResult< Readonly<{ diff --git a/scripts/test-browser-file-storage-runtime-removal.ts b/scripts/test-browser-file-storage-runtime-removal.ts index a1e98de2..399d9910 100644 --- a/scripts/test-browser-file-storage-runtime-removal.ts +++ b/scripts/test-browser-file-storage-runtime-removal.ts @@ -21,6 +21,10 @@ import { const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath"); const fixtureRoot = await createRemovalFixtureRoot("browser-file-storage-runtime-removal"); +const RUNTIME_RECIPE_MODULES = [ + "browser-file-storage-contracts.ts", + "browser-file-storage-fakes.ts", +] as const; const runtimePaths = [ "src/application/ports/browser-file-storage", "src/application/ports/browser-transfer", @@ -34,6 +38,12 @@ const runtimePaths = [ "tests/fixtures/browser-file-storage-boundaries", // The composition example of this runtime goes with it. "recipes/frontend-capabilities/indexeddb-feature-capability.ts", + // [0929] 05-03. These recipe contracts re-export this runtime's ports and + // their fakes implement them, so they go with it too, with their test. + ...RUNTIME_RECIPE_MODULES.map( + (module) => `recipes/frontend-capabilities/${module}`, + ), + "tests/recipes/browser-file-storage-contracts.test.ts", ] as const; const runtimeSourceRoots = runtimePaths.filter((entry) => entry.startsWith("src/"), @@ -57,6 +67,29 @@ let removedRuntimeTests: number; try { await prepareRemovalFixture(fixtureRoot); + // The recipe barrel stops exporting the removed recipe modules first, so the + // import graph below does not count every other recipe test as dependent. + const recipeIndexPath = path.join( + fixtureRoot, + "recipes/frontend-capabilities/index.ts", + ); + const recipeIndex = await readFile(recipeIndexPath, "utf8"); + const keptRecipeExports = recipeIndex + .split("\n") + .filter( + (line) => + !RUNTIME_RECIPE_MODULES.some((module) => + line.includes(`"./${module}"`), + ), + ); + if ( + keptRecipeExports.length !== + recipeIndex.split("\n").length - RUNTIME_RECIPE_MODULES.length + ) { + throw new Error("Expected the recipe barrel to export each runtime recipe module once"); + } + await writeFile(recipeIndexPath, keptRecipeExports.join("\n")); + removedRuntimeTests = await removeRuntimeDependentTests(fixtureRoot, runtimeSourceRoots); for (const runtimePath of runtimePaths) { diff --git a/tests/recipes/browser-file-storage-contracts.test.ts b/tests/recipes/browser-file-storage-contracts.test.ts index e1663170..1b5c6d97 100644 --- a/tests/recipes/browser-file-storage-contracts.test.ts +++ b/tests/recipes/browser-file-storage-contracts.test.ts @@ -16,7 +16,6 @@ import { asLocalFileRef, asObjectGeneration, browserFilePolicyReference, - failure, sanitizeDownloadFileName, } from "../../recipes/frontend-capabilities/index.ts"; import type { @@ -28,6 +27,16 @@ import type { StorageDurabilityComposition, StructuredOfflineStorageComposition, } from "../../recipes/frontend-capabilities/index.ts"; +import type { + BrowserStoragePolicy, + DownloadDeliveryPort, + DurableObjectMaintenancePort, + DurableObjectStorePort, + FileContentPort, + FilePickerPort, + StorageDurabilityPort, + TransientPreviewPort, +} from "../../src/application/ports/browser-file-storage/index.ts"; async function* byteChunks( ...values: ReadonlyArray @@ -41,11 +50,15 @@ async function* byteChunks( } async function* failedByteChunks() { - yield failure( - "NOT_READABLE", - true, - "The fixture source became unreadable.", - ); + yield { + ok: false, + error: { + code: "NOT_READABLE", + operation: "OBJECT_WRITE", + retryable: true, + recovery: "RETRY", + }, + } as const; } describe("production browser file and storage recipe contracts", () => { @@ -123,7 +136,7 @@ describe("production browser file and storage recipe contracts", () => { }), ).toMatchObject({ ok: false, - failure: { code: "POLICY_REJECTED" }, + error: { code: "POLICY_REJECTED", operation: "FILE_SELECT" }, }); const inspected = await adapter.inspect({ ref, @@ -178,7 +191,7 @@ describe("production browser file and storage recipe contracts", () => { }), ).toMatchObject({ ok: false, - failure: { code: "PROVIDER_UNAVAILABLE" }, + error: { code: "UNAVAILABLE", operation: "PREVIEW" }, }); adapter.release(ref); expect( @@ -253,6 +266,20 @@ describe("production browser file and storage recipe contracts", () => { }); }); + // [0929] 05-03. The fakes the catalog names for a runtime port implement + // that `src` port, not a recipe copy of it. + it("fakes the src runtime ports themselves", () => { + expectTypeOf().toMatchTypeOf< + FilePickerPort & FileContentPort + >(); + expectTypeOf().toMatchTypeOf(); + expectTypeOf().toMatchTypeOf(); + expectTypeOf().toMatchTypeOf(); + expectTypeOf().toMatchTypeOf< + DurableObjectStorePort & DurableObjectMaintenancePort + >(); + }); + it("keeps each browser technology independently composable", () => { expectTypeOf().toEqualTypeOf< "picker" | "content" | "previews" | "downloads" @@ -379,7 +406,7 @@ describe("production browser file and storage recipe contracts", () => { }), ).toMatchObject({ ok: false, - failure: { code: "POLICY_REJECTED" }, + error: { code: "POLICY_REJECTED", operation: "DOWNLOAD" }, }); const saved = await adapter.deliver({ @@ -528,88 +555,121 @@ describe("production browser file and storage recipe contracts", () => { }); it("keeps partially written OPFS objects invisible until logical commit", async () => { - const store = new MemoryDurableObjectStore(asByteCount(32)); - const id = asDurableObjectId("opaque-object"); - store.failNextPutAfter("FILES_READY"); - const failed = await store.put({ - id, - expectedGeneration: null, - source: byteChunks("ab", "cd"), - declaredByteLength: asByteCount(4), - mediaType: "application/octet-stream", - dataClass: "RECONSTRUCTABLE", - retention: { kind: "EXPIRES", expiresAt: "2026-08-01T00:00:00.000Z" }, - signal: new AbortController().signal, - onProgress() {}, + const storagePolicy: BrowserStoragePolicy = { + owner: "recipe-test", + namespace: "durable-objects", + classification: "PERSONAL", + authority: "LOCAL_FIRST", + accountScope: "OPAQUE_PARTITION", + retention: { kind: "EXPLICIT_DELETE" }, + softBudgetBytes: 32, + hardBudgetBytes: 64, + evictionPriority: "USER_AUTHORED", + logoutAction: "EXPORT_THEN_PURGE", + accountDeletionAction: "PURGE_PARTITION", + pressureAction: "RETAIN", + unavailableFallback: "EXPORT_REQUIRED", + }; + const store = new MemoryDurableObjectStore({ + scope: { + namespace: "durable-objects", + authorityToken: "authority_12345678", + namespaceToken: "namespace_12345678", + partitionToken: "partition_12345678", + }, + storagePolicy, + maxObjectBytes: 32, }); - expect(failed).toMatchObject({ - ok: false, - failure: { code: "PROVIDER_UNAVAILABLE" }, + // The recipe brands are still accepted by the runtime port. + const objectId = asDurableObjectId("object_opaque_0001"); + const source = (...values: ReadonlyArray) => ({ + byteLength: values.join("").length, + stream: () => byteChunks(...values), }); - expect(await store.open(id)).toMatchObject({ - ok: false, - failure: { code: "NOT_FOUND" }, - }); - expect( - await store.reconcile({ timeBudgetMs: 100, maxEntries: 10 }), - ).toMatchObject({ ok: true, value: { purgedCount: 1 } }); + store.failNextPutAfter("FILES_READY"); expect( await store.put({ - id, + objectId, expectedGeneration: null, - source: failedByteChunks(), - declaredByteLength: asByteCount(4), - mediaType: null, - dataClass: "RECONSTRUCTABLE", - retention: { kind: "EXPLICIT_DELETE" }, - signal: new AbortController().signal, - onProgress() {}, + mediaType: "application/octet-stream", + source: source("ab", "cd"), }), ).toMatchObject({ ok: false, - failure: { code: "NOT_READABLE" }, + error: { code: "UNAVAILABLE", recovery: "RECONCILE" }, + }); + expect(await store.open({ objectId })).toMatchObject({ + ok: false, + error: { code: "NOT_FOUND" }, + }); + // Like the runtime, reconcile rolls a stopped put back; it never resumes. + expect(await store.reconcile()).toMatchObject({ + ok: true, + value: { rolledBackTransactions: 1, moreTransactionsAvailable: false }, }); - expect( - await store.reconcile({ timeBudgetMs: 100, maxEntries: 10 }), - ).toMatchObject({ ok: true, value: { purgedCount: 1 } }); - const committed = await store.put({ - id, - expectedGeneration: null, - source: byteChunks("abcd"), - declaredByteLength: asByteCount(4), - mediaType: null, - dataClass: "RECONSTRUCTABLE", - retention: { kind: "EXPLICIT_DELETE" }, - signal: new AbortController().signal, - onProgress() {}, + expect( + await store.put({ + objectId, + expectedGeneration: null, + mediaType: "application/octet-stream", + source: { byteLength: 4, stream: failedByteChunks }, + }), + ).toMatchObject({ + ok: false, + error: { code: "NOT_READABLE", operation: "OBJECT_WRITE" }, }); - expect(committed).toMatchObject({ + // A put that fails on its own compensates, so nothing is left behind. + expect(await store.reconcile()).toMatchObject({ + ok: true, + value: { rolledBackTransactions: 0 }, + }); + + expect( + await store.put({ + objectId, + expectedGeneration: null, + mediaType: "application/octet-stream", + source: source("abcd"), + }), + ).toMatchObject({ ok: true, value: { + objectId, generation: 1, + byteLength: 4, integrity: { algorithm: "SHA-256-TREE-V1" }, }, }); - const opened = await store.open(id); + const opened = await store.open({ objectId }); expect(opened.ok).toBe(true); if (opened.ok) { - const chunks: number[] = []; - for await (const chunkResult of opened.value.chunks) { - expect(chunkResult.ok).toBe(true); - if (chunkResult.ok) chunks.push(...chunkResult.value); + const bytes: number[] = []; + for await (const chunk of opened.value.source.stream( + new AbortController().signal, + )) { + expect(chunk.ok).toBe(true); + if (chunk.ok) bytes.push(...chunk.value); } - expect(new TextDecoder().decode(new Uint8Array(chunks))).toBe( - "abcd", - ); + expect(new TextDecoder().decode(new Uint8Array(bytes))).toBe("abcd"); } expect( await store.remove({ - id, + objectId, expectedGeneration: asObjectGeneration(2), }), - ).toMatchObject({ ok: false, failure: { code: "CONFLICT" } }); + ).toMatchObject({ ok: false, error: { code: "CONFLICT" } }); + expect( + await store.enforcePolicies({ reason: "ACCOUNT_DELETION" }), + ).toMatchObject({ + ok: true, + value: { removedObjects: 1, chunkSweep: "COMPLETED" }, + }); + expect(await store.open({ objectId })).toMatchObject({ + ok: false, + error: { code: "NOT_FOUND" }, + }); }); it("stages and activates only exact public Cache Storage representations", async () => { @@ -669,5 +729,15 @@ describe("production browser file and storage recipe contracts", () => { ok: false, failure: { code: "POLICY_REJECTED" }, }); + // [0929] 05-03. Reported in the runtime's `PublicCacheInspection` shape. + expect(await cache.inspect()).toEqual({ + ok: true, + value: { + activeReleaseRegistryId: "release-1", + ownedCacheCount: 1, + unreadableOwnedCacheCount: 0, + releaseCandidates: [], + }, + }); }); }); diff --git a/tests/recipes/optional-capability-contracts.test.ts b/tests/recipes/optional-capability-contracts.test.ts index 659e67a8..7e524a52 100644 --- a/tests/recipes/optional-capability-contracts.test.ts +++ b/tests/recipes/optional-capability-contracts.test.ts @@ -1,3 +1,6 @@ +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; + import { describe, expect, it } from "vitest"; import { @@ -287,4 +290,35 @@ describe("optional capability recipes", () => { adapters.largeDataUi.window({ offset: 0, limit: 1, generation: 1 }).ok, ).toBe(false); }); + + // [0929] 05-03. A recipe that defines its own type under the name of an + // application port drifts from it: the recipe copies of the browser-file + // and OPFS ports missed every runtime change for months. A recipe may + // re-export a port, never define a second one with the same name. + it("defines no type under the name of an application port", async () => { + const definedNames = async (root: string): Promise> => { + const names = new Set(); + const entries = await readdir(root, { + recursive: true, + withFileTypes: true, + }); + for (const entry of entries) { + if (!entry.isFile() || !entry.name.endsWith(".ts")) continue; + const source = await readFile( + path.join(entry.parentPath, entry.name), + "utf8", + ); + for (const match of source.matchAll( + /^export (?:declare |async )?(?:interface|type|class|enum|function|const) ([A-Za-z0-9_]+)/gmu, + )) { + names.add(match[1]!); + } + } + return names; + }; + const portNames = await definedNames("src/application/ports"); + const recipeNames = await definedNames("recipes"); + + expect([...recipeNames].filter((name) => portNames.has(name))).toEqual([]); + }); });