OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
fix: override id logic (fixes session id and replay ingestion)
Carl-Gerhard Lindesvärd31392111e1ea
diff --git a/apps/api/src/controllers/track.controller.test.ts b/apps/api/src/controllers/track.controller.test.tsnew file mode 100644index 000000000..5632c63ec--- /dev/null+++ b/apps/api/src/controllers/track.controller.test.ts@@ -0,0 +1,108 @@+/**+ * Tests for:+ * - getOverrideDeviceId — the guard around a track event's caller-supplied+ * `__deviceId` (it becomes a Redis key segment, a BullMQ jobId and a ClickHouse+ * device_id, so it must be trimmed, non-empty, and length-bounded).+ * - handleReplay — replay files a chunk under the session id the SDK echoes back;+ * it needs no device resolution and trusts the client-sent session id.+ */++import { replayBuffer } from '@openpanel/db';+import type {+ IReplayPayload,+ ITrackHandlerPayload,+} from '@openpanel/validation';+import { beforeEach, describe, expect, it, vi } from 'vitest';+import { getOverrideDeviceId, handleReplay } from './track.controller';++const track = (+ properties?: Record<string, unknown>+): ITrackHandlerPayload =>+ ({+ type: 'track',+ payload: { name: 'page_view', properties },+ }) as ITrackHandlerPayload;++describe('getOverrideDeviceId', () => {+ it('returns a trimmed device id', () => {+ expect(getOverrideDeviceId(track({ __deviceId: ' cookie-abc ' }))).toBe(+ 'cookie-abc'+ );+ });++ it('returns the device id as-is when already clean', () => {+ expect(getOverrideDeviceId(track({ __deviceId: 'cookie-abc' }))).toBe(+ 'cookie-abc'+ );+ });++ it('ignores empty / whitespace-only values', () => {+ expect(getOverrideDeviceId(track({ __deviceId: '' }))).toBeUndefined();+ expect(getOverrideDeviceId(track({ __deviceId: ' ' }))).toBeUndefined();+ });++ it('ignores non-string values', () => {+ expect(getOverrideDeviceId(track({ __deviceId: 123 }))).toBeUndefined();+ expect(getOverrideDeviceId(track({}))).toBeUndefined();+ expect(getOverrideDeviceId(track(undefined))).toBeUndefined();+ });++ it('ignores pathologically long values (cap is 64)', () => {+ expect(+ getOverrideDeviceId(track({ __deviceId: 'x'.repeat(65) }))+ ).toBeUndefined();+ expect(getOverrideDeviceId(track({ __deviceId: 'x'.repeat(64) }))).toBe(+ 'x'.repeat(64)+ );+ });++ it('returns undefined for non-track payload types', () => {+ expect(+ getOverrideDeviceId({+ type: 'identify',+ payload: { profileId: 'p1', properties: { __deviceId: 'cookie' } },+ } as ITrackHandlerPayload)+ ).toBeUndefined();+ });+});++const chunk = (): IReplayPayload => ({+ chunk_index: 0,+ events_count: 1,+ is_full_snapshot: true,+ started_at: '2026-06-08T12:00:00.000Z',+ ended_at: '2026-06-08T12:00:01.000Z',+ payload: '[]',+});++describe('handleReplay', () => {+ beforeEach(() => {+ vi.restoreAllMocks();+ });++ it('files the chunk under the session id provided by the caller', async () => {+ const add = vi.spyOn(replayBuffer, 'add').mockResolvedValue(undefined);++ await handleReplay(chunk(), {+ projectId: 'proj-1',+ sessionId: 'sess-issued-123',+ });++ expect(add).toHaveBeenCalledTimes(1);+ expect(add).toHaveBeenCalledWith(+ expect.objectContaining({+ project_id: 'proj-1',+ session_id: 'sess-issued-123',+ })+ );+ });++ it('throws when the session id is missing', async () => {+ const add = vi.spyOn(replayBuffer, 'add').mockResolvedValue(undefined);++ await expect(+ handleReplay(chunk(), { projectId: 'proj-1', sessionId: undefined })+ ).rejects.toThrow('Session ID is required for replay');+ expect(add).not.toHaveBeenCalled();+ });+});diff --git a/apps/api/src/controllers/track.controller.ts b/apps/api/src/controllers/track.controller.tsindex 3a32f0fed..2cda17f2a 100644--- a/apps/api/src/controllers/track.controller.ts+++ b/apps/api/src/controllers/track.controller.ts@@ -71,6 +71,29 @@ function getIdentity(body: ITrackHandlerPayload): IIdentifyPayload | undefined {return undefined;}+const MAX_OVERRIDE_DEVICE_ID_LENGTH = 64;++function sanitizeOverrideDeviceId(raw: unknown): string | undefined {+ if (typeof raw !== 'string') {+ return undefined;+ }+ const trimmed = raw.trim();+ if (!trimmed || trimmed.length > MAX_OVERRIDE_DEVICE_ID_LENGTH) {+ return undefined;+ }+ return trimmed;+}++// Resolve a caller-supplied device id from a track event's `properties.__deviceId`.+export function getOverrideDeviceId(+ body: ITrackHandlerPayload+): string | undefined {+ if (body.type !== 'track') {+ return undefined;+ }+ return sanitizeOverrideDeviceId(body.payload?.properties?.__deviceId);+}+export function getTimestamp(timestamp: FastifyRequest['timestamp'],payload: ITrackHandlerPayload['payload']@@ -148,11 +171,7 @@ async function buildContext(validatedBody.payload.profileId = profileId;}- const overrideDeviceId =- validatedBody.type === 'track' &&- typeof validatedBody.payload?.properties?.__deviceId === 'string'- ? validatedBody.payload?.properties.__deviceId- : undefined;+ const overrideDeviceId = getOverrideDeviceId(validatedBody);// Get geo location (needed for track and identify)const [geo, salts] = await Promise.all([getGeoLocation(ip), getSalts()]);@@ -310,17 +329,19 @@ async function handleDecrement(await adjustProfileProperty(payload, context.projectId, -1);}-async function handleReplay(+// Replay only needs the server-issued session id (the SDK echoes it back). Trust+// it — scoped to the authed project, unguessable, same trust level as event data.+export async function handleReplay(payload: IReplayPayload,- context: TrackContext+ { projectId, sessionId }: { projectId: string; sessionId: string | undefined }): Promise<void> {- if (!context.sessionId) {+ if (!sessionId) {throw new HttpError('Session ID is required for replay', { status: 400 });}const row = {- project_id: context.projectId,- session_id: context.sessionId,+ project_id: projectId,+ session_id: sessionId,chunk_index: payload.chunk_index,started_at: payload.started_at,ended_at: payload.ended_at,@@ -395,9 +416,22 @@ export async function handler(case 'decrement':await handleDecrement(validatedBody.payload, context);break;- case 'replay':- await handleReplay(validatedBody.payload, context);+ case 'replay': {+ // BACKCOMPAT(replay-sessionid): TEMPORARY legacy branch, remove when new SDK is fully deployed+ if (!validatedBody.payload.sessionId) {+ await handleReplay(validatedBody.payload, {+ projectId: context.projectId,+ sessionId: context.sessionId,+ });+ break;+ }++ await handleReplay(validatedBody.payload, {+ projectId: context.projectId,+ sessionId: validatedBody.payload.sessionId,+ });break;+ }case 'group':await handleGroup(validatedBody.payload, context);break;@@ -484,7 +518,7 @@ export async function fetchDeviceId(} catch (error) {request.log.error({ err: error },- 'Error getting session end GET /track/device-id',+ 'Error getting session end GET /track/device-id');}diff --git a/apps/api/src/utils/ids.test.ts b/apps/api/src/utils/ids.test.tsnew file mode 100644index 000000000..c1a4cf43c--- /dev/null+++ b/apps/api/src/utils/ids.test.ts@@ -0,0 +1,112 @@+/**+ * Tests for getDeviceId — specifically the caller-supplied (override) device id+ * path. The override must resolve a real, stable sessionId through the same+ * `getInfoFromSession` logic internal device ids use, so sessions open/extend/close+ * identically. Returning an empty sessionId here is the bug that left sessions+ * unbuffered and made the createSessionEnd job throw "Session not found".+ *+ * Redis is mocked: we drive `multi().exec()` to simulate "an active sessionEnd job+ * exists" vs "no active job" without a real connection.+ */++import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++const { execMock } = vi.hoisted(() => ({ execMock: vi.fn() }));++vi.mock('@openpanel/redis', async (importOriginal) => {+ const actual = await importOriginal<typeof import('@openpanel/redis')>();+ return {+ ...actual,+ getRedisCache: () => ({+ multi: () => {+ const chain = {+ hget: () => chain,+ exec: execMock,+ };+ return chain;+ },+ }),+ };+});++const { getDeviceId } = await import('./ids');++const SALTS = { current: 'salt-current', previous: 'salt-previous' };+const BASE = {+ projectId: 'proj-1',+ ip: '1.2.3.4',+ ua: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/148.0.0.0',+ salts: SALTS,+};++beforeEach(() => {+ vi.useFakeTimers();+ vi.setSystemTime(new Date('2026-06-08T12:00:00.000Z'));+ execMock.mockReset();+});++afterEach(() => {+ vi.useRealTimers();+});++describe('getDeviceId — override device id', () => {+ it('derives a non-empty, deterministic sessionId when no active session exists', async () => {+ execMock.mockResolvedValue([+ [null, null],+ [null, null],+ ]);++ const result = await getDeviceId({+ ...BASE,+ overrideDeviceId: 'cookie-abc',+ });++ expect(result.deviceId).toBe('cookie-abc');+ expect(result.sessionId).toBeTruthy();++ // Same override within the same time window → same session id (stable).+ const again = await getDeviceId({+ ...BASE,+ overrideDeviceId: 'cookie-abc',+ });+ expect(again.sessionId).toBe(result.sessionId);+ });++ it('reuses the sessionId from an active sessionEnd job instead of splitting', async () => {+ execMock.mockResolvedValue([+ [+ null,+ JSON.stringify({+ payload: {+ projectId: 'proj-1',+ deviceId: 'cookie-abc',+ sessionId: 'sess-active-123',+ },+ }),+ ],+ [null, null],+ ]);++ const result = await getDeviceId({+ ...BASE,+ overrideDeviceId: 'cookie-abc',+ });++ expect(result.deviceId).toBe('cookie-abc');+ expect(result.sessionId).toBe('sess-active-123');+ });++ it('produces distinct session ids for distinct override device ids', async () => {+ execMock.mockResolvedValue([+ [null, null],+ [null, null],+ ]);++ const a = await getDeviceId({ ...BASE, overrideDeviceId: 'cookie-a' });+ const b = await getDeviceId({ ...BASE, overrideDeviceId: 'cookie-b' });++ expect(a.sessionId).toBeTruthy();+ expect(b.sessionId).toBeTruthy();+ expect(a.sessionId).not.toBe(b.sessionId);+ });+});diff --git a/apps/api/src/utils/ids.ts b/apps/api/src/utils/ids.tsindex 3614da1b7..ec0cfc993 100644--- a/apps/api/src/utils/ids.ts+++ b/apps/api/src/utils/ids.ts@@ -18,7 +18,13 @@ export async function getDeviceId({overrideDeviceId?: string;}) {if (overrideDeviceId) {- return { deviceId: overrideDeviceId, sessionId: '' };+ // Resolve a caller-supplied device id through the same path as internal ones+ // (stable, so it's both candidates) — sessions open/extend/close identically.+ return await getInfoFromSession({+ projectId,+ currentDeviceId: overrideDeviceId,+ previousDeviceId: overrideDeviceId,+ });}if (!ua) {diff --git a/packages/sdks/web/src/index.ts b/packages/sdks/web/src/index.tsindex c15da114a..3493717f1 100644--- a/packages/sdks/web/src/index.ts+++ b/packages/sdks/web/src/index.ts@@ -124,6 +124,7 @@ export class OpenPanel extends OpenPanelBase {type: 'replay',payload: {...chunk,+ sessionId: this.sessionId,},});});diff --git a/packages/validation/src/track.validation.ts b/packages/validation/src/track.validation.tsindex eae1f055e..24fd95771 100644--- a/packages/validation/src/track.validation.ts+++ b/packages/validation/src/track.validation.ts@@ -67,6 +67,9 @@ export interface IReplayPayload {started_at: string;ended_at: string;payload: string;+ // Server-issued session id (from a prior /track response) the SDK echoes back,+ // so the chunk is filed under the right session without device resolution.+ sessionId?: string;}export type ITrackHandlerPayload =@@ -167,6 +170,7 @@ export const zReplayPayload = z.object({started_at: z.string().datetime(),ended_at: z.string().datetime(),payload: z.string().max(1_048_576 * 2), // 2MB max+ sessionId: z.string().max(64).optional(),}) satisfies z.ZodType<IReplayPayload>;export const zTrackHandlerPayload = z.discriminatedUnion('type', [