Skip to content

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

10.6 KB
Raw Blame
// The event buffer and the ClickHouse client are HANDED IN
// (`deps.buffers.event`, `deps.ch`) rather than mocked onto a module
// specifier.
//
// The subject and the real-module snapshot are STATIC imports. Bun's
// `mock.module` still applies because it swaps an already-loaded module's
// exports in place, so a consumer that imported before the mock call still
// sees it — the subscribe assertions go red if it ever stops.
//
// Scope: the /live websocket glue plus one representative ClickHouse query
// (`getRealtimeActiveSessions`) proving the deps + filter/limit wiring. The
// other five queries are exercised end-to-end by realtime.rpc.test.ts's
// unauthenticated-boundary tests and this repo's local ClickHouse run.

import { afterAll, beforeEach, expect, mock, test } from 'bun:test';
import * as actualRedis from '@openpanel/redis';
import * as subject from './realtime.service';

const activeVisitorCountByProject = new Map<string, number>();
const eventBuffer = {
  getActiveVisitorCount: mock(
    async (projectId: string) => activeVisitorCountByProject.get(projectId) ?? 0
  ),
};

const subscribeToPublishedEvent = mock(
  (_channel: string, _type: string, _cb: (event: unknown) => void) => {
    return () => {
      unsubscribeCalls++;
    };
  }
);
let unsubscribeCalls = 0;

// Spread the real module — a partial factory here would be a process-wide
// hazard for every other test file mocking `@openpanel/redis` narrowly (see
// `@openpanel/redis`'s import at the top of realtime.service.ts).
const realRedis = { ...actualRedis };
mock.module('@openpanel/redis', () => ({
  ...realRedis,
  subscribeToPublishedEvent,
}));

afterAll(() => {
  mock.module('@openpanel/redis', () => realRedis);
});

// `deps.ch.query` is what ch-query.ts calls; it returns the raw
// ClickHouse response envelope, so the stub speaks that shape.
let nextRows: unknown[] = [];
const chQuery = mock(
  async (_args: {
    query: string;
    query_params: Record<string, string | number>;
  }) => ({
    json: async () => ({ data: nextRows, meta: [], rows: nextRows.length }),
  })
);

const MINUTES_PER_REALTIME_WINDOW = 30;
const MS_PER_MINUTE = 60_000;
const REALTIME_WINDOW_MS = MINUTES_PER_REALTIME_WINDOW * MS_PER_MINUTE;
const CLOCK_TOLERANCE_MS = 5000;
const ACTIVE_SESSIONS_LIMIT = 50;
const RECENT_SESSIONS_LIMIT = 30;

const noop = () => undefined;
const deps = {
  ch: { query: chQuery },
  buffers: { event: eventBuffer },
  logger: {
    fatal: noop,
    error: noop,
    warn: noop,
    info: noop,
    debug: noop,
    trace: noop,
    child: () => deps.logger,
  },
} as unknown as import('../../services').ServiceDeps;

beforeEach(() => {
  activeVisitorCountByProject.clear();
  subscribeToPublishedEvent.mockClear();
  chQuery.mockClear();
  nextRows = [];
  unsubscribeCalls = 0;
});

test('getActiveVisitorCount reads through the event buffer, keyed by project', async () => {
  activeVisitorCountByProject.set('proj_1', 7);

  await expect(subject.getActiveVisitorCount(deps, 'proj_1')).resolves.toBe(7);
  expect(eventBuffer.getActiveVisitorCount).toHaveBeenCalledWith('proj_1');
});

test('subscribeToVisitorActivity subscribes on events:batch and filters by projectId', async () => {
  const onActivity = mock(() => undefined);
  const unsubscribe = await subject.subscribeToVisitorActivity(
    'proj_1',
    onActivity
  );

  expect(subscribeToPublishedEvent).toHaveBeenCalledTimes(1);
  const [channel, type, callback] = subscribeToPublishedEvent.mock.calls[0]!;
  expect(channel).toBe('events');
  expect(type).toBe('batch');

  (callback as (event: unknown) => void)({ projectId: 'proj_other', count: 1 });
  expect(onActivity).not.toHaveBeenCalled();

  (callback as (event: unknown) => void)({ projectId: 'proj_1', count: 1 });
  expect(onActivity).toHaveBeenCalledTimes(1);

  unsubscribe();
  expect(unsubscribeCalls).toBe(1);
});

