fix(bootstrap): 실패한 scope closer를 label과 함께 진단에 남긴다
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는 Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를 `FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단 기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을 읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인 closer를 찾으려면 closer를 하나씩 지워 봐야 한다. 고른 방법(리뷰 대안 (다)): - scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나 남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`· `CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질 때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면 `scope_participant: <label>`. template participant 실패도 같은 길로 남는다. - 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`, 값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은 제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다. - 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로 넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다 (`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가 실패해도 나머지를 부른다"는 그대로다. - 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서 바로 드러나야 진단에서 label이 빠지는 일이 없다. 버린 대안: - (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다. - (나) wrapper만 제품 label을 기록: template participant 실패는 계속 조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다. - label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의 뜻이 흐려진다. 위험·한계: - 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다. 더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다. - 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은 부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의 label)은 모두 맞는다. - 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09). 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts tests/unit/runtime-adapters-product-scope-participants.test.ts tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts - corepack pnpm check:diagnostics - node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts Refs: 1105/02-01
This commit is contained in:
@@ -98,6 +98,14 @@ export type ProductCompositionContext = Readonly<{
|
||||
* or rejects keeps the scope from reaching READY, as the template's own do.
|
||||
*/
|
||||
export type ProductScopeParticipant = Readonly<{
|
||||
/**
|
||||
* 1105/02-01. A lowercase kebab-case token such as `browser-files`
|
||||
* (`isScopeParticipantLabel` in `src/contracts/diagnostics.ts`). A close
|
||||
* that throws or rejects records `cache.operation.failed` with
|
||||
* `operation: "SCOPE_RESET"`, `reason: "PARTICIPANT_FAILED"` and this label
|
||||
* as `scope_participant`, so the stuck scope names its cause. Composition
|
||||
* throws a `TypeError` on any other label.
|
||||
*/
|
||||
label: string;
|
||||
close(): void | Promise<void>;
|
||||
}>;
|
||||
|
||||
@@ -13,6 +13,7 @@ import {
|
||||
import {
|
||||
attemptBucket,
|
||||
durationBucket,
|
||||
isScopeParticipantLabel,
|
||||
statusGroup,
|
||||
type DiagnosticRecordInput,
|
||||
} from "../contracts/diagnostics.ts";
|
||||
@@ -390,37 +391,34 @@ export async function createRuntimeAdapters(
|
||||
});
|
||||
});
|
||||
// 2026-11-03 02-01. The product's closers. `composeProduct` runs after the
|
||||
// scope exists (its context needs the fence), so they join through this one
|
||||
// slot, filled below. Each runs even when an earlier one fails, and any
|
||||
// failure keeps the scope from READY, as for the template's own.
|
||||
// scope exists (its context needs the fence), so they join through this
|
||||
// list, filled below, which the scope reads at each reset. Each runs even
|
||||
// when an earlier one fails, and any failure keeps the scope from READY, as
|
||||
// for the template's own. 1105/02-01. Each is its own participant at the
|
||||
// offline-lease step (10), so a failed close is recorded under its label.
|
||||
const productScopeParticipants: ProductScopeParticipant[] = [];
|
||||
const templateScopeParticipants = Object.freeze([
|
||||
Object.freeze({
|
||||
order: 4,
|
||||
label: "conditional-validators",
|
||||
close: () => conditionalValidators.clear(),
|
||||
}),
|
||||
]);
|
||||
const serverStateScope = createServerStateScopeRuntime({
|
||||
session: authSession,
|
||||
diagnostics,
|
||||
queryInvalidation: {
|
||||
resetLocal: () => serverStateGeneration.resetCurrent(),
|
||||
},
|
||||
participants: [
|
||||
{
|
||||
order: 4,
|
||||
label: "conditional-validators",
|
||||
close: () => conditionalValidators.clear(),
|
||||
},
|
||||
{
|
||||
order: 10,
|
||||
label: "product",
|
||||
async close() {
|
||||
let failed = false;
|
||||
for (const participant of productScopeParticipants) {
|
||||
try {
|
||||
await participant.close();
|
||||
} catch {
|
||||
failed = true;
|
||||
}
|
||||
}
|
||||
if (failed) throw new Error("A product scope participant failed.");
|
||||
},
|
||||
},
|
||||
participants: () => [
|
||||
...templateScopeParticipants,
|
||||
...productScopeParticipants.map((participant) =>
|
||||
Object.freeze({
|
||||
order: 10,
|
||||
label: participant.label,
|
||||
close: () => participant.close(),
|
||||
}),
|
||||
),
|
||||
],
|
||||
activateNextGeneration: () => serverStateGeneration.activateNext(),
|
||||
});
|
||||
@@ -678,7 +676,16 @@ export async function createRuntimeAdapters(
|
||||
const productContract: ProductComposition = product;
|
||||
const productCredentialProviders = productContract.credentialProviders;
|
||||
const onProductCredentialRejected = productContract.onCredentialRejected;
|
||||
productScopeParticipants.push(...(productContract.scopeParticipants ?? []));
|
||||
for (const participant of productContract.scopeParticipants ?? []) {
|
||||
// 1105/02-01. The label names the participant in diagnostics, so it must
|
||||
// be a token the diagnostic projection keeps.
|
||||
if (!isScopeParticipantLabel(participant.label)) {
|
||||
throw new TypeError(
|
||||
"A product scope participant label must be a lowercase kebab-case token (isScopeParticipantLabel).",
|
||||
);
|
||||
}
|
||||
productScopeParticipants.push(participant);
|
||||
}
|
||||
// Each installed contribution receives only the capabilities it declares.
|
||||
// The template's own capabilities come last, so a product cannot replace
|
||||
// them. 09-05. `indexedDb` is not built here: IndexedDB is an opt-in
|
||||
|
||||
Reference in New Issue
Block a user