fhirsmith 0.11.2 → 0.13.0

package/tx/workers/batch.js

@@ -5,7 +5,7 @@
 //
 
 const { TerminologyWorker } = require('./worker');
-const { Issue, OperationOutcome } = require('../library/operation-outcome');
+const { Issue, OperationOutcome, buildOperationOutcome, outcomeFromError } = require('../library/operation-outcome');
 const {debugLog} = require("../operation-context");
 
 class BatchWorker extends TerminologyWorker {
@@ -47,8 +47,7 @@ class BatchWorker extends TerminologyWorker {
         oo.addIssue(error);
         return res.status(error.statusCode || 500).json(oo.jsonObj);
       } else {
-        return res.status(error.statusCode || 500).json(this.operationOutcome(
-          'error', error.issueCode || 'exception', error.message));
+        return res.status(error.statusCode || 500).json(outcomeFromError(error));
       }
     }
   }
@@ -163,9 +162,8 @@ class BatchWorker extends TerminologyWorker {
       this.log.error(error);
       debugLog(error);
       const statusCode = error.statusCode || 500;
-      const issueCode = error.issueCode || 'exception';
-
-      return this.errorEntry(statusCode, issueCode, error.message);
+      // on a plain Error, issueCode is the FHIR issue type and txIssueType the tx-issue-type
+      return this.errorEntry(statusCode, error.issueCode || 'exception', error.message, error.txIssueType);
     }
   }
 
