fhirsmith 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to Health Intersections FHIRsmith will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.1] - 2026-10-16
+
+### Added
+
+- The dashboard always says which FHIRsmith release the server runs, and whether a newer one is available (looked up once a day with the npm audit check; before, the latest release was only looked up, and only mentioned, when the audit found something)
+- README: how to follow releases (GitHub release emails, the releases Atom feed, and the dashboard)
+
+### Fixed
+
+- Packages: SUSHI (and anything else using fhir-package-loader) couldn't download packages from this server: `GET /packages/{id}/{version}` returned the version's JSON document instead of the tarball (since 0.16.0). The rule was "JSON when Accept includes `application/json`", but fhir-package-loader downloads with axios's default `Accept: application/json, text/plain, */*`, and plenty of other HTTP clients send JSON alongside `*/*` by default without wanting it. The version document is now returned only when the request prefers JSON: a JSON type ranked above any `*/*`, `application/*` or tarball type by q-value (`application/json` alone, or `application/json, */*;q=0.1`). Everything else gets the tarball, and `FHIR-Package-Download` still forces it
+- A POST with no Content-Type now says so (it gave "Unsupported Media Type: " with nothing after it)
+- A form post whose Content-Type has a charset (`application/x-www-form-urlencoded; charset=UTF-8`) was refused as an unsupported media type
+- Links in published IGs to a resource by the id it had in its source (`ValueSet/2.16.840.1.113762.1.4.1`, from before ids were prefixed, as in `ValueSet/vsac-2.16.840.1.113762.1.4.1`) work again in a browser: a read of an id nothing has redirects to the one resource that had that id in its source, or lists them when there are several. Other requests still get a 404
+
+### Tx Conformance Statement
+
+FHIRsmith v0.16.1 passed all 3630 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.6, runner v7.0.2)
+
 ## [0.16.0] - 2026-10-15
 
 ### Security

package/README.md

@@ -259,7 +259,7 @@ Each GitHub Release includes:
     - `ghcr.io/healthintersections/fhirsmith:latest`
     - `ghcr.io/healthintersections/fhirsmith:vX.Y.Z`
     - `ghcr.io/healthintersections/fhirsmith:X.Y.Z`
