fhirsmith 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -1,10 +1,56 @@
 # Changelog
 
-All notable changes to the Health Intersections Node Server will be documented in this file.
+All notable changes to Health Intersections FHIRsmith will be documented in this file.
 
 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.14.0] - 2026-09-27
+
+### Added
+
+- New Module: TestReport repository 
+- Initial Implementation of $closure
+- add support for caching across multiple servers
+- better support for web invocation of operations 
+- add ECL control panel
+
+### Changed
+
+- improve home page graphs and cache information
+- better memory management - prevent an operation running the server out of memory 
+- $validate-code: inferSystem is only applied to the code parameter, per its definition - it is ignored for coding and codeableConcept
+- $validate-code: a Coding with neither a system nor a code is reported as one problem, not two (Coding_has_no_system_or_code__cannot_validate)
+- $subsumes: a missing system (codeA/codeB with no system parameter, or a codingA/codingB with no system) is now 400 with issue code invalid and tx-issue-type invalid-data (was 404/422 not-found), with message id SUBSUMPTION_NO_SYSTEM (shared with the Java terminology service); mismatched codingA/codingB systems use SUBSUMPTION_SYSTEM_MISMATCH
+- SNOMED expressions: a refined or conjoined attribute value must be bracketed, per the compositional grammar (405813007=(85562004:272741003=24028007)); the unbracketed form is now rejected, and the renderer emits the brackets (it used to produce expressions other parsers reject)
+
+### Fixed
+
+- Fix processing of sourceScope during $translate operation
+- Fix broken links in HTML references (#256)
+- Fix bug in concept map conversion 
+- Fix issue processing MRCM rules (#287)
+- Fix message about depending on a draft resource (add source info)
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3516 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.5
+
+## [v0.13.4] - 2026-09-17
+
+### Changed 
+
+- Clean up TxCaps expansion parameter list
+
+### Fixed 
+
+- Fix performance issue with snomed text search
+- clean up release process to avoid version mismatch, and to clean out old dockers
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3507 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11, tests v1.9.4, runner v6.10.4)
+
 ## [v0.13.3] - 2026-09-10
 
 ### Fixed

package/README.md

@@ -31,7 +31,7 @@ This server provides a set of server-side services that are useful for the FHIR
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/HealthIntersections/fhirsmith/pkgs/container/fhirsmith)
 
 Note: In production, this server always runs behind an nginx reverse proxy, so there's no
-in-build support for SSL, rate limiting etc.
+in-build support for SSL, rate limiting etc. See [nginx.md](nginx.md) for how to configure it.
 
 ## Quick Start
 
@@ -170,7 +170,8 @@ npm start
 
 The server will be available at `http://localhost:{port}` using the port specified in the config.
 In the production servers listed above, the server always sits behind an NGINX server which manages
-SSL, security, rate limiting etc.
+SSL, security, rate limiting etc. See [nginx.md](nginx.md) for configuration advice, including
+running several servers behind one front door.
 
 ## Testing
 
@@ -259,6 +260,26 @@ Each GitHub Release includes:
     - `ghcr.io/healthintersections/fhirsmith:X.Y.Z`
 - **npm package** published to npmjs.org as `fhirsmith` *(if you add this)*
 
+Release images carry OCI labels, so an image says which release it is without
+having to trust the tag it was pulled under:
+
+```bash
+docker inspect --format '{{json .Config.Labels}}' ghcr.io/healthintersections/fhirsmith:latest
+```
+
+`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.
+
+### CI Images
+
+Every push to main also publishes `:cibuild` and `:cibuild-<sha>` to the same
+package. These are **not releases** - they are whatever was last merged. The
+Docker Build workflow prunes all but the ten most recent afterwards, so they do
+not bury the current release on the package page. To prune by hand (or to run
+the one-off backfill of images published before that job existed), run the
+**GHCR Cleanup** workflow from the Actions tab with `dry_run` on first, read the
+log, then run it again with `dry_run` off.
+
 ### Creating a Release
 
 GitHub Actions will automatically:
@@ -283,7 +304,18 @@ GitHub Actions will automatically:
 ### Tx Conformance Statement
      {copy content from text-cases-summary.txt}
 ```
