fhirsmith 0.9.7 → 0.10.0

package/tx/tx-html.js

@@ -471,6 +471,33 @@ class TxHtmlRenderer {
     if (param.valueCode !== undefined) {
       return `<code>${escape(param.valueCode)}</code>`;
     }
+    if (param.valueId !== undefined) {
+      return escape(String(param.valueId));
+    }
+    if (param.valueOid !== undefined) {
+      return escape(String(param.valueOid));
+    }
+    if (param.valueUuid !== undefined) {
+      return escape(String(param.valueUuid));
+    }
+    if (param.valueMarkdown !== undefined) {
+      // Render markdown to HTML the same way the rest of the server does, using
+      // commonmark in safe mode (raw HTML in the markdown is escaped, so this is
+      // XSS-safe).
+      const commonmark = require('commonmark');
+      const reader = new commonmark.Parser();
+      const writer = new commonmark.HtmlRenderer({ safe: true });
+      return writer.render(reader.parse(String(param.valueMarkdown)));
+    }
+    if (param.valueInteger64 !== undefined) {
+      return escape(String(param.valueInteger64));
+    }
+    if (param.valuePositiveInt !== undefined) {
+      return escape(String(param.valuePositiveInt));
+    }
+    if (param.valueUnsignedInt !== undefined) {
+      return escape(String(param.valueUnsignedInt));
+    }
     if (param.valueDate !== undefined) {
       return escape(param.valueDate);
     }

package/tx/tx.js

@@ -27,6 +27,7 @@ const LookupWorker = require('./workers/lookup');
 const SubsumesWorker = require('./workers/subsumes');
 const { MetadataHandler } = require('./workers/metadata');
 const { BatchValidateWorker } = require('./workers/batch-validate');
+const { CacheControlWorker } = require('./workers/cache-control');
 const {CapabilityStatementXML} = require("./xml/capabilitystatement-xml");
 const {TerminologyCapabilitiesXML} = require("./xml/terminologycapabilities-xml");
 const {ParametersXML} = require("./xml/parameters-xml");
@@ -36,7 +37,7 @@ const {ConceptMapXML} = require("./xml/conceptmap-xml");
 const {TxHtmlRenderer} = require("./tx-html");
 const {Renderer} = require("./library/renderer");
 const {OperationsWorker} = require("./workers/operations");
-const {RelatedWorker} = require("./workers/related");
+const {CompareWorker} = require("./workers/compare");
 const {codeSystemFromR5} = require("./xversion/xv-codesystem");
 const {operationOutcomeFromR5} = require("./xversion/xv-operationoutcome");
 const {parametersFromR5} = require("./xversion/xv-parameters");
@@ -296,6 +297,12 @@ class TXModule {
         endpointInfo.resourceCache, endpointInfo.expansionCache
       );
       opContext.usageTracker = this.usageTracker;
+      // Normalise the cache-id from the X-Cache-Id header onto the operation
+      // context once, here, so every worker honours a front-loaded cache no
+      // matter how it later assembles its Parameters (some use buildParameters,
+      // others read req.body / query directly). An explicit cache-id parameter
+      // on the request still wins (see setupAdditionalResources).
+      opContext.cacheId = req.get('X-Cache-Id') || null;
 
       // Attach everything to request
       req.txProvider = endpointInfo.provider;
@@ -595,23 +602,23 @@ class TXModule {
       }
     });
 
