Skip to content

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

18.2 KB
Raw Blame
/**
 * 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);
}