OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
ralph(M3-CLOSE-001): Ops surface in core: /metrics (the ONE registry) + /openapi.json (@elysiajs/openapi 1.4.15, zod slots)
ralphbca2a5c47ebf
diff --git a/packages/core/package.json b/packages/core/package.jsonindex d22c79251..dfd518528 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -19,6 +19,7 @@"bullmq": "6.3.3","elysia": "1.4.30","nanoid": "^5.1.6",+ "prom-client": "^15.1.3","superjson": "^1.13.3","zod": "catalog:"},diff --git a/packages/core/src/metrics.ts b/packages/core/src/metrics.tsnew file mode 100644index 000000000..09531311d--- /dev/null+++ b/packages/core/src/metrics.ts@@ -0,0 +1,12 @@+// The one prom-client registry for the whole process (this package's+// AGENTS.md layout; TARGET_ARCHITECTURE §18: "One `prom-client` registry+// built by `core/src/metrics.ts`, served at `/metrics` from the ops scope in+// every role"). `apps/api/src/metrics.ts` and `apps/worker/src/metrics.ts`+// are V1-side registries that die with the apps they live in (ADR-007+// package fates: `worker` dies, `api` becomes a shell over this package) —+// core neither reads nor extends either one. Every collector a core module+// registers from here on registers on THIS registry, and only this one.++import client from 'prom-client';++export const registry = new client.Registry();diff --git a/packages/core/src/modules/health/health.routes.ts b/packages/core/src/modules/health/health.routes.tsindex fb766d540..5e53482d5 100644--- a/packages/core/src/modules/health/health.routes.ts+++ b/packages/core/src/modules/health/health.routes.ts@@ -4,8 +4,18 @@// a shutdown flag are real (P3+) — porting them against `unknown` deps now// would be a fake check, not a deferred one.+import { z } from 'zod';import { defineRoutes } from '../../http/define';+// The first zod schema through the OpenAPI plugin (ADR-003): response schemas+// generate with `io: 'output'`, which is what zod 4's native Standard Schema+// JSON conversion does by default for the `response` slot — no+// `mapJsonSchema` override needed, and none is added, because that hook gets+// no `io` argument and would collapse the input/output split the ADR requires.+const healthLiveResponseSchema = z.object({ live: z.literal(true) });+export const healthRoutes = defineRoutes((app) =>- app.get('/healthz/live', () => ({ live: true }))+ app.get('/healthz/live', () => ({ live: true as const }), {+ response: healthLiveResponseSchema,+ }));diff --git a/packages/core/src/rest.routes.test.ts b/packages/core/src/rest.routes.test.tsindex a42d01592..9cbcf2017 100644--- a/packages/core/src/rest.routes.test.ts+++ b/packages/core/src/rest.routes.test.ts@@ -1,7 +1,9 @@import { expect, test } from 'bun:test';import { Elysia } from 'elysia';+import client from 'prom-client';import { stubAppDeps } from '../test/http-fixtures';import { requestContext } from './http/context';+import { registry } from './metrics';import { dashboardRoutes, opsRoutes, publicApiRoutes } from './rest.routes';// The acceptance shape for ADR-007 decision 19: an app built from the mounts@@ -34,3 +36,67 @@ test('publicApiRoutes and dashboardRoutes compose with no modules yet', async ()expect(response.status).toBe(200);});++// The M3 gate: /metrics serves prometheus text exposition from THE core+// registry — not a route-local one, not the prom-client global default.+test('/metrics serves the one core registry, prometheus text exposition', async () => {+ const { deps } = stubAppDeps();+ const probeName = 'core_rest_routes_metrics_probe_total';+ const probe = new client.Counter({+ name: probeName,+ help: 'test probe registered on the core registry',+ registers: [registry],+ });+ probe.inc();++ const app = new Elysia().use(requestContext(deps)).use(opsRoutes(deps));++ const response = await app.handle(new Request('http://localhost/metrics'));+ const body = await response.text();++ expect(response.status).toBe(200);+ expect(response.headers.get('content-type')).toBe(registry.contentType);+ expect(body).toContain(`${probeName} 1`);++ registry.removeSingleMetric(probeName);+});++test('/openapi.json serves the OpenAPI document with health routes present, /metrics hidden', async () => {+ const { deps } = stubAppDeps();++ const app = new Elysia().use(requestContext(deps)).use(opsRoutes(deps));++ const response = await app.handle(+ new Request('http://localhost/openapi.json')+ );++ expect(response.status).toBe(200);++ const document = (await response.json()) as {+ paths: Record<string, unknown>;+ };+ const liveRoute = document.paths['/healthz/live'] as {+ get: {+ responses: {+ 200: {+ content: {+ 'application/json': {+ schema: {+ properties: Record<string, unknown>;+ required: string[];+ };+ };+ };+ };+ };+ };+ };++ const liveSchema =+ liveRoute.get.responses[200].content['application/json'].schema;+ expect(liveSchema.properties).toEqual({+ live: { const: true, type: 'boolean' },+ });+ expect(liveSchema.required).toEqual(['live']);+ expect(document.paths['/metrics']).toBeUndefined();+});diff --git a/packages/core/src/rest.routes.ts b/packages/core/src/rest.routes.tsindex f46b1231a..89df30d08 100644--- a/packages/core/src/rest.routes.ts+++ b/packages/core/src/rest.routes.ts@@ -4,10 +4,21 @@// module's HTTP half is one `.use()` on the surface it belongs to; most// modules touch exactly one.+import { openapi } from '@elysiajs/openapi';import { Elysia } from 'elysia';import type { AppDeps } from './context';+import { registry } from './metrics';import { healthRoutes } from './modules/health/health.routes';+// ADR-002/ADR-003 pin: @elysiajs/openapi at the 1.4.15 fallback (2.0 is+// NO-GO per spike 6). `specPath` is set explicitly rather than taking the+// plugin's `${path}/json` default, because the ops surface's contract is+// exactly `/openapi.json`.+const OPENAPI_SPEC_PATH = '/openapi.json';+// `/metrics` is prometheus text exposition, not an OpenAPI-describable JSON+// endpoint (ADR-003: "the transform that hides /metrics from the spec").+const OPENAPI_EXCLUDED_PATHS = ['/metrics'];+// No module lands on either surface yet — the 35 modules' HTTP halves land// with their waves (P5-P8). Both still take `deps` now so a module addition// never changes the factory's signature, only its body. Return types are@@ -20,6 +31,20 @@ export const dashboardRoutes = (_deps: AppDeps) =>new Elysia({ name: 'core/dashboard-routes' });// healthz/metrics/misc share V1's ops surface (http/context.ts's-// UNLOGGED_PATH_PREFIXES) — unauthenticated, uncorsed, unlogged.+// UNLOGGED_PATH_PREFIXES) — unauthenticated, uncorsed, unlogged. /metrics and+// /openapi.json are the M3 gate's ops surface: the one core registry's+// prometheus exposition, and the OpenAPI reference built from the same zod+// schemas the routes validate against.export const opsRoutes = (deps: AppDeps) =>- new Elysia({ name: 'core/ops-routes' }).use(healthRoutes(deps));+ new Elysia({ name: 'core/ops-routes' })+ .use(healthRoutes(deps))+ .use(+ openapi({+ specPath: OPENAPI_SPEC_PATH,+ exclude: { paths: OPENAPI_EXCLUDED_PATHS },+ })+ )+ .get('/metrics', async ({ set }) => {+ set.headers['content-type'] = registry.contentType;+ return await registry.metrics();+ });diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex df0f86dd2..418d50715 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1213,6 +1213,9 @@ importers:nanoid:specifier: ^5.1.6version: 5.1.6+ prom-client:+ specifier: ^15.1.3+ version: 15.1.3superjson:specifier: ^1.13.3version: 1.13.3