OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
ralph(P1-004): /event stays: legacy compat route through the Kafka produce path + usage metric
ralph2f71d3a8e1e3
diff --git a/apps/api/package.json b/apps/api/package.jsonindex c9e2ffd3b..4422248be 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -51,6 +51,7 @@"fastify-zod-openapi": "^5.6.1","pino": "catalog:","pino-pretty": "catalog:",+ "prom-client": "^15.1.3","ramda": "^0.29.1","sharp": "^0.33.5","source-map-support": "^0.5.21",diff --git a/apps/api/src/controllers/event.controller.test.ts b/apps/api/src/controllers/event.controller.test.tsnew file mode 100644index 000000000..57d733c77--- /dev/null+++ b/apps/api/src/controllers/event.controller.test.ts@@ -0,0 +1,244 @@+/**+ * Tests for the legacy `POST /event` compat route (ADR-015 entry 1, reversed:+ * the route is KEPT, produces to Kafka exactly like /track, and is measured+ * per client so the deferred removal decision has data).+ *+ * Covers:+ * - postEvent maps the legacy `{name, properties}` body onto the same Kafka+ * produce path /track uses, with a producer-minted event id.+ * - legacyEventUsageHook increments openpanel_legacy_event_requests_total,+ * labelled by client id, and never mints a label for an unauthenticated+ * request.+ * - validateSdkRequest still accepts the `mixan-*` headers (ADR-015 entry 5 is+ * pending the same usage metric, so the fallback stays for now).+ *+ * `@openpanel/db` is partially mocked (importActual + overrides) because it+ * imports `@openpanel/queue`, which the produce assertions replace.+ */++import { getSalts } from '@openpanel/db';+import { getAsnInfo, getGeoLocation } from '@openpanel/geo';+import { produceIncomingEvent } from '@openpanel/queue';+import type { DeprecatedPostEventPayload } from '@openpanel/validation';+import type { FastifyReply, FastifyRequest } from 'fastify';+import { beforeEach, describe, expect, it, vi } from 'vitest';+import { postEvent } from './event.controller';+import { legacyEventUsageHook } from '@/hooks/legacy-event.hook';+import { legacyEventRequestsTotal } from '@/metrics';+import { validateSdkRequest } from '@/utils/auth';++vi.mock('@openpanel/queue', async () => {+ const actual =+ await vi.importActual<typeof import('@openpanel/queue')>(+ '@openpanel/queue'+ );+ return { ...actual, produceIncomingEvent: vi.fn() };+});++vi.mock('@openpanel/geo', () => ({+ getGeoLocation: vi.fn(),+ getAsnInfo: vi.fn(),+}));++vi.mock('@openpanel/db', async () => {+ const actual =+ await vi.importActual<typeof import('@openpanel/db')>('@openpanel/db');+ return { ...actual, getSalts: vi.fn(), getClientByIdCached: vi.fn() };+});++const PROJECT_ID = 'legacy-event-project';+const CLIENT_ID = '11111111-1111-4111-8111-111111111111';+const OTHER_CLIENT_ID = '22222222-2222-4222-8222-222222222222';+const UUID_PATTERN =+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;++const legacyBody = (+ overrides: Partial<DeprecatedPostEventPayload> = {}+): DeprecatedPostEventPayload => ({+ name: 'legacy_event',+ timestamp: new Date('2026-01-01T00:00:00.000Z').toISOString(),+ properties: { __referrer: '', foo: 'bar' },+ ...overrides,+});++const makeRequest = (+ body: DeprecatedPostEventPayload,+ headers: Record<string, string> = {}+) =>+ ({+ body,+ headers: { 'user-agent': 'Mozilla/5.0 (Macintosh)', ...headers },+ clientIp: '203.0.113.10',+ timestamp: Date.now(),+ client: { id: CLIENT_ID, projectId: PROJECT_ID },+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+ }) as unknown as FastifyRequest<{ Body: DeprecatedPostEventPayload }>;++interface ReplySpy {+ status: ReturnType<typeof vi.fn>;+ send: ReturnType<typeof vi.fn>;+}++const makeReply = (): FastifyReply & ReplySpy => {+ const reply = {+ status: vi.fn(() => reply),+ send: vi.fn(() => reply),+ } as ReplySpy;+ return reply as unknown as FastifyReply & ReplySpy;+};++const producedCall = () => {+ const call = vi.mocked(produceIncomingEvent).mock.calls[0];+ if (!call) {+ throw new Error('produceIncomingEvent was not called');+ }+ return { payload: call[0], partitionKey: call[1] };+};++const counterValue = async (clientId: string) => {+ const { values } = await legacyEventRequestsTotal.get();+ return (+ values.find((value) => value.labels.client_id === clientId)?.value ?? 0+ );+};++beforeEach(() => {+ vi.clearAllMocks();+ vi.mocked(getSalts).mockResolvedValue({+ current: 'current-salt',+ previous: 'previous-salt',+ });+ vi.mocked(getGeoLocation).mockResolvedValue({+ country: 'SE',+ city: 'Stockholm',+ region: 'Stockholm',+ longitude: 18,+ latitude: 59,+ } as Awaited<ReturnType<typeof getGeoLocation>>);+ vi.mocked(getAsnInfo).mockResolvedValue({+ asn: 1234,+ org: 'Example ISP',+ isHosting: false,+ });+ vi.mocked(produceIncomingEvent).mockResolvedValue(undefined);+});++describe('postEvent', () => {+ it('produces the legacy payload to Kafka and answers 202 "ok"', async () => {+ const request = makeRequest(legacyBody());+ const reply = makeReply();++ await postEvent(request, reply);++ expect(produceIncomingEvent).toHaveBeenCalledTimes(1);+ const { payload, partitionKey } = producedCall();++ expect(payload.projectId).toBe(PROJECT_ID);+ expect(payload.event.name).toBe('legacy_event');+ expect(payload.event.properties).toMatchObject({ foo: 'bar' });+ expect(payload.deviceId).toBeTruthy();+ expect(partitionKey).toBe(payload.deviceId);++ // V1's wire contract for this route: 202 with a plain-text body.+ expect(reply.status).toHaveBeenCalledWith(202);+ expect(reply.send).toHaveBeenCalledWith('ok');+ });++ it('mints the event id at the producer, like /track', async () => {+ await postEvent(makeRequest(legacyBody()), makeReply());++ expect(producedCall().payload.id).toMatch(UUID_PATTERN);+ });++ it('replaces the client-supplied timestamp with the server timestamp', async () => {+ const request = makeRequest(legacyBody());+ await postEvent(request, makeReply());++ const { payload } = producedCall();+ expect(payload.event.timestamp).toBe(request.timestamp);+ expect(payload.event.isTimestampFromThePast).toBe(false);+ });++ it('answers 400 when the client carries no project', async () => {+ const request = makeRequest(legacyBody());+ (request as { client?: unknown }).client = { id: CLIENT_ID };+ const reply = makeReply();++ await postEvent(request, reply);++ expect(produceIncomingEvent).not.toHaveBeenCalled();+ expect(reply.status).toHaveBeenCalledWith(400);+ expect(reply.send).toHaveBeenCalledWith('missing origin');+ });+});++describe('legacyEventUsageHook', () => {+ it('counts a request against its client id', async () => {+ const before = await counterValue(CLIENT_ID);++ await legacyEventUsageHook(makeRequest(legacyBody()));++ expect(await counterValue(CLIENT_ID)).toBe(before + 1);+ });++ it('keeps one series per client', async () => {+ const request = makeRequest(legacyBody());+ (request as { client?: unknown }).client = {+ id: OTHER_CLIENT_ID,+ projectId: PROJECT_ID,+ };+ const before = await counterValue(OTHER_CLIENT_ID);+ const otherBefore = await counterValue(CLIENT_ID);++ await legacyEventUsageHook(request);++ expect(await counterValue(OTHER_CLIENT_ID)).toBe(before + 1);+ expect(await counterValue(CLIENT_ID)).toBe(otherBefore);+ });++ it('mints no label for an unauthenticated request', async () => {+ const request = makeRequest(legacyBody());+ (request as { client?: unknown }).client = undefined;++ await legacyEventUsageHook(request);++ const { values } = await legacyEventRequestsTotal.get();+ expect(values.some((value) => !value.labels.client_id)).toBe(false);+ });++ it('is exposed under the name the removal decision will query', async () => {+ await expect(legacyEventRequestsTotal.get()).resolves.toMatchObject({+ name: 'openpanel_legacy_event_requests_total',+ type: 'counter',+ });+ });+});++describe('mixan-* header fallback', () => {+ it('authenticates a client sent as mixan-client-id (ADR-015 entry 5 deferred)', async () => {+ const { getClientByIdCached } = await import('@openpanel/db');+ vi.mocked(getClientByIdCached).mockResolvedValue({+ id: CLIENT_ID,+ projectId: PROJECT_ID,+ // Keeps this test about the header fallback rather than re-proving+ // secret verification, which the auth contracts already cover.+ ignoreCorsAndSecret: true,+ project: {+ id: PROJECT_ID,+ filters: [],+ allowUnsafeRevenueTracking: false,+ },+ } as unknown as Awaited<ReturnType<typeof getClientByIdCached>>);++ const request = makeRequest(legacyBody(), {+ 'mixan-client-id': CLIENT_ID,+ 'mixan-client-secret': 'legacy-secret',+ });+ delete (request as { client?: unknown }).client;++ const client = await validateSdkRequest(request);++ expect(client.id).toBe(CLIENT_ID);+ expect(request.clientSecretAuth).toBe(true);+ });+});diff --git a/apps/api/src/hooks/legacy-event.hook.ts b/apps/api/src/hooks/legacy-event.hook.tsnew file mode 100644index 000000000..f9198b9a9--- /dev/null+++ b/apps/api/src/hooks/legacy-event.hook.ts@@ -0,0 +1,21 @@+import type { FastifyRequest } from 'fastify';+import { recordLegacyEventRequest } from '@/metrics';++/**+ * Counts traffic on the legacy `POST /event` route per client so the deferred+ * removal decision has data (ADR-015 entry 1, reversed).+ *+ * Registered after `clientHook` and before the hooks that can short-circuit+ * the request (`isBotHook`, `subscriptionHook`), for two reasons: the label+ * can then only ever be a client id that exists in the database — an+ * unauthenticated caller must not be able to mint prometheus label values —+ * and a client whose events are dropped as bot/wind-down traffic is still a+ * client that would break if `/event` disappeared.+ */+export async function legacyEventUsageHook(request: FastifyRequest) {+ const clientId = request.client?.id;++ if (clientId) {+ recordLegacyEventRequest(clientId);+ }+}diff --git a/apps/api/src/metrics.ts b/apps/api/src/metrics.tsnew file mode 100644index 000000000..5736ff8f5--- /dev/null+++ b/apps/api/src/metrics.ts@@ -0,0 +1,31 @@+import client from 'prom-client';++/**+ * Metrics owned by the API process.+ *+ * `fastify-metrics` serves prom-client's global registry at `/metrics`+ * (fastify-metrics `exposeMetrics()` reads `client.register`), and prom-client+ * metrics register themselves there on construction — so declaring a metric in+ * this module is all that is needed to expose it. It resolves to the same+ * physical `prom-client` package fastify-metrics loads, which is what makes+ * one shared registry possible.+ */++const LEGACY_EVENT_CLIENT_ID_LABEL = 'client_id';++/**+ * ADR-015 entry 1 was reversed: `POST /event` is kept as a legacy compat route+ * rather than deleted, because production still has projects posting to it.+ * This counter is the evidence the deferred removal decision needs — when it+ * reads zero for every client, `/event` and the `mixan-*` header fallback can+ * both go (ADR-015 entry 5 is pending the same measurement).+ */+export const legacyEventRequestsTotal = new client.Counter({+ name: 'openpanel_legacy_event_requests_total',+ help: 'Requests to the legacy POST /event ingestion route, by client id',+ labelNames: [LEGACY_EVENT_CLIENT_ID_LABEL],+});++export function recordLegacyEventRequest(clientId: string) {+ legacyEventRequestsTotal.inc({ [LEGACY_EVENT_CLIENT_ID_LABEL]: clientId });+}diff --git a/apps/api/src/routes/event.router.ts b/apps/api/src/routes/event.router.tsindex 1d9e8cbea..abc0b462c 100644--- a/apps/api/src/routes/event.router.ts+++ b/apps/api/src/routes/event.router.ts@@ -3,11 +3,14 @@ import * as controller from '@/controllers/event.controller';import { clientHook } from '@/hooks/client.hook';import { duplicateHook } from '@/hooks/duplicate.hook';import { isBotHook } from '@/hooks/is-bot.hook';+import { legacyEventUsageHook } from '@/hooks/legacy-event.hook';import { subscriptionHook } from '@/hooks/subscription.hook';const eventRouter: FastifyPluginAsyncZodOpenApi = async (fastify) => {fastify.addHook('preValidation', duplicateHook);fastify.addHook('preHandler', clientHook);+ // Usage metric before the hooks that can short-circuit — see the hook.+ fastify.addHook('preHandler', legacyEventUsageHook);fastify.addHook('preHandler', isBotHook);fastify.addHook('preHandler', subscriptionHook);@@ -16,7 +19,8 @@ const eventRouter: FastifyPluginAsyncZodOpenApi = async (fastify) => {url: '/',schema: {tags: ['Event'],- description: 'Deprecated direct event ingestion endpoint. Use /track instead.',+ description:+ 'Deprecated direct event ingestion endpoint. Use /track instead.',},handler: controller.postEvent,});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 2d2f8bede..df0f86dd2 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -197,6 +197,9 @@ importers:pino-pretty:specifier: 'catalog:'version: 13.1.3+ prom-client:+ specifier: ^15.1.3+ version: 15.1.3ramda:specifier: ^0.29.1version: 0.29.1