-    // ValueSet/$related(GET and POST)
-    router.get('/ValueSet/\\$related', async (req, res) => {
+    // ValueSet/$compare(GET and POST)
+    router.get('/ValueSet/\\$compare', async (req, res) => {
       const start = Date.now();
       try {
-        let worker = new RelatedWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$related', Date.now() - start);
+        this.countRequest('$compare', Date.now() - start);
       }
     });
-    router.post('/ValueSet/\\$related', async (req, res) => {
+    router.post('/ValueSet/\\$compare', async (req, res) => {
       const start = Date.now();
       try {
-        let worker = new RelatedWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handle(req, res);
       } finally {
-        this.countRequest('$related', Date.now() - start);
+        this.countRequest('$compare', Date.now() - start);
       }
     });
 
@@ -655,6 +662,26 @@ class TXModule {
       }
     });
 
+    // $cache-control (GET and POST) - base-level operation: mode=start|end
+    router.get('/\\$cache-control', async (req, res) => {
+      const start = Date.now();
+      try {
+        let worker = new CacheControlWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        await worker.handle(req, res, this.log);
+      } finally {
+        this.countRequest('$cache-control', Date.now() - start);
+      }
+    });
+    router.post('/\\$cache-control', async (req, res) => {
+      const start = Date.now();
+      try {
+        let worker = new CacheControlWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        await worker.handle(req, res, this.log);
+      } finally {
+        this.countRequest('$cache-control', Date.now() - start);
+      }
+    });
+
     // ConceptMap/$translate (GET and POST)
     router.get('/ConceptMap/\\$translate', async (req, res) => {
       const start = Date.now();
@@ -779,23 +806,23 @@ class TXModule {
     });
 
 
-    // ValueSet/[id]/$related
-    router.get('/ValueSet/:id/\\$related', async (req, res) => {
+    // ValueSet/[id]/$compare
+    router.get('/ValueSet/:id/\\$compare', async (req, res) => {
       const start = Date.now();
       try {
-        let worker = new RelatedWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$related', Date.now() - start);
+        this.countRequest('$compare', Date.now() - start);
       }
     });
-    router.post('/ValueSet/:id/\\$related', async (req, res) => {
+    router.post('/ValueSet/:id/\\$compare', async (req, res) => {
       const start = Date.now();
       try {
-        let worker = new RelatedWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
+        let worker = new CompareWorker(req.txOpContext, this.log, req.txProvider, this.languages, this.i18n);
         await worker.handleInstance(req, res, this.log);
       } finally {
-        this.countRequest('$related', Date.now() - start);
+        this.countRequest('$compare', Date.now() - start);
       }
     });
 
@@ -1177,10 +1204,46 @@ class TXModule {
     }
   }
 
-  cacheCount() {
+  // Number of entries in the expansion cache, summed across endpoints.
+  expansionItemCount() {
+    let count = 0;
+    for (let ep of this.endpoints) {
+      count = count + ep.expansionCache.size();
+    }
+    return count;
+  }
+
+  // Number of concepts held in the client (resource) cache, summed across endpoints.
+  clientConceptCount() {
+    let count = 0;
+    for (let ep of this.endpoints) {
+      count = count + ep.resourceCache.conceptCount();
+    }
+    return count;
+  }
+
+  // Number of caches (cache-ids) currently held in the client cache, across endpoints.
+  clientCacheCount() {
+    let count = 0;
+    for (let ep of this.endpoints) {
+      count = count + ep.resourceCache.size();
+    }
+    return count;
+  }
+
+  // High-water marks for the client cache, summed across endpoints.
+  maxClientCacheCount() {
+    let count = 0;
+    for (let ep of this.endpoints) {
+      count = count + ep.resourceCache.maxSize();
+    }
+    return count;
+  }
+
+  maxClientConceptCount() {
     let count = 0;
     for (let ep of this.endpoints) {
-      count = count + ep.resourceCache.size() + ep.expansionCache.size();
+      count = count + ep.resourceCache.maxConceptCount();
     }
     return count;
   }

package/tx/workers/cache-control.js

@@ -0,0 +1,186 @@
+//
+// Cache Control Worker - Handles the $cache-control operation
+//
+// GET  /$cache-control?mode=start   - create a cache, return its (server-issued) id
+// 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)
+//
+// 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 { debugLog } = require('../operation-context');
+
+class CacheControlWorker extends TerminologyWorker {
+  /**
+   * @param {OperationContext} opContext - Operation context
+   * @param {Logger} log - Logger instance
+   * @param {Provider} provider - Provider for code systems and resources
+   * @param {LanguageDefinitions} languages - Language definitions
+   * @param {I18nSupport} i18n - Internationalization support
+   */
+  constructor(opContext, log, provider, languages, i18n) {
+    super(opContext, log, provider, languages, i18n);
+  }
+
+  opName() {
+    return 'cache-control';
+  }
+
+  // Not a value-set operation; the base class requires this to be implemented.
+  vsHandle() {
+    return null;
+  }
+
+  /**
+   * Express entry point for /$cache-control (GET and POST).
+   * Dispatches on the `mode` query parameter.
+   * @param {express.Request} req - Express request
+   * @param {express.Response} res - Express response
+   */
+  async handle(req, res) {
+    try {
+      const mode = this.getMode(req);
+      // GET is accepted as well as POST, for consistency with the server's other
+      // operations (which are all browsable) and the convenience of poking
+      // $cache-control from a browser. The operation is declared affectsState=true
+      // in its OperationDefinition, so conformant clients POST; an accidental
+      // GET-created cache is an empty entry that self-expires.
+      switch (mode) {
+        case 'start':
+          return await this.start(req, res);
+        case 'end':
+          return await this.end(req, res);
+        default:
+          return res.status(400).json(this.operationOutcome('error', 'invalid',
+            `$cache-control requires a 'mode' of 'start' or 'end'` +
+            (mode ? ` (got '${mode}')` : ` (none supplied)`)));
+      }
+    } catch (error) {
+      this.log.error(error);
+      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));
+    }
+  }
+
+  /**
+   * Determine the requested mode. The cache-control mode travels in the query
+   * string (?mode=start) so it survives even when a Parameters resource is POSTed
+   * as the body; a `mode` parameter in the body is accepted as a fallback.
+   * @param {express.Request} req
+   * @returns {string|null}
+   */
+  getMode(req) {
+    if (req.query && req.query.mode) {
+      return String(req.query.mode);
+    }
+    if (req.body && req.body.resourceType === 'Parameters') {
+      const p = this.findParameter(req.body, 'mode');
+      if (p) {
+        return this.getParameterValue(p);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * mode=start: mint a server-issued cache-id, create the (per-endpoint) cache,
+   * front-load any supplied resources into it, and return the id in the body.
+   *
+   * The id is returned in the body rather than a header to keep it readable by
+   * browser clients without CORS expose-header configuration; subsequent calls
+   * carry it back as the `${CACHE_ID_HEADER}` request header.
+   *
+   * The cache is created even when no resources are front-loaded: an explicitly
+   * empty cache must still *exist* so the server can later tell "cache I issued,
+   * currently empty" from "cache-id I never issued". That's why this uses
+   * ResourceCache.set (which always creates the entry) rather than add (which
+   * ignores empty resource lists).
+   *
+   * @param {express.Request} req
+   * @param {express.Response} res
+   */
+  async start(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 params = new Parameters(this.buildParameters(req));
+    const { txResources, primaryResources } = this.collectSuppliedResources(params.jsonObj);
+    const resources = txResources.concat(primaryResources);
+
+    const cacheId = crypto.randomUUID();
+    cache.set(cacheId, resources);
+
+    return res.status(200).json({
+      resourceType: 'Parameters',
+      parameter: [
+        { name: 'cache-id', valueId: cacheId }
+      ]
+    });
+  }
+
+  /**
+   * mode=end: release the cache named by the `${CACHE_ID_HEADER}` header so the
+   * server can reclaim it now rather than waiting for the idle timeout.
+   *
+   * Releasing is idempotent: ending an id the server doesn't have is not an error
+   * here (the authoritative "unknown cache" signal belongs on the validation path,
+   * a later step). A missing header is a client error, though.
+   *
+   * @param {express.Request} req
+   * @param {express.Response} res
+   */
+  async end(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=end requires the cache-id in the '${CACHE_ID_HEADER}' header`));
+    }
+
+    cache.clear(cacheId);
+
+    return res.status(200).json({ resourceType: 'Parameters', parameter: [] });
+  }
+
+  /**
+   * Build an OperationOutcome.
+   * @param {string} severity - error, warning, information
+   * @param {string} code - Issue code
+   * @param {string} message - Diagnostic message
+   * @returns {Object} OperationOutcome resource
+   */
+  operationOutcome(severity, code, message) {
+    return {
+      resourceType: 'OperationOutcome',
+      issue: [{
+        severity,
+        code,
+        details: { text: message }
+      }]
+    };
+  }
+}
+
+module.exports = { CacheControlWorker, CACHE_ID_HEADER };

package/tx/workers/{related.js → compare.js}

@@ -1,11 +1,11 @@
 //
-// Related Worker - Handles ValueSet $related operation
+// Compare Worker - Handles ValueSet $compare operation
 //
-// GET /ValueSet/{id}/$related
-// GET /ValueSet/$related?url=...&version=...
-// POST /ValueSet/$related (form body or Parameters with url)
-// POST /ValueSet/$related (body is ValueSet resource)
-// POST /ValueSet/$related (body is Parameters with valueSet parameter)
+// GET /ValueSet/{id}/$compare
+// GET /ValueSet/$compare?url=...&version=...
+// POST /ValueSet/$compare (form body or Parameters with url)
+// POST /ValueSet/$compare (body is ValueSet resource)
+// POST /ValueSet/$compare (body is Parameters with valueSet parameter)
 //
 
 const { TerminologyWorker } = require('./worker');
@@ -18,7 +18,7 @@ const {SearchFilterText} = require("../library/designations");
 const {ArrayMatcher} = require("../../library/utilities");
 const {debugLog} = require("../operation-context");
 
-class RelatedWorker extends TerminologyWorker {
+class CompareWorker extends TerminologyWorker {
   showLogic = false;
 
   /**
@@ -37,18 +37,18 @@ class RelatedWorker extends TerminologyWorker {
    * @returns {string}
    */
   opName() {
-    return 'related';
+    return 'compare';
   }
 
   /**
-   * Handle a type-level $related request
-   * GET/POST /ValueSet/$related
+   * Handle a type-level $compare request
+   * GET/POST /ValueSet/$compare
    * @param {express.Request} req - Express request
    * @param {express.Response} res - Express response
    */
   async handle(req, res) {
     try {
-      await this.handleTypeLevelRelated(req, res);
+      await this.handleTypeLevelCompare(req, res);
     } catch (error) {
       this.log.error(error);
       debugLog(error);
@@ -76,14 +76,14 @@ class RelatedWorker extends TerminologyWorker {
   }
 
   /**
-   * Handle an instance-level $related request
-   * GET/POST /ValueSet/{id}/$related
+   * Handle an instance-level $compare request
+   * GET/POST /ValueSet/{id}/$compare
    * @param {express.Request} req - Express request
    * @param {express.Response} res - Express response
    */
   async handleInstance(req, res) {
     try {
-      await this.handleInstanceLevelRelated(req, res);
+      await this.handleInstanceLevelCompare(req, res);
     } catch (error) {
       this.log.error(error);
       debugLog(error);
@@ -105,11 +105,11 @@ class RelatedWorker extends TerminologyWorker {
   }
 
   /**
-   * Handle type-level $related: /ValueSet/$related
+   * Handle type-level $compare: /ValueSet/$compare
    * ValueSet identified by url, or provided directly in body
    */
-  async handleTypeLevelRelated(req, res) {
-    this.deadCheck('related-type-level');
+  async handleTypeLevelCompare(req, res) {
+    this.deadCheck('compare-type-level');
 
     let params = req.body;
     this.addHttpParams(req, params);
@@ -121,16 +121,16 @@ class RelatedWorker extends TerminologyWorker {
     let thisVS = await this.readValueSet(res, "this", params, txp);
     let otherVS = await this.readValueSet(res, "other", params, txp);
 
-    const result = await this.doRelated(txp, thisVS, otherVS);
+    const result = await this.doCompare(txp, thisVS, otherVS);
     return res.json(result);
   }
   
   /**
-   * Handle instance-level related: /ValueSet/{id}/$related
+   * Handle instance-level compare: /ValueSet/{id}/$compare
    * ValueSet identified by resource ID
    */
-  async handleInstanceLevelRelated(req, res) {
-    this.deadCheck('related-instance-level');
+  async handleInstanceLevelCompare(req, res) {
+    this.deadCheck('compare-instance-level');
 
     let params = req.body;
     this.addHttpParams(req, params);
@@ -147,7 +147,7 @@ class RelatedWorker extends TerminologyWorker {
     }
     let otherVS = await this.readValueSet(res, "other", params, txp);
 
-    const result = await this.doRelated(txp, thisVS, otherVS);
+    const result = await this.doCompare(txp, thisVS, otherVS);
     return res.json(result);
   }
   
@@ -198,7 +198,7 @@ class RelatedWorker extends TerminologyWorker {
     }
   }
 
-  async doRelated(txp, thisVS, otherVS) {
+  async doCompare(txp, thisVS, otherVS) {
 
     // ok, we have to compare the composes. we don't care about anything else
     const thisC = thisVS.jsonObj.compose;
@@ -206,12 +206,12 @@ class RelatedWorker extends TerminologyWorker {
     if (!thisC) {
       return this.makeOutcome("indeterminate", `The ValueSet ${thisVS.vurl} has no compose`);
     }
-    Extensions.checkNoModifiers(thisC, 'RelatedWorker.doRelated', 'compose', thisVS.vurl)
+    Extensions.checkNoModifiers(thisC, 'CompareWorker.doCompare', 'compose', thisVS.vurl)
     this.checkNoLockedDate(thisVS.vurl, thisC);
     if (!otherC) {
       return this.makeOutcome("indeterminate", `The ValueSet ${otherVS.vurl} has no compose`);
     }
-    Extensions.checkNoModifiers(otherC, 'RelatedWorker.doRelated', 'compose', otherVS.vurl)
+    Extensions.checkNoModifiers(otherC, 'CompareWorker.doCompare', 'compose', otherVS.vurl)
     this.checkNoLockedDate(otherVS.vurl, otherC);
 
     let systems = new Map(); // tracks whether the comparison is version dependent or not
@@ -268,7 +268,7 @@ class RelatedWorker extends TerminologyWorker {
     } else if (status.left) {
       outcome = this.makeOutcome("superset", `The valueSet ${thisVS.vurl} is a super-set of the valueSet ${otherVS.vurl}`);
     } else {
-      outcome = this.makeOutcome("subset", `The valueSet ${thisVS.vurl} is a seb-set of the valueSet ${otherVS.vurl}`);
+      outcome = this.makeOutcome("subset", `The valueSet ${thisVS.vurl} is a sub-set of the valueSet ${otherVS.vurl}`);
     }
     if (txp.diagnostics) {
       outcome.parameter.push({name: 'performed-expansion', valueBoolean: exp ? true : false})
@@ -712,5 +712,5 @@ class RelatedWorker extends TerminologyWorker {
 }
 
 module.exports = {
-  RelatedWorker
+  CompareWorker
 };

package/tx/workers/metadata.js

@@ -233,7 +233,7 @@ class MetadataHandler {
               operation: [
                 { name: 'expand', definition: 'http://hl7.org/fhir/OperationDefinition/ValueSet-expand' },
                 { name: 'validate-code', definition: 'http://hl7.org/fhir/OperationDefinition/ValueSet-validate-code' },
-                { name: 'related', definition: 'https://raw.githubusercontent.com/HealthIntersections/FHIRsmith/refs/heads/main/tx/data/OperationDefinition-ValueSet-related.json' }
+                { name: 'compare', definition: 'http://hl7.org/fhir/tools/OperationDefinition/ValueSet-compare' }
               ]
             },
             {
@@ -266,7 +266,8 @@ class MetadataHandler {
             { name: 'validate-code', definition: 'http://hl7.org/fhir/OperationDefinition/Resource-validate-code' },
             { name: 'translate', definition: 'http://hl7.org/fhir/OperationDefinition/ConceptMap-translate' },
             { name: 'closure', definition: 'http://hl7.org/fhir/OperationDefinition/ConceptMap-closure' },
-            { name: 'related', definition: 'https://raw.githubusercontent.com/HealthIntersections/FHIRsmith/refs/heads/main/tx/data/OperationDefinition-ValueSet-related.json' },
+            { name: 'compare', definition: 'http://hl7.org/fhir/tools/OperationDefinition/ValueSet-compare' },
+            { name: 'cache-control', definition: 'http://hl7.org/fhir/tools/OperationDefinition/cache-control' },
             { name: 'versions', definition: 'http://hl7.org/fhir/OperationDefinition/fhir-versions' }
           ]
         }
@@ -395,10 +396,14 @@ class MetadataHandler {
   buildExpansionCapabilities() {
     return {
       parameter: [
-        {
-          name: 'cache-id',
-          documentation: 'This server supports caching terminology resources between calls. Clients only need to send value sets and codesystems once; thereafter they are automatically in scope for calls with the same cache-id. The cache is retained for 30 min from last call'
-        },
+        // NOTE: `cache-id` is deliberately not advertised as an expansion parameter.
+        // Caching is now discovered via the $cache-control operation in the
+        // CapabilityStatement, not by advertising a cache-id parameter here. The old
+        // advertisement implied the implicit "auto-create on first sight" protocol,
+        // which has been replaced: a cache must be created explicitly with
+        // $cache-control?mode=start before its cache-id can be used. Clients that
+        // only know the old mechanism will see no cache-id parameter and simply not
+        // cache (inlining each request), which is correct, just not optimised.
         {
           name: 'tx-resource',
           documentation: 'Additional valuesets needed for evaluation e.g. value sets referred to from the import statement of the value set being expanded'