fhirsmith 0.14.1 → 0.15.0

package/registry/registry.js

@@ -9,6 +9,15 @@ const Logger = require('../library/logger');
 const regLog = Logger.getInstance().child({ module: 'registry' });
 const folders = require('../library/folder-setup');
 const escape = require('escape-html');
+const registryOpenApi = require('./openapi');
+const { FhirsmithReleases, isFhirsmith, describeAge } = require('./fhirsmith-releases');
+
+// The query parameters of the public API. These are the contract published in openapi.yaml,
+// and tests/registry/openapi.test.js checks that the two agree - so change both together.
+// Parameters are read leniently (a repeated parameter takes its first value, and unknown
+// parameters are ignored) because existing ecosystem clients rely on that.
+const DISCOVERY_PARAMS = ['registry', 'server', 'fhirVersion', 'url', 'authoritativeOnly', 'language'];
+const RESOLVE_PARAMS = ['fhirVersion', 'url', 'version', 'valueSet', 'authoritativeOnly', 'language', 'usage'];
 
 class RegistryModule {
   constructor(stats) {
@@ -50,6 +59,13 @@ class RegistryModule {
       // Initialize API with crawler
       this.api = new RegistryAPI(this.crawler);
 
+      // FHIRsmith release dates, for the software page. CHANGELOG.md until GitHub answers
+      this.releases = new FhirsmithReleases(crawlerConfig, this.logger);
+      this.releases.loadFromChangelog();
+      if (config.releasesUrl !== '') {
+        this.releases.refresh().catch(() => {});
+      }
+
       // Load saved data if available
       await this.loadSavedData();
 
@@ -145,6 +161,9 @@ class RegistryModule {
     try {
       // Perform the crawl
       const newData = await this.crawler.crawl(this.config.masterUrl);
+      if (this.releases && this.config.releasesUrl !== '') {
+        await this.releases.refresh();
+      }
 
       // Thread-safe update of current data
       await this.updateData(() => {
@@ -210,6 +229,9 @@ class RegistryModule {
       // Content Security Policy
       res.setHeader('Content-Security-Policy', "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'");
 
+      // RFC 8631: where to find the machine-readable description of this API
+      res.setHeader('Link', `<${req.baseUrl}/openapi.json>; rel="service-desc", <${req.baseUrl}/openapi>; rel="service-doc"`);
+
       next();
     });
   }
@@ -230,6 +252,36 @@ class RegistryModule {
     this.router.get('/', this.handleMainPage.bind(this));
     this.router.get('/resolve', this.handleResolveEndpoint.bind(this));
     this.router.get('/log', this.handleLogEndpoint.bind(this));
+    this.router.get('/software', this.handleSoftwarePage.bind(this));
+
+    // OpenAPI description of this API: /openapi.json, /openapi.yaml, and /openapi (an HTML
+    // reference for browsers, the JSON otherwise)
+    this.router.get('/openapi.json', (req, res) => {
+      res.type('application/json').send(registryOpenApi.getJson());
+    });
+    this.router.get('/openapi.yaml', (req, res) => {
+      res.setHeader('Content-Type', 'application/yaml');
+      res.send(registryOpenApi.getYaml());
+    });
+    this.router.get('/openapi', (req, res) => {
+      const acceptsHtml = req.headers.accept && req.headers.accept.includes('text/html');
+      if (!acceptsHtml) {
+        res.type('application/json').send(registryOpenApi.getJson());
+        return;
+      }
+      try {
+        if (!htmlServer.hasTemplate('registry')) {
+          htmlServer.loadTemplate('registry', path.join(__dirname, 'registry-template.html'));
+        }
+        const html = htmlServer.renderPage('registry', 'Terminology Server Registry API',
+          registryOpenApi.renderHtml(), this.api ? this.api.getStatistics() : {});
+        res.setHeader('Content-Type', 'text/html');
+        res.send(html);
+      } catch (error) {
+        this.logger.error('Error rendering OpenAPI page:', error);
+        res.status(500).send(`<html><body><h1>Error</h1><p>${escape(error.message)}</p></body></html>`);
+      }
+    });
   }
 
   /**
@@ -357,21 +409,23 @@ class RegistryModule {
       const acceptsHtml = req.headers.accept && req.headers.accept.includes('text/html');
 
       if (!acceptsHtml) {
-        // Return JSON overview
-        return res.json({
-          name: 'FHIR Terminology Server Registry',
-          description: 'Registry and discovery service for FHIR terminology servers',
-          endpoints: {
-            status: '/registry/api/status',
-            statistics: '/registry/api/stats',
-            registries: '/registry/api/registries',
-            queryCodeSystem: '/registry/api/query/codesystem',
-            queryValueSet: '/registry/api/query/valueset',
-            bestServer: '/registry/api/best-server/{type}',
-            errors: '/registry/api/errors'
-          },
-          documentation: 'https://github.com/your-org/fhir-registry'
-        });
+        // The ecosystem Discovery API
+        const params = this._normalizeQueryParams(req.query);
+        if (params.url && !this._isValidUrl(params.url.split('|')[0])) {
+          return res.status(400).json({error: 'Invalid code system URL format'});
+        }
+        try {
+          const filters = {};
+          for (const name of DISCOVERY_PARAMS) {
+            if (params[name]) {
+              filters[name] = params[name];
+            }
+          }
+          return res.json(this.api.discover(filters));
+        } catch (error) {
+          this.logger.error('Error in discovery:', error);
+          return res.status(500).json({error: error.message});
+        }
       }
 
       // Render HTML page
@@ -416,6 +470,132 @@ class RegistryModule {
     }
   }
 
+  /**
+   * The software page - what each registered server is running, and for FHIRsmith,
+   * how old that release is
+   */
+  async handleSoftwarePage(req, res) {
+    const start = Date.now();
+    try {
+      if (!htmlServer.hasTemplate('registry')) {
+        htmlServer.loadTemplate('registry', path.join(__dirname, 'registry-template.html'));
+      }
+      const startTime = Date.now();
+      const content = this.buildSoftwareContent();
+      const stats = this.api.getStatistics();
+      stats.processingTime = Date.now() - startTime;
+      const html = htmlServer.renderPage('registry', 'Terminology Server Software', content, stats);
+      res.setHeader('Content-Type', 'text/html');
+      res.send(html);
+    } catch (error) {
+      this.logger.error('Error rendering software page:', error);
+      res.status(500).send(`<html><body><h1>Error</h1><p>${escape(error.message)}</p></body></html>`);
+    } finally {
+      this.stats.countRequest('software', Date.now() - start);
+    }
+  }
+
+  buildSoftwareContent(now = Date.now()) {
+    const data = this.api.getData();
+    if (!data || !data.registries) {
+      return '<div class="alert alert-info"><h4>Registry data not yet available</h4>' +
+        '<p>The initial crawl is in progress. Please refresh in a moment.</p></div>';
+    }
+
+    const rows = [];
+    for (const registry of data.registries) {
+      for (const server of registry.servers || []) {
+        for (const version of server.versions || []) {
+          rows.push({
+            name: server.name || server.code || '',
+            url: version.address || '',
+            fhirVersion: version.version || '',
+            software: version.software && version.software !== 'unknown' ? version.software : '',
+            softwareVersion: version.softwareVersion || '',
+            softwareReleaseDate: version.softwareReleaseDate || '',
+            error: version.error,
+            lastSuccess: version.lastSuccess
+          });
+        }
+      }
+    }
+    rows.sort((a, b) => a.name.localeCompare(b.name) || a.url.localeCompare(b.url));
+
+    let html = '<h3>Terminology Server Software</h3>';
+    const latest = this.releases ? this.releases.latest() : null;
+    if (latest) {
+      html += `<p>The current FHIRsmith release is <b>v${escape(latest.version)}</b>, released ` +
+        `${escape(latest.date.toISOString().substring(0, 10))}. ` +
+        'Servers running older FHIRsmith releases are missing security fixes, both in FHIRsmith ' +
+        'and in the libraries it depends on, and should be upgraded.</p>';
+    }
+
+    html += '<table class="grid">';
+    html += '<thead><tr><th>Server</th><th>URL</th><th>FHIR</th><th>Software</th><th>Version</th>' +
+      '<th>Released</th><th>Age</th></tr></thead><tbody>';
+    for (const row of rows) {
+      html += '<tr>';
+      html += `<td>${escape(row.name)}</td>`;
+      html += `<td><a href="${escape(row.url)}" target="_blank" rel="noopener">${escape(row.url)}</a>`;
+      if (row.error) {
+        html += ` <span class="text-danger" title="${escape(row.error)}">(unreachable)</span>`;
+      }
+      html += '</td>';
+      html += `<td>${escape(row.fhirVersion)}</td>`;
+      html += `<td>${row.software ? escape(row.software.replace('Reference Server', 'HealthIntersections')) : '<i>unknown</i>'}</td>`;
+      html += `<td>${row.softwareVersion ? escape(row.softwareVersion) : '<i>unknown</i>'}</td>`;
+      html += this._renderReleaseCells(row, now);
+      html += '</tr>';
+    }
+    html += '</tbody></table>';
+
+    if (this.releases && this.releases.source !== 'none') {
+      html += `<p class="text-muted"><small>FHIRsmith release dates from ${escape(this.releases.source)}.</small></p>`;
+    }
+    return html;
+  }
+
+  _renderReleaseCells(row, now) {
+    if (!isFhirsmith(row.software) || !this.releases) {
+      return this._renderReportedReleaseCells(row, now);
+    }
+    const d = this.releases.describe(row.softwareVersion, now);
+    const behind = d.behind ? ` (${d.behind} release${d.behind === 1 ? '' : 's'} behind)` : '';
+    switch (d.status) {
+      case 'current':
+        return `<td>${d.release.date.toISOString().substring(0, 10)}</td>` +
+          `<td><span class="text-success">${describeAge(d.ageDays)} - current release</span></td>`;
+      case 'outdated': {
+        // more than 3 months, or more than 3 releases, out of date is flagged
+        const cls = d.ageDays > 90 || d.behind > 3 ? 'text-danger' : 'text-warning';
+        return `<td>${d.release.date.toISOString().substring(0, 10)}</td>` +
+          `<td><span class="${cls}">${describeAge(d.ageDays)}${behind}</span></td>`;
+      }
+      case 'dev':
+        return `<td>${this._reportedReleaseDay(row)}</td><td>development build` +
+          (d.release ? ` after v${escape(d.release.version)}` : '') + behind + '</td>';
+      default:
+        return this._renderReportedReleaseCells(row, now);
+    }
+  }
+
+  // what the server says about its release (CapabilityStatement.software.releaseDate) -
+  // the only source for software other than FHIRsmith
+  _reportedReleaseDay(row) {
+    // the day as the server gives it - converting to UTC can move it a day
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(row.softwareReleaseDate || '');
+    return m ? m[1] : '';
+  }
+
+  _renderReportedReleaseCells(row, now) {
+    const day = this._reportedReleaseDay(row);
+    if (!day) {
+      return '<td></td><td></td>';
+    }
+    const days = Math.max(0, Math.floor((now - new Date(row.softwareReleaseDate).getTime()) / (24 * 60 * 60 * 1000)));
+    return `<td>${day}</td><td>${describeAge(days)}</td>`;
+  }
+
   /**
    * Build HTML content for main page
    */
@@ -1086,10 +1266,6 @@ class RegistryModule {
           this.logger.info(`Resolved CodeSystem ${url} for FHIR ${fhirVersion} (usage=${usage}, language=${language || 'none'}): ${matches}`);
         }
 
-        // If only authoritative servers are requested, filter results
-        if (authoritativeOnly === 'true' && result) {
-          result.candidates = [];
-        }
         if (acceptsHtml) {
           try {
             const startTime = Date.now();
@@ -1456,4 +1632,7 @@ class RegistryModule {
   }
 }
 
+RegistryModule.DISCOVERY_PARAMS = DISCOVERY_PARAMS;
+RegistryModule.RESOLVE_PARAMS = RESOLVE_PARAMS;
+
 module.exports = RegistryModule;

package/server.js

@@ -17,6 +17,7 @@ const { statSync, readdirSync } = require('fs');
 const escape = require('escape-html');
 const { resolveWithin } = require('./library/path-safety');
 const { readCgroupMemoryLimit } = require('./library/cgroup-memory');
+const { NpmAudit } = require('./library/npm-audit');
 
 // Load configuration BEFORE logger
 let config;
@@ -110,10 +111,13 @@ app.use(cors(config.server.cors));
 const modules = {};
 
 let stats = null;
+// periodic npm advisory check of the installed packages - see library/npm-audit.js
+let npmAudit = null;
 
 // Initialize modules based on configuration
 async function initializeModules() {
   stats = new ServerStats(config.stats, serverLog);
+  npmAudit = new NpmAudit(config.npmAudit || {}, Logger.getInstance().child({ module: 'npm-audit' }), __dirname, stats);
 
   // Initialize SHL module
   if (config.modules?.shl?.enabled) {
@@ -305,7 +309,8 @@ async function loadTemplates() {
 
 async function buildRootPageContent() {
   stats.requestCount++;
-  let content = '<div class="row mb-4">';
+  let content = npmAudit ? npmAudit.renderBanner() : '';
+  content += '<div class="row mb-4">';
   content += '<div class="col-12">';
 
   content += '<h3>Available Modules</h3>';
@@ -314,7 +319,7 @@ async function buildRootPageContent() {
   // Check which modules are enabled and add them to the list
   if (config.modules.packages.enabled) {
     content += '<li class="list-group-item">';
-    content += '<a href="/packages" class="text-decoration-none">Package Server</a>: Browse and download FHIR Implementation Guide packages';
+    content += '<a href="/packages" class="text-decoration-none">Package Server</a>: Browse and download FHIR Implementation Guide packages (<a href="/packages/openapi">API</a>)';
     content += '</li>';
   }
 
@@ -339,7 +344,7 @@ async function buildRootPageContent() {
   if (config.modules.registry && config.modules.registry.enabled) {
     content += '<li class="list-group-item">';
     content += '<a href="/tx-reg" class="text-decoration-none">Terminology Server Registry</a>: ';
-    content += 'Discover and query FHIR terminology servers for code system and value set support';
+    content += 'Discover and query FHIR terminology servers for code system and value set support (<a href="/tx-reg/openapi">API</a>)';
     content += '</li>';
   }
 
@@ -374,7 +379,7 @@ async function buildRootPageContent() {
   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 += 'TestReports submitted by TxTester and other test tools (<a href="/testing/openapi">API</a>)';
     content += '</li>';
   }
 
@@ -402,7 +407,9 @@ async function buildRootPageContent() {
     if (config.modules.tx.endpoints && config.modules.tx.endpoints.length > 0) {
       content += '<ul class="mt-2 mb-0">';
       for (const endpoint of config.modules.tx.endpoints) {
-        content += `<li><a href="${endpoint.path}" class="text-decoration-none">${endpoint.path}</a> (FHIR v${endpoint.fhirVersion}${endpoint.context ? ', context: ' + endpoint.context : ''})</li>`;
+        // the OpenAPI description is for the R5 endpoints
+        const api = String(endpoint.fhirVersion).startsWith('5') ? ` (<a href="${endpoint.path}/openapi">API</a>)` : '';
+        content += `<li><a href="${endpoint.path}" class="text-decoration-none">${endpoint.path}</a> (FHIR v${endpoint.fhirVersion}${endpoint.context ? ', context: ' + endpoint.context : ''})${api}</li>`;
       }
       content += '</ul>';
     }
@@ -658,6 +665,9 @@ app.get('/dashboard', async (req, res) => {
       startTime: stats.startTime
     });
     content += stats.taskDetails();
+    if (npmAudit) {
+      content += npmAudit.renderDashboard();
+    }
     content += `<p>Data: ${folders.dataDir()}</p>`;
 
     content = '<div class="row mb-4"><div class="col-12">' + content + '</div></div>';
@@ -790,6 +800,7 @@ async function startServer() {
       stats.markStarted();
       serverLog.info(`=== Server running on http://localhost:${PORT} ===`);
     });
+    npmAudit.start();
     if (modules.packages && config.modules.packages.enabled) {
       modules.packages.startInitialCrawler();
     }
@@ -817,6 +828,9 @@ async function startServer() {
 // Graceful shutdown
 process.on('SIGINT', async () => {
   serverLog.info('\nShutting down server...');
+  if (npmAudit) {
+    npmAudit.stop();
+  }
 
   // Shutdown all modules
   for (const [moduleName, moduleInstance] of Object.entries(modules)) {

package/testing/openapi-schemas.config.js

@@ -0,0 +1,58 @@
+// What utilities/generate-openapi-schemas.js generates for the testing module's OpenAPI
+// description (into openapi-schemas.json, which the loader merges into openapi.yaml's
+// components). Regenerate after changing this:
+//
+//   node utilities/generate-openapi-schemas.js testing
+//
+// tests/testing/openapi.test.js fails if the generated file is out of date, and checks that
+// the overlay requires everything validateReport() in testing.js requires.
+
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+
+module.exports = {
+  package: 'hl7.fhir.r5.core#5.0.0',
+  roots: ['TestReport', 'OperationOutcome', 'Bundle'],
+
+  // reports may not contain resources (validateReport rejects them too)
+  prohibit: ['contained'],
+
+  overlay: {
+    TestReport: {
+      description: 'A TestReport, as this server accepts it: an R5 TestReport (or an R4 one - see testScript), ' +
+        'with name, tester, issued and at least one participant, and no contained resources.',
+      required: ['name', 'tester', 'issued', 'participant'],
+      properties: {
+        participant: { minItems: 1 },
+        testScript: {
+          $replace: true,
+          description: 'The TestScript that was run: a canonical (R5), or a Reference (R4)',
+          anyOf: [{ type: 'string' }, ref('Reference')]
+        }
+      }
+    },
+
+    // the search response: a Bundle of TestReports, plus an OperationOutcome entry
+    // (search.mode = outcome) when unknown parameters were ignored
+    TestReportSearchBundle: {
+      description: 'A searchset Bundle of TestReports',
+      allOf: [
+        ref('Bundle'),
+        {
+          type: 'object',
+          properties: {
+            type: { const: 'searchset' },
+            entry: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  resource: { anyOf: [ref('TestReport'), ref('OperationOutcome')] }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+};