fhirsmith 0.18.2 → 1.0.0

package/tx/sct/ecl.js

@@ -479,6 +479,22 @@ class ECLLexer {
   }
 }
 
+/**
+ * Bounds on the shape of an ECL expression, so that a hostile expression is a
+ * clean parse error rather than a RangeError (stack overflow) here, in the
+ * evaluator, or in any of the other recursive AST walkers.
+ *
+ * MAX_ECL_DEPTH limits nesting - bracketed expression constraints, bracketed
+ * refinements and attribute sets. Real ECL nests a handful of levels.
+ *
+ * MAX_ECL_TERMS limits the number of sub expression constraints (focus
+ * concepts, refinement values, ...). It is needed as well as the depth limit
+ * because a compound chain ("A OR B OR C ...") is parsed iteratively but builds
+ * a left-deep tree, one level per operator, which every walker then recurses.
+ */
+const MAX_ECL_DEPTH = 100;
+const MAX_ECL_TERMS = 500;
+
 /**
  * ECL Parser - Parses tokens into AST
  */
@@ -487,6 +503,20 @@ class ECLParser {
     this.tokens = tokens;
     this.position = 0;
     this.current = this.tokens[0] || { type: ECLTokenType.EOF };
+    this.depth = 0;
+    this.terms = 0;
+  }
+
+  /** Run a parse step one nesting level deeper, enforcing MAX_ECL_DEPTH. */
+  #nested(fn) {
+    if (++this.depth > MAX_ECL_DEPTH) {
+      this.error(`The expression nests more than ${MAX_ECL_DEPTH} levels deep`);
+    }
+    try {
+      return fn();
+    } finally {
+      this.depth--;
+    }
   }
 
   error(message) {
@@ -526,7 +556,7 @@ class ECLParser {
   }
 
   parseExpressionConstraint() {
-    return this.parseCompoundExpressionConstraint();
+    return this.#nested(() => this.parseCompoundExpressionConstraint());
   }
 
   parseCompoundExpressionConstraint() {
@@ -607,6 +637,9 @@ class ECLParser {
   }
 
   parseSubExpressionConstraint() {
+    if (++this.terms > MAX_ECL_TERMS) {
+      this.error(`The expression has more than ${MAX_ECL_TERMS} terms`);
+    }
     // Handle constraint operators
     let operator = null;
     if (this.match(
@@ -701,7 +734,8 @@ class ECLParser {
   }
 
   /**
-   * Parse one "{{ ... }}" block. Returns { kind: 'M'|'D'|'C'|'+', filters } where
+   * Parse one "{{ ... }}" block (the D of a description filter is optional). Returns
+   * { kind: 'M'|'D'|'C'|'+', filters } where
    * filters is only populated for member filters; the other kinds keep their
    * raw token text so the evaluator can report them as unsupported.
    */
@@ -714,8 +748,13 @@ class ECLParser {
     } else if (this.match(ECLTokenType.SCTID) && /^[MDCmdc]$/.test(this.current.value)) {
       kind = this.current.value.toUpperCase();
       this.advance();
+    } else if (this.match(ECLTokenType.SCTID) && /^[A-Za-z_]/.test(this.current.value)) {
+      // ECL 2.2: descriptionFilterConstraint = "{{" ws [ "d" / "D" ] ws descriptionFilter ...
+      // - the D is optional, so a filter that starts with a field name (term, language,
+      // type, ...) is a description filter
+      kind = 'D';
     } else {
-      this.error('Expected M, D, C or + after {{');
+      this.error('Expected M, D, C, + or a description filter after {{');
     }
 
     if (kind === 'C' || kind === 'D') {
@@ -1256,7 +1295,7 @@ class ECLParser {
    * returned as-is; otherwise an ATTRIBUTE_SET with operator 'AND' or 'OR'.
    */
   parseRefinement() {
-    return this.parseRefinementSet(() => this.parseSubRefinement(), 'refinement');
+    return this.#nested(() => this.parseRefinementSet(() => this.parseSubRefinement(), 'refinement'));
   }
 
   parseRefinementSet(parseItem, what) {
@@ -1332,7 +1371,7 @@ class ECLParser {
    * (the contents of an attribute group - no nested groups)
    */
   parseAttributeSet() {
-    return this.parseRefinementSet(() => {
+    return this.#nested(() => this.parseRefinementSet(() => {
       if (this.match(ECLTokenType.LPAREN) && !this.#parenIsAttributeName()) {
         this.advance();
         const inner = this.parseAttributeSet();
@@ -1340,7 +1379,7 @@ class ECLParser {
         return inner;
       }
       return this.parseAttribute();
-    }, 'attribute set');
+    }, 'attribute set'));
   }
 
   parseAttributeGroup(cardinality = null) {
@@ -2355,6 +2394,8 @@ class ECLValidator {
 }
 
 module.exports = {
+  MAX_ECL_DEPTH,
+  MAX_ECL_TERMS,
   ECLValidator,
   ECLLexer,
   ECLParser,

package/tx/sct/editions.js

@@ -63,8 +63,47 @@ function editionCode(edition) {
   return e ? e.code : null;
 }
 
+/**
+ * The editions snomed.info can resolve an edition-specific concept link for: the same list as
+ * SnomedUtilities.getEditionFromVersion in org.hl7.fhir.core. A code from any other edition
+ * links to http://snomed.info/id/<code>. Also the editions offered when an edition is chosen
+ * (the IPS module's national profiles), in this order.
+ */
+const SNOMED_LINKABLE_EDITIONS = new Set([
+  '900000000000207008', // International
+  '449081005', // International Spanish
+  '11000221109', // Argentinian
+  '32506021000036107', // Australian (with drug extension)
+  '11000234105', // Austrian
+  '11000172109', // Belgian
+  '20621000087109', // Canadian English
+  '20611000087101', // Canadian Canadian French
+  '21000325107', // Chilean
+  '11000279109', // Czech
+  '554471000005108', // Danish
+  '11000181102', // Estonian
+  '11000229106', // Finnish
+  '11000274103', // German
+  '1121000189102', // Indian
+  '11000220105', // Irish
+  '11000146104', // Netherlands
+  '21000210109', // New Zealand
+  '51000202101', // Norwegian
+  '11000267109', // Republic of Korea (South Korea)
+  '900000001000122104', // Spanish National
+  '45991000052106', // Swedish
+  '2011000195101', // Swiss
+  '83821000000107', // UK
+  '999000021000000109', // UK Clinical
+  '5631000179106', // Uruguay
+  '731000124108', // US
+  '5991000124107', // US (with ICD-10-CM maps)
+  '827022005' // IPS Terminology
+]);
+
 module.exports = {
   EDITIONS,
+  SNOMED_LINKABLE_EDITIONS,
   editionName,
   editionCode
 };

package/tx/sct/expressions.js

@@ -13,6 +13,10 @@ const MAX_TERM_LENGTH = 1024;
 // Attribute values are themselves expanded, so a chain of definitions can descend a
 // long way; in real data it is a handful of levels.
 const MAX_NORMALISATION_DEPTH = 50;
+// How deep bracketed attribute values may nest in an expression the parser accepts. The parser
+// (and everything that walks the parsed expression) recurses once per level, so without a bound
+// a hostile expression is a RangeError (stack overflow) rather than a parse error.
+const MAX_EXPRESSION_DEPTH = 100;
 
 const NO_REFERENCE = 0xFFFFFFFF;
 
@@ -483,6 +487,7 @@ class SnomedExpressionParser {
   parse(source) {
     this.source = source;
     this.cursor = 0;
+    this.depth = 0;
 
     const result = new SnomedExpression();
     result.start = this.cursor;
@@ -681,9 +686,12 @@ class SnomedExpressionParser {
     this.ws();
 
     if (this.gchar('(')) {
+      this.depth++;
+      this.rule(this.depth <= MAX_EXPRESSION_DEPTH, `The expression nests more than ${MAX_EXPRESSION_DEPTH} levels deep`);
       const result = this.expression();
       this.ws();
       this.fixed(')');
+      this.depth--;
       return result;
     } else {
       const result = new SnomedExpression();
@@ -2951,6 +2959,7 @@ module.exports = {
 
   // Enums and constants
   SnomedServicesRenderOption,
-  SnomedRefinementGroupMatchState
+  SnomedRefinementGroupMatchState,
+  MAX_EXPRESSION_DEPTH
 };
 

package/tx/sct/load-config.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * How each SNOMED CT cache file is loaded, from the tx module's "snomed" block in config.json:
+ *
+ *   "snomed": {
+ *     "load": "read" | "mmap",   // the default for every edition (absent: "read")
+ *     "prewarm": [ ... ],        // map these, then read them through once in the background at startup
+ *     "read": [ ... ]            // read these into the process even when load is "mmap"
+ *   }
+ *
+ * An entry names a cache file (e.g. "sct_us_20250901b.cache"), an edition version URI
+ * ("http://snomed.info/sct/731000124108/version/20250901"), or an edition URI
+ * ("http://snomed.info/sct/731000124108", every loaded version of the edition). "read" wins
+ * over "prewarm", which wins over "load".
+ *
+ *   read    - the file is read into this process (private memory, as before)
+ *   mmap    - the file is mapped read-only; pages are read from disk when first touched, and
+ *             shared with every other process that maps the same file
+ *   prewarm - mapped, and read through once in the background at startup so its pages are
+ *             already in the shared page cache when the first requests arrive
+ */
+
+const path = require('path');
+
+const MODES = ['read', 'mmap'];
+
+class SnomedLoadConfig {
+  /**
+   * @param {object} [block] - the "snomed" block of the tx module config
+   * @param {function(string)} [warn]
+   */
+  constructor(block, warn = () => {}) {
+    this.warn = warn;
+    block = block || {};
+    this.load = 'read';
+    if (block.load !== undefined) {
+      if (MODES.includes(block.load)) {
+        this.load = block.load;
+      } else {
+        warn(`snomed.load must be "read" or "mmap", not ${JSON.stringify(block.load)}; using "read"`);
+      }
+    }
+    this.lists = {};
+    for (const name of ['prewarm', 'read']) {
+      const v = block[name];
+      if (v === undefined) {
+        this.lists[name] = [];
+      } else if (Array.isArray(v) && v.every(e => typeof e === 'string' && e.trim())) {
+        this.lists[name] = v.map(e => e.trim());
+      } else {
+        warn(`snomed.${name} must be a list of cache file names or edition URIs; ignored`);
+        this.lists[name] = [];
+      }
+    }
+    for (const e of this.lists.prewarm) {
+      if (this.lists.read.includes(e)) {
+        warn(`snomed: ${e} is in both "prewarm" and "read"; it will be read`);
+      }
+    }
+    this.used = new Set();
+  }
+
+  /** True if any edition can end up mapped. */
+  mapsAnything() {
+    return this.load === 'mmap' || this.lists.prewarm.length > 0;
+  }
+
+  static #matches(entry, fileName, versionUri) {
+    if (entry === fileName) return true;
+    if (!versionUri) return false;
+    return entry === versionUri || versionUri.startsWith(entry.replace(/\/+$/, '') + '/version/');
+  }
+
+  #find(list, fileName, versionUri) {
+    const hit = this.lists[list].filter(e => SnomedLoadConfig.#matches(e, fileName, versionUri));
+    hit.forEach(e => this.used.add(e));
+    return hit.length > 0;
+  }
+
+  /**
+   * @param {string} filePath - the cache file
+   * @param {string|null} versionUri - its edition version URI, e.g. http://snomed.info/sct/900000000000207008/version/20250201
+   * @returns {'read'|'mmap'|'prewarm'}
+   */
+  modeFor(filePath, versionUri) {
+    const fileName = path.basename(filePath);
+    const read = this.#find('read', fileName, versionUri);
+    const prewarm = this.#find('prewarm', fileName, versionUri);
+    if (read) return 'read';
+    if (prewarm) return 'prewarm';
+    return this.load;
+  }
+
+  /** Warn about entries that matched no loaded edition. Call once every edition is loaded. */
+  checkUnused() {
+    for (const list of ['prewarm', 'read']) {
+      for (const e of this.lists[list]) {
+        if (!this.used.has(e)) {
+          this.warn(`snomed.${list}: "${e}" matches no SNOMED CT edition in the library`);
+        }
+      }
+    }
+  }
+}
+
+module.exports = { SnomedLoadConfig };

package/tx/sct/mmap.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Read-only memory mapping of SNOMED CT cache files ("snomed": {"load": "mmap"} in config.json).
+ *
+ * Node has no mmap of its own, so this calls the C library's mmap() through koffi (an FFI
+ * module that ships prebuilt binaries for Linux glibc and musl, macOS and the BSDs, so
+ * nothing is compiled at install time). The mapping is never unmapped: a loaded edition
+ * stays loaded for the life of the process.
+ *
+ * mapFile() returns null where mapping is not available (Windows, koffi missing, mmap
+ * failing), and the caller then reads the file into memory as before. It says why through the
+ * warn function it is given (the server log), or console.warn where there is none.
+ */
+
+const fs = require('fs');
+
+const PROT_READ = 1;
+const MAP_PRIVATE = 2;          // same value on Linux, macOS and the BSDs
+const MAP_FAILED = 0xFFFFFFFFFFFFFFFFn;
+
+let libcMmap;                   // undefined: not tried yet; null: not available
+let unavailable = null;         // why libcMmap is null
+
+function getMmap() {
+  if (libcMmap === undefined) {
+    libcMmap = null;
+    if (process.platform === 'win32' || !process.arch.endsWith('64')) {
+      unavailable = `not supported on ${process.platform}/${process.arch}`;
+    } else {
+      try {
+        const koffi = require('koffi');
+        const mmap = koffi.load(null).func('void *mmap(void *addr, size_t len, int prot, int flags, int fd, int64_t off)');
+        libcMmap = { koffi, mmap };
+      } catch (e) {
+        unavailable = e.message;
+      }
+    }
+  }
+  return libcMmap;
+}
+
+/** True if mapFile() can map files on this platform (it may still fail for a given file). */
+function mappingAvailable() {
+  return getMmap() !== null;
+}
+
+/**
+ * @param {string} filePath
+ * @param {function(string)} [warn] - where to say why the file was not mapped
+ * @returns {Buffer|null} a read-only Buffer over the whole file, or null
+ */
+function mapFile(filePath, warn = (msg) => console.warn(msg)) {
+  const lib = getMmap();
+  if (!lib) {
+    warn(`SNOMED CT: memory mapping is not available here (${unavailable}); reading ${filePath} into memory`);
+    return null;
+  }
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    if (size === 0) return null;
+    const ptr = lib.mmap(null, size, PROT_READ, MAP_PRIVATE, fd, 0);
+    if (ptr === null || lib.koffi.address(ptr) === MAP_FAILED) {
+      warn(`SNOMED CT: could not map ${filePath} (errno ${lib.koffi.errno()}); reading it into memory`);
+      return null;
+    }
+    return Buffer.from(lib.koffi.view(ptr, size));
+  } finally {
+    fs.closeSync(fd);   // the mapping keeps its own reference to the file
+  }
+}
+
+/**
+ * Read a file through once, in the background, so its pages are in the page cache before
+ * requests need them (madvise(MADV_WILLNEED) is only a hint, and on Linux it read almost
+ * nothing of a mapped file). The reads go through one small buffer, so this costs no process
+ * memory; the pages land in the page cache that every mapping of the file shares.
+ *
+ * @param {string} filePath
+ * @returns {Promise<number>} milliseconds taken
+ */
+async function prewarmFile(filePath) {
+  const start = Date.now();
+  const buf = Buffer.allocUnsafe(4 * 1024 * 1024);
+  const fh = await fs.promises.open(filePath, 'r');
+  try {
+    let pos = 0;
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+      if (bytesRead === 0) break;
+      pos += bytesRead;
+    }
+  } finally {
+    await fh.close();
+  }
+  return Date.now() - start;
+}
+
+/**
+ * For tests: replace the mmap binding ({koffi, mmap}, or null with a reason for "not
+ * available"), or with no arguments go back to the real one.
+ */
+function _setMmapForTesting(lib, reason = 'disabled by a test') {
+  libcMmap = arguments.length === 0 ? undefined : lib;
+  unavailable = lib ? null : reason;
+}
+
+module.exports = { mapFile, prewarmFile, mappingAvailable, _setMmapForTesting };