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
import { describe, expect, it } from 'bun:test';
import {
  concurrencyEnvKey,
  concurrencyOverride,
  ENABLED_QUEUE_VALUES,
  loadConfig,
} from './env';

// `loadConfig` takes its source, so nothing here touches process.env.
const base = { ROLE: 'worker' } as NodeJS.ProcessEnv;

describe('ROLE', () => {
  it('defaults to api and accepts the three roles', () => {
    expect(loadConfig({}).ROLE).toBe('api');
    for (const role of ['api', 'worker', 'all'] as const) {
      expect(loadConfig({ ROLE: role }).ROLE).toBe(role);
    }
  });

  it('fails boot loudly on an unknown value, naming it', () => {
    expect(() => loadConfig({ ROLE: 'wroker' })).toThrow(
      /unknown value "wroker"/
    );
  });
});

describe('ENABLED_QUEUES', () => {
  it('is every known consumer when unset', () => {
    expect(loadConfig(base).ENABLED_QUEUES).toEqual([...ENABLED_QUEUE_VALUES]);
  });

  it('covers the Kafka token plus the seven registry queues', () => {
    expect(ENABLED_QUEUE_VALUES).toEqual([
      'events',
      'sessions',
      'cron',
      'notification',
      'import',
      'insights',
      'gsc',
      'cohortCompute',
    ]);
  });

  it('parses the cloud split', () => {
    expect(
      loadConfig({ ...base, ENABLED_QUEUES: 'events' }).ENABLED_QUEUES
    ).toEqual(['events']);
    expect(
      loadConfig({ ...base, ENABLED_QUEUES: ' sessions , cron ' })
        .ENABLED_QUEUES
    ).toEqual(['sessions', 'cron']);
  });

  it('rejects an unknown token instead of silently idling', () => {
    expect(() =>
      loadConfig({ ...base, ENABLED_QUEUES: 'sessions,nope' })
    ).toThrow(/unknown queue "nope"/);
  });

  it('names the rename when it sees the old events_kafka spelling', () => {
    expect(() =>
      loadConfig({ ...base, ENABLED_QUEUES: 'events_kafka' })
    ).toThrow(/"events_kafka" was renamed to "events"/);
  });
});

describe('<QUEUE>_CONCURRENCY', () => {
  it('keeps the env key derivation — cohortCompute reads COHORTCOMPUTE_CONCURRENCY', () => {
    expect(concurrencyEnvKey('cohortCompute')).toBe(
      'COHORTCOMPUTE_CONCURRENCY'
    );
    const config = loadConfig({ ...base, COHORTCOMPUTE_CONCURRENCY: '9' });
    expect(concurrencyOverride(config, 'cohortCompute')).toBe(9);
  });

  it('is undefined when unset, so the registry default stands', () => {
    expect(concurrencyOverride(loadConfig(base), 'sessions')).toBeUndefined();
  });

  it('ignores a non-numeric or non-positive value', () => {
    expect(
      concurrencyOverride(
        loadConfig({ ...base, SESSIONS_CONCURRENCY: 'lots' }),
        'sessions'
      )
    ).toBeUndefined();
    expect(
      concurrencyOverride(
        loadConfig({ ...base, SESSIONS_CONCURRENCY: '0' }),
        'sessions'
      )
    ).toBeUndefined();
  });
});

describe('the boot flags main.ts branches on', () => {
  it('DISABLE_WORKERS is any defined value; DISABLE_BULLBOARD is 1 or true', () => {
    expect(loadConfig(base).DISABLE_WORKERS).toBe(false);
    expect(loadConfig({ ...base, DISABLE_WORKERS: '0' }).DISABLE_WORKERS).toBe(
      true
    );

    expect(loadConfig(base).DISABLE_BULLBOARD).toBe(false);
    expect(
      loadConfig({ ...base, DISABLE_BULLBOARD: '1' }).DISABLE_BULLBOARD
    ).toBe(true);
    expect(
      loadConfig({ ...base, DISABLE_BULLBOARD: 'true' }).DISABLE_BULLBOARD
    ).toBe(true);
    // Only those two spellings are accepted.
    expect(
      loadConfig({ ...base, DISABLE_BULLBOARD: 'yes' }).DISABLE_BULLBOARD
    ).toBe(false);
  });

  it('QUEUE_NAMESPACE and QUEUE_CLUSTER default to off, so queue keys stay unprefixed', () => {
    const config = loadConfig(base);
    expect(config.QUEUE_CLUSTER).toBe(false);
    expect(config.QUEUE_NAMESPACE).toBeUndefined();
  });

  it('reports every problem at once, never just the first', () => {
    expect(() =>
      loadConfig({ ROLE: 'nope', ENABLED_QUEUES: 'alsonope' })
    ).toThrow(/unknown value "nope"[\s\S]*unknown queue "alsonope"/);
  });
});

