OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
/**
* Shared building blocks for the session E2E + stress harnesses:
* config, an HTTP track client, the reaper trigger, Redis/ClickHouse helpers,
* fixtures, polling, and a tiny check/report framework.
*/
import { getClientByIdCached, hashPassword } from '@openpanel/core';
import { ClientType, chQuery, db } from '@openpanel/db';
import { getRedisCache } from '@openpanel/redis';
// ── Config ──────────────────────────────────────────────────────────────────
export const API_URL = process.env.E2E_API_URL || 'http://localhost:3333';
export const WORKER_URL = process.env.E2E_WORKER_URL || 'http://localhost:9999';
export const ORG_ID = 'openpanel-dev';
export const PROJECT_ID = 'e2e-sessions';
/** The `ignoreCorsAndSecret` client — auth path (a), a diagnostic baseline. */
export const CLIENT_ID = 'e2e1e2e1-0000-4000-8000-000000000001';
/** The client that carries a real scrypt secret — auth paths (b) and (c). */
export const SECRET_CLIENT_ID = 'e2e1e2e1-0000-4000-8000-000000000002';
/**
* The plaintext presented as `openpanel-client-secret`. Stored on the fixture
* client as `salt.hashKey` (scrypt, keyLength 32). Local fixture only — the
* hash is regenerated by `ensureFixtures()` on every run.
*/
export const CLIENT_SECRET = 'e2e-saturation-secret';
/** Project CORS allow-list entry backing auth path (b). */
export const CORS_DOMAIN = 'e2e.test';
export const CORS_ORIGIN = `https://${CORS_DOMAIN}`;
export const UA =
'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36';
// ── Auth paths ──────────────────────────────────────────────────────────────
/**
* The three ways a request can clear `validateIngestRequest`, in the order
* that function checks them (packages/core/src/modules/ingest/src/client-auth.ts):
*
* - `bypass` — `client.ignoreCorsAndSecret` returns immediately, before any
* I/O. NO REAL TRAFFIC TAKES THIS PATH. Diagnostic baseline only.
* - `cors` — an allowed origin returns immediately after a regex. This is
* what browser / web-SDK traffic does.
* - `secret` — a presented `openpanel-client-secret` goes through
* `getCache(...)` around a scrypt `verifyPassword`. This is what
* server-side SDK traffic does, and it is the pessimistic path.
*
* Every number a harness prints must be labelled with the mode it ran under.
*/
export type AuthMode = 'bypass' | 'cors' | 'secret';
const AUTH_MODES: readonly AuthMode[] = ['bypass', 'cors', 'secret'];
export const AUTH_PATH_DESCRIPTION: Record<AuthMode, string> = {
bypass:
'(a) ignoreCorsAndSecret — immediate return, no I/O, not real traffic',
cors: '(b) allowed CORS origin — immediate return after a regex (browser/web SDK)',
secret:
'(c) presented client secret — cached scrypt verify (server-side SDK)',
};
function parseAuthMode(raw: string | undefined): AuthMode {
if (!raw) {
return 'bypass';
}
const found = AUTH_MODES.find((mode) => mode === raw);
if (!found) {
throw new Error(
`E2E_AUTH_MODE must be one of ${AUTH_MODES.join('|')}, got "${raw}"`
);
}
return found;
}
/** Default `bypass` so the pre-existing suites keep the path they were written against. */
export const AUTH_MODE: AuthMode = parseAuthMode(process.env.E2E_AUTH_MODE);
export function authHeaders(
mode: AuthMode = AUTH_MODE
): Record<string, string> {
if (mode === 'bypass') {
return { 'openpanel-client-id': CLIENT_ID };
}
if (mode === 'cors') {
return { 'openpanel-client-id': SECRET_CLIENT_ID, origin: CORS_ORIGIN };
}
return {
'openpanel-client-id': SECRET_CLIENT_ID,
'openpanel-client-secret': CLIENT_SECRET,
};
}
/**
* The Redis key `client-auth.ts` caches the scrypt verdict under for
* `secret`-mode requests: client id + base64 of the PRESENTED plaintext.
* Deleting it evicts L2 only — `getCache` is called with `useLruCache`, so the
* API process also holds an in-process L1 copy this harness cannot reach.
*/
export const authVerifyCacheKey = (secret: string = CLIENT_SECRET) =>
`client:auth:${SECRET_CLIENT_ID}:${Buffer.from(secret).toString('base64')}`;
export const SESSION_TIMEOUT_MS = Number.parseInt(
process.env.SESSION_TIMEOUT_MS || String(1000 * 60 * 30),
10
);
/** How long to wait for a session to fall outside its idle window before closing. */
export const IDLE_WAIT_MS = SESSION_TIMEOUT_MS + 2000;
export const redis = getRedisCache();
export const runId = Date.now();
export { chQuery };
// ── Redis key helpers ───────────────────────────────────────────────────────
export const sessionKey = (deviceId: string) =>
`session:${PROJECT_ID}:${deviceId}`;
export const wallclockKey = `session:wallclock:${PROJECT_ID}`;
export const profileKey = (profileId: string) =>
`session:profile:${PROJECT_ID}:${profileId}`;
export const claimKey = (deviceId: string, sessionId: string) =>
`session:end:emitted:${PROJECT_ID}:${deviceId}:${sessionId}`;
/** The session-buffer's Redis list (ground-truth pending CH rows). */
export const SESSION_BUFFER_LIST = 'session-buffer';
export async function getBlob(deviceId: string) {
const raw = await redis.get(sessionKey(deviceId));
return raw ? JSON.parse(raw) : null;
}
// ── Timing ──────────────────────────────────────────────────────────────────
export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
/** Poll `fn` until it returns a truthy value or the timeout elapses. */
export async function pollUntil<T>(
fn: () => Promise<T>,
{ timeoutMs = 30_000, intervalMs = 750 } = {}
): Promise<T | null> {
const deadline = Date.now() + timeoutMs;
while (true) {
const value = await fn();
if (value) {
return value;
}
if (Date.now() >= deadline) {
return null;
}
await sleep(intervalMs);
}
}
// ── Report framework ──────────────────────────────────────────────────────
type Result = { scenario: string; name: string; ok: boolean; detail?: string };
const results: Result[] = [];
let currentScenario = 'setup';
export function scenario(name: string) {
currentScenario = name;
console.log(`\n▶ ${name}`);
}
export function check(name: string, ok: boolean, detail?: string) {
results.push({ scenario: currentScenario, name, ok, detail });
console.log(
` ${ok ? '✓' : '✗'} ${name}${detail && !ok ? ` — ${detail}` : ''}`
);
}
/** Print the summary and return the number of failed checks. */
export function summarize(): number {
const failed = results.filter((r) => !r.ok);
console.log(`\n${'─'.repeat(60)}`);
console.log(
`${results.length - failed.length}/${results.length} checks passed`
);
if (failed.length) {
console.log('\nFailures:');
for (const f of failed) {
console.log(
` ✗ [${f.scenario}] ${f.name}${f.detail ? ` — ${f.detail}` : ''}`
);
}
}
return failed.length;
}
/** Total checks recorded so far, independent of summarize()'s printing. */
export function checkCount(): number {
return results.length;
}
// ── HTTP ────────────────────────────────────────────────────────────────────
export type TrackResponse = { deviceId: string; sessionId: string };
// Set by beginLatencyRecording()/endLatencyRecording() around the phase whose
// per-request latency matters (the emit phase) — track() pushes into it
// whenever it's non-null, everywhere else stays a no-op.
let latencySink: number[] | null = null;
/** Start recording every subsequent track() round-trip's latency, in ms. */
export function beginLatencyRecording(): number[] {
const samples: number[] = [];
latencySink = samples;
return samples;
}
export function endLatencyRecording() {
latencySink = null;
}
export async function track(body: unknown, ip: string): Promise<TrackResponse> {
const startedAt = performance.now();
try {
const res = await fetch(`${API_URL}/track`, {
method: 'POST',
headers: {
'content-type': 'application/json',
...authHeaders(),
'user-agent': UA,
'x-client-ip': ip,
},
body: JSON.stringify(body),
});
if (!res.ok) {
throw new Error(`POST /track ${res.status}: ${await res.text()}`);
}
return (await res.json()) as TrackResponse;
} finally {
latencySink?.push(performance.now() - startedAt);
}
}
// ── Latency percentiles ─────────────────────────────────────────────────────
export interface LatencyStats {
count: number;
p50: number;
p95: number;
p99: number;
mean: number;
}
function percentile(sorted: number[], p: number): number {
if (sorted.length === 0) {
return 0;
}
const rank = (p / 100) * (sorted.length - 1);
const lo = Math.floor(rank);
const hi = Math.ceil(rank);
if (lo === hi) {
return sorted[lo] ?? 0;
}
const weight = rank - lo;
return (sorted[lo] ?? 0) * (1 - weight) + (sorted[hi] ?? 0) * weight;
}
export function summarizeLatencies(samplesMs: number[]): LatencyStats {
if (samplesMs.length === 0) {
return { count: 0, p50: 0, p95: 0, p99: 0, mean: 0 };
}
const sorted = [...samplesMs].sort((a, b) => a - b);
return {
count: sorted.length,
p50: percentile(sorted, 50),
p95: percentile(sorted, 95),
p99: percentile(sorted, 99),
mean: sorted.reduce((a, b) => a + b, 0) / sorted.length,
};
}
export function formatLatencyStats(s: LatencyStats): string {
return (
`latency (${s.count} requests): ` +
`P50=${s.p50.toFixed(1)}ms P95=${s.p95.toFixed(1)}ms P99=${s.p99.toFixed(1)}ms mean=${s.mean.toFixed(1)}ms`
);
}
export const screenView = (
ip: string,
path: string,
extra: Record<string, unknown> = {}
) =>
track(
{
type: 'track',
payload: {
name: 'screen_view',
properties: { __path: `https://e2e.test${path}`, __ip: ip, ...extra },
},
},
ip
);
// ── Auth-cache warming and the scrypt outlier ───────────────────────────────
/**
* Why warming matters: `client-auth.ts` shields `verifyPassword` behind
* `VERIFY_CACHE_SECONDS = 300`, so a scrypt is a LATENCY OUTLIER, not a
* per-request cost. A rung shorter than the TTL pays it once, at whatever
* moment it happens to fall. Paying it before recording starts is what stops
* a knee from being an artefact of a scrypt spike landing mid-rung.
*/
export const AUTH_WARM_REQUESTS = Number.parseInt(
process.env.E2E_AUTH_WARM_REQUESTS || '3',
10
);
/** Warm/probe traffic lives outside the 100.x space the session ids use. */
const WARM_IP = '203.0.113.7';
const PROBE_IP = '203.0.113.8';
export interface AuthWarmResult {
mode: AuthMode;
requests: number;
latenciesMs: number[];
maxMs: number | null;
}
/** One raw /track round-trip that reports its status instead of throwing. */
async function timedTrack(
headers: Record<string, string>,
ip: string
): Promise<{ status: number; ms: number }> {
const startedAt = performance.now();
const res = await fetch(`${API_URL}/track`, {
method: 'POST',
headers: {
'content-type': 'application/json',
...headers,
'user-agent': UA,
'x-client-ip': ip,
},
body: JSON.stringify({
type: 'track',
payload: {
name: 'screen_view',
properties: { __path: 'https://e2e.test/warm', __ip: ip },
},
}),
});
await res.text();
return { status: res.status, ms: performance.now() - startedAt };
}
/**
* Send and DISCARD `requests` authenticated requests so the auth verdict is
* resident before the measured phase starts. Latencies are returned so the
* caller can show where the scrypt landed.
*/
export async function warmAuthCache(
mode: AuthMode = AUTH_MODE,
requests: number = AUTH_WARM_REQUESTS
): Promise<AuthWarmResult> {
const latenciesMs: number[] = [];
const headers = authHeaders(mode);
for (let i = 0; i < requests; i++) {
const { status, ms } = await timedTrack(headers, WARM_IP);
if (status < 200 || status >= 300) {
throw new Error(
`auth warm-up rejected (${status}) in mode "${mode}" — the fixture for this auth path is wrong, not the load`
);
}
latenciesMs.push(ms);
}
return {
mode,
requests,
latenciesMs,
maxMs: latenciesMs.length ? Math.max(...latenciesMs) : null,
};
}
export interface AuthCostProbe {
coldMs: number;
coldStatus: number;
warmMs: number;
warmStatus: number;
scryptMs: number;
}
/**
* Measure what the TTL is hiding: one request whose secret has never been seen
* (guaranteed L1+L2 miss, so a real scrypt runs and is then refused) against
* one on the warmed real secret. The delta is the outlier a mid-rung cache
* expiry would inject.
*/
export async function probeAuthCost(): Promise<AuthCostProbe> {
const neverSeenSecret = `e2e-cold-${Date.now()}-${Math.random().toString(36).slice(2)}`;
const cold = await timedTrack(
{
'openpanel-client-id': SECRET_CLIENT_ID,
'openpanel-client-secret': neverSeenSecret,
},
PROBE_IP
);
const warm = await timedTrack(authHeaders('secret'), PROBE_IP);
return {
coldMs: cold.ms,
coldStatus: cold.status,
warmMs: warm.ms,
warmStatus: warm.status,
scryptMs: cold.ms - warm.ms,
};
}
/** Run a worker cron on demand via the local /debug/cron endpoint. */
export async function triggerCron(type: string) {
const res = await fetch(`${WORKER_URL}/debug/cron/${type}`, {
method: 'POST',
headers: { accept: 'application/json' },
});
if (!res.ok) {
throw new Error(`trigger cron ${type} ${res.status}: ${await res.text()}`);
}
}
export const triggerReaper = () => triggerCron('sessionReaper');
// ── ClickHouse counting (scoped to a set of session ids for run isolation) ──
const quoteList = (ids: string[]) =>
ids.map((id) => `'${id.replace(/'/g, '')}'`).join(',');
export async function countByName(
sessionIds: string[],
name: string
): Promise<number> {
if (sessionIds.length === 0) {
return 0;
}
const rows = await chQuery<{ c: string }>(
`SELECT count() AS c FROM events WHERE project_id = '${PROJECT_ID}' AND name = '${name}' AND session_id IN (${quoteList(sessionIds)})`
);
return Number(rows[0]?.c ?? 0);
}
// ── Fixtures ────────────────────────────────────────────────────────────────
export async function ensureFixtures() {
scenario('setup: project + client');
try {
await db.organization.upsert({
where: { id: ORG_ID },
create: { id: ORG_ID, name: 'OpenPanel Dev' },
update: {},
});
await db.project.upsert({
where: { id: PROJECT_ID },
create: {
id: PROJECT_ID,
name: 'E2E Sessions',
organizationId: ORG_ID,
cors: [CORS_DOMAIN],
},
// The allow-list is what makes auth path (b) reachable; the bypass
// client returns before the CORS check, so this changes nothing for it.
update: { cors: [CORS_DOMAIN] },
});
await db.client.upsert({
where: { id: CLIENT_ID },
create: {
id: CLIENT_ID,
name: 'e2e',
organizationId: ORG_ID,
projectId: PROJECT_ID,
type: ClientType.write,
ignoreCorsAndSecret: true,
secret: null,
},
update: { ignoreCorsAndSecret: true, projectId: PROJECT_ID },
});
// `hashPassword` here is @openpanel/shared/server's scrypt hash, re-exported
// by @openpanel/core under its own name (core/src/index.ts) — reached that
// way because apps/api does not declare @openpanel/shared, and adding it
// would move the lockfile.
const secret = await hashPassword(CLIENT_SECRET);
await db.client.upsert({
where: { id: SECRET_CLIENT_ID },
create: {
id: SECRET_CLIENT_ID,
name: 'e2e-secret',
organizationId: ORG_ID,
projectId: PROJECT_ID,
type: ClientType.write,
ignoreCorsAndSecret: false,
secret,
},
update: {
ignoreCorsAndSecret: false,
projectId: PROJECT_ID,
secret,
},
});
await getClientByIdCached.clear({ db }, CLIENT_ID);
await getClientByIdCached.clear({ db }, SECRET_CLIENT_ID);
check('fixtures ready', true);
} catch (error) {
check('fixtures ready', false, (error as Error).message);
throw error;
}
}
export async function preflight() {
scenario('preflight');
const api = await fetch(`${API_URL}/`)
.then((r) => r.ok || r.status === 404)
.catch(() => false);
check(`api reachable at ${API_URL}`, !!api);
const worker = await fetch(`${WORKER_URL}/debug/cron`)
.then((r) => r.ok)
.catch(() => false);
check(`worker debug reachable at ${WORKER_URL}`, !!worker);
if (!(api && worker)) {
throw new Error('Stack not reachable — start it with `pnpm dev` first.');
}
if (SESSION_TIMEOUT_MS > 60_000) {
console.warn(
`\n⚠ SESSION_TIMEOUT_MS=${SESSION_TIMEOUT_MS}ms — this run will be slow.\n` +
' Re-run the stack AND the harness with e.g. SESSION_TIMEOUT_MS=4000.'
);
}
}
/** Run `fn` over `items` with at most `concurrency` in flight. */
export async function runPool<T>(
items: T[],
concurrency: number,
fn: (item: T, index: number) => Promise<void>
): Promise<void> {
let next = 0;
const workers = Array.from(
{ length: Math.min(concurrency, items.length) },
async () => {
while (true) {
const i = next++;
if (i >= items.length) {
return;
}
await fn(items[i]!, i);
}
}
);
await Promise.all(workers);
}
export async function shutdown(failed: number): Promise<never> {
await redis.quit().catch(() => {});
process.exit(failed ? 1 : 0);
}