-- **npm package** published to npmjs.org as `fhirsmith` *(if you add this)*
+- **npm package** published to npmjs.org as [`fhirsmith`](https://www.npmjs.com/package/fhirsmith)
 
 Release images carry OCI labels, so an image says which release it is without
 having to trust the tag it was pulled under:
@@ -271,6 +271,19 @@ docker inspect --format '{{json .Config.Labels}}' ghcr.io/healthintersections/fh
 `org.opencontainers.image.version` is the release, `.revision` the commit it was
 built from, and `.source` is what links the package to this repository on GHCR.
 
+### Tracking Releases
+
+Server administrators should follow releases: a server is only as safe as the
+release it runs.
+
+- **Email**: on the [GitHub repository](https://github.com/HealthIntersections/FHIRsmith),
+  choose **Watch → Custom → Releases**. Each release is emailed with its notes (needs a GitHub account)
+- **Atom feed**: `https://github.com/HealthIntersections/FHIRsmith/releases.atom` - each
+  entry carries the release notes, for a feed reader or a Slack/Teams feed integration
+- **The server itself**: once a day the server looks up the latest release on npm, and the
+  dashboard says whether a newer one is available (this is part of the npm audit check, so
+  `npmAudit.enabled = false` turns it off too)
+
 ### CI Images
 
 Every push to main also publishes `:cibuild` and `:cibuild-<sha>` to the same

package/gr.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash 
+git tag v$1
+git push origin v$1

package/library/npm-audit.js

@@ -13,8 +13,9 @@
 // Config (all optional), top level of config.json:
 //   "npmAudit": { "enabled": true, "intervalHours": 24 }
 //
-// Each check also looks up the latest fhirsmith release on npm, so the advice can say
-// whether upgrading will help. When this server is already on the latest release it won't:
+// Each check also looks up the latest fhirsmith release on npm. The dashboard always says
+// whether a newer release is available, and the advice about any findings says whether
+// upgrading will help. When this server is already on the latest release it won't:
 // npm ignores our package.json "overrides" for anything but a clone + npm ci, so an
 // npm-installed server can carry transitive versions the repo itself has overridden away.
 
@@ -185,6 +186,41 @@ class NpmAudit {
     return true;
   }
 
+  /**
+   * This server's own version, from package.json (collectPackages reads it too, but that
+   * can fail for reasons that have nothing to do with the version)
+   */
+  readInstalledVersion() {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(this.appDir, 'package.json'), 'utf8'));
+      if (pkg.version) {
+        this.installedVersion = pkg.version;
+      }
+    } catch (e) {
+      // leave it as it was
+    }
+  }
+
+  /**
+   * Dashboard line: this server's version, and whether there is a newer release
+   */
+  renderRelease() {
+    if (!this.installedVersion) {
+      return '';
+    }
+    let html = `<p><strong>FHIRsmith release:</strong> this server runs ${escape(this.installedVersion)}`;
+    const cmp = compareVersions(this.installedVersion, this.latestVersion);
+    if (cmp === null) {
+      html += ' (the latest release could not be checked)';
+    } else if (cmp < 0) {
+      html += ` - <span style="color:#b60">FHIRsmith ${escape(this.latestVersion)} is available</span>` +
+        ' (<a href="https://github.com/HealthIntersections/FHIRsmith/releases">release notes</a>)';
+    } else {
+      html += ', the latest release';
+    }
+    return html + '</p>';
+  }
+
   /**
    * Look up the latest fhirsmith release. A failure only means the advice is less specific,
    * so it is logged and otherwise ignored (the previous answer is kept)
@@ -227,6 +263,9 @@ class NpmAudit {
     if (this.stats) {
       this.stats.task('npm audit', 'Checking');
     }
+    // independent of the audit: failures here are logged and otherwise ignored
+    this.readInstalledVersion();
+    await this.checkLatest();
     try {
       const packages = this.collectPackages();
       const response = await axios.post(this.url, packages, {
@@ -255,7 +294,6 @@ class NpmAudit {
       this.lastError = null;
       const summary = this.summary();
       if (findings.length > 0) {
-        await this.checkLatest();
         if (this.logger) {
           this.logger.warn(`npm audit: ${summary} in ${this.packageCount} packages: ` +
             findings.map(f => `${f.name} (${f.severity}) ${f.url}`).join('; '));
@@ -356,6 +394,7 @@ class NpmAudit {
     if (!this.enabled) {
       return html + '<p><strong>npm audit:</strong> disabled (npmAudit.enabled = false)</p></div>';
     }
+    html += this.renderRelease();
     if (!this.checkedAt) {
       html += '<p><strong>npm audit:</strong> ';
       html += this.lastError ? `<span style="color:#b00">could not be run: ${escape(this.lastError)}</span>` : 'not run yet';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhirsmith",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "txVersion": "1.9.6",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",

package/packages/openapi.yaml

@@ -350,9 +350,12 @@ paths:
       summary: Download a package tarball, or get a version's document
       description: |
         Returns the package tarball (`.tgz`) - or, when the request's `Accept` header
-        asks for `application/json` (or npm's `application/vnd.npm.install-v1+json`),
-        the version's npm document: the same object as that version's entry in the
-        package document. The response varies on `Accept` and `FHIR-Package-Download`.
+        prefers JSON, the version's npm document: the same object as that version's entry
+        in the package document. Preferring JSON means ranking `application/json` (or npm's
+        `application/vnd.npm.install-v1+json`) above any `*/*`, `application/*` or tarball
+        type by q-value: `application/json` alone does, but `application/json, text/plain, */*`
+        (axios's default, which SUSHI sends) does not. The response varies on `Accept` and
+        `FHIR-Package-Download`.
 
         A request with a `FHIR-Package-Download` header always gets the tarball. The
         HL7 Java tools send it; a client that downloads tarballs from this URL while

package/packages/packages.js

@@ -944,11 +944,13 @@ class PackagesModule {
     }
   }
 
-  stopCrawlerJob() {
+  // node-cron 4: stop() may return a promise
+  async stopCrawlerJob() {
     if (this.crawlerJob) {
       this.crawler.shutdown();
-      this.crawlerJob.stop();
+      const job = this.crawlerJob;
       this.crawlerJob = null;
+      await job.stop();
       pckLog.info('Package crawler job stopped');
     }
   }
@@ -1831,14 +1833,34 @@ class PackagesModule {
     res.send(htmlServer.renderPage('packages', 'npm Registry Check', content, stats));
   }
 
-  // GET /{id}/{version} is npm's version document when the request asks for JSON, and the
-  // tarball otherwise - which is what FHIR clients have always got there, without asking
-  // for JSON. A request carrying the TARBALL_HEADER always gets the tarball.
+  // GET /{id}/{version} is npm's version document when the request prefers JSON, and the
+  // tarball otherwise - which is what FHIR clients have always got there. Preferring JSON
+  // means ranking it above anything else the request accepts: a JSON type with a higher q
+  // than any */*, application/* or tarball type. Many clients send JSON together with */*
+  // at the same q - axios's default, application/json, text/plain, */*, which is what
+  // SUSHI (fhir-package-loader) sends when it downloads a tarball from here - and they get
+  // the tarball. A request carrying the TARBALL_HEADER always gets the tarball.
   wantsVersionDocument(req) {
     if (req.get(TARBALL_HEADER) !== undefined) {
       return false;
     }
-    return /application\/(json|vnd\.npm\.install-v1\+json)/i.test(req.get('accept') || '');
+    let json = 0;
+    let other = 0;
+    for (const part of String(req.get('accept') || '').split(',')) {
+      const [type, ...params] = part.split(';').map(s => s.trim().toLowerCase());
+      const qParam = params.find(p => p.startsWith('q='));
+      const q = qParam ? parseFloat(qParam.substring(2)) : 1;
+      if (!type || Number.isNaN(q)) {
+        continue;
+      }
+      if (type === 'application/json' || type === 'application/vnd.npm.install-v1+json') {
+        json = Math.max(json, q);
+      } else if (['*/*', 'application/*', 'application/tar+gzip', 'application/gzip', 'application/x-gzip',
+        'application/x-tar', 'application/octet-stream'].includes(type)) {
+        other = Math.max(other, q);
+      }
+    }
+    return json > 0 && json > other;
   }
 
   async serveVersionDocument(secure, id, version, req, res) {
@@ -2844,7 +2866,7 @@ class PackagesModule {
   async shutdown() {
     pckLog.info('Shutting down Packages module...');
 
-    this.stopCrawlerJob();
+    await this.stopCrawlerJob();
 
     // Close database connection
     if (this.db) {

package/packages/readme.md

@@ -31,7 +31,7 @@ In summary:
 | `GET /packages/catalog` | Search packages: `name`, `canonical`, `pkgcanonical`, `fhirversion`, `dependency`, `dependson`, `sort` |
 | `GET /packages/-/v1/search` | npm search API: `text`, `size`, `from`, plus the `/catalog` parameters |
 | `GET /packages/{id}` | npm package document: all versions, dependencies, tarball URLs |
-| `GET /packages/{id}/{version}` | Download a package tarball; or, when the request's `Accept` asks for JSON, npm's document for that version. A `FHIR-Package-Download` header always gets the tarball (the HL7 Java tools send it) |
+| `GET /packages/{id}/{version}` | Download a package tarball; or, when the request's `Accept` prefers JSON (ranks it above `*/*`), npm's document for that version. A `FHIR-Package-Download` header always gets the tarball (the HL7 Java tools send it) |
 | `GET /packages/updates` | Versions published since a date |
 | `GET /packages/broken` | Package versions whose dependencies this registry doesn't hold |
 | `GET /packages/npm-check` | Check any registry against the npm registry protocol (a form, in a browser) |

package/shl/shl.js

@@ -418,10 +418,12 @@ class SHLModule {
     }
   }
 
-  stopCleanupJob() {
+  // node-cron 4: stop() may return a promise
+  async stopCleanupJob() {
     if (this.cleanupJob) {
-      this.cleanupJob.stop();
+      const job = this.cleanupJob;
       this.cleanupJob = null;
+      await job.stop();
     }
   }
 
@@ -1060,7 +1062,7 @@ class SHLModule {
   async shutdown() {
     shlLog.info('Shutting down SHL module...');
 
-    this.stopCleanupJob();
+    await this.stopCleanupJob();
 
     // Stop FHIR validator
     if (this.fhirValidator) {

package/tx/library/resource-ids.js

@@ -58,6 +58,21 @@ function stripIdPrefix(id, spaceId) {
   return id.startsWith(prefix) && id.length > prefix.length ? id.substring(prefix.length) : null;
 }
 
+/**
+ * The id a resource had in its source, for an id in any id space: everything after the
+ * prefix, which never contains a '-' (see checkIdPrefix). Null if the id has no prefix.
+ *
+ * @param {string} id
+ * @returns {string|null}
+ */
+function originalId(id) {
+  if (typeof id !== 'string') {
+    return null;
+  }
+  const i = id.indexOf('-');
+  return i > 0 && i < id.length - 1 ? id.substring(i + 1) : null;
+}
+
 /**
  * Whether a prefix given in the library YAML is acceptable. It's the start of an id, so it
  * may only use id characters, and no '-', so that the prefix of any id is unambiguous.
@@ -104,4 +119,4 @@ function assignIdSpace(provider, spaceId) {
 
 const CORE_PREFIX = 'core';
 
-module.exports = { applyIdPrefix, stripIdPrefix, checkIdPrefix, assignIdSpace, CORE_PREFIX };
+module.exports = { applyIdPrefix, stripIdPrefix, originalId, checkIdPrefix, assignIdSpace, CORE_PREFIX };

package/tx/tx-html.js

@@ -1329,6 +1329,30 @@ class TxHtmlRenderer {
     return html;
   }
 
+  /**
+   * The page for a read of an id that nothing has, but that several resources had in their
+   * source (see ReadWorker.notFound): a list of them, to pick from.
+   *
+   * @param {string} resourceType
+   * @param {string} id - the id that was asked for
+   * @param {Array<{id, url, version, title, source}>} matches
+   * @returns {string} html
+   */
+  renderIdChoices(resourceType, id, matches) {
+    let html = `<p>There is no ${escape(resourceType)} with the id <code>${escape(id)}</code> on this server. ` +
+      `Every resource here has an id that starts with a prefix for the source it came from, and ` +
+      `${matches.length} ${escape(resourceType)} resources had the id <code>${escape(id)}</code> in their source:</p>`;
+    html += '<table class="grid"><tr><th>Id</th><th>URL</th><th>Version</th><th>Title</th><th>Source</th></tr>';
+    for (const m of matches) {
+      // relative to /{type}/{id}, like the redirect when there is only one
+      html += `<tr><td><a href="${escape(encodeURIComponent(m.id))}">${escape(m.id)}</a></td>` +
+        `<td>${escape(m.url || '')}</td><td>${escape(m.version || '')}</td>` +
+        `<td>${escape(m.title || '')}</td><td>${escape(m.source || '')}</td></tr>`;
+    }
+    html += '</table>';
+    return html;
+  }
+
   /**
    * Render Bundle resource
    */