test('subscribeToProjectEventBatches hands the whole batch through, filtered by projectId', async () => {
  const onBatch = mock((_event: unknown) => undefined);
  await subject.subscribeToProjectEventBatches('proj_1', onBatch);

  const callback = subscribeToPublishedEvent.mock.calls[0]![2] as (
    event: unknown
  ) => void;

  callback({ projectId: 'proj_1', count: 3 });
  expect(onBatch).toHaveBeenCalledWith({ projectId: 'proj_1', count: 3 });
});

test('subscribeToProjectNotifications subscribes on notification:created and filters by projectId', async () => {
  const onNotification = mock((_notification: unknown) => undefined);
  await subject.subscribeToProjectNotifications('proj_1', onNotification);

  const [channel, type, callback] = subscribeToPublishedEvent.mock.calls[0]!;
  expect(channel).toBe('notification');
  expect(type).toBe('created');

  (callback as (event: unknown) => void)({
    projectId: 'proj_other',
    title: 't',
  });
  expect(onNotification).not.toHaveBeenCalled();

  (callback as (event: unknown) => void)({ projectId: 'proj_1', title: 't' });
  expect(onNotification).toHaveBeenCalledTimes(1);
});

// The `organization:subscription_updated` channel is instance-wide.
// Unfiltered, a subscriber saw the `organizationId` of every organization whose
// subscription changed — including ones it is not a member of. This test is red
// without the filter.
test('subscribeToOrganizationSubscriptionUpdates subscribes on organization:subscription_updated and filters by organizationId', async () => {
  const onUpdate = mock((_message: unknown) => undefined);
  await subject.subscribeToOrganizationSubscriptionUpdates('org_1', onUpdate);

  const [channel, type, callback] = subscribeToPublishedEvent.mock.calls[0]!;
  expect(channel).toBe('organization');
  expect(type).toBe('subscription_updated');

  (callback as (event: unknown) => void)({ organizationId: 'org_other' });
  expect(onUpdate).not.toHaveBeenCalled();

  (callback as (event: unknown) => void)({ organizationId: 'org_1' });
  expect(onUpdate).toHaveBeenCalledTimes(1);
  expect(onUpdate).toHaveBeenCalledWith({ organizationId: 'org_1' });
});

test('getRealtimeActiveSessions scopes the query to the project and the 30-minute window', async () => {
  nextRows = [
    {
      name: 'screen_view',
      session_id: 'sess_1',
      created_at: '2026-09-04 00:00:00',
      path: '/',
      origin: 'https://example.com',
      referrer: '',
      referrer_name: '',
      country: 'SE',
      city: 'Stockholm',
      region: '',
      os: 'macOS',
      os_version: '',
      browser: 'Chrome',
      browser_version: '',
      device: 'desktop',
    },
  ];

  const result = await subject.getRealtimeActiveSessions(deps, 'proj_1');

  expect(chQuery).toHaveBeenCalledTimes(1);
  // The statement binds its values, so the project scoping and the window live
  // in `query_params` — the assertion follows them there.
  const { query, query_params } = chQuery.mock.calls[0]![0];
  expect(query).toContain('project_id = {p1:String}');
  expect(query).toContain('created_at >= {p2:String}');
  expect(query).toContain('LIMIT {p3:UInt64}');
  expect(query_params.p1).toBe('proj_1');
  const windowStart = String(query_params.p2).replace(' ', 'T');
  const windowAgeMs = Date.now() - Date.parse(`${windowStart}Z`);
  expect(windowAgeMs).toBeGreaterThanOrEqual(REALTIME_WINDOW_MS);
  expect(windowAgeMs).toBeLessThan(REALTIME_WINDOW_MS + CLOCK_TOLERANCE_MS);
  expect(query_params.p3).toBe(ACTIVE_SESSIONS_LIMIT);
  expect(result).toHaveLength(1);
  expect(result[0]?.sessionId).toBe('sess_1');
});