describe('blank KEY= is absent, not empty', () => {
  it('falls through to the default on every field, not just the preprocessed ones', () => {
    const config = loadConfig({ ...base, API_PORT: '', LOG_LEVEL: '   ' });
    expect(config.API_PORT).toBe(3000);
    expect(config.LOG_LEVEL).toBe('info');
    expect(config.SHUTDOWN_FORCE_EXIT_MS).toBe(20_000);
  });

  it('treats a blank SELF_HOSTED as unset rather than as the string ""', () => {
    expect(loadConfig({ ...base, SELF_HOSTED: '' }).core.selfHosted).toBe(
      false
    );
    expect(loadConfig({ ...base, SELF_HOSTED: 'true' }).core.selfHosted).toBe(
      true
    );
    // One truthiness rule tree-wide: `1` counts, anything else does not.
    expect(loadConfig({ ...base, SELF_HOSTED: '1' }).core.selfHosted).toBe(
      true
    );
    expect(loadConfig({ ...base, SELF_HOSTED: 'yes' }).core.selfHosted).toBe(
      false
    );
  });
});

describe('tuning knobs keep the module default on a malformed value', () => {
  const malformed = ['0', '-1', '7.5', '7days', 'junk', ''];

  it('EVENT_LIST_MAX_LOOKBACK_DAYS / SESSION_LIST_MAX_LOOKBACK_DAYS', () => {
    for (const bad of malformed) {
      const config = loadConfig({
        ...base,
        EVENT_LIST_MAX_LOOKBACK_DAYS: bad,
        SESSION_LIST_MAX_LOOKBACK_DAYS: bad,
      });
      expect(config.core.query.eventListMaxLookbackDays).toBeUndefined();
      expect(config.core.query.sessionListMaxLookbackDays).toBeUndefined();
    }

    const config = loadConfig({
      ...base,
      EVENT_LIST_MAX_LOOKBACK_DAYS: '7',
      SESSION_LIST_MAX_LOOKBACK_DAYS: '3650',
    });
    expect(config.core.query.eventListMaxLookbackDays).toBe(7);
    expect(config.core.query.sessionListMaxLookbackDays).toBe(3650);
  });

  it('reads each list its own variable — no cross-talk', () => {
    const config = loadConfig({ ...base, EVENT_LIST_MAX_LOOKBACK_DAYS: '7' });
    expect(config.core.query.eventListMaxLookbackDays).toBe(7);
    expect(config.core.query.sessionListMaxLookbackDays).toBeUndefined();
  });

  it('COHORT_QUERY_MEMORY_LIMIT_BYTES / COHORT_QUERY_SPILL_BYTES', () => {
    const config = loadConfig({
      ...base,
      COHORT_QUERY_MEMORY_LIMIT_BYTES: '2gb',
      COHORT_QUERY_SPILL_BYTES: '-1',
    });
    expect(config.core.query.cohortQueryMemoryLimitBytes).toBeUndefined();
    expect(config.core.query.cohortQuerySpillBytes).toBeUndefined();
  });
});

