Files
clean-architecture-frontend…/tests/unit/storage-registry.test.ts
T
DongHyeonka b5c7128bda test(storage): Web Storage의 Firefox quota 이름과 만료 경계를 고정한다
문제: 2026-11-01 05-06에서 남은 두 분기를 테스트가 잡지 못한다. 이번
리뷰에서도 두 변이가 Web Storage 관련 테스트 3파일 49건을 통과했다.
- W4: quota 판정 목록에서 Firefox의 NS_ERROR_DOM_QUOTA_REACHED를 빼도
  테스트가 통과한다. 빠지면 Firefox의 quota 실패가 memory fallback 없이
  STORAGE_UNAVAILABLE이 된다.
- W8: 만료 비교 `<=`를 `<`로 바꿔도 통과한다. 만료 시각과 같은 순간에
  값을 돌려준다.

고른 방법: 각 분기에 실패하는 테스트 하나씩. 저장소 test double에
Firefox 이름으로 던지는 모드를 더했고, 만료 경계는 expiresAt 100·101을
now 100에서 읽는다.

위험·한계: 테스트만 바꾼다. codec을 직접 부르는 테스트는 여전히 없다.

검증: W4·W8 변이를 하나씩 넣고 storage-registry·runtime-adapters·
browser-storage-policy 테스트를 돌렸다. 둘 다 새 테스트가 실패했고,
원래 코드에서 storage-registry 26건 통과. check:types:test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 1101/05-06
2026-11-04 20:57:19 +09:00

