fhirsmith 0.13.3 → 0.14.0

package/tx/html/tx-template.html

@@ -89,6 +89,7 @@
             <a href="[%endpoint-path%]/metadata" style="color: gold">Capability Statement</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/metadata?mode=terminology" style="color: gold">Terminology Capabilities</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/op.html" style="color: gold">Operations</a>  &nbsp;|&nbsp;
+            <a href="[%endpoint-path%]/ecl" style="color: gold">ECL</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/problems.html" style="color: gold">Problems</a>  &nbsp;|&nbsp;
             [%library-link%]
   &nbsp;

package/tx/library/conceptmap.js

@@ -196,6 +196,14 @@ class ConceptMap extends CanonicalResource {
    * their elements matched. group.unmapped only applies to a group that was in scope
    * for the translation, so the caller needs the same source/target test that
    * listTranslations applies - without the per-element filter.
+   *
+   * "In scope" here is only about this group's source and target code systems. It assumes
+   * the MAP itself is in scope, which is a separate and prior question: ConceptMap.sourceScope
+   * limits the map to codes that are members of that value set, and a map that does not cover
+   * the code has no groups in scope at all, whatever their systems say. That test needs a value
+   * set lookup and a $validate-code, so it lives in the worker (TranslateWorker.filterMapsByScope)
+   * and is applied to the map before this is ever called. Do not read a group coming back from
+   * here as evidence that the map applies.
    * @returns {Object[]} the matching group objects
    */
   listGroupsInScope(coding, targetScope, targetSystem) {
@@ -238,19 +246,27 @@ class ConceptMap extends CanonicalResource {
     return result;
   }
     /**
-   * Gets the source scope (R5) or source system (R3/R4)
-   * @returns {string|undefined} Source scope/system
+   * Gets the source scope (R5+) or source (R3/R4).
+   *
+   * R5 renamed ConceptMap.source[x] to ConceptMap.sourceScope[x], so an R4 resource spells this
+   * sourceUri / sourceCanonical and an R5 one sourceScopeUri / sourceScopeCanonical. Both have to
+   * be read: this server serves R4 as well as R5, and the R4 client sends the R4 spelling. Reading
+   * only the R5 names made this silently undefined on an R4 server, which made every map look
+   * unscoped - so the scope never limited anything, and $translate answered for codes outside it.
+   * @returns {string|undefined} Source scope
    */
   get sourceScope() {
-    return this.jsonObj.sourceScopeUri ? this.jsonObj.sourceScopeUri : this.jsonObj.sourceScopeCanonical;
+    return this.jsonObj.sourceScopeUri || this.jsonObj.sourceScopeCanonical
+      || this.jsonObj.sourceUri || this.jsonObj.sourceCanonical;
   }
 
   /**
-   * Gets the target scope (R5) or target system (R3/R4)
-   * @returns {string|undefined} Target scope/system
+   * Gets the target scope (R5+) or target (R3/R4). See sourceScope for why both are read.
+   * @returns {string|undefined} Target scope
    */
   get targetScope() {
-    return this.jsonObj.targetScopeUri ? this.jsonObj.targetScopeUri : this.jsonObj.targetScopeCanonical;
+    return this.jsonObj.targetScopeUri || this.jsonObj.targetScopeCanonical
+      || this.jsonObj.targetUri || this.jsonObj.targetCanonical;
   }
 
   /**

package/tx/library/designations.js

@@ -26,6 +26,10 @@ class SearchFilterText {
 
     this.filter = filter ? filter.toLowerCase() : null;
     this.stems = [];
+    // The words the stems came from, index-aligned with stems. A provider whose text
+    // index cannot hold a particular token (RxNorm's stem table has nothing that starts
+    // with a digit, for one) needs the word itself to search the text with instead.
+    this.words = [];
     this.stemmer = natural.PorterStemmer;
     if (filter) {
       this._process();
@@ -135,6 +139,7 @@ class SearchFilterText {
 
   _process() {
     let i = 0;
+    const found = [];
 
     while (i < this.filter.length) {
       if (this._isAlphaNumeric(this.filter[i])) {
@@ -142,14 +147,18 @@ class SearchFilterText {
         while (i < this.filter.length && this._isAlphaNumeric(this.filter[i])) {
           i++;
         }
-        const word = this.filter.substring(j, i);
-        this.stems.push(this.stemmer.stem(word.toLowerCase()));
+        const word = this.filter.substring(j, i).toLowerCase();
+        found.push({ word: word, stem: this.stemmer.stem(word) });
       } else {
         i++;
       }
     }
 
-    this.stems.sort();
+    // Sorted by stem, because _find() binary searches stems - words ride along so that
+    // words[n] is always the word stems[n] came from.
+    found.sort((a, b) => (a.stem < b.stem ? -1 : (a.stem > b.stem ? 1 : 0)));
+    this.stems = found.map((f) => f.stem);
+    this.words = found.map((f) => f.word);
   }
 
   _isAlphaNumeric(char) {

package/tx/library/extensions.js

@@ -24,8 +24,8 @@ const Extensions = {
     if (resource.jsonObj) {
       resource = resource.jsonObj
     }
-    if (resource.implicitRules) {
-      throw new Issue("error", "business-rule", null, null, 'Cannot process resource "'+name+'" due to the presence of implicit rules @'+place);
+    if (resource.implicitRules && 'https://hl7.org/fhir/implicit-rules/omitted-mandatory-interversion-code' != resource.implicitRules) {
+      throw new Issue("error", "business-rule", null, null, 'Cannot process resource "'+name+'" due to the presence of implicit rules \''+resource.implicitRules+'\' @'+place);
     }
   },
 

package/tx/library/operation-outcome.js

@@ -198,7 +198,9 @@ class OperationOutcome {
   listMissedErrors(list) {
     for (let iss of this.jsonObj.issue || []) {
       if (iss.severity === 'error' && iss.details && iss.details.text && !list.find(msg => msg === iss.details.text )) {
-        return list.push(iss.details.text);
+        // every error that nothing else reported, not just the first one - an early return here
+        // meant the summary message named only one of them
+        list.push(iss.details.text);
       }
     }
 

package/tx/library/renderer.js

@@ -1445,6 +1445,7 @@ class Renderer {
 
     // Analyze columns needed
     const columnInfo = this.analyzeExpansionColumns(vs.expansion);
+    columnInfo.versions = this.expansionVersions(vs);
 
     // Build the expansion table
     const expTbl = x.table("codes");
@@ -1595,6 +1596,40 @@ class Renderer {
   /**
    * Add a row for an expansion contains entry
    */
+  /**
+   * The version each code system was expanded at, by system uri.
+   *
+   * An expansion.contains only carries a version when the expansion needed to distinguish
+   * one, so a link built from the row alone would silently point at whichever version the
+   * server happens to prefer - not what the reader is looking at. The expansion says which
+   * version it used in its used-codesystem parameters, and a value set that came with its
+   * definition says so in its compose; either will do.
+   *
+   * @param {Object} vs the expanded ValueSet
+   * @returns {Map<string, string>} system uri to version
+   */
+  expansionVersions(vs) {
+    const versions = new Map();
+    for (const inc of vs.compose?.include || []) {
+      if (inc.system && inc.version && !versions.has(inc.system)) {
+        versions.set(inc.system, inc.version);
+      }
+    }
+    for (const p of vs.expansion?.parameter || []) {
+      if (p.name !== 'used-codesystem') {
+        continue;
+      }
+      const vurl = getValuePrimitive(p);
+      if (vurl && vurl.includes('|')) {
+        const system = vurl.substring(0, vurl.indexOf('|'));
+        if (!versions.has(system)) {
+          versions.set(system, vurl.substring(vurl.indexOf('|') + 1));
+        }
+      }
+    }
+    return versions;
+  }
+
   async addExpansionRow(tbl, contains, level, columnInfo) {
     const tr = tbl.tr();
 
@@ -1617,12 +1652,14 @@ class Renderer {
       codeTd.tx('\u00A0'.repeat(level * 2)); // Non-breaking spaces for indentation
     }
 
-    // Try to link the code
+    // The code links to $lookup on it - what a reader wants from a row in an expansion is
+    // to find out what that code is - at the version the expansion used.
     if (contains.code) {
-      const link = this.linkResolver ?
-          await this.linkResolver.resolveCode(this.opContext, contains.system, contains.version, contains.code) : null;
+      const version = contains.version || columnInfo.versions?.get(contains.system) || null;
+      const link = this.linkResolver?.lookupLink
+        ? this.linkResolver.lookupLink(contains.system, version, contains.code) : null;
       if (link) {
-        codeTd.ah(link.link).tx(contains.code);
+        codeTd.ah(link, 'Look this code up').code().tx(contains.code);
       } else {
         codeTd.code().tx(contains.code);
       }
@@ -2732,4 +2769,4 @@ class Renderer {
 
 }
 
-module.exports = { Renderer };
+module.exports = { Renderer, VALID_FILTER_OPS };

package/tx/operation-context.js

@@ -4,6 +4,7 @@ const crypto = require("crypto");
 const {Languages} = require("../library/languages");
 const {Issue} = require("./library/operation-outcome");
 const Logger = require("../library/logger");
+const { readCgroupMemoryLimit } = require('../library/cgroup-memory');
 
 /**
  * Check if running under a debugger
@@ -110,6 +111,63 @@ class ResourceCache {
     // so a client polling $cache-control?mode=check can work out how often it needs
     // to poll instead of guessing. Null = not advertised.
     this.idleTimeoutMs = null;
+    // This server instance's code (modules.tx.instanceCode), prefixed onto every
+    // cache-id it issues as "<code>.<uuid>". A proxy in front of several instances
+    // routes on the prefix to get a cached request back to the one instance that
+    // holds the cache (see nginx.md). Null = unprefixed ids (a single server).
+    this.instanceCode = null;
+  }
+
+  /**
+   * Set the instance code that is prefixed onto the cache-ids this cache issues.
+   * 1-16 letters and digits: the code is followed by a '.', a proxy has to be able
+   * to match it with a simple pattern, and the whole id must stay a valid FHIR id. Empty/null/undefined means no prefix.
+   *
+   * @param {string|null|undefined} code
+   * @throws {Error} if the code is not letters and digits
+   */
+  setInstanceCode(code) {
+    this.instanceCode = ResourceCache.checkInstanceCode(code);
+  }
+
+  /**
+   * Validate an instance code from config.
+   * @param {string|null|undefined} code
+   * @returns {string|null} the code, or null for none (empty/null/undefined)
+   * @throws {Error} if the code is not letters and digits
+   */
+  static checkInstanceCode(code) {
+    if (code === undefined || code === null || code === '') {
+      return null;
+    }
+    // At most 16 characters: the cache-id goes back to the client as a FHIR id
+    // (valueId), which is capped at 64 - and "<code>." plus a 36-character UUID
+    // has to fit.
+    if (typeof code !== 'string' || !/^[A-Za-z0-9]{1,16}$/.test(code)) {
+      throw new Error(`tx instanceCode '${code}' is not valid: it must be 1-16 letters and digits`);
+    }
+    return code;
+  }
+
+  /**
+   * Mint a new cache-id: a UUID, prefixed with "<instanceCode>." when this server
+   * has an instance code. Minting only - the caller creates the entry with set().
+   * @returns {string}
+   */
+  newCacheId() {
+    const uuid = crypto.randomUUID();
+    return this.instanceCode ? `${this.instanceCode}.${uuid}` : uuid;
+  }
+
+  /**
+   * The instance code in a cache-id, or null if it has none. Ids this server mints
+   * are either a bare UUID (no '.') or "<code>.<uuid>".
+   * @param {string} cacheId
+   * @returns {string|null}
+   */
+  static issuerOf(cacheId) {
+    const dot = typeof cacheId === 'string' ? cacheId.indexOf('.') : -1;
+    return dot > 0 ? cacheId.substring(0, dot) : null;
   }
 
   /**
@@ -164,7 +222,9 @@ class ResourceCache {
 
   /**
    * The message to report for a cache-id that isn't here: which of the three
-   * fates it met, with the numbers that make it checkable. Both throw sites
+   * fates it met, with the numbers that make it checkable - or, when there's no
+   * record of it and its prefix names another instance, that it was routed here
+   * by mistake. Both throw sites
    * (worker.setupAdditionalResources and batchValidate.frontLoadBatch) use this
    * so they can never drift apart.
    *
@@ -175,6 +235,15 @@ class ResourceCache {
   describeMissing(cacheId) {
     const t = this.tombstone(cacheId);
     if (!t) {
+      // No record of it here. If its prefix names a different instance, say so:
+      // that's a routing problem (proxy misconfigured, or the owning instance is
+      // down and the request fell through to a backup), not a lifecycle one.
+      const issuer = ResourceCache.issuerOf(cacheId);
+      if (issuer && issuer !== this.instanceCode) {
+        return this.instanceCode
+          ? { messageId: 'CACHE_ID_OTHER_INSTANCE', params: [cacheId, issuer, this.instanceCode] }
+          : { messageId: 'CACHE_ID_OTHER_INSTANCE_UNNAMED', params: [cacheId, issuer] };
+      }
       return { messageId: 'CACHE_ID_UNKNOWN', params: [cacheId] };
     }
     const ago = formatDuration(Date.now() - t.at);
@@ -752,18 +821,12 @@ class ExpansionCache {
  * Returns the byte limit, or 0 if unavailable (disables the check).
  */
 function readMemoryLimit() {
-  try {
-    const raw = require('fs').readFileSync('/sys/fs/cgroup/memory.max', 'utf8').trim();
-    if (raw === 'max') return 0; // no cgroup limit
-    return parseInt(raw);
-  } catch {
-    return 0; // not on Linux / no cgroup
-  }
+  return readCgroupMemoryLimit().limit;
 }
 
 const MEMORY_LIMIT = readMemoryLimit();
 const MEMORY_FRACTION = 0.98;
-const MEMORY_THRESHOLD = MEMORY_LIMIT > 0 ? MEMORY_LIMIT * MEMORY_FRACTION : 0; // 90% of cgroup limit
+const MEMORY_THRESHOLD = MEMORY_LIMIT > 0 ? MEMORY_LIMIT * MEMORY_FRACTION : 0; // MEMORY_FRACTION of cgroup limit
 const CHECK_FREQUENCY = 100;
 // How long an operation may compute without yielding the event loop (ms).
 // Node runs all JS on one thread: while a long operation executes, no other
@@ -891,8 +954,8 @@ class OperationContext {
     if (elapsed > this.timeLimit) {
       const timeInSeconds = Math.round(this.timeLimit / 1000);
       this.log(`Operation took too long @ ${place} (${this.constructor.name})`);
-      const error = new Issue("error", "too-costly", null,
-          `Operation exceeded time limit of ${timeInSeconds} seconds at ${place}`);
+      const error = new Issue("error", "too-costly", null, null,
+          `Operation exceeded time limit of ${timeInSeconds} seconds at ${place}`, "too-costly", 422);
       error.diagnostics = this.diagnostics();
       throw error;
     }
@@ -904,8 +967,8 @@ class OperationContext {
         const usedGB = (rss / 1024 / 1024 / 1024).toFixed(1);
         const limitGB = (MEMORY_LIMIT / 1024 / 1024 / 1024).toFixed(1);
         this.log(`Memory Limit: ${usedGB} GB of ${limitGB} GB limit @ ${place}`);
-        const error = new Issue("error", "too-costly", null,
-            `Operation aborted: server memory usage (${usedGB} GB) exceeds safe threshold (${MEMORY_FRACTION * 100}% of ${limitGB} GB limit) at ${place}`);
+        const error = new Issue("error", "too-costly", null, null,
+            `Operation aborted: server memory usage (${usedGB} GB) exceeds safe threshold (${MEMORY_FRACTION * 100}% of ${limitGB} GB limit) at ${place}`, "too-costly", 422);
         error.diagnostics = this.diagnostics();
         throw error;
       }
@@ -963,8 +1026,8 @@ class OperationContext {
       this._clock.lastYield = resumed;
       if (this._clock.clientGone) {
         this.log(`Operation abandoned @ ${place}: client disconnected`);
-        const error = new Issue("error", "too-costly", null,
-            `Operation abandoned at ${place}: the client disconnected before the response was ready`);
+        const error = new Issue("error", "too-costly", null, null,
+            `Operation abandoned at ${place}: the client disconnected before the response was ready`, "too-costly", 422);
         error.abandoned = true;
         error.diagnostics = this.diagnostics();
         throw error;
@@ -972,6 +1035,39 @@ class OperationContext {
     }
   }
 
+  /**
+   * Await something this operation does not itself compute - typically a
+   * shared structure another request is building - without charging the wait
+   * to the compute deadline. The current compute slice is closed before
+   * waiting and a new one opened after; aborts if the client disconnected
+   * meanwhile.
+   *
+   * @param {Promise} promise
+   * @param {string} place - Location identifier for debugging
+   * @returns {Promise<*>} what the promise resolves to
+   */
+  async waitFor(promise, place = 'unknown') {
+    const now = performance.now();
+    this._clock.compute += now - this._clock.sliceStart;
+    let result;
+    try {
+      result = await promise;
+    } finally {
+      const resumed = performance.now();
+      this._clock.sliceStart = resumed;
+      this._clock.lastYield = resumed;
+    }
+    if (this._clock.clientGone) {
+      this.log(`Operation abandoned @ ${place}: client disconnected`);
+      const error = new Issue("error", "too-costly", null, null,
+          `Operation abandoned at ${place}: the client disconnected before the response was ready`, "too-costly", 422);
+      error.abandoned = true;
+      error.diagnostics = this.diagnostics();
+      throw error;
+    }
+    return result;
+  }
+
   unSeeAll() {
     this.contexts = [];
   }

package/tx/provider.js

@@ -449,6 +449,91 @@ class Provider {
     return null;
   }
 
+  /**
+   * A checker for codes in one code system, so that a page can ask about many codes
+   * without paying to build the code system each time.
+   *
+   * This is for deciding whether to offer a link. A property value that came back from
+   * $lookup as a code is, by the definition of CodeSystem.property.type, a concept in the
+   * same code system - but a provider can declare a property that way and then put
+   * something else in it (ICD-11's classKind is chapter|block|window|category, none of
+   * which is an ICD-11 concept), and a link to a code that is not there is worse than no
+   * link. So the codes are checked, once each, against the code system itself.
+   *
+   * @param {OperationContext} opContext
+   * @param {string} system
+   * @param {string|null} version
+   * @returns {Promise<function(string): Promise<string|null>>|null} a function returning
+   *   the code's display (possibly empty) if it exists and null if it does not, or null
+   *   when this server does not have that code system at all
+   */
+  async codeChecker(opContext, system, version) {
+    validateParameter(opContext, "opContext", OperationContext);
+    if (!system) {
+      return null;
+    }
+    if (system.includes("|")) {
+      version = version || system.substring(system.indexOf("|") + 1);
+      system = system.substring(0, system.indexOf("|"));
+    }
+    const vurl = system + (version ? "|" + version : "");
+    const vurlMM = VersionUtilities.isSemVer(version) ? system + "|" + VersionUtilities.getMajMin(version) : null;
+
+    let factory = this.codeSystemFactories.get(vurl);
+    if (factory == null && vurlMM) {
+      factory = this.codeSystemFactories.get(vurlMM);
+    }
+    if (factory != null) {
+      const csp = await factory.build(opContext, []);
+      if (csp) {
+        opContext.registerProvider(csp);
+        return async (code) => {
+          const located = await csp.locate(code);
+          return located && located.context ? (await csp.display(located.context)) || '' : null;
+        };
+      }
+    }
+
+    let cs = this.codeSystems.get(vurl);
+    if (cs == null && vurlMM) {
+      cs = this.codeSystems.get(vurlMM);
+    }
+    if (cs != null) {
+      return async (code) => {
+        const c = cs.codeMap.get(code);
+        return c ? (c.display || '') : null;
+      };
+    }
+    return null;
+  }
+
+  /**
+   * A link to $lookup for a code on this server.
+   *
+   * resolveCode() answers "where does this code live" - a code system page, or the
+   * publisher's own browser - which is the right answer in prose. In an expansion the
+   * question is different: the reader has a list of codes in front of them and wants to
+   * know what one of them actually is, which is what $lookup answers, here, in the
+   * version the expansion used.
+   *
+   * @param {string} system
+   * @param {string|null} version - may also be carried on system as system|version
+   * @param {string} code
+   * @returns {string|null} the URL, or null if there is not enough to build one
+   */
+  lookupLink(system, version, code) {
+    if (!system || !code) {
+      return null;
+    }
+    if (system.includes("|")) {
+      version = version || system.substring(system.indexOf("|") + 1);
+      system = system.substring(0, system.indexOf("|"));
+    }
+    return this.path + "/CodeSystem/$lookup?system=" + encodeURIComponent(system)
+      + (version ? "&version=" + encodeURIComponent(version) : "")
+      + "&code=" + encodeURIComponent(code);
+  }
+
   async hasCsVersion(system, version) {
     for (let cs of this.codeSystems.values()) {
       if (cs.url == system && cs.version == version) {