Skip to content

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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.yaml
index df0f86dd2..418d50715 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1213,6 +1213,9 @@ importers:
nanoid:
specifier: ^5.1.6
version: 5.1.6
+ prom-client:
+ specifier: ^15.1.3
+ version: 15.1.3
superjson:
specifier: ^1.13.3
version: 1.13.3