Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

17.7 KB
Raw Blame
#!/usr/bin/env node
/**
 * Chart behaviour guard.
 *
 * CI already runs `helm lint`, `helm template` and `kubeconform` against the chart. All three answer
 * the same question — does this render into schema-valid YAML — and none of them can see a chart that
 * renders perfectly and behaves wrongly in a cluster: a ServiceMonitor selector that matches two
 * Services, a probe budget that boot cannot meet, or a configuration change that reaches no running
 * container. Each of those shipped, and each passed every existing check.
 *
 * So this guard renders the chart with real helm and asserts against the rendered objects rather than
 * against the template source. Reading the objects is what makes the assertions possible: "does the
 * pod template change" is not a property of any one template file, it is a property of the render.
 *
 * `render-is-deterministic` is a control, not a feature check. `config-change-rolls-pods` can be
 * satisfied by a checksum over anything that varies per render — a timestamp, a random value — which
 * would roll every pod on every `helm upgrade`, a worse defect than the one being prevented, and one
 * that reads as a pass. The control fails on exactly that. Keep the two together; the feature check
 * alone is not evidence.
 *
 * Run locally: `npm run check:chart`. Runs in CI (Helm chart and workflows job). Needs Docker.
 */
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';

// Pinned in step with the `helm lint` / `helm template` steps of .github/workflows/ci.yml. A version
// skew here renders with an older helm, which fails loudly rather than passing something wrong.
const HELM_IMAGE = 'alpine/helm:4.2.3';
const CHARTS = fileURLToPath(new URL('../charts', import.meta.url));

const render = (...setArgs) =>
  execFileSync('docker', ['run', '--rm', '-v', `${CHARTS}:/charts:ro`, HELM_IMAGE, 'template', 'ci', '/charts/openwa', ...setArgs], {
    encoding: 'utf8',
    maxBuffer: 1 << 24,
  });

/** Render with `valuesYaml` as a values file (`-f -`), which parses numbers unlike `--set`. */
const renderValues = valuesYaml =>
  execFileSync('docker', ['run', '-i', '--rm', '-v', `${CHARTS}:/charts:ro`, HELM_IMAGE, 'template', 'ci', '/charts/openwa', '-f', '-'], {
    encoding: 'utf8',
    input: valuesYaml,
    maxBuffer: 1 << 24,
  });

const documents = out => out.split('\n---\n');
const kindOf = doc => /^kind:\s*(\S+)/m.exec(doc)?.[1];
const nameOf = doc => /^\s{2}name:\s*(\S+)/m.exec(doc)?.[1];
const byKind = (out, kind) => documents(out).filter(d => kindOf(d) === kind);

/**
 * The flat scalar entries of the mapping at `path`, e.g. `mapAt(doc, ['spec', 'selector', 'matchLabels'])`.
 *
 * Indentation-aware rather than a regex per call site: the same key sits at a different depth in each
 * object, and a regex written for one depth does not fail on another — it silently matches nothing and
 * yields an empty mapping, which an `every()` over its entries then reports as "matches everything".
 * Nested blocks below `path` are flattened in; every caller here reads scalars it names explicitly.
 */
