fhirsmith 0.13.4 → 0.14.0

package/publisher/github-release.js

@@ -0,0 +1,195 @@
+// Tagging an IG source repository and publishing a GitHub release for it, at the end of a
+// successful publication run.
+//
+// Authentication is a GitHub App rather than a personal access token. The reason is scope: the
+// publisher only ever publishes from the HL7 and FHIR organisations, and an App installed on
+// exactly those two - with Contents: Read and write, which covers both tags and releases - can be
+// revoked, audited and attributed on its own. A fine-grained PAT cannot span two organisations
+// (each is limited to a single resource owner), and a classic PAT would act as whoever minted it.
+//
+// The GitHub CLI is deliberately not used. gh cannot authenticate as an App - it only accepts
+// access tokens - so an installation token has to be minted here regardless, and once that code
+// exists the three remaining REST calls are less machinery than requiring gh to be installed and
+// kept current on the server. Nothing in this file needs the database, which also keeps it
+// testable without sqlite3.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const axios = require('axios');
+
+const API_ROOT = 'https://api.github.com';
+const API_VERSION = '2022-11-28';
+
+// GitHub rejects an App JWT whose exp is more than 10 minutes out, measured against ITS clock, so
+// a token minted right on the 10 minute mark fails whenever this server's clock runs slow. Backdate
+// iat by a minute against skew the other way, and take 8 minutes rather than the full 10 - the
+// token is spent within seconds of being minted, so the headroom costs nothing.
+const JWT_BACKDATE_SECONDS = 60;
+const JWT_LIFETIME_SECONDS = 480;
+
+function isConfigured(cfg) {
+  return !!(cfg && cfg['app-id'] && cfg['private-key'] && cfg.installations);
+}
+
+// task.github_org carries whatever case the requester typed, and GitHub org names are not
+// case-sensitive, so the config's spelling should not have to match it.
+function installationIdFor(cfg, org) {
+  const map = (cfg && cfg.installations) || {};
+  const wanted = String(org || '').toLowerCase();
+  const key = Object.keys(map).find((k) => k.toLowerCase() === wanted);
+  return key ? map[key] : null;
+}
+
+function base64url(input) {
+  return Buffer.from(input).toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+}
+
+function appJwt(appId, privateKeyPem, nowSeconds) {
+  const now = nowSeconds || Math.floor(Date.now() / 1000);
+  const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const payload = base64url(JSON.stringify({
+    iat: now - JWT_BACKDATE_SECONDS,
+    exp: now + JWT_LIFETIME_SECONDS,
+    iss: String(appId)
+  }));
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(header + '.' + payload);
+  signer.end();
+  return header + '.' + payload + '.' + base64url(signer.sign(privateKeyPem));
+}
+
+function apiHeaders(authorization) {
+  return {
+    'Authorization': authorization,
+    'Accept': 'application/vnd.github+json',
+    'X-GitHub-Api-Version': API_VERSION,
+    'User-Agent': 'FHIRsmith-publisher'
+  };
+}
+
+async function installationToken(cfg, org, http) {
+  const installationId = installationIdFor(cfg, org);
+  if (!installationId) {
+    throw new Error('No GitHub App installation is configured for the organisation ' + org);
+  }
+  const pem = fs.readFileSync(cfg['private-key'], 'utf8');
+  const jwt = appJwt(cfg['app-id'], pem);
+  const res = await http.post(
+      API_ROOT + '/app/installations/' + installationId + '/access_tokens',
+      {},
+      { headers: apiHeaders('Bearer ' + jwt) });
+  if (!res.data || !res.data.token) {
+    throw new Error('GitHub returned no installation token for organisation ' + org);
+  }
+  return res.data.token;
+}
+
+// Create the tag if it is not already there. A re-publication of the same version finds it
+// present: the tag is left alone (it is a public ref others may have resolved), but if it points
+// somewhere other than what was just published, say so - a release attached to a commit that is
+// not the published one is exactly the sort of thing nobody notices for a year.
+async function ensureTag(repoUrl, tag, sha, headers, http, log) {
+  const existing = await http.get(repoUrl + '/git/ref/' + encodeURIComponent('tags/' + tag),
+      { headers, validateStatus: (s) => s === 200 || s === 404 });
+  if (existing.status === 200) {
+    const existingSha = existing.data && existing.data.object && existing.data.object.sha;
+    if (existingSha && existingSha !== sha) {
+      log('warn', 'Tag ' + tag + ' already exists and points at ' + existingSha.substring(0, 8) +
+          ', not the commit just published (' + sha.substring(0, 8) + '). Leaving the tag as it is.');
+    } else {
+      log('info', 'Tag ' + tag + ' already exists and is correct - leaving it alone');
+    }
+    return false;
+  }
+  await http.post(repoUrl + '/git/refs', { ref: 'refs/tags/' + tag, sha: sha }, { headers });
+  log('info', 'Created tag ' + tag + ' at ' + sha.substring(0, 8));
+  return true;
+}
+
+// A re-publication should end up with the current build's zip attached, so an existing release for
+// this tag is removed and rebuilt. The tag itself survives that - deleting a release does not
+// delete its ref.
+async function replaceExistingRelease(repoUrl, tag, headers, http, log) {
+  const existing = await http.get(repoUrl + '/releases/tags/' + encodeURIComponent(tag),
+      { headers, validateStatus: (s) => s === 200 || s === 404 });
+  if (existing.status !== 200) {
+    return false;
+  }
+  await http.delete(repoUrl + '/releases/' + existing.data.id, { headers });
+  log('info', 'Removed the previous release for ' + tag + ' so it can be replaced');
+  return true;
+}
+
+async function uploadAsset(uploadUrlTemplate, assetName, zipPath, headers, http) {
+  // upload_url comes back as an RFC 6570 template, e.g. https://…/assets{?name,label}
+  const base = uploadUrlTemplate.replace(/\{[^}]*\}$/, '');
+  const url = base + '?name=' + encodeURIComponent(assetName);
+  const body = fs.readFileSync(zipPath);
+  const res = await http.post(url, body, {
+    headers: Object.assign({}, headers, {
+      'Content-Type': 'application/zip',
+      'Content-Length': body.length
+    }),
+    maxBodyLength: Infinity,
+    maxContentLength: Infinity
+  });
+  return res.data;
+}
+
+/**
+ * Tag the source repository and publish a release carrying the source zip.
+ *
+ * Resolves with a summary; throws on failure. Callers are expected to treat a failure as a
+ * warning: by the time this runs the IG itself is already published.
+ */
+async function publishRelease(opts) {
+  const {
+    config, org, repo, tag, sha, releaseName, body, zipPath, assetName
+  } = opts;
+  const http = opts.http || axios;
+  const log = opts.log || function () {};
+
+  if (!isConfigured(config)) {
+    throw new Error('GitHub App is not configured');
+  }
+  if (!fs.existsSync(zipPath)) {
+    throw new Error('Source zip not found at ' + zipPath);
+  }
+
+  const token = await installationToken(config, org, http);
+  const headers = apiHeaders('Bearer ' + token);
+  const repoUrl = API_ROOT + '/repos/' + org + '/' + repo;
+
+  const tagCreated = await ensureTag(repoUrl, tag, sha, headers, http, log);
+  const releaseReplaced = await replaceExistingRelease(repoUrl, tag, headers, http, log);
+
+  const created = await http.post(repoUrl + '/releases', {
+    tag_name: tag,
+    name: releaseName,
+    body: body || '',
+    draft: false,
+    prerelease: false
+  }, { headers });
+
+  await uploadAsset(created.data.upload_url, assetName, zipPath, headers, http);
+
+  log('info', (releaseReplaced ? 'Replaced' : 'Created') + ' release ' + tag + ' on ' + org + '/' +
+      repo + ' with ' + assetName + ' attached: ' + created.data.html_url);
+
+  return {
+    tagCreated: tagCreated,
+    releaseReplaced: releaseReplaced,
+    url: created.data.html_url
+  };
+}
+
+module.exports = {
+  isConfigured,
+  installationIdFor,
+  appJwt,
+  installationToken,
+  publishRelease
+};