test('getRealtimeRecentSessions only reads session starts in the project and window', async () => {
  nextRows = [
    {
      name: 'session_start',
      session_id: 'sess_2',
      profile_id: 'prof_2',
      created_at: '2026-09-04 00:00:00',
      path: '/pricing',
      origin: 'https://example.com',
      referrer: '',
      referrer_name: 'Google',
      country: 'SE',
      city: 'Stockholm',
      region: '',
      os: 'macOS',
      os_version: '',
      browser: 'Chrome',
      browser_version: '',
      device: 'desktop',
    },
  ];

  const result = await subject.getRealtimeRecentSessions(deps, 'proj_1');

  expect(chQuery).toHaveBeenCalledTimes(1);
  const { query, query_params } = chQuery.mock.calls[0]![0];
  expect(query).toContain('project_id = {p1:String}');
  expect(query).toContain('name = {p2:String}');
  expect(query).toContain('created_at >= {p3:String}');
  expect(query).toContain('LIMIT {p4:UInt64}');
  expect(query_params.p1).toBe('proj_1');
  expect(query_params.p2).toBe('session_start');
  expect(query_params.p4).toBe(RECENT_SESSIONS_LIMIT);
  expect(result).toHaveLength(1);
  expect(result[0]?.sessionId).toBe('sess_2');
  expect(result[0]?.referrerName).toBe('Google');
});

test('getRealtimeTopSources splits one grouping-sets scan into referrers and countries', async () => {
  nextRows = [
    {
      referrer_name: 'Google',
      country: '',
      sessions: 12,
      is_referrer_row: 1,
      is_country_row: 0,
    },
    {
      referrer_name: '',
      country: 'SE',
      sessions: 9,
      is_referrer_row: 0,
      is_country_row: 1,
    },
    {
      referrer_name: 'Reddit',
      country: '',
      sessions: 3,
      is_referrer_row: 1,
      is_country_row: 0,
    },
  ];

  const result = await subject.getRealtimeTopSources(deps, 'proj_1');

  expect(chQuery).toHaveBeenCalledTimes(1);
  const { query, query_params } = chQuery.mock.calls[0]![0];
  expect(query).toContain('GROUPING SETS ((referrer_name), (country))');
  expect(query).toContain('project_id = {p1:String}');
  expect(query_params.p1).toBe('proj_1');
  expect(result).toEqual({
    referrers: [
      { name: 'Google', sessions: 12 },
      { name: 'Reddit', sessions: 3 },
    ],
    countries: [{ country: 'SE', sessions: 9 }],
  });
});

test('getRealtimeHistogram fills every minute of the window and takes the total from the same scan', async () => {
  const minuteAgo = new Date(Math.floor(Date.now() / 60_000) * 60_000 - 60_000);
  const minuteKey = minuteAgo.toISOString().slice(0, 19).replace('T', ' ');
  nextRows = [
    { minute: '1970-01-01 00:00:00', sessions: 40, visitors: 15, is_total: 1 },
    { minute: minuteKey, sessions: 4, visitors: 2, is_total: 0 },
  ];

  const result = await subject.getRealtimeHistogram(deps, 'proj_1');

  expect(chQuery).toHaveBeenCalledTimes(1);
  expect(chQuery.mock.calls[0]![0].query).toContain(
    'GROUPING SETS ((minute), ())'
  );
  expect(result.totalSessions).toBe(40);
  expect(result.minutes).toHaveLength(MINUTES_PER_REALTIME_WINDOW + 1);
  const filled = result.minutes.find(
    (entry) => entry.minute === minuteAgo.toISOString()
  );
  expect(filled).toEqual({
    minute: minuteAgo.toISOString(),
    sessions: 4,
    visitors: 2,
  });
  expect(result.minutes.filter((entry) => entry.sessions === 0)).toHaveLength(
    MINUTES_PER_REALTIME_WINDOW
  );
});