Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

fix: multiple session start events

Carl-Gerhard Lindesvärd06aae98983cc
diff --git a/apps/api/src/controllers/track.controller.ts b/apps/api/src/controllers/track.controller.ts
index 5066ba85e..2621e28a7 100644
--- a/apps/api/src/controllers/track.controller.ts
+++ b/apps/api/src/controllers/track.controller.ts
@@ -119,7 +119,6 @@ interface TrackContext {
identity?: IIdentifyPayload;
deviceId: string;
sessionId: string;
- session?: EventsQueuePayloadIncomingEvent['payload']['session'];
geo: GeoLocation;
}
@@ -178,7 +177,6 @@ async function buildContext(
identity,
deviceId: deviceIdResult.deviceId,
sessionId: deviceIdResult.sessionId,
- session: deviceIdResult.session,
geo,
};
}
@@ -187,8 +185,7 @@ async function handleTrack(
payload: ITrackPayload,
context: TrackContext
): Promise<void> {
- const { projectId, deviceId, geo, headers, timestamp, sessionId, session } =
- context;
+ const { projectId, deviceId, geo, headers, timestamp, sessionId } = context;
const uaInfo = parseUserAgent(headers['user-agent'], payload.properties);
const groupId = uaInfo.isServer
@@ -217,7 +214,6 @@ async function handleTrack(
geo,
deviceId,
sessionId,
- session,
};
const partitionKey = groupId || generateId();
diff --git a/apps/api/src/utils/ids.ts b/apps/api/src/utils/ids.ts
index f2bd9a453..3614da1b7 100644
--- a/apps/api/src/utils/ids.ts
+++ b/apps/api/src/utils/ids.ts
@@ -1,12 +1,8 @@
import crypto from 'node:crypto';
import { generateDeviceId } from '@openpanel/common/server';
import { getSafeJson } from '@openpanel/json';
-import type {
- EventsQueuePayloadCreateSessionEnd,
- EventsQueuePayloadIncomingEvent,
-} from '@openpanel/queue';
+import type { EventsQueuePayloadCreateSessionEnd } from '@openpanel/queue';
import { getRedisCache } from '@openpanel/redis';
-import { pick } from 'ramda';
export async function getDeviceId({
projectId,
@@ -52,7 +48,6 @@ export async function getDeviceId({
interface DeviceIdResult {
deviceId: string;
sessionId: string;
- session?: EventsQueuePayloadIncomingEvent['payload']['session'];
}
async function getInfoFromSession({
@@ -83,10 +78,6 @@ async function getInfoFromSession({
return {
deviceId: currentDeviceId,
sessionId: data.payload.sessionId,
- session: pick(
- ['referrer', 'referrerName', 'referrerType'],
- data.payload
- ),
};
}
}
@@ -98,10 +89,6 @@ async function getInfoFromSession({
return {
deviceId: previousDeviceId,
sessionId: data.payload.sessionId,
- session: pick(
- ['referrer', 'referrerName', 'referrerType'],
- data.payload
- ),
};
}
}
diff --git a/apps/worker/src/jobs/events.incoming-event.ts b/apps/worker/src/jobs/events.incoming-event.ts
index b34e8194c..5035e3186 100644
--- a/apps/worker/src/jobs/events.incoming-event.ts
+++ b/apps/worker/src/jobs/events.incoming-event.ts
@@ -15,6 +15,7 @@ import { logger as baseLogger } from '@/utils/logger';
import {
createSessionEndJob,
extendSessionEndJob,
+ getActiveSessionEndJob,
} from '@/utils/session-handler';
const GLOBAL_PROPERTIES = ['__path', '__referrer', '__timestamp', '__revenue'];
@@ -92,7 +93,6 @@ export async function incomingEvent(
deviceId,
sessionId,
uaInfo,
- session,
} = jobPayload;
const properties = body.properties ?? {};
const reqId = headers['request-id'] ?? 'unknown';
@@ -198,10 +198,16 @@ export async function incomingEvent(
return createEventAndNotify(payload as IServiceEvent, logger, projectId);
}
+ const activeSessionEndJob = await getActiveSessionEndJob(
+ projectId,
+ deviceId,
+ );
+ const activeSessionPayload = activeSessionEndJob?.data.payload;
+
const payload: IServiceCreateEventPayload = merge(baseEvent, {
- referrer: session?.referrer ?? baseEvent.referrer,
- referrerName: session?.referrerName ?? baseEvent.referrerName,
- referrerType: session?.referrerType ?? baseEvent.referrerType,
+ referrer: activeSessionPayload?.referrer ?? baseEvent.referrer,
+ referrerName: activeSessionPayload?.referrerName ?? baseEvent.referrerName,
+ referrerType: activeSessionPayload?.referrerType ?? baseEvent.referrerType,
} as Partial<IServiceCreateEventPayload>) as IServiceCreateEventPayload;
const isExcluded = await isEventExcludedByProjectFilter(payload, projectId);
@@ -213,10 +219,11 @@ export async function incomingEvent(
return null;
}
- if (session) {
+ if (activeSessionEndJob) {
await extendSessionEndJob({
projectId,
deviceId,
+ job: activeSessionEndJob,
}).catch((error) => {
logger.warn({ err: error }, 'Failed to extend session end job');
});
diff --git a/apps/worker/src/jobs/events.incoming-events.test.ts b/apps/worker/src/jobs/events.incoming-events.test.ts
index 870867a54..30547d7dc 100644
--- a/apps/worker/src/jobs/events.incoming-events.test.ts
+++ b/apps/worker/src/jobs/events.incoming-events.test.ts
@@ -187,11 +187,6 @@ describe('incomingEvent', () => {
projectId,
deviceId,
sessionId: 'session-123',
- session: {
- referrer: '',
- referrerName: '',
- referrerType: '',
- },
};
const changeDelay = vi.fn();
@@ -420,4 +415,74 @@ describe('incomingEvent', () => {
expect(sessionsQueue.add).not.toHaveBeenCalled();
});
+
+ it('should emit session_start only once when 3 events arrive in rapid succession', async () => {
+ // Regression test: previously the API baked `session: undefined` into every
+ // payload when no session-end job existed yet. Even with sequential
+ // per-device processing in the worker, the worker re-checks the BullMQ
+ // session-end job at processing time, so events 2 and 3 should extend
+ // rather than emit duplicate session_starts.
+ const spySessionsQueueAdd = vi
+ .spyOn(sessionsQueue, 'add')
+ .mockResolvedValue({} as Job);
+ const spySessionsQueueGetJob = vi.spyOn(sessionsQueue, 'getJob');
+
+ const buildJobData = (
+ eventName: string,
+ ): EventsQueuePayloadIncomingEvent['payload'] => ({
+ geo,
+ event: {
+ name: eventName,
+ timestamp: new Date().toISOString(),
+ isTimestampFromThePast: false,
+ properties: { __path: 'https://example.com/test' },
+ },
+ uaInfo,
+ headers: {
+ 'request-id': '123',
+ 'user-agent':
+ 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+ 'openpanel-sdk-name': 'web',
+ 'openpanel-sdk-version': '1.0.0',
+ },
+ projectId,
+ deviceId,
+ sessionId: newSessionId,
+ });
+
+ // Event 1: no session-end job exists yet → emit session_start.
+ spySessionsQueueGetJob.mockResolvedValueOnce(undefined);
+ // Events 2 and 3: session-end job is now present (delayed) → extend only.
+ const liveJob = {
+ id: `sessionEnd:${projectId}:${deviceId}`,
+ getState: vi.fn().mockResolvedValue('delayed'),
+ changeDelay: vi.fn(),
+ data: {
+ type: 'createSessionEnd',
+ payload: {
+ sessionId: newSessionId,
+ deviceId,
+ referrer: '',
+ referrerName: '',
+ referrerType: '',
+ },
+ },
+ } as Partial<Job> as Job;
+ spySessionsQueueGetJob.mockResolvedValue(liveJob);
+
+ (createEvent as Mock).mockImplementation((event) => event);
+
+ await incomingEvent(buildJobData('event_a'));
+ await incomingEvent(buildJobData('event_b'));
+ await incomingEvent(buildJobData('event_c'));
+
+ const sessionStartCalls = (createEvent as Mock).mock.calls.filter(
+ ([arg]) => arg?.name === 'session_start',
+ );
+ expect(sessionStartCalls).toHaveLength(1);
+
+ // Only the first event should have queued a session-end job; subsequent
+ // events extend the existing one via changeDelay.
+ expect(spySessionsQueueAdd).toHaveBeenCalledTimes(1);
+ });
});
diff --git a/apps/worker/src/utils/session-handler.ts b/apps/worker/src/utils/session-handler.ts
index 3c7220046..0ca4c11ed 100644
--- a/apps/worker/src/utils/session-handler.ts
+++ b/apps/worker/src/utils/session-handler.ts
@@ -1,6 +1,10 @@
import type { IServiceCreateEventPayload } from '@openpanel/db';
-import { sessionsQueue } from '@openpanel/queue';
+import {
+ type EventsQueuePayloadCreateSessionEnd,
+ sessionsQueue,
+} from '@openpanel/queue';
import { LRUCache } from '@openpanel/redis';
+import type { Job } from 'bullmq';
import { logger as baseLogger } from '@/utils/logger';
export const SESSION_TIMEOUT = 1000 * 60 * 30;
@@ -14,12 +18,27 @@ const CHANGE_DELAY_THROTTLE_MAP = new LRUCache<string, number>({
ttl: SESSION_TIMEOUT,
});
+export type SessionEndJob = Job<EventsQueuePayloadCreateSessionEnd>;
+
+// Treats any existing session-end job as "session in progress" regardless of
+// state — avoids duplicate session_starts when the close job is mid-flight.
+export async function getActiveSessionEndJob(
+ projectId: string,
+ deviceId: string,
+): Promise<SessionEndJob | null> {
+ const jobId = getSessionEndJobId(projectId, deviceId);
+ const job = await sessionsQueue.getJob(jobId);
+ return (job as SessionEndJob | undefined) ?? null;
+}
+
export async function extendSessionEndJob({
projectId,
deviceId,
+ job,
}: {
projectId: string;
deviceId: string;
+ job?: SessionEndJob | null;
}) {
const last = CHANGE_DELAY_THROTTLE_MAP.get(`${projectId}:${deviceId}`) ?? 0;
const isThrottled = Date.now() - last < CHANGE_DELAY_THROTTLE_MS;
@@ -28,17 +47,17 @@ export async function extendSessionEndJob({
return;
}
- const jobId = getSessionEndJobId(projectId, deviceId);
- const job = await sessionsQueue.getJob(jobId);
+ const resolvedJob =
+ job ?? (await getActiveSessionEndJob(projectId, deviceId));
- if (!job) {
+ if (!resolvedJob) {
return;
}
- const state = await job.getState();
+ const state = await resolvedJob.getState();
if (state !== 'delayed') {
baseLogger.warn(
- { jobId, state },
+ { jobId: resolvedJob.id, state },
'Session end job is not in delayed state, skipping extend',
);
return;
@@ -47,11 +66,11 @@ export async function extendSessionEndJob({
// Narrow TOCTOU window: state could flip from delayed → waiting between
// the getState() check above and this call.
try {
- await job.changeDelay(SESSION_TIMEOUT);
+ await resolvedJob.changeDelay(SESSION_TIMEOUT);
CHANGE_DELAY_THROTTLE_MAP.set(`${projectId}:${deviceId}`, Date.now());
} catch (error) {
baseLogger.warn(
- { err: error, jobId },
+ { err: error, jobId: resolvedJob.id },
'Session end job moved out of delayed state during extend',
);
}
diff --git a/packages/queue/src/queues.ts b/packages/queue/src/queues.ts
index 94d6577fa..bb7b8cb45 100644
--- a/packages/queue/src/queues.ts
+++ b/packages/queue/src/queues.ts
@@ -66,10 +66,6 @@ export interface EventsQueuePayloadIncomingEvent {
headers: Record<string, string | undefined>;
deviceId: string;
sessionId: string;
- session?: Pick<
- IServiceCreateEventPayload,
- 'referrer' | 'referrerName' | 'referrerType'
- >;
};
}
export interface EventsQueuePayloadCreateEvent {