@cosmicdrift/kumiko-framework 0.297.0 → 0.304.0

package/src/observability/__tests__/metrics-wiring.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { composeEnvSchema, readKumikoMeta } from "../../env";
+import { prometheusMetricsEnvSchema, resolveObservabilityWiring } from "../metrics-wiring";
+
+describe("resolveObservabilityWiring", () => {
+  it("returns {} without a token", () => {
+    expect(resolveObservabilityWiring(undefined)).toEqual({});
+  });
+
+  it("returns {} for an empty token", () => {
+    expect(resolveObservabilityWiring("")).toEqual({});
+  });
+
+  it("wires a prometheus provider and metrics route when a token is set", () => {
+    const token = "a".repeat(32);
+    const wiring = resolveObservabilityWiring(token);
+
+    expect("metrics" in wiring).toBe(true);
+    if (!("metrics" in wiring)) throw new Error("expected wiring to include metrics");
+
+    expect(wiring.metrics).toEqual({ path: "/metrics", token });
+    expect(wiring.observability.name).toBe("prometheus");
+    expect(wiring.observability.meter.snapshot()).toEqual(new Map());
+  });
+});
+
+describe("prometheusMetricsEnvSchema", () => {
+  it("rejects tokens shorter than 32 characters", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(31),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts a 32-character token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(32),
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a missing token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("exposes pulumi secret metadata for consumer env-schemas", () => {
+    const { schema } = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }).extend(prometheusMetricsEnvSchema.shape),
+    });
+
+    const field = schema.shape["PROMETHEUS_METRICS_TOKEN"];
+    if (!(field instanceof z.ZodType))
+      throw new Error("expected PROMETHEUS_METRICS_TOKEN in composed schema");
+    const meta = readKumikoMeta(field);
+    expect(meta.pulumi?.secret).toBe(true);
+    expect(meta.pulumi?.generator).toBe("openssl rand -base64 32");
+  });
+});

package/src/observability/index.ts

@@ -16,6 +16,11 @@ export {
   createSafeMetricsHandle,
   createUnboundMetricsHandle,
 } from "./metrics-handle";
+export {
+  type ObservabilityWiring,
+  prometheusMetricsEnvSchema,
+  resolveObservabilityWiring,
+} from "./metrics-wiring";
 export { createNoopProvider } from "./noop-provider";
 export {
   createPrometheusMeter,

package/src/observability/metrics-wiring.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { createNoopProvider } from "./noop-provider";
+import { createPrometheusMeter, type PrometheusMeter } from "./prometheus-meter";
+import type { ObservabilityProvider } from "./types";
+
+export const prometheusMetricsEnvSchema = z.object({
+  PROMETHEUS_METRICS_TOKEN: z
+    .string()
+    .min(32)
+    .optional()
+    .describe("Bearer token for /metrics; unset keeps the endpoint off.")
+    .meta({ kumiko: { pulumi: { secret: true, generator: "openssl rand -base64 32" } } }),
+});
+
+type PrometheusObservabilityProvider = ObservabilityProvider & { readonly meter: PrometheusMeter };
+
+export type ObservabilityWiring =
+  | {
+      readonly observability: PrometheusObservabilityProvider;
+      readonly metrics: { readonly path: string; readonly token: string };
+    }
+  | Record<string, never>;
+
+// Fail-closed: public tenant hosts share the /metrics port, so no token means no endpoint.
+export function resolveObservabilityWiring(metricsToken: string | undefined): ObservabilityWiring {
+  if (!metricsToken) return {};
+  return {
+    // Overrides the spread's name "noop", which would otherwise show up in diagnostics/logs.
+    observability: { ...createNoopProvider(), name: "prometheus", meter: createPrometheusMeter() },
+    metrics: { path: "/metrics", token: metricsToken },
+  };
+}

package/src/stack/test-stack.ts

@@ -42,8 +42,9 @@ export type TestStack = {
   // to assert a consumer pushed an invalidation without opening a real SSE
   // connection.
   sseBroker: SseBroker;
-  // Command-dispatcher behind the HTTP routes — for direct system-writes
-  // in tests and dev-server extraRoutes (provider-webhook wiring).
+  // Command-dispatcher behind the HTTP routes — for direct system-writes in
+  // tests and behind entry:"signature" extraRoutes / the `wire` hook
+  // (provider-webhook wiring).
   dispatcher: Dispatcher;
   // The AppContext buildServer handed the request path, incl. the fields it
   // wires itself (_fileProviderResolver). A dev-server that starts its own
@@ -105,6 +106,10 @@ export type TestStackOptions = {
    *  The resolver is auto-built from the test Redis. Mirrors
    *  buildServer's `rateLimit` option 1:1 — see there for shape. */
   rateLimit?: import("../api/server").ServerOptions["rateLimit"];
+  /** Forwarded to buildServer — Integration-Tests that exercise `extraRoutes`
+   *  MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`),
+   *  never `createTestDispatcher`. */
+  extraRoutes?: import("../api/server").ServerOptions["extraRoutes"];
   /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
    *  AppContext — set/delete/get + rotation job pick it up. Omit for
    *  suites that don't touch secrets. */
@@ -404,6 +409,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       },
       eventDedup,
       sseBroker,
+      ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
       // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
       // deterministic drains — no timer-induced flakiness. pollIntervalMs
       // stays short anyway in case a test opts into `.start()`. pgClient

package/src/testing/handler-context.ts

@@ -5,6 +5,8 @@
 // production services (delivery-service uses it to run cross-feature notify
 // calls without a real dispatcher). Hence the runtime classification despite
 // living under `testing/` — no vitest imports, no test side-effects.
+
+import { ANONYMOUS_ROLE } from "../engine/system-user";
 import type {
   AppendEventArgs,
   FetchForWritingArgs,
@@ -76,7 +78,7 @@ export function bridgeStub(opts?: {
   const stubUser: SessionUser = opts?.user ?? {
     id: "00000000-0000-0000-0000-000000000000",
     tenantId: "00000000-0000-0000-0000-000000000000" as SessionUser["tenantId"], // @cast-boundary engine-bridge
-    roles: ["all"],
+    roles: [ANONYMOUS_ROLE],
   };
   return {
     user: stubUser,

package/src/ui-types/index.ts

@@ -61,6 +61,8 @@ export type {
   OpenToAllAccessRule,
   OpenToAllDeclaration,
   OpenToAllPersonalData,
+  RoleAccessPersonalData,
+  RoleAccessRule,
 } from "../engine/types/handlers";
 export { isOpenToAllGranted } from "../engine/types/handlers";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";