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-003): context.ts + services.ts: AppDeps/Ctx/HttpCtx/JobCtx, createCtx, lazy services - the circularity compiles

ralphf013cd50bc50
diff --git a/packages/core/src/context.test.ts b/packages/core/src/context.test.ts
new file mode 100644
index 000000000..a76734bd2
--- /dev/null
+++ b/packages/core/src/context.test.ts
@@ -0,0 +1,157 @@
+import { beforeAll, expect, mock, test } from 'bun:test';
+import type { AppDeps, Ctx, ProducerScope } from './context';
+import type { Logger } from './logger';
+import type { ServiceDeps, Services } from './services';
+
+// mock.module is not hoisted, so the subject is imported inside beforeAll —
+// see AGENTS.md. Mocking createServices is what makes "not built yet"
+// observable at all: the real container is `{}` either way.
+const serviceDeps: ServiceDeps[] = [];
+const createServices = mock((deps: ServiceDeps): Services => {
+ serviceDeps.push(deps);
+ return {};
+});
+mock.module('./services', () => ({ createServices }));
+
+let createCtx: typeof import('./context').createCtx;
+let extendCtx: typeof import('./context').extendCtx;
+
+beforeAll(async () => {
+ ({ createCtx, extendCtx } = await import('./context'));
+});
+
+const REQUEST_ID = 'req_abcdefghijklmnopqrstu';
+
+function stubLogger(): Logger {
+ const noop = () => undefined;
+ const logger: Logger = {
+ fatal: noop,
+ error: noop,
+ warn: noop,
+ info: noop,
+ debug: noop,
+ trace: noop,
+ child: () => logger,
+ };
+ return logger;
+}
+
+function stubDeps(): { deps: AppDeps; scopes: ProducerScope[] } {
+ const scopes: ProducerScope[] = [];
+ return {
+ scopes,
+ deps: {
+ db: {},
+ ch: {},
+ redis: {},
+ clients: {},
+ buffers: {},
+ producers: {
+ scope(meta) {
+ scopes.push(meta);
+ return { scopedFor: meta.requestId };
+ },
+ },
+ logger: stubLogger(),
+ config: { selfHosted: true },
+ },
+ };
+}
+
+function build(): { ctx: Ctx; deps: AppDeps; scopes: ProducerScope[] } {
+ const { deps, scopes } = stubDeps();
+ const logger = deps.logger.child({ requestId: REQUEST_ID });
+ return {
+ ctx: createCtx(deps, { requestId: REQUEST_ID, logger }),
+ deps,
+ scopes,
+ };
+}
+
+test('services are not built until they are read', () => {
+ createServices.mockClear();
+
+ const { ctx } = build();
+ expect(createServices).not.toHaveBeenCalled();
+
+ expect(ctx.services).toBeDefined();
+ expect(createServices).toHaveBeenCalledTimes(1);
+});
+
+test('services are built once per ctx, and once per further ctx', () => {
+ createServices.mockClear();
+
+ const { ctx } = build();
+ const first = ctx.services;
+ expect(ctx.services).toBe(first);
+ expect(createServices).toHaveBeenCalledTimes(1);
+
+ build().ctx.services;
+ expect(createServices).toHaveBeenCalledTimes(2);
+});
+
+test('the services graph is built from the scoped ctx, not from boot deps', () => {
+ createServices.mockClear();
+ serviceDeps.length = 0;
+
+ const { ctx } = build();
+ ctx.services;
+
+ expect(createServices).toHaveBeenCalledTimes(1);
+ expect(serviceDeps[0]?.logger).toBe(ctx.logger);
+ expect(serviceDeps[0]?.queues).toBe(ctx.queues);
+});
+
+test('the requestId reaches the producer scope and the ctx', () => {
+ const { ctx, scopes } = build();
+
+ expect(scopes).toEqual([{ requestId: REQUEST_ID }]);
+ expect(ctx.requestId).toBe(REQUEST_ID);
+ expect(ctx.queues).toEqual({ scopedFor: REQUEST_ID });
+});
+
+test('the logger is the caller-bound child, unwrapped', () => {
+ const { deps } = stubDeps();
+ const logger = deps.logger.child({ requestId: REQUEST_ID });
+
+ expect(createCtx(deps, { requestId: REQUEST_ID, logger }).logger).toBe(
+ logger
+ );
+});
+
+test('boot handles are passed through by reference', () => {
+ const { ctx, deps } = build();
+
+ expect(ctx.db).toBe(deps.db);
+ expect(ctx.ch).toBe(deps.ch);
+ expect(ctx.redis).toBe(deps.redis);
+ expect(ctx.clients).toBe(deps.clients);
+ expect(ctx.buffers).toBe(deps.buffers);
+});
+
+test('extendCtx adds transport extras without building services', () => {
+ createServices.mockClear();
+
+ const { ctx } = build();
+ const jobCtx = extendCtx(ctx, {
+ job: { id: 'job_1', attempt: 1, queue: 'sessions', name: 'session' },
+ });
+
+ expect(jobCtx.job.id).toBe('job_1');
+ expect(jobCtx.requestId).toBe(REQUEST_ID);
+ expect(createServices).not.toHaveBeenCalled();
+
+ expect(jobCtx.services).toBe(ctx.services);
+ expect(createServices).toHaveBeenCalledTimes(1);
+});
+
+test('services survives a copy — enumerable, and spreading forces the build', () => {
+ createServices.mockClear();
+
+ const { ctx } = build();
+ const copy = { ...ctx };
+
+ expect(createServices).toHaveBeenCalledTimes(1);
+ expect(copy.services).toBe(ctx.services);
+ expect(createServices).toHaveBeenCalledTimes(1);
+});
diff --git a/packages/core/src/context.ts b/packages/core/src/context.ts
new file mode 100644
index 000000000..04e771c28
--- /dev/null
+++ b/packages/core/src/context.ts
@@ -0,0 +1,148 @@
+// One boot scope, one work scope, one builder. HTTP routes, tRPC procedures,
+// job handlers and the Kafka consumer all extend the same `Ctx`, so a service
+// written once works under every transport and the requestId minted at the
+// edge reaches the query, the enqueue and the job that enqueue causes
+// (ADR-007 decision 18, ADR-018 R1).
+
+import type { Logger } from './logger';
+import { createServices, type Services } from './services';
+import type { CookieOptions } from './shared/cookie';
+
+// Handles core does not own yet. Each real type arrives with the phase that
+// builds it (db/ch/redis P3, clients P4, buffers P8); they are named now so
+// AppDeps and Ctx are written once in their final shape and replacing an alias
+// moves no field. `unknown` is deliberate — reading one before its type lands
+// is a compile error rather than a silent `any`.
+export type Db = unknown;
+export type ClickHouseClient = unknown;
+export type RedisClient = unknown;
+export type ServiceClients = unknown;
+export type Buffers = unknown;
+
+// Replaced by jobs.registry.ts (P2-004). `scope` is real here because
+// createCtx calls it.
+export type QueueProducers = unknown;
+
+/** The envelope meta a scoped producer stamps on everything it enqueues. */
+export interface ProducerScope {
+ requestId: string;
+}
+
+export interface ProducerHandle {
+ scope(meta: ProducerScope): QueueProducers;
+}
+
+// Elysia's cookie primitive, wrapped (P2-007), and the resolved session
+// (P6 auth).
+export type CookieJar = unknown;
+export type Session = unknown;
+
+/** The env-derived flags core needs. apps/api's config/env.ts is the sole
+ * reader of process.env; core reads none. */
+export interface RuntimeFlags {
+ selfHosted: boolean;
+}
+
+/** Boot scope. Built once in apps/api's main.ts, closed once in shutdown. */
+export interface AppDeps {
+ db: Db;
+ ch: ClickHouseClient;
+ redis: RedisClient;
+ clients: ServiceClients;
+ buffers: Buffers;
+ producers: ProducerHandle;
+ logger: Logger;
+ config: RuntimeFlags;
+}
+
+/** Work scope. One per HTTP request, RPC call, job run or Kafka batch. */
+export interface Ctx {
+ db: Db;
+ ch: ClickHouseClient;
+ redis: RedisClient;
+ clients: ServiceClients;
+ buffers: Buffers;
+ logger: Logger;
+ queues: QueueProducers;
+ services: Services;
+ requestId: string;
+}
+
+/** What HTTP and tRPC add. No req/res in core, from day one. */
+export interface HttpCtx extends Ctx {
+ headers: Headers;
+ ip: string;
+ cookies: CookieJar;
+ /** Memoized: two guards and a handler asking cost one lookup. */
+ session: () => Promise<Session | null>;
+ setCookie(name: string, value: string, options?: CookieOptions): void;
+}
+
+/** What a job run adds. */
+export interface JobCtx extends Ctx {
+ job: { id: string; attempt: number; queue: string; name: string };
+}
+
+export interface ScopeMeta {
+ requestId: string;
+ /** Already child()-bound by the caller — createCtx does not bind it. */
+ logger: Logger;
+}
+
+/**
+ * The single builder. When something new must reach every handler it is added
+ * here once and all four transports have it.
+ */
+export function createCtx(deps: AppDeps, scope: ScopeMeta): Ctx {
+ const ctx: Ctx = {
+ db: deps.db,
+ ch: deps.ch,
+ redis: deps.redis,
+ clients: deps.clients,
+ buffers: deps.buffers,
+ logger: scope.logger,
+ queues: deps.producers.scope({ requestId: scope.requestId }),
+ requestId: scope.requestId,
+ // Installed as a getter immediately below.
+ services: undefined as unknown as Services,
+ };
+
+ installLazyServices(ctx);
+ return ctx;
+}
+
+/**
+ * Extend a Ctx into an HttpCtx or a JobCtx. Never spread one: `{ ...ctx }`
+ * reads `services`, which forces the build the hot path exists to avoid.
+ */
+export function extendCtx<Extras extends object>(
+ ctx: Ctx,
+ extras: Extras
+): Ctx & Extras {
+ return Object.assign(Object.create(ctx) as Ctx, extras);
+}
+
+// The services graph is built from the SCOPED ctx, never from deps: a service
+// must log to this request's logger and enqueue through this request's
+// producers. /track never touches it and pays one defineProperty.
+function installLazyServices(ctx: Ctx): void {
+ let built: Services | undefined;
+ Object.defineProperty(ctx, 'services', {
+ get() {
+ built ??= createServices({
+ db: ctx.db,
+ ch: ctx.ch,
+ redis: ctx.redis,
+ clients: ctx.clients,
+ buffers: ctx.buffers,
+ logger: ctx.logger,
+ queues: ctx.queues,
+ });
+ return built;
+ },
+ // Enumerable so a transport that copies a Ctx keeps the field at all;
+ // configurable so one may reinstall it.
+ enumerable: true,
+ configurable: true,
+ });
+}
diff --git a/packages/core/src/services.ts b/packages/core/src/services.ts
new file mode 100644
index 000000000..e2c3d4fe3
--- /dev/null
+++ b/packages/core/src/services.ts
@@ -0,0 +1,33 @@
+// The composition root. Empty until the first module lands (ADR-007 build
+// step 4): the point of writing it now is that the Ctx <-> Services
+// circularity compiles.
+
+import type { Ctx } from './context';
+
+/** What every service factory receives — derived from Ctx, so it cannot drift. */
+export type ServiceDeps = Pick<
+ Ctx,
+ 'db' | 'ch' | 'redis' | 'clients' | 'buffers' | 'logger' | 'queues'
+>;
+
+// Two type rules the compiler enforces but cannot explain:
+//
+// 1. `Services` must stay an INTERFACE. A type alias over
+// `ReturnType<typeof createServices>` is circular — resolving it needs
+// every factory's signature and every factory's signature names
+// `Services`. Interface members resolve lazily, which breaks the loop.
+// 2. Every service method needs an explicit return type, or a factory's
+// return type cannot be computed from signatures alone. Omit one and
+// typecheck fails with ts7022/ts7023 naming the method.
+//
+// biome-ignore lint/suspicious/noEmptyInterface: empty by design until the first module lands, and it must stay an interface — see rule 1.
+export interface Services {}
+
+export function createServices(_deps: ServiceDeps): Services {
+ // When the first module lands, each factory is called with `deps` and a
+ // `() => container` thunk: captured, not copied, so two services may call
+ // each other without a cycle.
+ const container: Services = {};
+
+ return container;
+}