feat: add the module configuration and secrets contract
Modules had no way to be told anything. Announcements — the first real product Ekklesia will absorb — has zero environment variables and compiles a LAN IP address into its source, so this is the contract standing between it and the module system. - A module declares what it needs in its manifest, using six bounded types (string, integer, boolean, enum, url, secret) with no nesting and no regular expressions. Static declaration is what lets the platform validate configuration *before* deciding whether a module may start: an enabled module missing a required value is reported `blocked · configuration_missing · <key>` rather than taking startup down from inside its own `start` hook, and Doctor reports the same while still importing no module code. That forces `manifestVersion: 5`, a hard cutover. - Ordinary values persist in one Core table (migration 0005), one row per (module_id, key), stored as text until validated against the declaring module's current manifest. Nothing is coerced; an invalid stored value blocks the module rather than falling back to the default. A key the manifest no longer declares is retained and ignored. - Secrets are never persisted. There is no encryption at rest in this repository, so a `secret` key is deployment-supplied and mapped in by the host under a name the module never sees. A secret declaration has no `default` field, the write API refuses secret material, and the HTTP view has no `value` field for one — absent by construction, not filtered. - Modules receive a frozen `context.config` on the registration, runtime, and HTTP handler contexts: the same object identity, per module, beside `services` rather than inside it (services is deliberately one shared instance). No environment access, no database reference, no way to reach another module's values. - Configuration decides eligibility through ADR 0028's existing resolver: three new blocked reasons, each with a distinct operator fix, propagating to required dependents through the same mechanism as a disabled module. - Changes take effect at the next restart; both resources report restartRequired. New restricted permission `core.modules.configuration.manage`, separate from lifecycle, at the sibling prefix `/api/v1/module-configuration`. - Migration participation stays independent of configuration validity. Endpoints and credentials for shared infrastructure stay platform concerns; a module declares which bucket it needs, not an S3 endpoint. See ADR 0029. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
fdaad58848
commit
baa689b2a7
+193
-1
@@ -35,13 +35,14 @@ function discoveredModule(id: string, version = "0.1.0"): DiscoveredModule {
|
||||
manifest: {
|
||||
capabilities: [],
|
||||
compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
|
||||
configuration: [],
|
||||
dependencies: {
|
||||
capabilities: { optional: {}, required: {} },
|
||||
modules: { optional: {}, required: {} },
|
||||
},
|
||||
entrypoints: { server: "./dist/server.js" },
|
||||
id,
|
||||
manifestVersion: 4,
|
||||
manifestVersion: 5,
|
||||
name: `${id} module`,
|
||||
permissions: [],
|
||||
storage: { buckets: [] },
|
||||
@@ -137,6 +138,7 @@ function dependencies(overrides: Partial<DoctorDependencies> = {}): DoctorDepend
|
||||
discoverModules: vi.fn(async () => Object.freeze([])),
|
||||
discoverSchemas: vi.fn(async () => schemaAggregate()),
|
||||
planMigrations: vi.fn(async () => plan()),
|
||||
readModuleConfiguration: vi.fn(async () => Object.freeze({ records: Object.freeze([]) })),
|
||||
readModuleLifecycle: vi.fn(async () => Object.freeze({ modules: Object.freeze([]) })),
|
||||
runtimeSatisfies: vi.fn(() => true),
|
||||
...overrides,
|
||||
@@ -206,6 +208,7 @@ describe("Ekklesia Doctor diagnostics", () => {
|
||||
"modules.dependencies",
|
||||
"modules.permissions",
|
||||
"modules.lifecycle",
|
||||
"modules.configuration",
|
||||
"schemas.discovery",
|
||||
"migrations.discovery",
|
||||
"database.transport",
|
||||
@@ -1016,3 +1019,192 @@ describe("Ekklesia Doctor — module lifecycle", () => {
|
||||
expect(check(report, "modules.lifecycle").status).toBe("pass");
|
||||
});
|
||||
});
|
||||
|
||||
describe("Ekklesia Doctor — module configuration", () => {
|
||||
function configuringModule(
|
||||
id: string,
|
||||
configuration: readonly Record<string, unknown>[],
|
||||
): DiscoveredModule {
|
||||
const base = discoveredModule(id);
|
||||
return {
|
||||
...base,
|
||||
manifest: { ...base.manifest, configuration } as unknown as ModuleManifest,
|
||||
};
|
||||
}
|
||||
|
||||
it("skips the check, rather than guessing, when DATABASE_URL is not configured", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () => Object.freeze([discoveredModule("announcements")])),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(), services);
|
||||
|
||||
expect(check(report, "modules.configuration").status).toBe("skipped");
|
||||
expect(services.readModuleConfiguration).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("passes and says so plainly when a module declares no configuration", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () => Object.freeze([discoveredModule("calendar")])),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
|
||||
expect(check(report, "modules.configuration").status).toBe("pass");
|
||||
expect(check(report, "modules.configuration").details).toEqual([
|
||||
"0 modules declaring configuration · 0 blocked",
|
||||
"calendar 0.1.0 · no configuration declared",
|
||||
]);
|
||||
});
|
||||
|
||||
it("passes with a key count when configuration is satisfied, and prints no value", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [
|
||||
{ key: "slideSeconds", type: "integer", default: 7, required: false },
|
||||
{ key: "bucket", type: "string", required: true },
|
||||
]),
|
||||
]),
|
||||
),
|
||||
readModuleConfiguration: vi.fn(async () =>
|
||||
Object.freeze({
|
||||
records: Object.freeze([
|
||||
{ key: "bucket", moduleId: "announcements", value: "very-specific-bucket-name" },
|
||||
]),
|
||||
}),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
const configuration = check(report, "modules.configuration");
|
||||
|
||||
expect(configuration.status).toBe("pass");
|
||||
expect(configuration.details).toEqual([
|
||||
"1 module declaring configuration · 0 blocked",
|
||||
"announcements 0.1.0 · 2 keys declared · valid",
|
||||
]);
|
||||
// Counts and keys, never values: `pnpm doctor` output gets pasted into chat.
|
||||
expect(JSON.stringify(configuration)).not.toContain("very-specific-bucket-name");
|
||||
});
|
||||
|
||||
it("warns and names the offending key when required configuration is missing", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [{ key: "bucket", type: "string", required: true }]),
|
||||
]),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
const configuration = check(report, "modules.configuration");
|
||||
|
||||
expect(configuration.status).toBe("warning");
|
||||
expect(configuration.summary).toBe("1 module cannot run with its current configuration");
|
||||
expect(configuration.details).toEqual([
|
||||
"1 module declaring configuration · 1 blocked",
|
||||
"announcements 0.1.0 · 1 key declared · configuration_missing · bucket",
|
||||
]);
|
||||
});
|
||||
|
||||
it("names a missing secret's key and never its value", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [
|
||||
{ key: "storageCredential", type: "secret", required: true },
|
||||
]),
|
||||
]),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
|
||||
expect(check(report, "modules.configuration").details).toContain(
|
||||
"announcements 0.1.0 · 1 key declared · secret_missing · storageCredential",
|
||||
);
|
||||
});
|
||||
|
||||
it("reports a supplied secret as satisfied, without printing it", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [
|
||||
{ key: "storageCredential", type: "secret", required: true },
|
||||
]),
|
||||
]),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(
|
||||
{
|
||||
...options(databaseUrl),
|
||||
moduleSecrets: { get: () => "super-secret-value" },
|
||||
},
|
||||
services,
|
||||
);
|
||||
const configuration = check(report, "modules.configuration");
|
||||
|
||||
expect(configuration.status).toBe("pass");
|
||||
expect(JSON.stringify(configuration)).not.toContain("super-secret-value");
|
||||
});
|
||||
|
||||
it("does not evaluate a disabled module's configuration, and says so", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [{ key: "bucket", type: "string", required: true }]),
|
||||
]),
|
||||
),
|
||||
readModuleLifecycle: vi.fn(async () =>
|
||||
Object.freeze({ modules: Object.freeze([{ enabled: false, moduleId: "announcements" }]) }),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
const configuration = check(report, "modules.configuration");
|
||||
|
||||
// Claiming it is valid would assert something nothing checked; claiming it is broken would be
|
||||
// noise about a module nobody asked to run.
|
||||
expect(configuration.status).toBe("pass");
|
||||
expect(configuration.details).toContain(
|
||||
"announcements 0.1.0 · 1 key declared · not evaluated (disabled)",
|
||||
);
|
||||
});
|
||||
|
||||
it("fails safely, without a driver detail, when the configuration cannot be read", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () => Object.freeze([discoveredModule("announcements")])),
|
||||
readModuleConfiguration: vi.fn(async () => {
|
||||
throw new Error("connect ECONNREFUSED 10.40.0.2:5432 password=hunter2");
|
||||
}),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
const configuration = check(report, "modules.configuration");
|
||||
|
||||
expect(configuration.status).toBe("failure");
|
||||
expect(JSON.stringify(configuration)).not.toContain("hunter2");
|
||||
expect(JSON.stringify(configuration)).not.toContain("10.40.0.2");
|
||||
});
|
||||
|
||||
it("agrees with the lifecycle check, because both come from one resolution", async () => {
|
||||
const services = dependencies({
|
||||
discoverModules: vi.fn(async () =>
|
||||
Object.freeze([
|
||||
configuringModule("announcements", [{ key: "bucket", type: "string", required: true }]),
|
||||
]),
|
||||
),
|
||||
});
|
||||
|
||||
const report = await diagnoseEkklesia(options(databaseUrl), services);
|
||||
|
||||
// Doctor can never report a module as runnable that startup would block, or the reverse.
|
||||
expect(check(report, "modules.lifecycle").status).toBe("warning");
|
||||
expect(check(report, "modules.configuration").status).toBe("warning");
|
||||
expect(check(report, "modules.lifecycle").details).toContain(
|
||||
"announcements 0.1.0 · blocked · configuration_missing · bucket",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user