문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와
같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`,
`FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`,
`PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929
05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이
복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는
runtime에 없는 resume·quarantine을 전제했다.
고른 방법 (리뷰의 (c)):
- runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고
`src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe
port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`,
`DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는
`DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src
port가 그대로 받는다).
- fake는 src port를 `implements`한다.
- 파일 picker·content·preview·download fake와 storage durability fake:
결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다.
`PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다.
- `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는
scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은
reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다).
LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다.
- 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는
`IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대
CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다.
recipe 전용 `StructuredOfflineStore`의 fake로는 남는다.
- recipe 전용 port 두 곳:
- `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection`
모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다.
- `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로
나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로
계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를
import하지 않게 하려는 것이다.
- 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를
더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을
정의하면 실패한다(다시 내보내기는 허용).
- runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는
이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께
지우고, recipe barrel에서 두 export 줄을 먼저 뺀다.
버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복
유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지).
위험·한계:
- recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다
(조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore`
생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입
4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다.
- `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가
아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다.
- `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다.
barrel 줄 제거와 경로 추가는 코드로만 확인했다.
검증:
- RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다.
`expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes
tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node
통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요),
`verify-documentation-readiness` PASS_SCOPED.
`check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산
초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다.
이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖).
BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS·
storage durability·public cache 타입 중 src/application/ports와 이름이
같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를
구현하고 BrowserDataResult를 돌려준다(`result.failure.code` →
`result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy,
maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은
`FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity`
·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03
244 lines
6.5 KiB
TypeScript
244 lines
6.5 KiB
TypeScript
/**
|
|
* Opt-in capability contracts.
|
|
*
|
|
* This directory is a copyable recipe source, not a production entry. A project
|
|
* moves only the selected contract into its application-owned boundary and puts
|
|
* a concrete implementation behind that port.
|
|
*/
|
|
export const OPTIONAL_RECIPE_RUNTIME_SENTINEL =
|
|
"frontend-optional-recipe-must-not-reach-production";
|
|
|
|
export type CapabilityFailureCode =
|
|
| "ABORTED"
|
|
| "AUTH_EXPIRED"
|
|
| "BLOCKED"
|
|
| "CONFLICT"
|
|
| "CONSENT_DENIED"
|
|
| "CONTRACT_DRIFT"
|
|
| "CORRUPT_DATA"
|
|
| "DISCONNECTED"
|
|
| "EXPIRED_RESOURCE"
|
|
| "INTEGRITY_FAILED"
|
|
| "INVALID_INPUT"
|
|
| "LIMIT_EXCEEDED"
|
|
| "MIGRATION_FAILED"
|
|
| "NOT_FOUND"
|
|
| "NOT_READABLE"
|
|
| "PERMISSION_DENIED"
|
|
| "POLICY_REJECTED"
|
|
| "PROVIDER_UNAVAILABLE"
|
|
| "QUOTA_EXCEEDED"
|
|
| "STALE_RESULT"
|
|
| "STORAGE_EVICTED"
|
|
| "UNSUPPORTED";
|
|
|
|
export type CapabilityFailure = Readonly<{
|
|
code: CapabilityFailureCode;
|
|
retryable: boolean;
|
|
safeMessage: string;
|
|
}>;
|
|
|
|
export type CapabilityResult<T> =
|
|
| Readonly<{ ok: true; value: T }>
|
|
| Readonly<{ ok: false; failure: CapabilityFailure }>;
|
|
|
|
export type Cleanup = () => void;
|
|
|
|
export type RealtimeEvent<T> = Readonly<{
|
|
id: string;
|
|
sequence: number;
|
|
occurredAt: string;
|
|
payload: T;
|
|
}>;
|
|
|
|
export interface RealtimeSubscription {
|
|
readonly resumeToken: string | null;
|
|
unsubscribe(): void;
|
|
}
|
|
|
|
export interface RealtimePort<T> {
|
|
subscribe(input: {
|
|
channel: string;
|
|
resumeToken?: string;
|
|
signal?: AbortSignal;
|
|
onEvent(event: CapabilityResult<RealtimeEvent<T>>): void;
|
|
}): Promise<CapabilityResult<RealtimeSubscription>>;
|
|
heartbeat(signal?: AbortSignal): Promise<CapabilityResult<void>>;
|
|
}
|
|
|
|
export interface VersionedOfflineRepository<T extends { id: string }> {
|
|
open(input: {
|
|
schemaVersion: number;
|
|
signal?: AbortSignal;
|
|
}): Promise<CapabilityResult<void>>;
|
|
get(id: string, signal?: AbortSignal): Promise<CapabilityResult<T | null>>;
|
|
put(value: T, signal?: AbortSignal): Promise<CapabilityResult<void>>;
|
|
migrate(input: {
|
|
from: number;
|
|
to: number;
|
|
signal?: AbortSignal;
|
|
}): Promise<CapabilityResult<void>>;
|
|
close(): void;
|
|
}
|
|
|
|
export interface ServiceWorkerUpdatePort {
|
|
inspect(signal?: AbortSignal): Promise<
|
|
CapabilityResult<Readonly<{ updateAvailable: boolean; version: string | null }>>
|
|
>;
|
|
activate(version: string, signal?: AbortSignal): Promise<CapabilityResult<void>>;
|
|
rollback(signal?: AbortSignal): Promise<CapabilityResult<void>>;
|
|
unregister(): Promise<CapabilityResult<void>>;
|
|
}
|
|
|
|
/**
|
|
* [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"
|
|
| "TRANSFERRING"
|
|
| "VERIFYING"
|
|
| "FINALIZING";
|
|
transferredBytes: number;
|
|
totalBytes: number | null;
|
|
}>;
|
|
|
|
export type TransferByteSource = Readonly<{
|
|
byteLength: number | null;
|
|
chunks: AsyncIterable<Uint8Array>;
|
|
}>;
|
|
|
|
export interface FileTransferPort {
|
|
upload(input: {
|
|
file: Readonly<{
|
|
name: string;
|
|
size: number;
|
|
type: string;
|
|
content: TransferByteSource;
|
|
}>;
|
|
signal: AbortSignal;
|
|
onProgress(progress: FileTransferProgress): void;
|
|
}): Promise<CapabilityResult<Readonly<{ resourceId: string }>>>;
|
|
download(input: {
|
|
resourceId: string;
|
|
signal: AbortSignal;
|
|
onProgress(progress: FileTransferProgress): void;
|
|
}): Promise<
|
|
CapabilityResult<
|
|
Readonly<{
|
|
fileName: string;
|
|
mediaType: string;
|
|
content: TransferByteSource;
|
|
}>
|
|
>
|
|
>;
|
|
}
|
|
|
|
export interface GeneratedApiFacade {
|
|
execute<TOutput>(input: {
|
|
operationId: string;
|
|
contractVersion: string;
|
|
body?: unknown;
|
|
signal?: AbortSignal;
|
|
}): Promise<CapabilityResult<TOutput>>;
|
|
}
|
|
|
|
export interface FeatureFlagPort<TFlags extends Record<string, boolean | string | number>> {
|
|
evaluate<TKey extends keyof TFlags>(input: {
|
|
key: TKey;
|
|
fallback: TFlags[TKey];
|
|
maxAgeMs: number;
|
|
}): Promise<CapabilityResult<TFlags[TKey]>>;
|
|
}
|
|
|
|
export interface WorkerTaskPort<TInput, TOutput> {
|
|
run(input: {
|
|
taskId: string;
|
|
generation: number;
|
|
payload: TInput;
|
|
signal: AbortSignal;
|
|
}): Promise<CapabilityResult<TOutput>>;
|
|
cancel(taskId: string): void;
|
|
dispose(): void;
|
|
}
|
|
|
|
export type MultiTabEvent<T> = Readonly<{
|
|
eventId: string;
|
|
sourceId: string;
|
|
version: number;
|
|
payload: T;
|
|
}>;
|
|
|
|
export interface MultiTabPort<T> {
|
|
publish(event: MultiTabEvent<T>): CapabilityResult<void>;
|
|
subscribe(input: {
|
|
sourceId: string;
|
|
onEvent(event: CapabilityResult<MultiTabEvent<T>>): void;
|
|
}): Cleanup;
|
|
close(): void;
|
|
}
|
|
|
|
export type BrowserCapability =
|
|
| "clipboard-read"
|
|
| "clipboard-write"
|
|
| "media"
|
|
| "notification";
|
|
|
|
export type PermissionDecision = "granted" | "denied" | "dismissed";
|
|
|
|
export interface BrowserPermissionPort {
|
|
request(input: {
|
|
capability: BrowserCapability;
|
|
signal?: AbortSignal;
|
|
}): Promise<CapabilityResult<PermissionDecision>>;
|
|
}
|
|
|
|
export interface ClientWorkflowPort<TState, TEvent> {
|
|
snapshot(): Readonly<TState>;
|
|
dispatch(event: TEvent): CapabilityResult<Readonly<TState>>;
|
|
reset(): void;
|
|
subscribe(listener: (state: Readonly<TState>) => void): Cleanup;
|
|
}
|
|
|
|
export interface LargeDataUiFacade<TRow extends { id: string }> {
|
|
window(input: {
|
|
offset: number;
|
|
limit: number;
|
|
generation: number;
|
|
}): CapabilityResult<ReadonlyArray<TRow>>;
|
|
focus(rowId: string): CapabilityResult<void>;
|
|
replace(rows: ReadonlyArray<TRow>, generation: number): void;
|
|
}
|
|
|
|
export type SafeAnalyticsValue = boolean | number | string | null;
|
|
|
|
export interface AnalyticsErrorSink {
|
|
record(input: {
|
|
kind: "analytics" | "error";
|
|
eventId: string;
|
|
consent: "granted" | "denied" | "not-required";
|
|
attributes: Readonly<Record<string, SafeAnalyticsValue>>;
|
|
}): CapabilityResult<void>;
|
|
flush(signal?: AbortSignal): Promise<CapabilityResult<void>>;
|
|
dispose(): void;
|
|
}
|
|
|
|
export type OptionalCapabilityPorts = Readonly<{
|
|
realtime: RealtimePort<unknown>;
|
|
offline: VersionedOfflineRepository<{ id: string }>;
|
|
serviceWorker: ServiceWorkerUpdatePort;
|
|
fileTransfer: FileTransferPort;
|
|
generatedApi: GeneratedApiFacade;
|
|
featureFlag: FeatureFlagPort<Record<string, boolean | string | number>>;
|
|
worker: WorkerTaskPort<unknown, unknown>;
|
|
multiTab: MultiTabPort<unknown>;
|
|
browserPermission: BrowserPermissionPort;
|
|
clientWorkflow: ClientWorkflowPort<unknown, unknown>;
|
|
largeDataUi: LargeDataUiFacade<{ id: string }>;
|
|
analytics: AnalyticsErrorSink;
|
|
}>;
|