Merge remote-tracking branch 'origin/main' into fix/r9-form-and-primitives
This commit is contained in:
@@ -311,6 +311,7 @@ export function createFeatureHttpBinding<
|
||||
contract.contract.responseEnvelope === "ENVELOPE_V1",
|
||||
),
|
||||
outcome,
|
||||
contract.contract.responseEnvelope === "ENVELOPE_V1",
|
||||
);
|
||||
},
|
||||
});
|
||||
@@ -345,10 +346,18 @@ function envelopeProblemMapping(
|
||||
problem: unknown,
|
||||
status: number,
|
||||
): FeatureHttpProblemMapping | undefined {
|
||||
const code = envelopeCode(problem);
|
||||
if (code === undefined) return undefined;
|
||||
const { details } = problem as Readonly<Record<string, unknown>>;
|
||||
return envelopeFailureReading(status, { code, details });
|
||||
}
|
||||
|
||||
/** The backend `error.code` of an Envelope problem, when it is well formed. */
|
||||
function envelopeCode(problem: unknown): string | undefined {
|
||||
if (!problem || typeof problem !== "object") return undefined;
|
||||
const { code, details } = problem as Readonly<Record<string, unknown>>;
|
||||
const { code } = problem as Readonly<Record<string, unknown>>;
|
||||
return typeof code === "string" && /^[A-Z0-9_]{1,64}$/u.test(code)
|
||||
? envelopeFailureReading(status, { code, details })
|
||||
? code
|
||||
: undefined;
|
||||
}
|
||||
|
||||
@@ -358,6 +367,8 @@ function envelopeProblemMapping(
|
||||
* 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops
|
||||
* the header) it is the id the request carried.
|
||||
* 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`.
|
||||
* 1112/01-06. An Envelope operation's problem keeps the backend's own code as
|
||||
* `backendCode`, whatever code the feature mapped it to.
|
||||
*/
|
||||
function projectExecutionOutcome<WireOutput, Problem, Value>(
|
||||
operationId: string,
|
||||
@@ -372,8 +383,15 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
|
||||
) => FeatureHttpProblemMapping | undefined)
|
||||
| undefined,
|
||||
outcome: HttpExecutionOutcome<WireOutput, Problem>,
|
||||
enveloped: boolean,
|
||||
): Result<Value, AppFailure> {
|
||||
const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome);
|
||||
const projected = projectOutcome(
|
||||
operationId,
|
||||
mapSuccess,
|
||||
mapProblem,
|
||||
outcome,
|
||||
enveloped,
|
||||
);
|
||||
const metadata = "metadata" in outcome ? outcome.metadata : undefined;
|
||||
const requestId = metadata?.correlationReference ?? outcome.sentRequestId;
|
||||
const traceId = metadata?.traceReference;
|
||||
@@ -402,6 +420,7 @@ function projectOutcome<WireOutput, Problem, Value>(
|
||||
) => FeatureHttpProblemMapping | undefined)
|
||||
| undefined,
|
||||
outcome: HttpExecutionOutcome<WireOutput, Problem>,
|
||||
enveloped: boolean,
|
||||
): Result<Value, AppFailure> {
|
||||
// A throwing feature mapper is a mapping defect, not a transport failure: it
|
||||
// must not reject and lose the effect the server already confirmed.
|
||||
@@ -444,11 +463,13 @@ function projectOutcome<WireOutput, Problem, Value>(
|
||||
} catch {
|
||||
return mapperThrew(outcome.effect, outcome.metadata.status);
|
||||
}
|
||||
const backendCode = enveloped ? envelopeCode(outcome.problem) : undefined;
|
||||
return failure(
|
||||
mapped?.kind ?? kindForStatus(outcome.metadata.status),
|
||||
operationId,
|
||||
mapped?.code ?? "CONTRACT_PROBLEM",
|
||||
{
|
||||
...(backendCode === undefined ? {} : { backendCode }),
|
||||
httpStatus: outcome.metadata.status,
|
||||
// 백엔드 1101/02-01. A resend of an unknown answer waits on it.
|
||||
...(outcome.metadata.retryAfterMs === undefined
|
||||
@@ -578,6 +599,7 @@ function failure(
|
||||
operationId: string,
|
||||
code: string,
|
||||
details: Readonly<{
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
retryAfterMs?: number;
|
||||
effect?: FailureEffectCertainty;
|
||||
|
||||
@@ -117,7 +117,8 @@ export type BoundedPollCoordinatorDependencies<
|
||||
* (the V3 executor returns a rejected fetch as NETWORK_FAILURE). A throw,
|
||||
* like a result of the wrong shape, ends the lease with PROTOCOL_MISMATCH
|
||||
* and is not retried: it is a composition defect, not a server outage.
|
||||
* Design 9.2 maps each V3 executor outcome to a result.
|
||||
* docs/architecture/optional-adapter-recipes.md 「poll attempt 결과 대응」
|
||||
* maps each V3 executor outcome to a result.
|
||||
*/
|
||||
execute(input: Readonly<{
|
||||
operationId: string;
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
|
||||
|
||||
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
|
||||
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「판단 규칙」이다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
@@ -13,5 +13,5 @@
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
|
||||
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
|
||||
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-005의 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`, FE-GATE-007의 `tests/integration/fileserver-upload.test.ts`)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
|
||||
+28
-3
@@ -130,6 +130,13 @@ export type FailureEffectCertainty =
|
||||
export type AppFailure = Readonly<{
|
||||
kind: FailureKind;
|
||||
code: string;
|
||||
/**
|
||||
* 1112/01-06. The code the paired backend's Envelope carried, as it came:
|
||||
* a feature's `mapProblem` may change `code`, never this. Only the HTTP
|
||||
* binding sets it, for an `ENVELOPE_V1` operation's problem; elsewhere it
|
||||
* is absent.
|
||||
*/
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
/**
|
||||
* Whether sending the same operation again is safe as far as this failure
|
||||
@@ -164,6 +171,7 @@ export type ApiFailure = AppFailure;
|
||||
|
||||
export type FailureDetails = Readonly<{
|
||||
code?: string;
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
requestId?: string;
|
||||
traceId?: string;
|
||||
@@ -183,6 +191,9 @@ export function createFailure(
|
||||
return Object.freeze({
|
||||
kind: definition.kind,
|
||||
code: typeof details.code === "string" ? details.code : definition.kind,
|
||||
...(typeof details.backendCode === "string"
|
||||
? { backendCode: details.backendCode }
|
||||
: {}),
|
||||
retryable:
|
||||
details.effect === "MAYBE_APPLIED" ||
|
||||
details.effect === "APPLIED_CONFIRMED"
|
||||
@@ -259,6 +270,16 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
|
||||
IDEMPOTENCY_KEY_INVALID: 400,
|
||||
});
|
||||
|
||||
/**
|
||||
* 1112/01-03. The request did not fail: its caller aborted it
|
||||
* (`REQUEST_ABORTED`) or a scope fence ended it (`SCOPE_GENERATION_CHANGED`,
|
||||
* sign-out or account switch). Telemetry and terminal error screens do not
|
||||
* count it (testing strategy 7.1절).
|
||||
*/
|
||||
export function isAbortFailure(failure: AppFailure): boolean {
|
||||
return failure.kind === "REQUEST_ABORTED" || failure.kind === "SCOPE_GENERATION_CHANGED";
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement and its second fix). A `NOT_APPLIED` refusal
|
||||
* the same request gets on every attempt: a row above, code and status
|
||||
@@ -268,13 +289,17 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
|
||||
* 403, 503 RATE_LIMIT_*), a code a feature declared refused before its
|
||||
* write (it may be a rule on changing state), any other code, and
|
||||
* `NOT_STARTED`. The kind is not read: a feature's `mapProblem` sets it, and
|
||||
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`.
|
||||
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`. 1112/01-06.
|
||||
* Nor is `code`, for the same reason: the answer is `backendCode`, the code
|
||||
* the backend's Envelope carried. A failure without it is not settled.
|
||||
*/
|
||||
export function isRefusedOnEveryAttempt(failure: AppFailure): boolean {
|
||||
if (failure.effect !== "NOT_APPLIED") return false;
|
||||
const code = failure.backendCode;
|
||||
return (
|
||||
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) &&
|
||||
REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus
|
||||
code !== undefined &&
|
||||
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code) &&
|
||||
REFUSALS_OF_EVERY_ATTEMPT[code] === failure.httpStatus
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -53,11 +53,17 @@ export type ApplicationResult<Value> = Result<Value>;
|
||||
|
||||
class ApplicationQueryError extends Error {
|
||||
readonly failure: AppFailure;
|
||||
/**
|
||||
* 1112/01-04. What the cache diagnostics record (`safeErrorKind` reads
|
||||
* `kind` first): the failure's kind, not one name for every failure.
|
||||
*/
|
||||
readonly kind: AppFailure["kind"];
|
||||
|
||||
constructor(failure: AppFailure) {
|
||||
super(failure.kind);
|
||||
this.name = "ApplicationQueryError";
|
||||
this.failure = failure;
|
||||
this.kind = failure.kind;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -100,7 +106,6 @@ export function useApplicationQuery<Value>(
|
||||
"definitionId" in options ? options.definitionId : "APPLICATION_QUERY";
|
||||
const invalidation =
|
||||
"invalidation" in options ? options.invalidation : undefined;
|
||||
const [staleFailure, setStaleFailure] = useState(false);
|
||||
useEffect(() => {
|
||||
identity?.acquire();
|
||||
return () => identity?.release();
|
||||
@@ -170,9 +175,10 @@ export function useApplicationQuery<Value>(
|
||||
throw new DOMException("Query cancelled", "AbortError");
|
||||
}
|
||||
if (error instanceof ApplicationQueryError) throw error;
|
||||
// 1112/01-04. The definition it came from, as the other failures here.
|
||||
throw new ApplicationQueryError(
|
||||
normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_QUERY",
|
||||
operationId: queryDefinitionId,
|
||||
}),
|
||||
);
|
||||
} finally {
|
||||
@@ -181,17 +187,13 @@ export function useApplicationQuery<Value>(
|
||||
},
|
||||
});
|
||||
const hasData = query.data !== undefined && query.data !== null;
|
||||
|
||||
useEffect(() => {
|
||||
if (query.isError && hasData) {
|
||||
setStaleFailure(true);
|
||||
} else if (query.isSuccess && !query.isFetching) {
|
||||
setStaleFailure(false);
|
||||
}
|
||||
}, [hasData, query.isError, query.isFetching, query.isSuccess]);
|
||||
// 1112/01-05. Read while rendering: the data is stale because the last
|
||||
// fetch failed, and no fetch runs now. A retry that is running shows as
|
||||
// refreshing; copied into state by an effect, the old failure came back
|
||||
// over the retry's reset.
|
||||
const staleFailure = query.isError && hasData && !query.isFetching;
|
||||
|
||||
const retry = useCallback(async () => {
|
||||
setStaleFailure(false);
|
||||
await query.refetch({ cancelRefetch: false });
|
||||
}, [query]);
|
||||
|
||||
@@ -375,6 +377,12 @@ export function useApplicationMutation<Input, Value>(
|
||||
"definitionId" in options
|
||||
? options.definitionId ?? "LEGACY_MUTATION"
|
||||
: "LEGACY_MUTATION";
|
||||
// 1112/01-04. An unexpected throw names the mutation definition it came
|
||||
// from; a legacy mutation without one keeps the generic name.
|
||||
const failureOperationId =
|
||||
"definitionId" in options && options.definitionId
|
||||
? options.definitionId
|
||||
: "APPLICATION_MUTATION";
|
||||
const definitionVersion =
|
||||
"definitionVersion" in options ? options.definitionVersion : 0;
|
||||
const duplicatePolicy =
|
||||
@@ -708,7 +716,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
error instanceof ApplicationQueryError
|
||||
? error.failure
|
||||
: normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_MUTATION",
|
||||
operationId: failureOperationId,
|
||||
});
|
||||
const failure = mutationFailureWithEffect(reportedFailure);
|
||||
switch (failure.effect) {
|
||||
@@ -765,7 +773,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
.catch((error: unknown) => {
|
||||
const failure = withFailureEffect(
|
||||
normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_MUTATION",
|
||||
operationId: failureOperationId,
|
||||
}),
|
||||
"NOT_STARTED",
|
||||
);
|
||||
@@ -801,6 +809,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
queryClient,
|
||||
definitionId,
|
||||
duplicatePolicy,
|
||||
failureOperationId,
|
||||
mutationIntentFactory,
|
||||
mutationOperationId,
|
||||
requiresIdempotencyKey,
|
||||
|
||||
Reference in New Issue
Block a user