function mapAt(doc, path) {
  const lines = doc.split('\n');
  let depth = -1;
  let i = 0;
  for (const key of path) {
    const re = new RegExp(`^(\\s*)${key}:\\s*$`);
    let found = -1;
    for (; i < lines.length; i++) {
      const m = re.exec(lines[i]);
      if (m && m[1].length > depth) {
        found = m[1].length;
        break;
      }
    }
    if (found < 0) return null;
    depth = found;
    i++;
  }
  const out = {};
  for (; i < lines.length; i++) {
    const trimmed = lines[i].trim();
    if (!trimmed || trimmed.startsWith('#')) continue;
    if (lines[i].length - lines[i].trimStart().length <= depth) break;
    const m = /^([^:]+):\s*(.*)$/.exec(trimmed);
    if (m) out[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
  }
  return out;
}

/** The StatefulSet's pod template — the bytes the kubelet compares to decide whether to roll pods. */
function podTemplate(out) {
  const doc = byKind(out, 'StatefulSet')[0] ?? '';
  const at = doc.indexOf('\n  template:');
  return at < 0 ? '' : doc.slice(at);
}

/**
 * When the kubelet gives up on a probe. The first attempt fires at `initialDelaySeconds` and the
 * verdict lands on the Nth consecutive failure, so the budget is initialDelay + period × (threshold −
 * 1) — one period shorter than the obvious reading.
 */
const probeBudget = probe =>
  Number(probe?.initialDelaySeconds ?? 0) + Number(probe?.periodSeconds ?? 10) * (Number(probe?.failureThreshold ?? 3) - 1);

const results = [];
const check = (id, ok, detail) => results.push({ id, ok, detail });

// A configuration-only upgrade must perturb the pod template. Both the ConfigMap and the Secret reach
// the container through envFrom, which is read once at container creation — so without a pod-template
// change the rollout is a no-op and the running container keeps the values it started with.
{
  const sts = nameOf(byKind(render(), 'StatefulSet')[0] ?? '') ?? 'StatefulSet';
  const envRolls = podTemplate(render('--set', 'env.LOG_LEVEL=info')) !== podTemplate(render('--set', 'env.LOG_LEVEL=debug'));
  const secretRolls = podTemplate(render('--set', 'secretEnv.API_KEY=aaa')) !== podTemplate(render('--set', 'secretEnv.API_KEY=bbb'));
  const stale = [!envRolls && 'ConfigMap (env)', !secretRolls && 'Secret (secretEnv)'].filter(Boolean);
  check(
    'config-change-rolls-pods',
    envRolls && secretRolls,
    stale.length ? `${sts}: pod template unchanged by ${stale.join(' and ')} — an upgrade would roll nothing` : 'env and secretEnv each move the pod template',
  );
}

// CONTROL. Two identical renders must produce an identical pod template. A checksum over anything
// that varies per render satisfies the assertion above while restarting every pod on every upgrade.
{
  const a = podTemplate(render());
  const b = podTemplate(render());
  const at = [...a].findIndex((ch, i) => ch !== b[i]);
  check(
    'render-is-deterministic',
    a === b,
    a === b
      ? 'two identical renders agree, so the checksums above are over the configuration and not over the render'
      : `pod template differs between two identical renders at offset ${at}: ${JSON.stringify(a.slice(at, at + 60))} vs ${JSON.stringify(b.slice(at, at + 60))}`,
  );
}

// Boot is long (migrations, the database connect retry, plugin load, backfills). That belongs to a
// startupProbe: it suspends the liveness probe until it succeeds, so the boot window and the
// running-health window can be set independently. Without one, the liveness budget alone
// decides how long boot may take.
{
  const sts = byKind(render(), 'StatefulSet')[0] ?? '';
  const startup = mapAt(sts, ['startupProbe']);
  const liveness = mapAt(sts, ['livenessProbe']);
  const startupBudget = probeBudget(startup);
  const livenessBudget = probeBudget(liveness);
  check(
    'boot-budget-exceeds-liveness-budget',
    Boolean(startup) && startupBudget > livenessBudget,
    !startup
      ? `${nameOf(sts) ?? 'StatefulSet'}: no startupProbe, so boot must finish inside the ${livenessBudget}s liveness budget or the kubelet restarts the pod mid-boot`
      : `startupProbe allows ${startupBudget}s, liveness allows ${livenessBudget}s`,
  );
}

// A probe that times out counts as a failure. The kubelet default is 1s, which /ready misses by
// design (it bounds each database probe at READINESS_PROBE_TIMEOUT_MS so it can answer its own 503)
// and which a CPU-throttled pod can miss even on the static /live route. The constant is read from
// the controller so the two cannot drift; a rename fails here rather than skipping the check.
{
  const source = readFileSync(new URL('../src/modules/health/health.controller.ts', import.meta.url), 'utf8');
  const match = /READINESS_PROBE_TIMEOUT_MS\s*=\s*([\d_]+)/.exec(source);
  const handlerMs = match ? Number(match[1].replace(/_/g, '')) : NaN;
  const sts = byKind(render(), 'StatefulSet')[0] ?? '';
  const timeout = name => Number(mapAt(sts, [name])?.timeoutSeconds ?? 1);
  const readiness = timeout('readinessProbe');
  const short = ['livenessProbe', 'startupProbe'].filter(name => timeout(name) < 2);
  check(
    'probe-timeouts-cover-handlers',
    Number.isFinite(handlerMs) && readiness * 1000 > handlerMs && short.length === 0,
    !Number.isFinite(handlerMs)
      ? 'READINESS_PROBE_TIMEOUT_MS not found in src/modules/health/health.controller.ts'
      : readiness * 1000 <= handlerMs
        ? `readinessProbe times out at ${readiness}s, not above the ${handlerMs}ms the handler may take`
        : short.length
          ? `${short.join(' and ')} time out below 2s`
          : `readiness ${readiness}s exceeds the ${handlerMs}ms handler bound; liveness and startup allow ${timeout('livenessProbe')}s and ${timeout('startupProbe')}s`,
  );
}

// The image also starts as a non-root uid, which is the only way to meet Pod Security "restricted".
// That needs a pod-level securityContext (fsGroup is what makes a fresh volume writable by the uid)
// and a way to drop the capability list the root entrypoint needs, while the default stays as it is.
// The profile rendered is the one values.yaml documents, so the comment cannot drift from what works.
{
  const podContext = out => {
    const sts = byKind(out, 'StatefulSet')[0] ?? '';
    return /^ {6}securityContext:\n((?: {8}.*\n)+)/m.exec(sts)?.[1] ?? '';
  };
  const addsCaps = out => /^ {14}add:/m.test(byKind(out, 'StatefulSet')[0] ?? '');
  const byDefault = render();
  const values = readFileSync(`${CHARTS}/openwa/values.yaml`, 'utf8');
  const profile = /^# {3}podSecurityContext:\n(?:# {3}.*\n)+/m.exec(values)?.[0] ?? '';
  const nonRoot = renderValues(profile.replace(/^# {3}/gm, ''));
  const pod = podContext(nonRoot);
  const problems = [
    podContext(byDefault) && 'the default render sets a pod securityContext',
    !addsCaps(byDefault) && 'the default render lost the capabilities the root entrypoint needs',
    !/^ {14}- KILL$/m.test(byKind(byDefault, 'StatefulSet')[0] ?? '') &&
      'the root init cannot forward shutdown signals after the privilege drop',
    !/runAsNonRoot: true/.test(pod) && 'podSecurityContext.runAsNonRoot does not reach the pod spec',
    !/fsGroup: 997/.test(pod) && 'podSecurityContext.fsGroup does not reach the pod spec',
    // Without it the kubelet re-owns every file on the volume on every mount before the pod starts.
    !/fsGroupChangePolicy: OnRootMismatch/.test(pod) && 'podSecurityContext.fsGroupChangePolicy is not OnRootMismatch',
    addsCaps(nonRoot) && 'containerSecurityContext.capabilities.add: null still renders an add list',
  ].filter(Boolean);
  check(
    'non-root-profile-renders',
    problems.length === 0,
    problems.length ? problems.join('; ') : 'the default is unchanged, and podSecurityContext plus add: null render a non-root pod',
  );
}

// One scrape target per pod per endpoint. Prometheus Operator yields a target for every address of
// every Service matching the selector and de-duplicates nothing by pod, so a selector matching N
// Services produces N series sets separated only by the `service` label.
{
  const out = render('--set', 'serviceMonitor.enabled=true');
  const monitor = byKind(out, 'ServiceMonitor')[0] ?? '';
  const selector = mapAt(monitor, ['spec', 'selector', 'matchLabels']) ?? {};
  const port = /^\s*-\s*port:\s*(\S+)/m.exec(monitor)?.[1];
  const matched = byKind(out, 'Service')
    .filter(doc => {
      const labels = mapAt(doc, ['metadata', 'labels']) ?? {};
      return Object.entries(selector).every(([k, v]) => labels[k] === v);
    })
    .filter(doc => new RegExp(`^\\s*-?\\s*name:\\s*${port}\\b`, 'm').test(doc))
    .map(doc => nameOf(doc) ?? '(unnamed)');
  check(
    'one-scrape-target-per-pod',
    Object.keys(selector).length > 0 && matched.length === 1,
    Object.keys(selector).length === 0
      ? `${nameOf(monitor) ?? 'ServiceMonitor'}: empty selector — it would match every Service in the namespace`
      : `${matched.length} Service(s) match the selector on port '${port}': ${matched.join(', ') || '(none)'}`,
  );
}

// A values file is parsed as YAML, so an unquoted number reaches the templates as a float64, and
// `quote` prints one of a million or more in exponent form. The app then reads "5.24288e+07" for a
// byte limit (and refuses to boot) or "1.2345678e+07" for a password. `--set` parses integers as
// int64, so the renders above never see it. Fractions and booleans must still pass through as written.
{
  const out = renderValues(
    'env:\n  MEDIA_DOWNLOAD_MAX_BYTES: 52428800\n  CHECK_RATIO: 1.5\n  CHECK_FLAG: true\n' +
      'secretEnv:\n  DATABASE_PASSWORD: 12345678\n',
  );
  const data = mapAt(byKind(out, 'ConfigMap')[0] ?? '', ['data']) ?? {};
  const secret = mapAt(byKind(out, 'Secret')[0] ?? '', ['stringData']) ?? {};
  const got = {
    MEDIA_DOWNLOAD_MAX_BYTES: data.MEDIA_DOWNLOAD_MAX_BYTES,
    CHECK_RATIO: data.CHECK_RATIO,
    CHECK_FLAG: data.CHECK_FLAG,
    DATABASE_PASSWORD: secret.DATABASE_PASSWORD,
  };
  const want = { MEDIA_DOWNLOAD_MAX_BYTES: '52428800', CHECK_RATIO: '1.5', CHECK_FLAG: 'true', DATABASE_PASSWORD: '12345678' };
  const wrong = Object.keys(want).filter(k => got[k] !== want[k]);
  check(
    'values-file-numbers-render-as-written',
    wrong.length === 0,
    wrong.length
      ? `values-file entries rendered differently from how they were written: ${wrong.map(k => `${k}=${JSON.stringify(got[k])}`).join(', ')}`
      : 'unquoted numbers in a values file reach the ConfigMap and Secret as written',
  );
}

// The kubelet injects Docker-link variables for every Service in the namespace unless the pod opts
// out, so a Service named `redis` or `database` sets REDIS_PORT or DATABASE_PORT to tcp://<ip>:<port>
// and boot validation refuses it. The app reads no service-link variable.
{
  const sts = byKind(render(), 'StatefulSet')[0] ?? '';
  const links = /^\s*enableServiceLinks:\s*(\S+)/m.exec(sts)?.[1];
  check(
    'no-service-link-env',
    links === 'false',
    links === 'false'
      ? 'enableServiceLinks: false, so no Service in the namespace can set REDIS_PORT or DATABASE_PORT'
      : `${nameOf(sts) ?? 'StatefulSet'}: enableServiceLinks is ${links ?? 'unset (defaults to true)'}, so a Service named redis or database injects REDIS_PORT or DATABASE_PORT`,
  );
}

// With NODE_ENV=production the app sends upgrade-insecure-requests, so a dashboard opened over a
// TLS-less ingress fetches its scripts over https and renders blank. NOTES must warn on exactly that
// combination: ingress.tls or an explicit CSP_UPGRADE_INSECURE_REQUESTS=false silences it. `helm
// template` does not render NOTES, so this one goes through a client-side dry-run install.
{
  const notes = (...setArgs) =>
    execFileSync('docker', ['run', '--rm', '-v', `${CHARTS}:/charts:ro`, HELM_IMAGE, 'install', 'ci', '/charts/openwa', '--dry-run=client', ...setArgs], {
      encoding: 'utf8',
      maxBuffer: 1 << 24,
    }).split('\nNOTES:\n')[1] ?? '';
  const warns = out => out.includes('this ingress has no TLS');
  const tls = ['--set', 'ingress.tls[0].secretName=openwa-tls', '--set', 'ingress.tls[0].hosts[0]=openwa.example.com'];
  const cases = [
    ['ingress without TLS', true, ['--set', 'ingress.enabled=true']],
    ['CSP upgrade off', false, ['--set', 'ingress.enabled=true', '--set-string', 'env.CSP_UPGRADE_INSECURE_REQUESTS=false']],
    // `--set` parses this one as a YAML boolean rather than a string.
    ['CSP upgrade off as a boolean', false, ['--set', 'ingress.enabled=true', '--set', 'env.CSP_UPGRADE_INSECURE_REQUESTS=false']],
    ['ingress with TLS', false, ['--set', 'ingress.enabled=true', ...tls]],
    // A null drops the key from the ConfigMap, so the image's NODE_ENV=production applies.
    ['NODE_ENV removed', true, ['--set', 'ingress.enabled=true', '--set', 'env.NODE_ENV=null']],
    // An empty value reaches the container and overrides the image default.
    ['NODE_ENV empty', false, ['--set', 'ingress.enabled=true', '--set-string', 'env.NODE_ENV=']],
    ['no ingress', false, []],
  ];
  const wrong = cases.filter(([, want, args]) => warns(notes(...args)) !== want).map(([name, want]) => `${name} (expected ${want ? 'a' : 'no'} warning)`);
  check(
    'notes-warn-on-tls-less-ingress',
    wrong.length === 0,
    wrong.length ? `NOTES got the plain-http ingress warning wrong for: ${wrong.join(', ')}` : 'NOTES warns only when the ingress has no TLS and the CSP upgrade is on',
  );
}

// `helm upgrade --reuse-values` renders the new templates with the PREVIOUS release's values, which hold
// none of the keys a newer chart added. A template that reads one without a default fails the upgrade
// with a nil pointer, and so does a chart that stops rendering when a block is removed.
{
  let detail;
  let ok = false;
  try {
    const probe = mapAt(byKind(render('--set', 'startupProbe=null'), 'StatefulSet')[0] ?? '', ['startupProbe']);
    ok = probe?.periodSeconds === '5' && probe?.failureThreshold === '60';
    detail = ok
      ? 'values without the startupProbe block render with the 5 s period and 60 failures'
      : `values without startupProbe rendered periodSeconds ${probe?.periodSeconds}, failureThreshold ${probe?.failureThreshold}`;
  } catch (error) {
    detail = `the chart does not render with values that predate startupProbe: ${String(error.stderr ?? error.message).split('\n')[0]}`;
  }
  check('renders-with-previous-release-values', ok, detail);
}

const failed = results.filter(r => !r.ok);
if (failed.length) {
  console.error('\n✖ Chart behaviour check failed:');
  for (const r of failed) console.error(`  - ${r.id}: ${r.detail}`);
  console.error('\nThese assert against the rendered objects, so `helm lint` and `kubeconform` cannot catch them.');
  console.error('Re-run with `npm run check:chart` after fixing the chart.\n');
  process.exit(1);
}
for (const r of results) console.log(`  ✓ ${r.id} — ${r.detail}`);
console.log(`✓ Chart behaviour check OK (${results.length} assertions against the rendered chart).`);