Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

ralph(P2-009): Three mount files + curated index.ts + health module: core answers a request

ralph61ccc7cb4449
diff --git a/packages/core/src/index.test.ts b/packages/core/src/index.test.ts
new file mode 100644
index 000000000..d8b97f8a2
--- /dev/null
+++ b/packages/core/src/index.test.ts
@@ -0,0 +1,23 @@
+import { expect, test } from 'bun:test';
+import * as core from './index';
+
+// The curated barrel is the package's real public API (ADR-008 acceptance
+// note): what apps/api needs to build AppDeps once and mount the three route
+// surfaces plus the tRPC router. A name missing here is a name apps/api
+// cannot reach — there is no `./*` wildcard to fall back on.
+test('the mount surface is curated', () => {
+ expect(core.appRouter).toBeDefined();
+ expect(core.publicApiRoutes).toBeTypeOf('function');
+ expect(core.dashboardRoutes).toBeTypeOf('function');
+ expect(core.opsRoutes).toBeTypeOf('function');
+ expect(core.createCtx).toBeTypeOf('function');
+ expect(core.extendCtx).toBeTypeOf('function');
+ expect(core.requestContext).toBeTypeOf('function');
+ expect(core.requestLogging).toBeTypeOf('function');
+ expect(core.createTrpcFetchHandler).toBeTypeOf('function');
+ expect(core.queues).toBeDefined();
+});
+
+test('a service, a client or a buffer is not on the barrel', () => {
+ expect(Object.keys(core)).not.toContain('createServices');
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 590013d7c..116c9c8bf 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -2,5 +2,37 @@
//
// Never `export *`. What leaves this package is exactly what is named here
// plus the `*.constants` subpaths in package.json's exports map — see
-// AGENTS.md.
-export {};
+// AGENTS.md. Everything below is what `apps/api` needs to build `AppDeps`
+// once and mount the three route surfaces plus the tRPC router over it; a
+// service, a client or a buffer is not reachable from here by design.
+
+export type {
+ AppDeps,
+ Ctx,
+ HttpCtx,
+ JobCtx,
+ RuntimeFlags,
+ ScopeMeta,
+ Session,
+} from './context';
+export { createCtx, extendCtx } from './context';
+export { requestContext, requestLogging } from './http/context';
+export type {
+ QueueProducerHandle,
+ QueueProducers,
+ Queues,
+} from './jobs.registry';
+export { queues } from './jobs.registry';
+export type { LogFn, Logger, LogLevel } from './logger';
+export {
+ REQUEST_ID_HEADER,
+ REQUEST_ID_LENGTH,
+ REQUEST_ID_LOG_FIELD,
+} from './logger';
+export { dashboardRoutes, opsRoutes, publicApiRoutes } from './rest.routes';
+export {
+ createTrpcFetchHandler,
+ TRPC_ENDPOINT,
+} from './rpc/handler';
+export type { AppRouter } from './rpc.router';
+export { appRouter } from './rpc.router';
diff --git a/packages/core/src/modules/health/health.routes.ts b/packages/core/src/modules/health/health.routes.ts
new file mode 100644
index 000000000..fb766d540
--- /dev/null
+++ b/packages/core/src/modules/health/health.routes.ts
@@ -0,0 +1,11 @@
+// Kubernetes liveness — shallow, event loop only. Ported from V1's
+// controllers/healthcheck.controller.ts `liveness`; `/healthcheck` and
+// `/healthz/ready`'s dependency/shutdown checks return once db, ch, redis and
+// a shutdown flag are real (P3+) — porting them against `unknown` deps now
+// would be a fake check, not a deferred one.
+
+import { defineRoutes } from '../../http/define';
+
+export const healthRoutes = defineRoutes((app) =>
+ app.get('/healthz/live', () => ({ live: true }))
+);
diff --git a/packages/core/src/modules/health/health.rpc.ts b/packages/core/src/modules/health/health.rpc.ts
new file mode 100644
index 000000000..0bc45867f
--- /dev/null
+++ b/packages/core/src/modules/health/health.rpc.ts
@@ -0,0 +1,10 @@
+// The one procedure `rpc.router.ts` mounts before the first real module lands
+// (ADR-007 decision 19) — proves the tRPC surface composes end to end. No V1
+// router named `health` exists; the 28 real ones arrive with their module
+// waves (P5-P8).
+
+import { createTRPCRouter, procedure } from '../../rpc/base';
+
+export const healthRouter = createTRPCRouter({
+ live: procedure.query(() => ({ live: true as const })),
+});
diff --git a/packages/core/src/rest.routes.test.ts b/packages/core/src/rest.routes.test.ts
new file mode 100644
index 000000000..a42d01592
--- /dev/null
+++ b/packages/core/src/rest.routes.test.ts
@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import { Elysia } from 'elysia';
+import { stubAppDeps } from '../test/http-fixtures';
+import { requestContext } from './http/context';
+import { dashboardRoutes, opsRoutes, publicApiRoutes } from './rest.routes';
+
+// The acceptance shape for ADR-007 decision 19: an app built from the mounts
+// plus requestContext answers a real request, end to end.
+test('opsRoutes answers a liveness probe through requestContext', async () => {
+ const { deps } = stubAppDeps();
+
+ const app = new Elysia().use(requestContext(deps)).use(opsRoutes(deps));
+
+ const response = await app.handle(
+ new Request('http://localhost/healthz/live')
+ );
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ live: true });
+});
+
+test('publicApiRoutes and dashboardRoutes compose with no modules yet', async () => {
+ const { deps } = stubAppDeps();
+
+ const app = new Elysia()
+ .use(requestContext(deps))
+ .use(publicApiRoutes(deps))
+ .use(dashboardRoutes(deps))
+ .use(opsRoutes(deps));
+
+ const response = await app.handle(
+ new Request('http://localhost/healthz/live')
+ );
+
+ expect(response.status).toBe(200);
+});
diff --git a/packages/core/src/rest.routes.ts b/packages/core/src/rest.routes.ts
new file mode 100644
index 000000000..f46b1231a
--- /dev/null
+++ b/packages/core/src/rest.routes.ts
@@ -0,0 +1,25 @@
+// The three URL surfaces `app.ts` hangs CORS, OpenAPI and guards on
+// (ADR-007 decision 19). Each is a factory over `AppDeps`, statically
+// composed from `.use()`d modules — no filesystem discovery. Adding a
+// module's HTTP half is one `.use()` on the surface it belongs to; most
+// modules touch exactly one.
+
+import { Elysia } from 'elysia';
+import type { AppDeps } from './context';
+import { healthRoutes } from './modules/health/health.routes';
+
+// 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
+// left inferred, as `defineRoutes`'s `RouteApp` is: `.use()`'d plugins widen
+// Elysia's type parameters in a way the bare `Elysia` type cannot express.
+export const publicApiRoutes = (_deps: AppDeps) =>
+ new Elysia({ name: 'core/public-api-routes' });
+
+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.
+export const opsRoutes = (deps: AppDeps) =>
+ new Elysia({ name: 'core/ops-routes' }).use(healthRoutes(deps));
diff --git a/packages/core/src/rpc.router.test.ts b/packages/core/src/rpc.router.test.ts
new file mode 100644
index 000000000..844fa585c
--- /dev/null
+++ b/packages/core/src/rpc.router.test.ts
@@ -0,0 +1,32 @@
+import { expect, test } from 'bun:test';
+import { stubHttpCtx } from '../test/rpc-fixtures';
+import { createTrpcFetchHandler } from './rpc/handler';
+import { appRouter } from './rpc.router';
+import type { CookieOptions } from './shared/cookie';
+
+const COOKIE_OPTIONS: CookieOptions = {
+ domain: '.openpanel.dev',
+ secure: true,
+ sameSite: 'lax',
+ httpOnly: true,
+ path: '/',
+};
+
+test('the composed appRouter serves the health procedure', async () => {
+ const { ctx, logger } = stubHttpCtx();
+ const handler = createTrpcFetchHandler({
+ router: appRouter,
+ logger,
+ cookieOptions: COOKIE_OPTIONS,
+ });
+
+ const response = await handler(
+ new Request('https://api.openpanel.dev/trpc/health.live'),
+ ctx
+ );
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({
+ result: { data: { json: { live: true } } },
+ });
+});
diff --git a/packages/core/src/rpc.router.ts b/packages/core/src/rpc.router.ts
new file mode 100644
index 000000000..650977c74
--- /dev/null
+++ b/packages/core/src/rpc.router.ts
@@ -0,0 +1,14 @@
+// The one static composition point for every tRPC procedure this package
+// serves. No `defineModule()`, no filesystem discovery — adding a module's
+// RPC half is one line here, which is what keeps `AppRouter` a real type
+// (ADR-007 decision 19). Only `health` exists so far; the 28 real routers
+// land with their module waves (P5-P8).
+
+import { healthRouter } from './modules/health/health.rpc';
+import { createTRPCRouter } from './rpc/base';
+
+export const appRouter = createTRPCRouter({
+ health: healthRouter,
+});
+
+export type AppRouter = typeof appRouter;