@@ -319,19 +317,13 @@ class BatchWorker extends TerminologyWorker {
   /**
    * Build an error response entry
    * @param {number} statusCode - HTTP status code
-   * @param {string} issueCode - FHIR issue code
+   * @param {string} issueCode - FHIR issue type
    * @param {string} message - Error message
+   * @param {string} [txIssueType] - tx-issue-type; defaulted from issueCode when not given
    * @returns {Object} Error entry
    */
-  errorEntry(statusCode, issueCode, message) {
-    const outcome = {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity: 'error',
-        code: issueCode,
-        diagnostics: message
-      }]
-    };
+  errorEntry(statusCode, issueCode, message, txIssueType = null) {
+    const outcome = buildOperationOutcome('error', issueCode, message, txIssueType);
 
     return {
       resource: outcome,
@@ -343,21 +335,17 @@ class BatchWorker extends TerminologyWorker {
   }
 
   /**
-   * Build an OperationOutcome
+   * Build an OperationOutcome. Delegates to the shared builder so that every outcome this
+   * server emits has details.text and a tx-issue-type coding: diagnostics is stripped by
+   * the test harness, so nothing a caller needs may live there.
    * @param {string} severity - error, warning, information
-   * @param {string} code - Issue code
-   * @param {string} message - Diagnostic message
+   * @param {string} code - FHIR issue type
+   * @param {string} message - the human readable account of the problem
+   * @param {string} [txIssueType] - tx-issue-type; defaulted from code when not given
    * @returns {Object} OperationOutcome resource
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        diagnostics: message
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 }
 

package/tx/workers/cache-control.js

@@ -5,20 +5,18 @@
 // POST /$cache-control?mode=start   - as above, optionally front-loading resources
 // GET  /$cache-control?mode=end     - tell the server it can release the cache now
 // POST /$cache-control?mode=end
-// (mode=check is reserved for later - report whether a cache is still valid + stats)
+// GET  /$cache-control?mode=check   - is this cache still alive? (and keep it alive)
+// POST /$cache-control?mode=check
 //
 // This is the explicit replacement for the implicit `cache-id` parameter protocol:
 // the server owns the cache-id namespace, so it can authoritatively reject an
 // unknown/expired cache later instead of failing obscurely deep inside a validation.
 //
-// NOTE: this is scaffolding. start()/end() currently parse the request into a
-// Parameters resource (the same way validate.js does) but do not yet create or
-// release anything. The behaviour is filled in by later steps.
-//
 
 const crypto = require('crypto');
 const { TerminologyWorker, CACHE_ID_HEADER } = require('./worker');
 const { Parameters } = require('../library/parameters');
+const { Issue, buildOperationOutcome, outcomeFromError } = require('../library/operation-outcome');
 const { debugLog } = require('../operation-context');
 
 class CacheControlWorker extends TerminologyWorker {
@@ -61,9 +59,11 @@ class CacheControlWorker extends TerminologyWorker {
           return await this.start(req, res);
         case 'end':
           return await this.end(req, res);
+        case 'check':
+          return await this.check(req, res);
         default:
           return res.status(400).json(this.operationOutcome('error', 'invalid',
-            `$cache-control requires a 'mode' of 'start' or 'end'` +
+            `$cache-control requires a 'mode' of 'start', 'end' or 'check'` +
             (mode ? ` (got '${mode}')` : ` (none supplied)`)));
       }
     } catch (error) {
@@ -71,8 +71,8 @@ class CacheControlWorker extends TerminologyWorker {
       debugLog(error);
       req.logInfo = this.usedSources.join('|') + ' - error' + (error.msgId ? ' ' + error.msgId : '');
       const statusCode = error.statusCode || 500;
-      const issueCode = error.issueCode || 'exception';
-      return res.status(statusCode).json(this.operationOutcome('error', issueCode, error.message));
+      return res.status(statusCode).json(
+        outcomeFromError(error));
     }
   }
 
@@ -193,6 +193,82 @@ class CacheControlWorker extends TerminologyWorker {
     return res.status(200).json({ resourceType: 'Parameters', parameter: [] });
   }
 
+  /**
+   * mode=check: report whether the cache named by the `${CACHE_ID_HEADER}` header is
+   * still alive, and - if it is - reset its idle clock.
+   *
+   * This is a keepalive as much as a probe, and deliberately so. A client's own
+   * local cache absorbs most of its terminology work, so the server can see nothing
+   * from a client that is still very much running and still relying on its cache;
+   * the cache then times out mid-job and the next request that finally does reach
+   * the server fails. Checking is exactly what a client that still cares about its
+   * cache does, so a check counts as use. (The alternative - a read-only `check`
+   * plus a separate `touch` - is two operations for one job, and there is no useful
+   * case for asking "is my cache alive?" while wanting it to expire anyway.)
+   *
+   * An unknown cache-id here is a 200 with `valid` = false, NOT the 404 that the
+   * validation path returns. A probe must be able to tell "the server is up and
+   * says my cache is gone" from "I could not reach the server" - those call for
+   * opposite responses, and collapsing them into one failure loses that. This also
+   * matches mode=end, which likewise tolerates an id the server doesn't have. The
+   * `outcome` parameter carries the same coded issue the validation path would have
+   * raised, so a client that wants the reason (never issued here / closed by the
+   * client / expired after N minutes idle) has it without a second call.
+   *
+   * @param {express.Request} req
+   * @param {express.Response} res
+   */
+  async check(req, res) {
+    const cache = this.opContext.resourceCache;
+    if (!cache) {
+      return res.status(500).json(this.operationOutcome('error', 'exception',
+        'No resource cache is available on this endpoint'));
+    }
+
+    const cacheId = req.headers[CACHE_ID_HEADER];
+    if (!cacheId) {
+      return res.status(400).json(this.operationOutcome('error', 'invalid',
+        `$cache-control mode=check requires the cache-id in the '${CACHE_ID_HEADER}' header`));
+    }
+
+    // Read the status BEFORE touching: the idle time is the interesting part of the
+    // answer, and refreshing first would report zero every time.
+    const status = cache.status(cacheId);
+
+    if (!status.exists) {
+      const { messageId, params } = cache.describeMissing(cacheId);
+      const issue = new Issue('error', 'not-found', null, messageId,
+        this.i18n.translate(messageId, this.opContext.langs, params),
+        'cache-id-unknown', 404).asIssue();
+      this.log.info(`cache-id '${cacheId}': check -> not valid (${messageId})`);
+      return res.status(200).json({
+        resourceType: 'Parameters',
+        parameter: [
+          { name: 'cache-id', valueId: cacheId },
+          { name: 'valid', valueBoolean: false },
+          { name: 'outcome', resource: { resourceType: 'OperationOutcome', issue: [issue] } }
+        ]
+      });
+    }
+
+    cache.touch(cacheId);
+
+    const parameter = [
+      { name: 'cache-id', valueId: cacheId },
+      { name: 'valid', valueBoolean: true },
+      { name: 'sealed', valueBoolean: status.sealed },
+      { name: 'resource-count', valueUnsignedInt: status.resources },
+      { name: 'idle', valueUnsignedInt: Math.floor(status.idleMs / 1000) }
+    ];
+    // The timeout lets a client work out how often it needs to check, instead of
+    // guessing against a number it cannot see. Omitted if this server isn't saying.
+    if (status.timeoutMs !== null && status.timeoutMs !== undefined) {
+      parameter.push({ name: 'timeout', valueUnsignedInt: Math.floor(status.timeoutMs / 1000) });
+    }
+
+    return res.status(200).json({ resourceType: 'Parameters', parameter });
+  }
+
   /**
    * Build an OperationOutcome.
    * @param {string} severity - error, warning, information
@@ -200,15 +276,9 @@ class CacheControlWorker extends TerminologyWorker {
    * @param {string} message - Diagnostic message
    * @returns {Object} OperationOutcome resource
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        details: { text: message }
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    // the shared builder, so that every outcome has details.text and a tx-issue-type coding
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 }
 

package/tx/workers/closure.js

@@ -5,6 +5,8 @@
 // POST /ConceptMap/$closure
 //
 
+const { buildOperationOutcome } = require('../library/operation-outcome');
+
 class ClosureWorker {
   /**
    * Handle a $closure request
@@ -18,14 +20,7 @@ class ClosureWorker {
     this.log.debug('ConceptMap $closure with params:', params);
 
     // TODO: Implement closure logic using provider
-    res.status(501).json({
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity: 'error',
-        code: 'not-supported',
-        diagnostics: 'ConceptMap $closure operation not yet implemented'
-      }]
-    });
+    res.status(501).json(buildOperationOutcome('error', 'not-supported', 'ConceptMap $closure operation not yet implemented'));
   }
 }
 

package/tx/workers/compare.js

@@ -11,7 +11,7 @@
 const { TerminologyWorker } = require('./worker');
 const {TxParameters} = require("../params");
 const {Extensions} = require("../library/extensions");
-const {Issue, OperationOutcome} = require("../library/operation-outcome");
+const { Issue, OperationOutcome, buildOperationOutcome, outcomeFromError } = require('../library/operation-outcome');
 const ValueSet = require("../library/valueset");
 const {ValueSetExpander} = require("./expand");
 const {SearchFilterText} = require("../library/designations");
@@ -59,18 +59,7 @@ class CompareWorker extends TerminologyWorker {
         oo.addIssue(error);
         return res.status(error.statusCode || 500).json(oo.jsonObj);
       } else {
-        const issueCode = error.issueCode || 'exception';
-        return res.status(statusCode).json({
-          resourceType: 'OperationOutcome',
-          issue: [{
-            severity: 'error',
-            code: issueCode,
-            details: {
-              text: error.message
-            },
-            diagnostics: error.message
-          }]
-        });
+        return res.status(statusCode).json(outcomeFromError(error));
       }
     }
   }
@@ -89,18 +78,7 @@ class CompareWorker extends TerminologyWorker {
       debugLog(error);
       req.logInfo = this.usedSources.join("|")+" - error"+(error.msgId  ? " "+error.msgId : "");
       const statusCode = error.statusCode || 500;
-      const issueCode = error.issueCode || 'exception';
-      return res.status(statusCode).json({
-        resourceType: 'OperationOutcome',
-        issue: [{
-          severity: 'error',
-          code: issueCode,
-          details: {
-            text : error.message
-          },
-          diagnostics: error.message
-        }]
-      });
+      return res.status(statusCode).json(outcomeFromError(error));
     }
   }
 
@@ -158,15 +136,9 @@ class CompareWorker extends TerminologyWorker {
    * @param {string} message - Diagnostic message
    * @returns {Object} OperationOutcome resource
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        diagnostics: message
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    // the shared builder, so that every outcome has details.text and a tx-issue-type coding
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 
   async readValueSet(res, prefix, params) {

package/tx/workers/expand.js

@@ -14,7 +14,7 @@ const {Designations, SearchFilterText} = require("../library/designations");
 const {Extensions} = require("../library/extensions");
 const {getValuePrimitive, getValueName, validateParameter} = require("../../library/utilities");
 const {div} = require("../../library/html");
-const {Issue, OperationOutcome} = require("../library/operation-outcome");
+const { Issue, OperationOutcome, buildOperationOutcome, outcomeFromError } = require('../library/operation-outcome');
 const crypto = require('crypto');
 const ValueSet = require("../library/valueset");
 const {VersionUtilities} = require("../../library/version-utilities");
@@ -447,8 +447,21 @@ class ValueSetExpander {
           }
         }
 
+        // '*' asks for every property the code system defines for the concept (R6's
+        // ValueSet.compose.property allows it, and a request can name it too). It is handled
+        // here rather than by expanding it into a list of names, because which properties
+        // exist is a property of the concept, not of the request
+        if (this.params.properties.includes('*') && csProps != null && cs != null) {
+          for (const cp of csProps) {
+            const vn = getValueName(cp);
+            this.defineProperty(expansion, n, this.getPropUrl(cs, cp.code, cp), cp.code, vn, cp[vn], true);
+          }
+        }
+
         for (const pn of this.params.properties) {
-          if (pn === 'definition') {
+          if (pn === '*') {
+            continue; // done above
+          } else if (pn === 'definition') {
             if (definition) {
               this.defineProperty(expansion, n, 'http://hl7.org/fhir/concept-properties#definition', pn, "valueString", definition);
             }
@@ -460,7 +473,9 @@ class ValueSetExpander {
               if (cp.code === pn) {
                 let vn = getValueName(cp);
                 let v = cp[vn];
-                this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, v);
+                // a concept may carry the same property more than once (the
+                // "dup" property in the test code system has two values)
+                this.defineProperty(expansion, n, this.getPropUrl(cs, pn, cp), pn, vn, v, true);
               }
             }
           }
@@ -571,19 +586,24 @@ class ValueSetExpander {
     }
     this.checkResourceCanonicalStatus(expansion, vs, this.valueSet);
 
+    const imported = [];
     for (const c of vs.expansion.contains || []) {
       await this.worker.checkAndYield('importValueSet');
-      count += await this.importValueSetItem(null, c, imports, offset);
+      count += await this.importValueSetItem(null, c, imports, offset, imported);
     }
+    this.importPropertyDefinitions(expansion, vs.expansion.property, imported);
     return count;
   }
 
-  async importValueSetItem(p, c, imports, offset) {
+  async importValueSetItem(p, c, imports, offset, imported) {
     let count = 0;
     await this.worker.checkAndYield('importValueSetItem');
     const s = this.keyC(c);
     if (this.passesImports(imports, c.system, c.code, offset) && !this.map.has(s) && !this.isExcluded(c.system, c.version, c.code)) {
       count++;
+      if (imported) {
+        imported.push(c);
+      }
       this.fullList.push(c);
       if (p != null) {
         if (!p.contains) {p.contains = [] }
@@ -595,7 +615,7 @@ class ValueSetExpander {
     }
     for (const cc of c.contains || []) {
       await this.worker.checkAndYield('importValueSetItem');
-      count += await this.importValueSetItem(c, cc, imports, offset);
+      count += await this.importValueSetItem(c, cc, imports, offset, imported);
     }
     return count;
   }
@@ -1087,7 +1107,7 @@ class ValueSetExpander {
           this.worker.opContext.log('prep filters');
           const prep = await cs.getPrepContext(true);
           if (!filter.isNull) {
-            await cs.searchFilter(filter, prep, true);
+            await cs.searchFilter(prep, filter, true);
           }
 
           if (cs.specialEnumeration()) {
@@ -1679,35 +1699,91 @@ class ValueSetExpander {
     return this.keyS(contains.system, contains.version, contains.code);
   }
 
-  defineProperty(expansion, contains, url, code, valueName, value) {
-    if (value === undefined || value == null) {
+  /**
+   * Record a property definition in expansion.property, and return the code to
+   * use for the per-concept value (an existing definition's code wins).
+   *
+   * @param {Object} expansion
+   * @param {string} url
+   * @param {string} code
+   * @returns {string}
+   */
+  declareProperty(expansion, url, code) {
+    if (!expansion.property) {
+      expansion.property = [];
+    }
+    // match on the uri only when there is one. A code system may declare several properties with
+    // no uri at all, and those are told apart by their code - matching on an undefined uri would
+    // collapse all of them into whichever one was declared first
+    let pd = url
+      ? expansion.property.find(t1 => t1.uri == url || t1.code == code)
+      : expansion.property.find(t1 => t1.code == code);
+    if (!pd) {
+      pd = {};
+      expansion.property.push(pd);
+      pd.code = code;
+      if (url) {
+        pd.uri = url;
+      }
+    } else if (url && !pd.uri) {
+      pd.uri = url;
+    }
+    if (url && pd.uri != url) {
+      throw new Error('URL mismatch on expansion: ' + pd.uri + ' vs ' + url + ' for code ' + code);
+    }
+    return pd.code;
+  }
+
+  /**
+   * Carry the property definitions of an imported expansion across to this one.
+   *
+   * Imported concepts are copied whole (see importValueSetItem), properties and
+   * all, but the definitions that give those properties a uri live on the
+   * imported expansion, so without this the outer expansion has concepts
+   * carrying a property that it never declares. Only definitions for properties
+   * that survived the import are copied.
+   *
+   * @param {Object} expansion - the expansion being built
+   * @param {Array} definitions - the imported expansion's `property`
+   * @param {Array} items - the concepts actually taken from the import
+   */
+  importPropertyDefinitions(expansion, definitions, items) {
+    if (!expansion || !definitions || definitions.length === 0 || items.length === 0) {
       return;
     }
-    // we only define it if the code system has a definition
-    if (url) {
-      if (!expansion.property) {
-        expansion.property = [];
+    const used = new Set();
+    for (const item of items) {
+      for (const property of item.property || []) {
+        used.add(property.code);
       }
-      let pd = expansion.property.find(t1 => t1.uri == url || t1.code == code);
-      if (!pd) {
-        pd = {};
-        expansion.property.push(pd);
-        pd.uri = url;
-        pd.code = code;
-      } else if (!pd.uri) {
-        pd.uri = url
-      }
-      if (pd.uri != url) {
-        throw new Error('URL mismatch on expansion: ' + pd.uri + ' vs ' + url + ' for code ' + code);
-      } else {
-        code = pd.code;
+    }
+    for (const definition of definitions) {
+      if (used.has(definition.code)) {
+        this.declareProperty(expansion, definition.uri, definition.code);
       }
     }
+  }
+
+  /**
+   * @param {boolean} [repeatable] - true when the code system may carry more than
+   *   one value for this property on one concept (only the code system property
+   *   loop passes this). Single-valued properties keep last-one-wins, so a status
+   *   derived from two sources still yields one entry.
+   */
+  defineProperty(expansion, contains, url, code, valueName, value, repeatable) {
+    if (value === undefined || value == null) {
+      return;
+    }
+    // every property that appears in contains.property has to be declared in expansion.property,
+    // whether or not the code system gave it a uri
+    code = this.declareProperty(expansion, url, code);
 
     if (!contains.property) {
       contains.property = [];
     }
-    let pdv = contains.property.find(t2 => t2.code == code);
+    let pdv = repeatable
+      ? contains.property.find(t2 => t2.code == code && t2[valueName] === value)
+      : contains.property.find(t2 => t2.code == code);
     if (!pdv) {
       pdv = {};
       contains.property.push(pdv);
@@ -1893,18 +1969,7 @@ class ExpandWorker extends TerminologyWorker {
         oo.addIssue(error);
         return res.status(error.statusCode || 500).json(oo.jsonObj);
       } else {
-        const issueCode = error.issueCode || 'exception';
-        return res.status(statusCode).json({
-          resourceType: 'OperationOutcome',
-          issue: [{
-            severity: 'error',
-            code: issueCode,
-            details: {
-              text: error.message
-            },
-            diagnostics: error.message
-          }]
-        });
+        return res.status(statusCode).json(outcomeFromError(error));
       }
     }
   }
@@ -1923,18 +1988,7 @@ class ExpandWorker extends TerminologyWorker {
       debugLog(error);
       req.logInfo = this.usedSources.join("|")+" - error"+(error.msgId  ? " "+error.msgId : "");
       const statusCode = error.statusCode || 500;
-      const issueCode = error.issueCode || 'exception';
-      return res.status(statusCode).json({
-        resourceType: 'OperationOutcome',
-        issue: [{
-          severity: 'error',
-          code: issueCode,
-          details: {
-            text : error.message
-          },
-          diagnostics: error.message
-        }]
-      });
+      return res.status(statusCode).json(outcomeFromError(error));
     }
   }
 
@@ -2196,15 +2250,9 @@ class ExpandWorker extends TerminologyWorker {
    * @param {string} message - Diagnostic message
    * @returns {Object} OperationOutcome resource
    */
-  operationOutcome(severity, code, message) {
-    return {
-      resourceType: 'OperationOutcome',
-      issue: [{
-        severity,
-        code,
-        diagnostics: message
-      }]
-    };
+  operationOutcome(severity, code, message, txIssueType = null) {
+    // the shared builder, so that every outcome has details.text and a tx-issue-type coding
+    return buildOperationOutcome(severity, code, message, txIssueType);
   }
 
 }