Skip to content

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.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.yaml
index 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.3
ramda:
specifier: ^0.29.1
version: 0.29.1