describe('derived values, computed once in the transform', () => {
  it('dashboardUrl is DASHBOARD_URL, unset means empty', () => {
    expect(loadConfig(base).core.dashboardUrl).toBe('');
    expect(
      loadConfig({ ...base, DASHBOARD_URL: 'https://own' }).core.dashboardUrl
    ).toBe('https://own');
  });

  it('adminAuth needs both halves or neither', () => {
    expect(loadConfig(base).core.adminAuth).toBeUndefined();
    expect(
      loadConfig({ ...base, ADMIN_USERNAME: 'ops', ADMIN_PASSWORD: 'pw' }).core
        .adminAuth
    ).toEqual({ username: 'ops', password: 'pw' });
    expect(() => loadConfig({ ...base, ADMIN_USERNAME: 'ops' })).toThrow(
      'ADMIN_PASSWORD'
    );
    expect(() => loadConfig({ ...base, ADMIN_PASSWORD: 'pw' })).toThrow(
      'ADMIN_USERNAME'
    );
  });

  it('devLogin is DEV_LOGIN split at the first slash, so the password keeps its own', () => {
    expect(loadConfig(base).core.auth.devLogin).toBeUndefined();
    expect(
      loadConfig({ ...base, DEV_LOGIN: '[email protected]/openpanel' }).core
        .auth.devLogin
    ).toEqual({ email: '[email protected]', password: 'openpanel' });
    expect(
      loadConfig({ ...base, DEV_LOGIN: '[email protected]/a/b' }).core.auth
        .devLogin
    ).toEqual({ email: '[email protected]', password: 'a/b' });
    for (const malformed of ['[email protected]', '/pw', '[email protected]/']) {
      let message = '';
      try {
        loadConfig({ ...base, DEV_LOGIN: malformed });
      } catch (error) {
        message = (error as Error).message;
      }
      expect(message).toContain('DEV_LOGIN must be "email/password"');
      // The value is a credential; the boot error must not echo it.
      expect(message).not.toContain(malformed);
    }
  });

  it('clickhouseClustered is CLICKHOUSE_CLUSTER alone, the rule the migrations use', () => {
    expect(loadConfig(base).core.clickhouseClustered).toBe(false);
    expect(
      loadConfig({ ...base, SELF_HOSTED: 'true' }).core.clickhouseClustered
    ).toBe(false);
    expect(
      loadConfig({ ...base, CLICKHOUSE_CLUSTER: '1' }).core.clickhouseClustered
    ).toBe(true);
    expect(
      loadConfig({ ...base, SELF_HOSTED: 'true', CLICKHOUSE_CLUSTER: '1' }).core
        .clickhouseClustered
    ).toBe(true);
  });

  it('the CORS allowlist, the verbose client ids and the listen address', () => {
    const config = loadConfig({
      ...base,
      DASHBOARD_URL: 'https://own',
      API_CORS_ORIGINS: ' https://a , https://b ',
      ENABLE_VERBOSE_LOGGING: 'c1,c2',
      API_HOST: '127.0.0.1',
      API_PORT: '4000',
    });
    expect(config.dashboardOrigins).toEqual([
      'https://own',
      'https://a',
      'https://b',
    ]);
    expect(config.verboseClientIds).toEqual(['c1', 'c2']);
    expect(config.listen).toEqual({ port: 4000, hostname: '127.0.0.1' });
    // No hostname unless API_HOST says one — Bun's `localhost` binds IPv6 only.
    expect(loadConfig(base).listen).toEqual({ port: 3000 });
  });

  it('the DLQ topic follows the events topic unless it is named', () => {
    expect(loadConfig(base).core.kafka.eventsDlqTopic).toBe('events-dlq');
    expect(
      loadConfig({ ...base, KAFKA_EVENTS_TOPIC: 'evt' }).core.kafka
        .eventsDlqTopic
    ).toBe('evt-dlq');
    expect(
      loadConfig({ ...base, KAFKA_EVENTS_DLQ_TOPIC: 'own' }).core.kafka
        .eventsDlqTopic
    ).toBe('own');
  });

  it('kafka security is plaintext without auth when nothing is set', () => {
    expect(loadConfig(base).core.kafka.security).toEqual({
      ssl: { enabled: false, caPath: undefined, rejectUnauthorized: undefined },
      sasl: undefined,
    });
  });

  it('KAFKA_SSL=true (or 1) enables TLS on its own; the CA path and switch ride along', () => {
    expect(
      loadConfig({ ...base, KAFKA_SSL: 'true' }).core.kafka.security.ssl
    ).toEqual({
      enabled: true,
      caPath: undefined,
      rejectUnauthorized: undefined,
    });
    expect(
      loadConfig({
        ...base,
        KAFKA_SSL: '1',
        KAFKA_SSL_CA_PATH: '/certs/ca.pem',
        KAFKA_SSL_REJECT_UNAUTHORIZED: 'false',
      }).core.kafka.security.ssl
    ).toEqual({
      enabled: true,
      caPath: '/certs/ca.pem',
      rejectUnauthorized: false,
    });
  });

  it('SASL credentials imply TLS and default to scram-sha-512', () => {
    expect(
      loadConfig({
        ...base,
        KAFKA_SASL_USERNAME: 'op',
        KAFKA_SASL_PASSWORD: 'secret',
      }).core.kafka.security
    ).toEqual({
      ssl: { enabled: true, caPath: undefined, rejectUnauthorized: undefined },
      sasl: { mechanism: 'scram-sha-512', username: 'op', password: 'secret' },
    });
  });

  it('accepts every mechanism case-insensitively', () => {
    for (const mechanism of [
      'plain',
      'scram-sha-256',
      'scram-sha-512',
    ] as const) {
      expect(
        loadConfig({
          ...base,
          KAFKA_SASL_USERNAME: 'op',
          KAFKA_SASL_PASSWORD: 'secret',
          KAFKA_SASL_MECHANISM: mechanism.toUpperCase(),
        }).core.kafka.security.sasl?.mechanism
      ).toBe(mechanism);
    }
  });

  it('KAFKA_SSL=false sends SASL over plaintext when asked explicitly', () => {
    expect(
      loadConfig({
        ...base,
        KAFKA_SSL: 'false',
        KAFKA_SASL_USERNAME: 'op',
        KAFKA_SASL_PASSWORD: 'secret',
        KAFKA_SASL_MECHANISM: 'plain',
      }).core.kafka.security
    ).toEqual({
      ssl: { enabled: false, caPath: undefined, rejectUnauthorized: undefined },
      sasl: { mechanism: 'plain', username: 'op', password: 'secret' },
    });
  });

  it('the dead-letter list cap defaults to 1000 and takes a positive integer', () => {
    expect(loadConfig(base).INGEST_DEAD_LETTER_MAX_ENTRIES).toBe(1000);
    expect(
      loadConfig({ ...base, INGEST_DEAD_LETTER_MAX_ENTRIES: '25' })
        .INGEST_DEAD_LETTER_MAX_ENTRIES
    ).toBe(25);
    // Same doctrine as its Kafka neighbours: a cap of 0 or -5 would silently
    // keep nothing, so it fails boot rather than becoming a surprise.
    expect(() =>
      loadConfig({ ...base, INGEST_DEAD_LETTER_MAX_ENTRIES: '0' })
    ).toThrow('INGEST_DEAD_LETTER_MAX_ENTRIES');
  });

  it('the log exporter and the stdout interception verdict', () => {
    expect(loadConfig(base).core.logging).toMatchObject({
      exporter: 'stdout',
      interceptProcessOutput: false,
    });
    expect(
      loadConfig({ ...base, HYPERDX_API_KEY: 'k' }).core.logging
    ).toMatchObject({ exporter: 'otlp', interceptProcessOutput: true });
    expect(
      loadConfig({ ...base, NODE_ENV: 'production' }).core.logging
    ).toMatchObject({ exporter: 'stdout', interceptProcessOutput: true });
  });

  it('ALLOW_REGISTRATION keeps "unset" distinct from "false"', () => {
    expect(loadConfig(base).core.auth.allowRegistration).toBeUndefined();
    expect(
      loadConfig({ ...base, ALLOW_REGISTRATION: 'false' }).core.auth
        .allowRegistration
    ).toBe(false);
    expect(
      loadConfig({ ...base, ALLOW_REGISTRATION: 'true' }).core.auth
        .allowRegistration
    ).toBe(true);
  });
});

