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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}