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

fix: preserve logical mutation intent

Browse Source
This commit is contained in:
DongHyeonka
2026-08-02 01:07:19 +09:00
parent 53d181fbe4
commit cbcc7b5ed7
21 changed files with 724 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/unit/http-execution-v3.test.ts
+139 -2
View File
@@ -21,6 +21,20 @@ const scope = Object.freeze({
const createInstalled: InstalledHttpContract<unknown, unknown, unknown> =
TEST_CREATE_HTTP_CONTRACT;
function mutationIntent(
overrides: Readonly<{ intentId?: string; idempotencyKey?: string }> = {},
) {
return Object.freeze({
intentId: overrides.intentId ?? "intent-1",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "opaque-input-identity",
...(overrides.idempotencyKey === undefined
? { idempotencyKey: "key-1" }
: { idempotencyKey: overrides.idempotencyKey }),
createdAtMonotonicMs: 1,
});
}
function operation(
overrides: Readonly<{
deadlineMs?: number;
@@ -47,6 +61,129 @@ async function flushMicrotasks(): Promise<void> {
}
describe("descriptor-driven HTTP execution lifetime", () => {
it("reuses one supplied idempotency key across every physical retry", async () => {
const observedKeys: Array<string | null> = [];
let attempt = 0;
const fetcher = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
observedKeys.push(new Headers(init?.headers).get("Idempotency-Key"));
attempt += 1;
if (attempt === 1) throw new TypeError("synchronous pre-dispatch failure");
return Promise.resolve(
Response.json(
{ id: "created", name: "Created" },
{ status: 201 },
),
);
});
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 1,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher,
sleep: async () => {},
random: () => 0,
});
const retryingCreate = {
...createInstalled,
frontend: {
...createInstalled.frontend,
retryBudget: 1 as const,
},
};
await expect(
executor.execute(
retryingCreate,
{ name: "created" },
{ scope, intent: mutationIntent({ idempotencyKey: "logical-key" }) },
),
).resolves.toMatchObject({ kind: "SUCCESS" });
expect(fetcher).toHaveBeenCalledTimes(2);
expect(observedKeys).toEqual(["logical-key", "logical-key"]);
});
it("never emits a mutation idempotency header for a query", async () => {
const observedKeys: Array<string | null> = [];
const fetcher = vi.fn(
async (_input: RequestInfo | URL, init?: RequestInit) => {
observedKeys.push(
new Headers(init?.headers).get("Idempotency-Key"),
);
return Response.json([]);
},
);
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher,
});
await expect(
executor.execute(
installed,
{ limit: 20 },
{ scope },
),
).resolves.toMatchObject({ kind: "SUCCESS" });
expect(fetcher).toHaveBeenCalledOnce();
expect(observedKeys).toEqual([null]);
});
it("keeps intent identities out of request URLs and safe observations", async () => {
const urls: string[] = [];
const observations: unknown[] = [];
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher: vi.fn(async (input) => {
urls.push(String(input));
return Response.json(
{ id: "created", name: "Created" },
{ status: 201 },
);
}),
observe: (observation) => observations.push(observation),
});
await expect(
executor.execute(
createInstalled,
{ name: "created" },
{
scope,
intent: Object.freeze({
intentId: "private-intent-id",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "private-canonical-input",
idempotencyKey: "private-idempotency-key",
createdAtMonotonicMs: 1,
}),
},
),
).resolves.toMatchObject({ kind: "SUCCESS" });
const safeEvidence = JSON.stringify({ urls, observations });
expect(urls).toEqual(["https://api.example/api/test-entities"]);
expect(observations).toHaveLength(1);
expect(safeEvidence).not.toContain("private-intent-id");
expect(safeEvidence).not.toContain("private-canonical-input");
expect(safeEvidence).not.toContain("private-idempotency-key");
});
it.each([
[{}, "limit=20"],
[{ limit: "7" }, "limit=7"],
@@ -127,7 +264,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
{ name: "created" },
{
scope,
intent: { intentId: "intent-1", startedBy: "USER", idempotencyKey: "key-1" },
intent: mutationIntent(),
},
),
).resolves.toMatchObject({
@@ -169,7 +306,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
{ name: "created" },
{
scope: fencedScope,
intent: { intentId: "intent-2", startedBy: "USER", idempotencyKey: "key-2" },
intent: mutationIntent({ intentId: "intent-2", idempotencyKey: "key-2" }),
},
),
).resolves.toMatchObject({
tests/unit/runtime-adapters.test.ts
+120
View File
@@ -4,6 +4,7 @@ import {
createRuntimeAdapters,
createRuntimeHttpClient,
} from "../../src/bootstrap/runtime-adapters.ts";
import { createBrowserMutationIntentFactory } from "../../src/adapters/platform/browser-mutation-intent-factory.ts";
import { TEST_HTTP_CONTRACT } from "../helpers/http-contract-fixture.ts";
type Runtime = Parameters<typeof createRuntimeAdapters>[0]["runtime"];
@@ -53,6 +54,65 @@ const release: Release = {
};
describe("runtime adapter composition", () => {
it("creates validated intent and idempotency identities with independent UUID calls", () => {
const randomUUID = vi
.fn<() => string>()
.mockReturnValueOnce("intent-uuid")
.mockReturnValueOnce("idempotency-uuid");
const factory = createBrowserMutationIntentFactory({
randomUUID,
monotonicNow: () => 12.5,
});
const intent = factory.create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "opaque-canonical-input",
requiresIdempotencyKey: true,
});
expect(intent).toEqual({
intentId: "intent-uuid",
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "opaque-canonical-input",
idempotencyKey: "idempotency-uuid",
createdAtMonotonicMs: 12.5,
});
expect(Object.isFrozen(intent)).toBe(true);
expect(randomUUID).toHaveBeenCalledTimes(2);
});
it("rejects invalid or unbounded mutation intent values", () => {
const factory = createBrowserMutationIntentFactory({
randomUUID: () => "opaque-runtime-identifier",
monotonicNow: () => 1,
});
expect(() =>
factory.create({
operationId: " ",
canonicalInputIdentity: "valid-identity",
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
expect(() =>
factory.create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "x".repeat(16_385),
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
expect(() =>
createBrowserMutationIntentFactory({
randomUUID: () => "opaque-runtime-identifier",
monotonicNow: () => -1,
}).create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "valid-identity",
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
});
it("constructs the local demo seam and infrastructure adapters", async () => {
const adapters = await createRuntimeAdapters({
runtime,
@@ -66,6 +126,7 @@ describe("runtime adapter composition", () => {
});
expect(adapters.infrastructure.queryClient).toBeDefined();
expect(adapters.infrastructure.queryInvalidation).toBeDefined();
expect(adapters.infrastructure.mutationIntentFactory).toBeDefined();
expect(
adapters.infrastructure.crossContextInvalidationStatus(),
).toBe("DEGRADED_LOCAL_ONLY");
@@ -81,6 +142,8 @@ describe("runtime adapter composition", () => {
const adapters = await createRuntimeAdapters({ runtime, release, host: {} });
const previousClient = adapters.infrastructure.queryClient;
const previousCoordinator = adapters.infrastructure.queryInvalidation;
const runtimeMutationIntentFactory =
adapters.infrastructure.mutationIntentFactory;
const clearPrevious = vi.spyOn(previousClient, "clear");
await adapters.outputPorts.session.beginSignIn();
@@ -91,6 +154,9 @@ describe("runtime adapter composition", () => {
expect(adapters.infrastructure.queryInvalidation).not.toBe(
previousCoordinator,
);
expect(adapters.infrastructure.mutationIntentFactory).toBe(
runtimeMutationIntentFactory,
);
const clearCallsAfterReplacement = clearPrevious.mock.calls.length;
await previousCoordinator.resetLocal();
@@ -99,6 +165,60 @@ describe("runtime adapter composition", () => {
adapters.infrastructure.dispose();
});
it("passes the supplied command intent unchanged and keeps private identity out of URLs and diagnostics", async () => {
const requests: Array<Readonly<{ url: string; headers: Headers }>> = [];
const fetcher = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
requests.push({
url: String(input),
headers: new Headers(init?.headers),
});
return Response.json(
{ id: "resource-1", name: "Created resource" },
{ status: 201 },
);
});
const adapters = await createRuntimeAdapters({
runtime,
release,
host: {},
fetcher,
});
await adapters.outputPorts.session.beginSignIn();
await vi.waitFor(() =>
expect(adapters.infrastructure.serverStateScope.getPhase()).toBe("READY"),
);
const intent = Object.freeze({
intentId: "private-intent-id",
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "private-canonical-input",
idempotencyKey: "private-idempotency-key",
createdAtMonotonicMs: 42,
});
await expect(
adapters.featureInputs["reference-feature"].createResource(
{ name: "Created resource" },
{ intent },
),
).resolves.toMatchObject({ ok: true });
expect(requests).toHaveLength(1);
expect(requests[0]?.headers.get("Idempotency-Key")).toBe(
"private-idempotency-key",
);
expect(requests[0]?.url).toBe(
"http://localhost:8080/api/reference-resources",
);
const safeEvidence = JSON.stringify({
requests: requests.map((request) => request.url),
diagnostics: adapters.outputPorts.diagnostics.entries(),
});
expect(safeEvidence).not.toContain("private-intent-id");
expect(safeEvidence).not.toContain("private-canonical-input");
expect(safeEvidence).not.toContain("private-idempotency-key");
adapters.infrastructure.dispose();
});
it("does not fail boot when Web Storage capability getters throw", async () => {
const host: Record<string, unknown> = {};
Object.defineProperties(host, {