Skip to content

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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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', [