Files
clean-architecture-frontend…/tests/unit/realtime/bounded-polling-policy.test.ts
T
DongHyeonka a65df74046 fix(realtime)!: bounded poll을 V3 descriptor에 묶어 실행기 재시도를 막는다
문제
BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2,
protocol, semantics, replayPolicy, retry, transportMaxAttempts,
authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다.
assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와
대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET
descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다.
poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P).

고른 방법
- coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다.
  실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다
  (http-execution-v3.ts retryCeiling). 그래서 생성 때
  retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청
  한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다.
- 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT,
  retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는
  maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다.
- V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립
  (composeContractContributions)이 GET·HEAD에서 이미 거절한다.
- 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는
  retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은
  객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기
  옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가
  재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이
  없다.

위험·한계
- 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다.
- 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에
  넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고
  적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다.
- 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용
  operation을 따로 등록해야 한다.

검증
- 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과.
- 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError,
  retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서
  poll 3회 = 요청 3회.
- 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사
  삭제) 모두 검출.
- check:types 통과, 바꾼 파일 eslint 통과.

BREAKING CHANGE: BoundedPollOperationContract를 지운다.
createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의
둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다.
조립된 행(composeContractContributions(...).httpByOperationId.get(id))을
넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다.
execute 안에서는 같은 descriptor를 실행기에 넘긴다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01
2026-11-04 20:21:39 +09:00

123 lines
3.7 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
BOUNDED_POLLING_CEILINGS,
assertBoundedPollOperation,
definePollLeasePolicy,
type BoundedPollOperation,
} from "../../../src/application/policies/bounded-polling.ts";
import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts";
const input = {
operationId: "GET_JOB_STATUS",
owner: "reference-job",
minimumIntervalMs: 5_000,
successIntervalMs: 10_000,
maxIntervalMs: 60_000,
maxAttempts: 5,
maxElapsedMs: 120_000,
maxResponseBytes: 16_384,
visibility: "VISIBLE_ONLY",
fallbackReason: "CONVERGENCE",
terminalStates: ["COMPLETED", "FAILED"],
} as const;
describe("bounded polling policy", () => {
it("copies and freezes a finite immutable lease", () => {
const terminalStates = ["COMPLETED", "FAILED"];
const policy = definePollLeasePolicy({
...input,
terminalStates,
});
terminalStates.push("CANCELLED");
expect(policy.terminalStates).toEqual(["COMPLETED", "FAILED"]);
expect(Object.isFrozen(policy)).toBe(true);
expect(Object.isFrozen(policy.terminalStates)).toBe(true);
});
it("rejects push-like cadence and unbounded convergence", () => {
expect(() =>
definePollLeasePolicy({
...input,
minimumIntervalMs: 4_999,
}),
).toThrow(TypeError);
expect(() =>
definePollLeasePolicy({
...input,
terminalStates: [],
}),
).toThrow(TypeError);
expect(() =>
definePollLeasePolicy({
...input,
maxAttempts: 121,
}),
).toThrow(TypeError);
});
// 1103/04-01. The V3 executor retries a SAFE or IDEMPOTENT read
// `min(retryBudget, maxRetryAttempts, 2)` times, reading the budget from the
// descriptor it executes. A poll binds that descriptor, not a declaration.
function pollOperation(
contract: Partial<BoundedPollOperation["contract"]> = {},
frontend: Partial<BoundedPollOperation["frontend"]> = {},
): BoundedPollOperation {
return {
contract: {
...TEST_LIST_HTTP_CONTRACT.contract,
operationId: "GET_JOB_STATUS",
...contract,
},
frontend: {
...TEST_LIST_HTTP_CONTRACT.frontend,
retryBudget: 0,
responseByteLimit: 16_384,
...frontend,
},
} as BoundedPollOperation;
}
it("admits a replay-safe read whose descriptor turns transport retry off", () => {
const policy = definePollLeasePolicy(input);
expect(() =>
assertBoundedPollOperation(policy, pollOperation()),
).not.toThrow();
expect(() =>
assertBoundedPollOperation(
policy,
pollOperation({ method: "HEAD", retrySemantics: "IDEMPOTENT" }),
),
).not.toThrow();
expect(() =>
assertBoundedPollOperation(
policy,
pollOperation({}, { responseByteLimit: 8_192 }),
),
).not.toThrow();
});
it.each([
["another operation", { operationId: "GET_OTHER_STATUS" }, {}],
["one transport retry", {}, { retryBudget: 1 as const }],
["two transport retries", {}, { retryBudget: 2 as const }],
["a write method", { method: "POST" as const }, {}],
["keyed retry semantics", { retrySemantics: "KEYED" as const }, {}],
["never retry semantics", { retrySemantics: "NEVER" as const }, {}],
["an empty response limit", {}, { responseByteLimit: 0 }],
[
"a response limit over the poll ceiling",
{},
{ responseByteLimit: BOUNDED_POLLING_CEILINGS.maxResponseBytes + 1 },
],
])("refuses a descriptor with %s", (_case, contract, frontend) => {
const policy = definePollLeasePolicy(input);
expect(() =>
assertBoundedPollOperation(policy, pollOperation(contract, frontend)),
).toThrow(TypeError);
});
});