fix(bootstrap): report FEATURE_OVERRIDES keys the build does not declare (09-09)
A misspelt kill-switch key was ignored without a trace, so the feature kept running. Boot now records feature.override.unknown once per such key, and release admission lists them as warnings in its record without refusing the artifact (a shared document may still name another build's features). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
69e40f106f
commit
b685b616e4
+1
-1
@@ -22,7 +22,7 @@
|
||||
"check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture",
|
||||
"check:adapter-inventory": "node scripts/check-adapter-inventory.ts",
|
||||
"check:remediation-ledger": "node scripts/check-remediation-ledger.ts",
|
||||
"check:release-admission": "node scripts/check-release-admission.ts",
|
||||
"check:release-admission": "node scripts/generate-product-feature-index.ts && node scripts/check-release-admission.ts",
|
||||
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
|
||||
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
|
||||
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker",
|
||||
|
||||
@@ -47,6 +47,7 @@ const diagnosticProducerFiles: Readonly<Record<string, string>> = {
|
||||
"ui.render.failed": "src/application/create-application.ts",
|
||||
"release.mismatch.detected": "src/application/create-application.ts",
|
||||
"telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts",
|
||||
"feature.override.unknown": "src/bootstrap/runtime-adapters.ts",
|
||||
};
|
||||
|
||||
for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) {
|
||||
|
||||
@@ -7,7 +7,9 @@ import {
|
||||
isDeploymentTarget,
|
||||
type AdmissionInput,
|
||||
} from "../src/contracts/deployment-admission.ts";
|
||||
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
|
||||
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
|
||||
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
|
||||
|
||||
/**
|
||||
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
|
||||
@@ -79,6 +81,18 @@ async function main(): Promise<void> {
|
||||
}
|
||||
|
||||
const violations = findAdmissionViolations(declared, config);
|
||||
// 09-09. Inert by design (a shared document may name another build's
|
||||
// features), so this warns instead of refusing.
|
||||
const warnings = unknownProductFeatureOverrides(
|
||||
COMPILED_PRODUCT_FEATURE_IDS,
|
||||
"FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined,
|
||||
).map((featureId) => ({
|
||||
field: `FEATURE_OVERRIDES.${featureId}`,
|
||||
reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`,
|
||||
}));
|
||||
for (const warning of warnings) {
|
||||
process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`);
|
||||
}
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeFile(
|
||||
RECORD_PATH,
|
||||
@@ -93,6 +107,7 @@ async function main(): Promise<void> {
|
||||
releaseId: config.RELEASE_ID ?? null,
|
||||
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
|
||||
violations,
|
||||
warnings,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
|
||||
@@ -688,6 +688,11 @@ export const deploymentAdmissionArtifactSchema = z
|
||||
violations: z.array(
|
||||
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
|
||||
),
|
||||
// 09-09. Findings that do not refuse the artifact, e.g. an override key
|
||||
// naming a feature this build does not declare.
|
||||
warnings: z.array(
|
||||
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
|
||||
|
||||
@@ -56,6 +56,7 @@ import {
|
||||
import {
|
||||
activeProductFeatureIds,
|
||||
resolveProductFeatures,
|
||||
unknownProductFeatureOverrides,
|
||||
} from "../contracts/product-features.ts";
|
||||
import { describeRuntimeCapabilities } from "../contracts/runtime-capabilities.ts";
|
||||
import {
|
||||
@@ -442,6 +443,16 @@ export async function createRuntimeAdapters(
|
||||
const activeFeatureIds = new Set(
|
||||
activeProductFeatureIds(productFeatureStatuses),
|
||||
);
|
||||
for (const key of unknownProductFeatureOverrides(
|
||||
COMPILED_PRODUCT_FEATURE_IDS,
|
||||
config.FEATURE_OVERRIDES,
|
||||
)) {
|
||||
diagnostics.record({
|
||||
level: "warn",
|
||||
eventId: "feature.override.unknown",
|
||||
context: { feature_override_key: key },
|
||||
});
|
||||
}
|
||||
const productFeatures = Object.freeze({
|
||||
getSnapshot() {
|
||||
return productFeatureStatuses;
|
||||
|
||||
@@ -18,6 +18,7 @@ export const DIAGNOSTIC_EVENT_REGISTRY = Object.freeze({
|
||||
"ui.render.failed": Object.freeze({ level: "error" }),
|
||||
"release.mismatch.detected": Object.freeze({ level: "warn" }),
|
||||
"telemetry.delivery.dropped": Object.freeze({ level: "warn" }),
|
||||
"feature.override.unknown": Object.freeze({ level: "warn" }),
|
||||
});
|
||||
export type DiagnosticEventId = keyof typeof DIAGNOSTIC_EVENT_REGISTRY;
|
||||
|
||||
@@ -41,6 +42,7 @@ export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([
|
||||
"operation",
|
||||
"reason",
|
||||
"queue_size_bucket",
|
||||
"feature_override_key",
|
||||
] as const);
|
||||
export type DiagnosticContextKey =
|
||||
(typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number];
|
||||
@@ -82,6 +84,9 @@ export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({
|
||||
operation: "topology",
|
||||
reason: "taxonomy",
|
||||
queue_size_bucket: "bounded",
|
||||
// 09-09. A key from the deployed runtime document; it changes with a config
|
||||
// deployment, not with traffic.
|
||||
feature_override_key: "deployment",
|
||||
} satisfies Readonly<Record<DiagnosticContextKey, DiagnosticCardinalityClass>>);
|
||||
|
||||
export type DiagnosticContext = Readonly<
|
||||
|
||||
@@ -128,6 +128,21 @@ export function resolveProductFeatures(
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 09-09. Override keys naming no feature this build declares. They stay inert,
|
||||
* since one runtime document may serve builds with different features, but a
|
||||
* misspelt kill switch has to be reported rather than silently ignored.
|
||||
*/
|
||||
export function unknownProductFeatureOverrides(
|
||||
compiledIds: readonly string[],
|
||||
overrides: ProductFeatureOverrideMap = {},
|
||||
): readonly string[] {
|
||||
const declared = new Set(compiledIds);
|
||||
return Object.freeze(
|
||||
Object.keys(overrides).filter((featureId) => !declared.has(featureId)).sort(),
|
||||
);
|
||||
}
|
||||
|
||||
/** The feature ids serving traffic right now. */
|
||||
export function activeProductFeatureIds(
|
||||
statuses: readonly ProductFeatureStatus[],
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts";
|
||||
import { COMPILED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts";
|
||||
import { generateRuntimeConfig } from "../../scripts/generate-runtime-config.ts";
|
||||
|
||||
type Runtime = Parameters<typeof createRuntimeAdapters>[0]["runtime"];
|
||||
|
||||
// 09-09. An override key this build does not declare stays inert (one runtime
|
||||
// document may serve several builds), but a misspelt kill switch used to leave
|
||||
// the feature running without a trace.
|
||||
const MISSPELT = "reference-featrue";
|
||||
|
||||
function runtimeWith(overrides: Readonly<Record<string, "DISABLED">>): Runtime {
|
||||
return {
|
||||
config: {
|
||||
APP_ENV: "local",
|
||||
API_BASE_URL: "http://localhost:8080",
|
||||
TELEMETRY_ENABLED: false,
|
||||
AUTH_MODE: "demo",
|
||||
REQUEST_TIMEOUT_MS: 1000,
|
||||
MAX_RETRY_ATTEMPTS: 0,
|
||||
RELEASE_MANIFEST_URL: "/release-manifest.json",
|
||||
CONFIG_SCHEMA_VERSION: "2.0",
|
||||
CAPABILITY_OVERRIDES: {
|
||||
REALTIME: "DEFAULT",
|
||||
WEB_WORKER: "DEFAULT",
|
||||
SERVICE_WORKER: "DEFAULT",
|
||||
OFFLINE_COMMANDS: "DEFAULT",
|
||||
},
|
||||
FEATURE_OVERRIDES: overrides,
|
||||
},
|
||||
configSchema: "V2",
|
||||
build: {
|
||||
buildId: "build-a",
|
||||
commitSha: "abc123",
|
||||
routerBasePath: "/",
|
||||
runtimeConfigUrl: "/config.json",
|
||||
},
|
||||
validationDurationMs: 0,
|
||||
};
|
||||
}
|
||||
|
||||
const release = {
|
||||
schemaVersion: 2,
|
||||
appVersion: "0.1.0",
|
||||
buildId: "build-a",
|
||||
commitSha: "abc123",
|
||||
configSchemaVersion: "2.0",
|
||||
contractSet: {
|
||||
setAlgorithm: "CA_CONTRACT_SET_V1",
|
||||
setDigest: `sha256:${"0".repeat(64)}`,
|
||||
packages: [],
|
||||
},
|
||||
assetManifestHash: "hash-a",
|
||||
releaseId: "release-a",
|
||||
builtAt: "2026-07-25T00:00:00Z",
|
||||
routeChunks: {},
|
||||
} as Parameters<typeof createRuntimeAdapters>[0]["release"];
|
||||
|
||||
describe("unknown feature override keys (09-09)", () => {
|
||||
it("records one diagnostic per key the build does not declare", async () => {
|
||||
const declared = COMPILED_PRODUCT_FEATURE_IDS[0];
|
||||
const adapters = await createRuntimeAdapters({
|
||||
runtime: runtimeWith({
|
||||
[MISSPELT]: "DISABLED",
|
||||
...(declared === undefined ? {} : { [declared]: "DISABLED" }),
|
||||
}),
|
||||
release,
|
||||
host: {},
|
||||
});
|
||||
try {
|
||||
const unknown = adapters.outputPorts.diagnostics
|
||||
.entries()
|
||||
.filter((entry) => entry.eventId === "feature.override.unknown");
|
||||
expect(unknown).toEqual([
|
||||
expect.objectContaining({
|
||||
level: "warn",
|
||||
context: { feature_override_key: MISSPELT },
|
||||
}),
|
||||
]);
|
||||
} finally {
|
||||
adapters.infrastructure.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
it("warns in the admission record without refusing the artifact", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "admission-override-"));
|
||||
try {
|
||||
const config = await generateRuntimeConfig("local", {});
|
||||
await mkdir(path.join(root, "dist"), { recursive: true });
|
||||
await writeFile(
|
||||
path.join(root, "dist/config.json"),
|
||||
JSON.stringify({ ...config, FEATURE_OVERRIDES: { [MISSPELT]: "DISABLED" } }),
|
||||
);
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/check-release-admission.ts")],
|
||||
{
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
env: { ...process.env, APP_PROFILE: "local", RELEASE_TARGET: "local" },
|
||||
},
|
||||
);
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
expect(result.stderr).toContain(MISSPELT);
|
||||
const record = JSON.parse(
|
||||
await readFile(path.join(root, "artifacts/release/deployment-admission.json"), "utf8"),
|
||||
) as { status: string; warnings: { field: string; reason: string }[] };
|
||||
expect(record.status).toBe("ADMITTED");
|
||||
expect(record.warnings).toEqual([
|
||||
expect.objectContaining({ field: `FEATURE_OVERRIDES.${MISSPELT}` }),
|
||||
]);
|
||||
} finally {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user