package/tx/tx.js

@@ -516,8 +516,12 @@ class TXModule {
             return res.status(400).json(buildOperationOutcome('error', 'invalid', `Invalid XML: ${e.message}`));
           }
         }
-      } else if (contentType != 'application/x-www-form-urlencoded') {
-        return res.status(415).json(buildOperationOutcome('error', 'invalid', `Unsupported Media Type: ${contentType}`));
+      } else if (contentType.split(';')[0].trim().toLowerCase() != 'application/x-www-form-urlencoded') {
+        // compare the media type alone: a form post may carry a charset parameter
+        const message = contentType
+          ? `Unsupported Media Type: ${contentType}`
+          : `No Content-Type was given for this ${req.method}; use application/fhir+json or application/fhir+xml`;
+        return res.status(415).json(buildOperationOutcome('error', 'invalid', message));
       }
 
       if (req.body) {
@@ -994,7 +998,7 @@ class TXModule {
             ));
           }
           let worker = new ReadWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
-          await worker.handle(req, res, resourceType);
+          await worker.handle(req, res, resourceType, (req, res, resourceType, id, matches) => this.renderIdChoices(req, res, resourceType, id, matches));
         } finally {
           this.countRequest(endpointPath, 'read', Date.now() - start);
         }
@@ -1432,6 +1436,17 @@ class TXModule {
     return count;
   }
 