630 lines
20 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.ts";
import {
STORAGE_REGISTRY,
buildPhysicalKey,
defineStorageKey,
getStorageDefinition,
isStorageValueAllowed,
type StorageDefinition,
type StorageKeyInput,
} from "../../src/contracts/storage-keys.ts";
type StorageFailureMode = "none" | "quota" | "firefox-quota" | "security";
function createStorage(options: {
initial?: Readonly<Record<string, string>>;
writeFailure?: StorageFailureMode;
readFailure?: StorageFailureMode;
removeFailure?: StorageFailureMode;
} = {}) {
const values = new Map<string, string>(Object.entries(options.initial ?? {}));
const state = {
writeFailure: options.writeFailure ?? "none",
readFailure: options.readFailure ?? "none",
removeFailure: options.removeFailure ?? "none",
};
const getItem = vi.fn((key: string) => {
throwFor(state.readFailure);
return values.get(key) ?? null;
});
const setItem = vi.fn((key: string, value: string) => {
throwFor(state.writeFailure);
values.set(key, value);
});
const removeItem = vi.fn((key: string) => {
throwFor(state.removeFailure);
values.delete(key);
});
const storage: Storage = {
getItem,
setItem,
removeItem,
clear: () => values.clear(),
key: (index) => [...values.keys()][index] ?? null,
get length() {
return values.size;
},
};
return { storage, values, state, getItem, setItem, removeItem };
}
function throwFor(mode: StorageFailureMode): void {
if (mode === "quota") {
throw new DOMException("private quota detail", "QuotaExceededError");
}
if (mode === "firefox-quota") {
// Older Firefox names the quota error this way, with code 1014.
throw new DOMException("private quota detail", "NS_ERROR_DOM_QUOTA_REACHED");
}
if (mode === "security") {
throw new DOMException("private security detail", "SecurityError");
}
}
function serializedEnvelope(
value: unknown,
overrides: Readonly<{
schemaVersion?: number;
expiresAt?: number | null;
}> = {},
): string {
return JSON.stringify({
schemaVersion: overrides.schemaVersion ?? 1,
expiresAt: overrides.expiresAt ?? null,
value,
});
}
function definitionResolver(
extra: Readonly<Record<string, StorageDefinition>>,
) {
return (logicalName: string): StorageDefinition =>
extra[logicalName] ?? getStorageDefinition(logicalName);
}
describe("storage registry", () => {
it("builds namespace and schema-versioned physical keys", () => {
expect(buildPhysicalKey("preference", 2, "theme")).toBe(
"ca-frontend:preference:v2:theme",
);
expect(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey).toContain(":v1:");
});
it("rejects token or secret persistence registrations", () => {
expect(() =>
defineStorageKey({
logicalName: "TOKEN",
scope: "auth",
name: "token",
backend: "localStorage",
classification: "sensitive-forbidden",
schemaVersion: 1,
valueCodec: "none",
ttl: null,
migration: "discard",
quotaFallback: "feature-disable",
}),
).toThrow("Sensitive client storage registration is forbidden");
});
it("enforces the registry-owned typed value codec contract", () => {
const colorScheme = STORAGE_REGISTRY.COLOR_SCHEME;
expect(
["system", "light", "dark"].every((value) =>
isStorageValueAllowed(colorScheme, value),
),
).toBe(true);
expect(
[
"",
"LIGHT",
"private-custom-theme",
1,
null,
{ mode: "dark" },
].some((value) => isStorageValueAllowed(colorScheme, value)),
).toBe(false);
const opaqueString = STORAGE_REGISTRY.CHUNK_RELOAD_GUARD;
expect(isStorageValueAllowed(opaqueString, "a")).toBe(true);
expect(isStorageValueAllowed(opaqueString, "x".repeat(2_048))).toBe(true);
expect(isStorageValueAllowed(opaqueString, "")).toBe(false);
expect(isStorageValueAllowed(opaqueString, "x".repeat(2_049))).toBe(false);
expect(isStorageValueAllowed(opaqueString, { value: "opaque" })).toBe(false);
expect(
isStorageValueAllowed(
STORAGE_REGISTRY.QUERY_PERSISTENCE,
"must-never-persist",
),
).toBe(false);
});
it("rejects unregistered codecs and executable migration policies", () => {
const definition = {
logicalName: "UNSAFE_POLICY",
scope: "preference",
name: "unsafe-policy",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "unregistered-codec",
ttl: null,
migration: "discard",
quotaFallback: "no-persist",
} as unknown as StorageKeyInput;
expect(() => defineStorageKey(definition)).toThrow(
"Unknown client storage value codec",
);
expect(() =>
defineStorageKey({
...definition,
valueCodec: "opaque-string-v1",
migration: (() => "unsafe") as unknown as "discard",
}),
).toThrow("Unsupported client storage migration policy");
});
// 05-01. The cross-context adapter writes raw wire JSON to this physical
// key. StoragePort must refuse the key instead of discarding that value as
// a corrupt envelope or overwriting it with one.
it("refuses the externally owned pulse key without touching its value", () => {
const pulse = STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE;
const rawPulse = JSON.stringify({ protocolVersion: 1, topic: "t" });
const { storage, values, setItem, removeItem } = createStorage({
initial: { [pulse.physicalKey]: rawPulse },
});
const adapter = createBrowserStorageAdapter({ localStorage: storage });
expect(adapter.read("CACHE_INVALIDATION_PULSE")).toMatchObject({
ok: false,
error: { code: "CACHE_INVALIDATION_PULSE_READ_UNAVAILABLE" },
});
expect(adapter.write("CACHE_INVALIDATION_PULSE", "hello")).toMatchObject({
ok: false,
});
expect(adapter.remove("CACHE_INVALIDATION_PULSE")).toMatchObject({
ok: false,
});
expect(setItem).not.toHaveBeenCalled();
expect(removeItem).not.toHaveBeenCalled();
expect(values.get(pulse.physicalKey)).toBe(rawPulse);
expect(pulse.physicalKey).toBe("ca-frontend:cache-invalidation:v1:pulse");
expect(pulse).toMatchObject({ backend: "external", valueCodec: "none" });
expect(() => getStorageDefinition("CACHE_INVALIDATION_PULSE")).toThrow(
"Externally owned storage key: CACHE_INVALIDATION_PULSE",
);
});
it("rejects a value codec on an externally owned key", () => {
expect(() =>
defineStorageKey({
logicalName: "EXTERNAL_WITH_CODEC",
scope: "cache",
name: "external-with-codec",
backend: "external",
classification: "opaque-cache",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl: null,
migration: "discard",
quotaFallback: "no-persist",
}),
).toThrow("Externally owned storage keys have no StoragePort codec");
});
it("round-trips public preferences through the adapter", () => {
const { storage: localStorage } = createStorage();
const adapter = createBrowserStorageAdapter({ localStorage });
expect(adapter.write("COLOR_SCHEME", "dark")).toEqual({ ok: true });
expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
});
it("keeps local and session registry entries on their declared backends", () => {
const local = createStorage();
const session = createStorage();
const adapter = createBrowserStorageAdapter({
localStorage: local.storage,
sessionStorage: session.storage,
});
expect(adapter.write("COLOR_SCHEME", "light")).toEqual({ ok: true });
expect(adapter.write("CHUNK_RELOAD_GUARD", "release-a->release-b")).toEqual({
ok: true,
});
expect(
local.values.has(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey),
).toBe(true);
expect(
local.values.has(STORAGE_REGISTRY.CHUNK_RELOAD_GUARD.physicalKey),
).toBe(false);
expect(
session.values.has(STORAGE_REGISTRY.CHUNK_RELOAD_GUARD.physicalKey),
).toBe(true);
expect(adapter.read("CHUNK_RELOAD_GUARD")).toEqual({
ok: true,
value: "release-a->release-b",
});
});
it("falls back to memory when preference storage quota is exceeded", () => {
const { storage: localStorage } = createStorage({
writeFailure: "quota",
});
const record = vi.fn();
const adapter = createBrowserStorageAdapter({
localStorage,
diagnostics: { record },
});
expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
ok: false,
fallback: "memory",
error: { kind: "STORAGE_QUOTA_EXCEEDED" },
});
expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
expect(record).toHaveBeenCalledOnce();
expect(record).toHaveBeenCalledWith({
level: "warn",
eventId: "storage.operation.failed",
context: {
operation: "write:COLOR_SCHEME",
error_kind: "STORAGE_QUOTA_EXCEEDED",
reason: "QUOTA_EXCEEDED",
},
});
expect(JSON.stringify(record.mock.calls)).not.toContain("dark");
expect(JSON.stringify(record.mock.calls)).not.toContain(
"private quota detail",
);
});
// 2026-11-01 05-06. The second quota name was in the adapter's list but no
// test sent it, so dropping it went unseen.
it("falls back to memory on Firefox's quota error name too", () => {
const { storage: localStorage } = createStorage({
writeFailure: "firefox-quota",
});
const adapter = createBrowserStorageAdapter({ localStorage });
expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
ok: false,
fallback: "memory",
error: { kind: "STORAGE_QUOTA_EXCEEDED" },
});
expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
});
it("discards data from a previous schema version", () => {
const { storage: localStorage, values, removeItem } = createStorage({
initial: {
[STORAGE_REGISTRY.COLOR_SCHEME.physicalKey]: serializedEnvelope(
"dark",
{ schemaVersion: 2 },
),
},
});
const adapter = createBrowserStorageAdapter({ localStorage });
expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined });
expect(removeItem).toHaveBeenCalledOnce();
expect(values.has(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey)).toBe(false);
});
it("rejects values outside the selected key codec before persistence", () => {
const { storage: localStorage, setItem } = createStorage();
const adapter = createBrowserStorageAdapter({ localStorage });
expect(adapter.write("COLOR_SCHEME", { mode: "dark" })).toMatchObject({
ok: false,
error: {
kind: "STORAGE_UNAVAILABLE",
code: "COLOR_SCHEME_WRITE_VALUE_REJECTED",
},
});
expect(setItem).not.toHaveBeenCalled();
});
it.each([
["malformed JSON", "{private malformed value", "VALUE_REJECTED"],
[
"invalid envelope",
JSON.stringify({
schemaVersion: 1,
expiresAt: null,
value: "dark",
unexpected: "private",
}),
"VALUE_REJECTED",
],
["oversized record", "x".repeat(512), "SIZE_LIMIT_EXCEEDED"],
])(
"removes a %s once and suppresses it when native cleanup fails",
(_label, raw, reason) => {
const physicalKey = STORAGE_REGISTRY.COLOR_SCHEME.physicalKey;
const { storage, getItem, removeItem } = createStorage({
initial: { [physicalKey]: raw },
removeFailure: "security",
});
const record = vi.fn();
const adapter = createBrowserStorageAdapter({
localStorage: storage,
diagnostics: { record },
maxSerializedBytes: 128,
});
expect(adapter.read("COLOR_SCHEME")).toEqual({
ok: true,
value: undefined,
});
expect(adapter.read("COLOR_SCHEME")).toEqual({
ok: true,
value: undefined,
});
expect(getItem).toHaveBeenCalledOnce();
expect(removeItem).toHaveBeenCalledOnce();
// 05-02. A discarded value must not read as "storage unavailable".
expect(record).toHaveBeenCalledWith({
level: "warn",
eventId: "storage.operation.failed",
context: {
operation: "discard:COLOR_SCHEME",
error_kind: "STORAGE_UNAVAILABLE",
reason,
},
});
expect(JSON.stringify(record.mock.calls)).not.toMatch(
/private|malformed|unexpected/,
);
},
);
it("removes expired persistent records and does not return their value", () => {
const expiring = defineStorageKey({
logicalName: "EXPIRING_PREFERENCE",
scope: "preference",
name: "expiring",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl: 10,
migration: "discard",
quotaFallback: "memory",
});
const { storage, removeItem } = createStorage({
initial: {
[expiring.physicalKey]: serializedEnvelope("private-expired", {
expiresAt: 99,
}),
},
});
const adapter = createBrowserStorageAdapter({
localStorage: storage,
now: () => 100,
resolveDefinition: definitionResolver({
EXPIRING_PREFERENCE: expiring,
}),
});
expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({
ok: true,
value: undefined,
});
expect(removeItem).toHaveBeenCalledWith(expiring.physicalKey);
});
// 2026-11-01 05-06. A record is expired at its expiry instant, not after it.
it.each([
[100, undefined],
[101, "private-expiring"],
])("reads a record expiring at %i at time 100 as %s", (expiresAt, value) => {
const expiring = defineStorageKey({
logicalName: "EXPIRING_PREFERENCE",
scope: "preference",
name: "expiring",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl: 10,
migration: "discard",
quotaFallback: "memory",
});
const { storage } = createStorage({
initial: {
[expiring.physicalKey]: serializedEnvelope("private-expiring", {
expiresAt,
}),
},
});
const adapter = createBrowserStorageAdapter({
localStorage: storage,
now: () => 100,
resolveDefinition: definitionResolver({
EXPIRING_PREFERENCE: expiring,
}),
});
expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value });
});
it("prioritizes a failed-write memory envelope over stale persistent data and expires it", () => {
let timestamp = 100;
const expiring = defineStorageKey({
logicalName: "EXPIRING_PREFERENCE",
scope: "preference",
name: "expiring",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl: 10,
migration: "discard",
quotaFallback: "memory",
});
const { storage, state } = createStorage({
initial: {
[expiring.physicalKey]: serializedEnvelope("stale", {
expiresAt: 1_000,
}),
},
writeFailure: "quota",
});
const adapter = createBrowserStorageAdapter({
localStorage: storage,
now: () => timestamp,
resolveDefinition: definitionResolver({
EXPIRING_PREFERENCE: expiring,
}),
});
expect(adapter.write("EXPIRING_PREFERENCE", "fresh")).toMatchObject({
ok: false,
fallback: "memory",
});
expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({
ok: true,
value: "fresh",
});
state.writeFailure = "none";
timestamp = 111;
expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({
ok: true,
value: undefined,
});
});
it("clears a failed-write overlay after a later persistent write succeeds", () => {
const physicalKey = STORAGE_REGISTRY.COLOR_SCHEME.physicalKey;
const { storage, state, values } = createStorage({
writeFailure: "security",
});
const adapter = createBrowserStorageAdapter({ localStorage: storage });
expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
ok: false,
fallback: "memory",
error: { kind: "STORAGE_UNAVAILABLE" },
});
expect(adapter.read("COLOR_SCHEME")).toEqual({
ok: true,
value: "dark",
});
state.writeFailure = "none";
expect(adapter.write("COLOR_SCHEME", "light")).toEqual({ ok: true });
values.set(physicalKey, serializedEnvelope("system"));
expect(adapter.read("COLOR_SCHEME")).toEqual({
ok: true,
value: "system",
});
});
it("purges the memory overlay even when persistent remove throws", () => {
const { storage, state } = createStorage({
writeFailure: "quota",
removeFailure: "security",
});
const adapter = createBrowserStorageAdapter({ localStorage: storage });
expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
fallback: "memory",
});
state.writeFailure = "none";
expect(adapter.remove("COLOR_SCHEME")).toMatchObject({
ok: false,
error: { kind: "STORAGE_UNAVAILABLE" },
});
expect(adapter.read("COLOR_SCHEME")).toEqual({
ok: true,
value: undefined,
});
});
it("normalizes SecurityError reads and never exposes native details", () => {
const { storage } = createStorage({ readFailure: "security" });
const record = vi.fn();
const adapter = createBrowserStorageAdapter({
localStorage: storage,
diagnostics: { record },
});
const result = adapter.read("COLOR_SCHEME");
expect(result).toMatchObject({
ok: false,
error: {
kind: "STORAGE_UNAVAILABLE",
code: "COLOR_SCHEME_READ_UNAVAILABLE",
},
});
expect(JSON.stringify({ result, calls: record.mock.calls })).not.toContain(
"private security detail",
);
});
it.each([
["cyclic", (() => {
const value: { self?: unknown; secret: string } = {
secret: "private-cyclic",
};
value.self = value;
return value;
})()],
["BigInt", { secret: "private-bigint", value: 1n }],
["exotic", new Date(0)],
])("rejects %s values before calling the backend", (_label, value) => {
const { storage, setItem } = createStorage();
const record = vi.fn();
const adapter = createBrowserStorageAdapter({
localStorage: storage,
diagnostics: { record },
});
const result = adapter.write("COLOR_SCHEME", value);
expect(result).toMatchObject({
ok: false,
error: {
kind: "STORAGE_UNAVAILABLE",
code: "COLOR_SCHEME_WRITE_VALUE_REJECTED",
},
});
expect(setItem).not.toHaveBeenCalled();
expect(JSON.stringify({ result, calls: record.mock.calls })).not.toMatch(
/private-cyclic|private-bigint/,
);
});
it("rejects oversized serialized values before persistence and redacts them", () => {
const secret = `private-oversize-${"x".repeat(512)}`;
const { storage, setItem } = createStorage();
const record = vi.fn();
const adapter = createBrowserStorageAdapter({
sessionStorage: storage,
diagnostics: { record },
maxSerializedBytes: 128,
});
const result = adapter.write("CHUNK_RELOAD_GUARD", secret);
expect(result).toMatchObject({
ok: false,
error: {
kind: "STORAGE_UNAVAILABLE",
code: "CHUNK_RELOAD_GUARD_WRITE_SIZE_LIMIT_EXCEEDED",
},
});
expect(record).toHaveBeenCalledWith(
expect.objectContaining({
context: expect.objectContaining({ reason: "SIZE_LIMIT_EXCEEDED" }),
}),
);
expect(setItem).not.toHaveBeenCalled();
expect(JSON.stringify({ result, calls: record.mock.calls })).not.toContain(
secret,
);
});
});