-2. Update `package.json` & `package-lock.json` to have the same release version
+2. Update `package.json` & `package-lock.json` to the release version:
+
+```bash
+   npm version --no-git-tag-version X.Y.Z
+   npm install --package-lock-only
+```
+
+   This matters more than it looks. The server reports its version from
+   `package.json` (`server.js`, `tx/tx.js`) - not from the `APP_VERSION` build
+   arg - so a package.json left on the previous number ships a Docker image that
+   calls itself by the wrong release for good. The **Verify Version** job fails
+   the release if `package.json` or `package-lock.json` disagrees with the tag.
 
 3. Commit your changes:
 ```bash
@@ -304,7 +336,19 @@ or do it via a PR
     - Verify the [GitHub Release](https://github.com/HealthIntersections/fhirsmith/releases) was created
     - Confirm Docker images are available at [GHCR](https://github.com/HealthIntersections/fhirsmith/pkgs/container/fhirsmith)
 
-6. Update `package.json` to have the next release version -SNAPSHOT
+6. Submit the tx conformance report to [testing.fhir.org](https://testing.fhir.org/testing):
+```bash
+   node utilities/submit-test-report.js -token {token}
+```
+
+   The tx test run writes `test-cases-report.json` next to `test-cases-summary.txt` (both
+   are ignored by git); this uploads it as a TestReport. The report records the version in
+   `package.json` when the tests ran, so for it to name the release, run the tx tests
+   after step 2 - the script warns if the report is from a different version, or from a
+   snapshot. Use `-server {url}` to send it to a different /testing server; the token can
+   also come from `FHIRSMITH_TESTING_TOKEN`.
+
+7. Update `package.json` to have the next release version -SNAPSHOT
 
 **If a release fails:**
 - Delete the tag: `git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`

package/config-template.json

@@ -101,7 +101,25 @@
       // key - e.g. "git@github-ig-registry:FHIR/ig-registry.git", with a matching Host block
       // in the service user's ~/.ssh/config carrying IdentityFile and IdentitiesOnly yes.
       // The alias is what lets ssh tell this remote apart from the website remote.
-      "ig-registry-url": "git@github.com:FHIR/ig-registry.git"
+      "ig-registry-url": "git@github.com:FHIR/ig-registry.git",
+      // Tagging the IG source repo and publishing a GitHub release with a zip of its source, at
+      // the end of a successful publication. Omit this whole block to skip that step - without it
+      // there is no credential that can write to a source repository.
+      //
+      // This is a GitHub App, not a personal access token: a fine-grained PAT cannot span two
+      // organisations, and a classic PAT would act as whoever minted it. Create the App with
+      // "Where can this GitHub App be installed?" = Any account, give it Contents: Read and write
+      // (which covers tags as well as releases), then install it on each org below with access to
+      // all repositories. The installation id is in the URL of the installation's settings page.
+      "github-app": {
+        "app-id": "123456",
+        "private-key": "/absolute/path/to/app-private-key.pem",
+        // github org name (as it appears on the publication task) -> installation id
+        "installations": {
+          "HL7": 12345678,
+          "FHIR": 87654321
+        }
+      }
     },
     "npmprojector": {
       "enabled": true,
@@ -163,6 +181,39 @@
       // Off by default - the file names every database, cache and package the server runs.
       "publishLibrarySource": false,
       "cacheTimeout": 30,
+      // Optional. A short code (1-16 letters and digits) naming this server instance. Every
+      // cache-id the server issues then starts with "<code>.", so a proxy in front of
+      // several instances can route cached requests back to the instance that holds the
+      // cache. Leave unset for a single server. See nginx.md.
+      // "instanceCode": "tx1",
+      // $closure: closure tables are kept on the server, across sessions and restarts, so
+      // the operation is off unless it is turned on here. When it is on, only one server
+      // instance may use the database - route every $closure request to it (see nginx.md).
+      "closure": {
+        "enabled": false,
+        // relative paths resolve under the data folder's databases directory
+        "database": "closure.db",
+        // require table names to be UUIDs, so names chosen by unrelated clients can't
+        // collide (public servers). Otherwise a name is anything up to 64 characters with
+        // no white space
+        "requireUuidNames": false,
+        // limits: these are the defaults, which apply when a limit is left out; 0 = no limit
+        "maxTables": 1000,
+        "maxConceptsPerTable": 10000,
+        "maxConceptsPerRequest": 1000,
+        "maxEntriesPerTable": 250000,
+        "maxEntriesPerRequest": 50000,
+        // bytes of configuration kept with a table - mostly the tx-resource code systems
+        "maxConfigSize": 5242880,
+        // calls that can queue for one table (counting the one running), and how long, in
+        // seconds, a call will wait for its turn; beyond either, the call gets a 429
+        "maxQueue": 10,
+        "lockTimeout": 60
+        // delete tables that nobody has touched (initialised, added to or resynced) for this
+        // many days. Checked at startup and then daily. Leave it out and nothing is ever
+        // deleted - the right default for a private server; public servers should set it:
+        // , "retentionDays": 90
+      },
       "expansionCacheSize": 1000,
       "expansionCacheMemoryThreshold": 0,
       "endpoints": [
@@ -198,6 +249,24 @@
       "enabled": true,
       "database": "/var/fhir/data/extension-tracker.db",
       "url": "/ext-tracker"
+    },
+    // TestReports from TxTester and other tools, at /testing. See testing/readme.md
+    "testing": {
+      "enabled": false,
+      // relative paths resolve under the data folder's databases directory
+      "database": "testing.db",
+      // if set, every POST must carry this token in tokenHeader (a "Bearer " prefix is
+      // allowed). Leave it out and anyone can submit a report
+      // "token": "<!-- secret -->",
+      "tokenHeader": "Authorization",
+      // DELETE of a report needs this token, in the same header. No adminToken, no deletes
+      // "adminToken": "<!-- secret -->",
+      // bytes
+      "maxSize": 512000,
+      // reports per IP address per window; max 0 turns the limit off
+      "rateLimit": { "windowMinutes": 1, "max": 60 }
+      // delete reports received more than this many days ago. Leave it out to keep everything
+      // , "retentionDays": 365
     }
   }
 }

package/library/cgroup-memory.js

@@ -0,0 +1,113 @@
+/**
+ * The memory limit the kernel will actually enforce on this process.
+ *
+ * Reading `/sys/fs/cgroup/memory.max` only works inside a container with its own
+ * cgroup namespace, where the process's cgroup is mounted as the root. Under plain
+ * systemd (how tx.fhir.org runs) the whole host hierarchy is visible, the root cgroup
+ * has no memory.max at all, and the limit lives at e.g.
+ * `/sys/fs/cgroup/system.slice/fhirsmith.service/memory.max`. So: find our cgroup in
+ * /proc/self/cgroup, then walk from it up to the root, taking the smallest limit -
+ * a MemoryMax on the enclosing slice binds just as hard as one on the unit.
+ *
+ * Handles cgroup v2 (unified) and v1 (memory controller). Anything unreadable or
+ * unlimited is ignored; if nothing is found the result is 0.
+ *
+ * @module library/cgroup-memory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// cgroup v1 reports "unlimited" as a page-rounded LONG_MAX; anything this big is no limit.
+const V1_UNLIMITED = 2 ** 60;
+
+function readLimitFile(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8').trim();
+  } catch {
+    return 0;
+  }
+  if (raw === '' || raw === 'max') {
+    return 0;
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0 || n >= V1_UNLIMITED) {
+    return 0;
+  }
+  return n;
+}
+
+/**
+ * Walk from cgroupPath up to '/', returning the smallest limit found under mountDir.
+ */
+function smallestLimit(mountDir, cgroupPath, fileName) {
+  let limit = 0;
+  let source = null;
+  let p = path.posix.normalize(cgroupPath || '/');
+  for (;;) {
+    const file = path.join(mountDir, p, fileName);
+    const n = readLimitFile(file);
+    if (n > 0 && (limit === 0 || n < limit)) {
+      limit = n;
+      source = file;
+    }
+    if (p === '/' || p === '.' || p === '') {
+      break;
+    }
+    p = path.posix.dirname(p);
+  }
+  return { limit, source };
+}
+
+/**
+ * @param {Object} [opts] - For tests: alternative locations of the proc file and cgroup mount.
+ * @param {string} [opts.procFile='/proc/self/cgroup']
+ * @param {string} [opts.cgroupRoot='/sys/fs/cgroup']
+ * @returns {{limit: number, source: string|null}} limit in bytes (0 = none found), and the
+ *   file it came from.
+ */
+function readCgroupMemoryLimit(opts = {}) {
+  const procFile = opts.procFile || '/proc/self/cgroup';
+  const cgroupRoot = opts.cgroupRoot || '/sys/fs/cgroup';
+
+  let lines = [];
+  try {
+    lines = fs.readFileSync(procFile, 'utf8').split('\n').filter(l => l.trim() !== '');
+  } catch {
+    // not Linux, or /proc not mounted - fall through to the namespaced-root guess
+  }
+
+  // v2: "0::/system.slice/fhirsmith.service"
+  const v2 = lines.find(l => l.startsWith('0::'));
+  if (v2) {
+    const result = smallestLimit(cgroupRoot, v2.substring(3), 'memory.max');
+    if (result.limit > 0) {
+      return result;
+    }
+  }
+
+  // v1: "4:memory:/system.slice/fhirsmith.service"
+  for (const l of lines) {
+    const parts = l.split(':');
+    if (parts.length >= 3 && parts[1].split(',').includes('memory')) {
+      const result = smallestLimit(path.join(cgroupRoot, 'memory'), parts.slice(2).join(':'), 'memory.limit_in_bytes');
+      if (result.limit > 0) {
+        return result;
+      }
+    }
+  }
+
+  // No /proc/self/cgroup: a namespaced container still has its own limit at the root.
+  if (lines.length === 0) {
+    const file = path.join(cgroupRoot, 'memory.max');
+    const n = readLimitFile(file);
+    if (n > 0) {
+      return { limit: n, source: file };
+    }
+  }
+
+  return { limit: 0, source: null };
+}
+
+module.exports = { readCgroupMemoryLimit };

package/library/folder-setup.js

@@ -12,7 +12,14 @@ class FolderSetup {
       return this;
     }
 
-    this._dataDir = dataDir || process.env.FHIRSMITH_DATA_DIR || path.join(__dirname, '..', 'data');
+    const configured = dataDir || process.env.FHIRSMITH_DATA_DIR || path.join(__dirname, '..', 'data');
+    if (typeof configured !== 'string') {
+      throw new Error('Invalid data directory: expected a path, got ' + typeof configured);
+    }
+    // Absolute from here on: these paths are handed to child processes that run with a different
+    // working directory (the IG Publisher, git, sushi), and the IG Publisher refuses relative paths.
+    // A relative FHIRSMITH_DATA_DIR is taken relative to the directory the server was started in.
+    this._dataDir = path.resolve(configured);
     fs.mkdirSync(this._dataDir, { recursive: true });
     this._initialized = true;