describe('cross-field invariants, checked before the transform', () => {
  it('refuses a consuming role with nothing to consume', () => {
    expect(() => loadConfig({ ROLE: 'worker', ENABLED_QUEUES: ' , ' })).toThrow(
      /consumes queues but ENABLED_QUEUES names none/
    );
    // ROLE=api never consumes, so the same env is fine for it.
    expect(() =>
      loadConfig({ ROLE: 'api', ENABLED_QUEUES: ' , ' })
    ).not.toThrow();
  });

  it('refuses DEV_LOGIN under NODE_ENV=production', () => {
    const devLogin = { ...base, DEV_LOGIN: '[email protected]/openpanel' };
    expect(() => loadConfig({ ...devLogin, NODE_ENV: 'production' })).toThrow(
      /DEV_LOGIN is set while NODE_ENV=production/
    );
    expect(() =>
      loadConfig({ ...devLogin, NODE_ENV: 'development' })
    ).not.toThrow();
    expect(() => loadConfig(devLogin)).not.toThrow();
  });

  it('refuses LOG_EXPORTER=otlp without a HyperDX key', () => {
    expect(() => loadConfig({ ...base, LOG_EXPORTER: 'otlp' })).toThrow(
      /LOG_EXPORTER=otlp requires HYPERDX_API_KEY/
    );
    expect(() =>
      loadConfig({ ...base, LOG_EXPORTER: 'otlp', HYPERDX_API_KEY: 'k' })
    ).not.toThrow();
  });

  it('refuses a Kafka heartbeat that cannot fit inside the session timeout', () => {
    expect(() =>
      loadConfig({
        ...base,
        KAFKA_SESSION_TIMEOUT_MS: '1000',
        KAFKA_HEARTBEAT_INTERVAL_MS: '1000',
      })
    ).toThrow(/must be below KAFKA_SESSION_TIMEOUT_MS/);
  });

  it('passes KAFKA_REBALANCE_TIMEOUT_MS to the consumer, defaulting to kafkajs', () => {
    expect(loadConfig(base).core.kafka.rebalanceTimeoutMs).toBe(60_000);
    expect(
      loadConfig({ ...base, KAFKA_REBALANCE_TIMEOUT_MS: '30000' }).core.kafka
        .rebalanceTimeoutMs
    ).toBe(30_000);
  });

  it('reads REDIS_CACHE_COMMAND_TIMEOUT_MS, defaulting to 5000', () => {
    expect(loadConfig(base).REDIS_CACHE_COMMAND_TIMEOUT_MS).toBe(5000);
    expect(
      loadConfig({ ...base, REDIS_CACHE_COMMAND_TIMEOUT_MS: '2000' })
        .REDIS_CACHE_COMMAND_TIMEOUT_MS
    ).toBe(2000);
    expect(() =>
      loadConfig({ ...base, REDIS_CACHE_COMMAND_TIMEOUT_MS: 'soon' })
    ).toThrow();
  });

  it('refuses a reaper deadman below the session idle window', () => {
    expect(() =>
      loadConfig({
        ...base,
        SESSION_TIMEOUT_MS: '60000',
        SESSION_REAPER_WALLCLOCK_DEADMAN_MS: '1000',
      })
    ).toThrow(/is below SESSION_TIMEOUT_MS/);
  });

  it('refuses a vacuum threshold that would race the reaper', () => {
    expect(() =>
      loadConfig({
        ...base,
        SESSION_TIMEOUT_MS: '60000',
        SESSION_VACUUM_STALE_THRESHOLD_MS: '60000',
      })
    ).toThrow(/must exceed the reaper deadman/);
  });

  it('refuses half a Kafka SASL credential pair, naming the missing half', () => {
    expect(() => loadConfig({ ...base, KAFKA_SASL_USERNAME: 'op' })).toThrow(
      /KAFKA_SASL_PASSWORD is missing/
    );
    expect(() =>
      loadConfig({ ...base, KAFKA_SASL_PASSWORD: 'secret' })
    ).toThrow(/KAFKA_SASL_USERNAME is missing/);
  });

  it('refuses a SASL mechanism without credentials', () => {
    expect(() =>
      loadConfig({ ...base, KAFKA_SASL_MECHANISM: 'plain' })
    ).toThrow(/KAFKA_SASL_MECHANISM is set but/);
  });

  it('refuses an unsupported SASL mechanism before any client exists', () => {
    expect(() =>
      loadConfig({
        ...base,
        KAFKA_SASL_USERNAME: 'op',
        KAFKA_SASL_PASSWORD: 'secret',
        KAFKA_SASL_MECHANISM: 'oauthbearer',
      })
    ).toThrow(
      'Unsupported KAFKA_SASL_MECHANISM "oauthbearer". Supported: plain, scram-sha-256, scram-sha-512'
    );
  });

  it('refuses TLS-only options on a plaintext connection', () => {
    expect(() =>
      loadConfig({ ...base, KAFKA_SSL_CA_PATH: '/certs/ca.pem' })
    ).toThrow(/require TLS/);
    expect(() =>
      loadConfig({
        ...base,
        KAFKA_SSL: 'false',
        KAFKA_SSL_REJECT_UNAUTHORIZED: 'false',
      })
    ).toThrow(/require TLS/);
  });

  it('refuses a non-boolean KAFKA_SSL', () => {
    expect(() => loadConfig({ ...base, KAFKA_SSL: 'yes' })).toThrow(
      /must be "true" or "false" \(got "yes"\)/
    );
  });

  it('never puts the SASL password in a boot error', () => {
    let message = '';
    try {
      loadConfig({
        ...base,
        KAFKA_SASL_USERNAME: 'op',
        KAFKA_SASL_PASSWORD: 'hunter2-secret',
        KAFKA_SASL_MECHANISM: 'nope',
      });
    } catch (error) {
      message = error instanceof Error ? error.message : String(error);
    }
    expect(message).toContain('Unsupported KAFKA_SASL_MECHANISM');
    expect(message).not.toContain('hunter2-secret');
  });

  it('refuses a profile-backfill project list with the flag off', () => {
    expect(() =>
      loadConfig({ ...base, EXPERIMENTAL_PROFILE_BACKFILL_PROJECTS: 'p1' })
    ).toThrow(/the allowlist has no effect/);
    expect(() =>
      loadConfig({
        ...base,
        EXPERIMENTAL_PROFILE_BACKFILL: '1',
        EXPERIMENTAL_PROFILE_BACKFILL_PROJECTS: 'p1',
      })
    ).not.toThrow();
  });
});