+  // A read of an unprefixed id that several resources had in their source: the page
+  // that lists them (status 300, Multiple Choices). See ReadWorker.notFound.
+  async renderIdChoices(req, res, resourceType, id, matches) {
+    const txhtml = new TxHtmlRenderer(new Renderer(req.txOpContext, req.txEndpoint.provider), this.liquid, this.languages, this.i18n, req.txEndpoint.path);
+    const content = txhtml.renderIdChoices(resourceType, id, matches);
+    const html = await txhtml.renderPage(`${resourceType}/${id}`, content, req.txEndpoint, req.txStartTime);
+    res.status(300);
+    res.setHeader('Content-Type', 'text/html');
+    return res.send(html);
+  }
+
   // $closure usage for the home page: null when closure isn't turned on
   closureStats() {
     if (!this.closureStore) {

package/tx/workers/read.js

@@ -8,6 +8,9 @@ const { TerminologyWorker } = require('./worker');
 const {debugLog} = require("../operation-context");
 
 const { buildOperationOutcome } = require('../library/operation-outcome');
+const { originalId } = require('../library/resource-ids');
+const { acceptsHtml } = require('../tx-html');
+
 class ReadWorker extends TerminologyWorker {
   /**
    * @param {OperationContext} opContext - Operation context
@@ -32,10 +35,12 @@ class ReadWorker extends TerminologyWorker {
    * @param {express.Request} req - Express request (with txProvider attached)
    * @param {express.Response} res - Express response
    * @param {string} resourceType - The resource type (CodeSystem, ValueSet, ConceptMap)
-   * @param {Object} log - Logger instance
+   * @param {Function} [renderChoices] - (req, res, resourceType, id, matches) renders the
+   *   page that lists the resources an unprefixed id could mean (see notFound)
    */
-  async handle(req, res, resourceType) {
+  async handle(req, res, resourceType, renderChoices = null) {
     const { id } = req.params;
+    this.renderChoices = renderChoices;
 
     this.log.debug(`Read ${resourceType}/${id}`);
 
@@ -114,7 +119,7 @@ class ReadWorker extends TerminologyWorker {
       }
     }
 
-    return res.status(404).json(buildOperationOutcome('error', 'not-found', `CodeSystem/${id} not found`));
+    return await this.notFound(req, res, 'CodeSystem', id);
   }
 
   /**
@@ -131,7 +136,7 @@ class ReadWorker extends TerminologyWorker {
       }
     }
 
-    return res.status(404).json(buildOperationOutcome('error', 'not-found', `ValueSet/${id} not found`));
+    return await this.notFound(req, res, 'ValueSet', id);
   }
   /**
    * Handle ConceptMap read
@@ -147,7 +152,84 @@ class ReadWorker extends TerminologyWorker {
       }
     }
 
-    return res.status(404).json(buildOperationOutcome('error', 'not-found', `ConceptMap/${id} not found`));
+    return await this.notFound(req, res, 'ConceptMap', id);
+  }
+
+  /**
+   * Nothing has the id asked for. Published IGs link to resources by the id they had in
+   * their source (ValueSet/2.16.840.1.113762.1.4.1), from before every id was put in its
+   * provider's id space (ValueSet/vsac-2.16.840.1.113762.1.4.1). So for a browser, look
+   * for resources that had that id in their source: if there's one, redirect to it, and
+   * if there are several, list them. Anything other than a browser still gets a 404 -
+   * an unprefixed id can't say which resource it means (see library/resource-ids.js).
+   */
+  async notFound(req, res, resourceType, id) {
+    if (this.renderChoices && acceptsHtml(req)) {
+      const matches = await this.findByOriginalId(resourceType, id);
+      if (matches.length === 1) {
+        req.logInfo = `redirected to ${matches[0].id}`;
+        // relative, so that it works whatever path the server is behind; keeps the query
+        const q = req.originalUrl.indexOf('?');
+        return res.redirect(302, encodeURIComponent(matches[0].id) + (q >= 0 ? req.originalUrl.substring(q) : ''));
+      }
+      if (matches.length > 1) {
+        req.logInfo = `${matches.length} matches`;
+        return await this.renderChoices(req, res, resourceType, id, matches);
+      }
+    }
+    return res.status(404).json(buildOperationOutcome('error', 'not-found', `${resourceType}/${id} not found`));
+  }
+
+  /**
+   * The resources of a type that had this id in their source, across all the providers.
+   *
+   * @returns {Promise<Array<{id, url, version, title, source}>>} in provider order
+   */
+  async findByOriginalId(resourceType, id) {
+    const found = [];
+    const add = (resource) => {
+      const json = resource.jsonObj || resource;
+      if (json.id && !found.some(m => m.id === json.id)) {
+        found.push({
+          id: json.id,
+          url: json.url || null,
+          version: json.version || null,
+          title: json.title || json.name || null,
+          source: typeof resource.sourcePackage === 'string' ? resource.sourcePackage : null
+        });
+      }
+    };
+
+    switch (resourceType) {
+      case 'CodeSystem':
+        // the map holds a code system under more than one key (url, url|version)
+        for (const cs of new Set(this.provider.codeSystems.values())) {
+          this.deadCheck('findByOriginalId-cs');
+          if (originalId(cs.jsonObj.id) === id) {
+            add(cs);
+          }
+        }
+        break;
+      case 'ValueSet':
+        for (const vsp of this.provider.valueSetProviders) {
+          this.deadCheck('findByOriginalId-vs');
+          const vs = vsp.spaceId ? await vsp.fetchValueSetById(`${vsp.spaceId}-${id}`) : null;
+          if (vs) {
+            add(vs);
+          }
+        }
+        break;
+      case 'ConceptMap':
+        for (const cmp of this.provider.conceptMapProviders) {
+          this.deadCheck('findByOriginalId-cm');
+          const cm = cmp.spaceId ? await cmp.fetchConceptMapById(`${cmp.spaceId}-${id}`) : null;
+          if (cm) {
+            add(cm);
+          }
+        }
+        break;
+    }
+    return found;
   }
 }