package/publisher/publisher.js

@@ -2,6 +2,8 @@ const express = require('express');
 const path = require('path');
 const fs = require('fs');
 const validation = require('./validation');
+const gitRemote = require('./git-remote');
+const githubRelease = require('./github-release');
 const Database = require('sqlite3').Database;
 const bcrypt = require('bcrypt');
 const session = require('express-session');
@@ -150,6 +152,7 @@ class PublisherModule {
                                           build_output_path TEXT,
                                           failure_reason TEXT,
                                           announcement TEXT,
+                                          release_url TEXT,
                                           approved_by INTEGER,
                                           queued_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                                           building_at DATETIME,
@@ -235,6 +238,17 @@ class PublisherModule {
         });
       });
     }
+    if (!columnNames.includes('release_url')) {
+      await new Promise((resolve, reject) => {
+        this.db.run('ALTER TABLE tasks ADD COLUMN release_url TEXT', (err) => {
+          if (err) reject(err);
+          else {
+            this.logger.info('Migration: added release_url column to tasks table');
+            resolve();
+          }
+        });
+      });
+    }
     const websiteColumns = await new Promise((resolve, reject) => {
       this.db.all("PRAGMA table_info(websites)", (err, rows) => {
         if (err) reject(err);
@@ -722,7 +736,7 @@ class PublisherModule {
 
   async cloneRepository(task, draftDir) {
     const { spawn } = require('child_process');
-    const gitUrl = 'https://github.com/' + task.github_org + '/' + task.github_repo + '.git';
+    const gitUrl = gitRemote.githubUrl(task.github_org, task.github_repo);
 
     await this.logTaskMessage(task.id, 'info', 'Cloning repository: ' + gitUrl + ' (branch: ' + task.git_branch + ')');
 
@@ -734,7 +748,10 @@ class PublisherModule {
         gitUrl,
         draftDir
       ], {
-        stdio: ['pipe', 'pipe', 'pipe']
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // no terminal prompt: a missing repo looks like a private one to GitHub, and
+        // git would otherwise ask for a username (see git-remote.js)
+        env: gitRemote.gitEnv()
       });
 
       let stderr = '';
@@ -748,7 +765,10 @@ class PublisherModule {
           await this.logTaskMessage(task.id, 'info', 'Repository cloned successfully');
           resolve();
         } else {
-          const error = 'Git clone failed with code ' + code + ': ' + stderr;
+          const explained = gitRemote.explainCloneFailure(stderr, task.github_org, task.github_repo, task.git_branch);
+          const error = explained
+            ? 'Git clone failed: ' + explained
+            : 'Git clone failed with code ' + code + ': ' + stderr;
           await this.logTaskMessage(task.id, 'error', error);
           reject(new Error(error));
         }
@@ -868,6 +888,28 @@ class PublisherModule {
       errors.push('Version mismatch: task specifies "' + task.version + '" but build produced "' + qaData['ig-ver'] + '"');
     }
 
+    // publication-request.json is what the publication run actually follows - it decides the
+    // version folder the IG is published into. If it wasn't updated along with the IG, the run
+    // publishes the new content over the previous release's folder, so catch it here, before the
+    // task can be approved.
+    const prPath = path.join(draftDir, 'publication-request.json');
+    if (fs.existsSync(prPath)) {
+      let pr = null;
+      try {
+        pr = JSON.parse(fs.readFileSync(prPath, 'utf8'));
+      } catch (e) {
+        errors.push('publication-request.json could not be parsed: ' + e.message);
+      }
+      if (pr) {
+        if (pr['package-id'] !== task.npm_package_id) {
+          errors.push('publication-request.json package-id is "' + pr['package-id'] + '" but the task specifies "' + task.npm_package_id + '"');
+        }
+        if (pr.version !== task.version) {
+          errors.push('publication-request.json version is "' + pr.version + '" but the task specifies "' + task.version + '" - update publication-request.json in the IG');
+        }
+      }
+    }
+
     if (errors.length > 0) {
       for (const err of errors) {
         await this.logTaskMessage(task.id, 'error', err);
@@ -950,10 +992,14 @@ class PublisherModule {
       if (typeof json.url === 'string' && json.url.startsWith('file:')) {
         problems.push('url is a local file path (' + json.url + ')');
       }
+      if (json.version !== task.version) {
+        problems.push('its version is ' + json.version + ', not ' + task.version);
+      }
       if (problems.length > 0) {
-        throw new Error('Published package ' + pkgPath + ' is a draft build, not a publication build (' +
-            problems.join('; ') + '). The IG Publisher publication run likely skipped package ' +
-            'regeneration (e.g. a Jekyll/template failure). Not committing.');
+        throw new Error('Published package ' + pkgPath + ' is not the publication build of ' +
+            task.npm_package_id + '#' + task.version + ' (' + problems.join('; ') + '). ' +
+            'Either the IG Publisher publication run skipped package regeneration (e.g. a Jekyll/template ' +
+            'failure), or publication-request.json points at another version. Not committing.');
       }
       await this.logTaskMessage(task.id, 'info', 'Verified publication package: ' + pkgPath);
     }
@@ -1203,15 +1249,24 @@ class PublisherModule {
     // Step 7: Commit and push the ig-registry
     await this.logTaskMessage(task.id, 'info', 'Committing changes to ig-registry...');
     const registryCommitMsg = 'publish ' + task.npm_package_id + '#' + task.version;
-    await this.runCommand('git', ['commit', '-a', '-m', registryCommitMsg], { cwd: registryDir }, task.id, 'Committing ig-registry changes');
-    await this.runCommand('git', ['pull'], { cwd: registryDir }, task.id, 'Pulling latest ig-registry');
-    await this.runCommand('git', ['push'], { cwd: registryDir }, task.id, 'Pushing ig-registry changes');
+    // A republication of a version the registry already lists (a technical correction) leaves the
+    // registry as it was, and 'git commit' fails on a clean tree - which is not an error here.
+    const registryStatus = await this.runCommand('git', ['status', '--porcelain', '--untracked-files=no'],
+        { cwd: registryDir }, task.id, 'Checking for ig-registry changes');
+    if (registryStatus.trim() === '') {
+      await this.logTaskMessage(task.id, 'warn', 'The publication run made no changes to the ig-registry - nothing to commit');
+    } else {
+      await this.runCommand('git', ['commit', '-a', '-m', registryCommitMsg], { cwd: registryDir }, task.id, 'Committing ig-registry changes');
+      await this.runCommand('git', ['pull'], { cwd: registryDir }, task.id, 'Pulling latest ig-registry');
+      await this.runCommand('git', ['push'], { cwd: registryDir }, task.id, 'Pushing ig-registry changes');
+    }
 
     // Step 8: Read the announcement text and store it in the database
+    let announcement = null;
     const announcementPath = path.join(zipsDir, task.npm_package_id + '#' + task.version + '-announcement.txt');
     if (fs.existsSync(announcementPath)) {
       try {
-        const announcement = fs.readFileSync(announcementPath, 'utf8');
+        announcement = fs.readFileSync(announcementPath, 'utf8');
         await this.updateTaskFields(task.id, { announcement: announcement });
         await this.logTaskMessage(task.id, 'info', 'Announcement text saved (' + announcement.length + ' chars)');
       } catch (err) {
@@ -1221,6 +1276,9 @@ class PublisherModule {
       await this.logTaskMessage(task.id, 'warn', 'No announcement file found at ' + announcementPath);
     }
 
+    // Step 8b: Tag the source repository and publish a GitHub release carrying its source zip
+    await this.createSourceRelease(task, draftDir, zipsDir, announcement);
+
     // Step 9: Run the website update script
     if (website.server_update_script) {
       await this.logTaskMessage(task.id, 'info', 'Running website update script: ' + website.server_update_script);
@@ -1228,6 +1286,60 @@ class PublisherModule {
     }
   }
 
+  // Tag the IG source repository and publish a GitHub release with a zip of the source at the
+  // commit that was published. Runs only when a GitHub App is configured; without one there is no
+  // credential that can write to the source repository, and the step is skipped.
+  //
+  // Nothing here is allowed to fail the task. By the time this runs the IG is published, the web
+  // folder is pushed and the registry is updated - a release that did not get made is worth a
+  // warning in the log and nothing more.
+  async createSourceRelease(task, draftDir, zipsDir, announcement) {
+    const appConfig = this.config && this.config['github-app'];
+    if (!githubRelease.isConfigured(appConfig)) {
+      await this.logTaskMessage(task.id, 'info',
+          'No GitHub App configured - skipping the source tag and release');
+      return;
+    }
+
+    try {
+      // The draft clone is the exact tree that was published, so its HEAD is the commit the
+      // release should point at.
+      const sha = (await this.runCommand('git', ['rev-parse', 'HEAD'], { cwd: draftDir },
+          task.id, 'Reading the published commit')).trim();
+
+      // git archive takes the committed state, not the working directory: by now the publisher has
+      // built in this folder twice and left output/, temp/, template/ and fsh-generated/ behind,
+      // none of which are in the archive. It is also exactly reproducible from the tag.
+      const stem = task.npm_package_id + '-' + task.version;
+      const assetName = stem + '-source.zip';
+      const zipPath = path.join(zipsDir, assetName);
+      await this.runCommand('git',
+          ['archive', '--format=zip', '--prefix=' + stem + '/', '-o', zipPath, 'HEAD'],
+          { cwd: draftDir }, task.id, 'Building the source zip');
+
+      const result = await githubRelease.publishRelease({
+        config: appConfig,
+        org: task.github_org,
+        repo: task.github_repo,
+        tag: 'v' + task.version,
+        sha: sha,
+        releaseName: task.npm_package_id + '#' + task.version,
+        body: announcement || '',
+        zipPath: zipPath,
+        assetName: assetName,
+        // logTaskMessage never rejects, and github-release logs without waiting
+        log: (level, message) => { void this.logTaskMessage(task.id, level, message); }
+      });
+
+      await this.updateTaskFields(task.id, { release_url: result.url });
+    } catch (err) {
+      const detail = (err.response && err.response.data && err.response.data.message) || err.message;
+      await this.logTaskMessage(task.id, 'warn',
+          'Could not tag and release the source repository: ' + detail +
+          '. The IG itself is published - this does not affect it.');
+    }
+  }
+
   async runPublisherGoPublish(taskId, publisherJar, sourceDir, webDir, registryDir, historyDir, templatesDir, zipsDir, logFile) {
     const { spawn } = require('child_process');
 
@@ -1692,6 +1804,18 @@ class PublisherModule {
           return res.status(400).send('An active task for this package and version is already in progress. Wait for it to complete or fail before resubmitting.');
         }
 
+        // Check the repo and branch actually exist before queueing, so a typo is
+        // reported now rather than when the build starts. If GitHub can't be
+        // reached, don't block - the clone will report any real problem.
+        const remote = await gitRemote.checkRemoteBranch(github_org, github_repo, git_branch);
+        if (!remote.ok) {
+          if (remote.unreachable) {
+            this.logger.warn('Could not verify ' + github_org + '/' + github_repo + '#' + git_branch + ' before queueing: ' + remote.error);
+          } else {
+            return res.status(400).send('Invalid task details: ' + remote.error);
+          }
+        }
+
         // Insert task (ID will be auto-generated)
         const result = await new Promise((resolve, reject) => {
           this.db.run(
@@ -1908,6 +2032,9 @@ class PublisherModule {
           let content = '<h3>Task Output: #' + task.id + ' - ' + escape(task.npm_package_id) + '#' + escape(task.version) + '</h3>';
           content += '<p><strong>Status:</strong> <span class="badge bg-' + this.getStatusColor(task.status) + '">' + escape(task.status) + '</span></p>';
           content += '<p><strong>GitHub:</strong> ' + escape(task.github_org) + '/' + escape(task.github_repo) + ' (' + escape(task.git_branch) + ')</p>';
+          if (task.release_url) {
+            content += '<p><strong>Release:</strong> <a href="' + escape(task.release_url) + '" target="_blank" rel="noopener noreferrer">' + escape(task.release_url) + '</a></p>';
+          }
 
           if (task.publisher_version) {
             content += '<p><strong>IG Publisher:</strong> <code>' + escape(task.publisher_version) + '</code></p>';
@@ -2053,6 +2180,9 @@ class PublisherModule {
         content += '</div>';
         content += '<div class="col-md-6">';
         content += '<p><strong>GitHub:</strong> ' + escape(task.github_org) + '/' + escape(task.github_repo) + ' (' + escape(task.git_branch) + ')</p>';
+        if (task.release_url) {
+          content += '<p><strong>Release:</strong> <a href="' + escape(task.release_url) + '" target="_blank" rel="noopener noreferrer">' + escape(task.release_url) + '</a></p>';
+        }
         content += '<p><strong>Created by:</strong> ' + escape(task.user_name) + ' (' + escape(task.user_login) + ')</p>';
         if (task.approved_by_name) {
           content += '<p><strong>Approved by:</strong> ' + escape(task.approved_by_name) + '</p>';
@@ -2747,10 +2877,12 @@ class PublisherModule {
     await this.logTaskMessage(taskId, 'info', description);
 
     return new Promise((resolve, reject) => {
-      const proc = spawn(command, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        ...options
-      });
+      const spawnOptions = { stdio: ['pipe', 'pipe', 'pipe'], ...options };
+      if (command === 'git') {
+        // never let git block on (or fail obscurely at) a credentials prompt
+        spawnOptions.env = gitRemote.gitEnv(spawnOptions.env || process.env);
+      }
+      const proc = spawn(command, args, spawnOptions);
 
       let stdout = '';
       let stderr = '';

package/server.js

@@ -16,6 +16,7 @@ const folders = require('./library/folder-setup');  // <-- ADD: load early
 const { statSync, readdirSync } = require('fs');
 const escape = require('escape-html');
 const { resolveWithin } = require('./library/path-safety');
+const { readCgroupMemoryLimit } = require('./library/cgroup-memory');
 
 // Load configuration BEFORE logger
 let config;
@@ -39,6 +40,12 @@ serverLog.info(`========================================`);
 serverLog.info(`FHIRsmith v${packageJson.version} starting (PID ${process.pid})`);
 serverLog.info(`Node.js ${process.version} on ${os.type()} ${os.release()} (${os.arch()})`);
 serverLog.info(`Memory: ${freeMemGB} GB free / ${totalMemGB} GB total`);
+{
+  const cg = readCgroupMemoryLimit();
+  serverLog.info(cg.limit > 0
+    ? `Memory limit: ${(cg.limit / 1024 / 1024 / 1024).toFixed(1)} GB (from ${cg.source})`
+    : 'Memory limit: none found in cgroup - RSS guard disabled');
+}
 serverLog.info(`Data directory: ${folders.dataDir()}`);
 serverLog.info(`========================================`);
 
@@ -57,6 +64,7 @@ const PublisherModule = require('./publisher/publisher.js');
 const TokenModule = require('./token/token.js');
 const NpmProjectorModule = require('./npmprojector/npmprojector.js');
 const TXModule = require('./tx/tx.js');
+const TestingModule = require('./testing/testing.js');
 
 const htmlServer = require('./library/html-server');
 const ServerStats = require("./stats");
@@ -219,6 +227,18 @@ async function initializeModules() {
       throw error;
     }
   }
+  if (config.modules?.testing?.enabled) {
+    try {
+      serverLog.info('Initializing module: testing...');
+      modules.testing = new TestingModule(stats.forModule('testing'));
+      await modules.testing.initialize(config.modules.testing);
+      app.use('/testing', modules.testing.router);
+    } catch (error) {
+      serverLog.error('Failed to initialize testing module:', error);
+      throw error;
+    }
+  }
+
   // Initialize TX module
   // Note: TX module registers its own endpoints directly on the app
   // because it supports multiple endpoints at different paths
@@ -346,6 +366,13 @@ async function buildRootPageContent() {
     content += '</li>';
   }
 
+  if (config.modules?.testing?.enabled) {
+    content += '<li class="list-group-item">';
+    content += '<a href="/testing" class="text-decoration-none">Test Reports</a>: ';
+    content += 'TestReports submitted by TxTester and other test tools';
+    content += '</li>';
+  }
+
   if (config.modules.folder && config.modules.folder.enabled) {
     content += '<li class="list-group-item">';
     content += '<strong>Cache Folder</strong>: ';
@@ -405,13 +432,7 @@ async function buildRootPageContent() {
 
   // Process RSS vs cgroup limit (or system total)
   const rssMB = (memUsage.rss / 1024 / 1024).toFixed(0);
-  let memLimit;
-  try {
-    const raw = fs.readFileSync('/sys/fs/cgroup/memory.max', 'utf8').trim();
-    memLimit = raw === 'max' ? os.totalmem() : parseInt(raw);
-  } catch {
-    memLimit = os.totalmem();
-  }
+  const memLimit = readCgroupMemoryLimit().limit || os.totalmem();
   const memLimitMB = (memLimit / 1024 / 1024).toFixed(0);
   const processPCT = (memUsage.rss * 100) / memLimit;
 
@@ -440,6 +461,15 @@ async function buildRootPageContent() {
   content += `<td><strong>Client Cache:</strong> ${stats.clientCaches()} caches / ${stats.clientConcepts()} concepts</td>`;
   content += `<td><strong>Max Client Cache:</strong> ${stats.maxClientCaches()} caches / ${stats.maxClientConcepts()} concepts</td>`;
   content += '</tr>';
+  const closure = stats.closureStats();
+  if (closure) {
+    content += '<tr>';
+    content += `<td><strong>Closure Tables:</strong> ${closure.tables} tables` +
+      (closure.retentionDays ? ` (unused for ${closure.retentionDays} days = deleted)` : '') + `</td>`;
+    content += `<td><strong>Closure Entries:</strong> ${closure.entries} entries / ${closure.concepts} concepts</td>`;
+    content += `<td><strong>Closure Database:</strong> ${closure.bytes === null ? 'in memory' : formatBytes(closure.bytes)}</td>`;
+    content += '</tr>';
+  }
   content += getLogStats();
   content += '</table>';
 
@@ -591,13 +621,7 @@ app.get('/dashboard', async (req, res) => {
     const v8PCT = (memUsage.heapUsed * 100) / heapStats.heap_size_limit;  // % of V8 heap limit used
 
     // Process RSS as % of cgroup memory limit (or system total as fallback)
-    let memLimit;
-    try {
-      const raw = fs.readFileSync('/sys/fs/cgroup/memory.max', 'utf8').trim();
-      memLimit = raw === 'max' ? os.totalmem() : parseInt(raw);
-    } catch {
-      memLimit = os.totalmem();
-    }
+    const memLimit = readCgroupMemoryLimit().limit || os.totalmem();
     const processPCT = (memUsage.rss * 100) / memLimit;
 
     const totalMemBytes = os.totalmem();
@@ -649,6 +673,19 @@ app.get('/dashboard', async (req, res) => {
   }
 });
 
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} bytes`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  if (bytes < 1024 * 1024 * 1024) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  }
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+
 function pctColor(pct) {
   // Gradient from green (#deffe0) at 0% to red (#ffd3d1) at 100%
   const t = Math.max(0, Math.min(100, pct)) / 100;

package/stats.js

@@ -124,20 +124,13 @@ class ServerStats {
       // event-loop block into noise; the max is what shows request-freezing
       // stalls (see the 2026-07-30 tx.fhir.org incident).
       const loopMax = this.eventLoopMonitor.max / 1e6;
-      // Two distinct caches: the expansion cache (count entries) and the client
-      // (resource) cache (count concepts held - a sense of how much it's carrying).
-      let expansionItems = 0;
-      let clientConcepts = 0;
-      for (let m of this.cachingModules) {
-        if (typeof m.expansionItemCount === 'function') {
-          expansionItems = expansionItems + m.expansionItemCount();
-        }
-        if (typeof m.clientConceptCount === 'function') {
-          clientConcepts = clientConcepts + m.clientConceptCount();
-        }
-      }
+      // The client (resource) cache, as concepts held - a sense of how much it's carrying.
+      // (The expansion cache isn't tracked over time: it fills to its limit over a few
+      // days and then sits there, so a history of it says nothing. The home page still
+      // shows its current size.)
+      const clientConcepts = this._sumCachingModules('clientConceptCount');
 
-      this.history.push({time: now, mem: currentMem - this.startMem, rpm: requestsPerMin, tat: requestsTat, block: loopDelay, blockMax: loopMax, expansion: expansionItems, clientConcepts: clientConcepts});
+      this.history.push({time: now, mem: currentMem - this.startMem, rpm: requestsPerMin, tat: requestsTat, block: loopDelay, blockMax: loopMax, clientConcepts: clientConcepts});
 
       this.eventLoopMonitor.reset();
       this.requestCountSnapshot = combinedCount;
@@ -328,6 +321,19 @@ class ServerStats {
   maxClientCaches() { return this._sumCachingModules('maxClientCacheCount'); }
   maxClientConcepts() { return this._sumCachingModules('maxClientConceptCount'); }
 
+  // $closure usage, from whichever module keeps closure tables; null if none does
+  closureStats() {
+    for (let m of this.cachingModules) {
+      if (typeof m.closureStats === 'function') {
+        const s = m.closureStats();
+        if (s) {
+          return s;
+        }
+      }
+    }
+    return null;
+  }
+
   getTaskColor(status) {
     switch (status) {
       case "started": return "LightGrey";