fhirsmith 0.9.7 → 0.10.1

package/tx/operation-context.js

@@ -3,6 +3,7 @@ const inspector = require("inspector");
 const crypto = require("crypto");
 const {Languages} = require("../library/languages");
 const {Issue} = require("./library/operation-outcome");
+const Logger = require("../library/logger");
 
 /**
  * Check if running under a debugger
@@ -59,6 +60,37 @@ class ResourceCache {
     this.stats = stats;
     this.cache = new Map();
     this.locks = new Map(); // For thread-safety with async operations
+    this.log = Logger.getInstance().child({module: 'tx-cache'});
+    // Running total of concepts across every resource in every entry, maintained
+    // incrementally on each mutation so cache sizing/limits are O(1) to consult.
+    // Each entry also carries its own `concepts` subtotal so removal/replacement
+    // can adjust the total without rescanning.
+    this.totalConcepts = 0;
+    // High-water marks (never decremented) - the most caches and the most concepts
+    // this cache has held at once, for capacity reporting.
+    this.maxConcepts = 0;
+    this.maxSizeValue = 0;
+  }
+
+  /**
+   * Update the high-water marks after a mutation that may have grown the cache.
+   */
+  _trackMax() {
+    if (this.totalConcepts > this.maxConcepts) {
+      this.maxConcepts = this.totalConcepts;
+    }
+    if (this.cache.size > this.maxSizeValue) {
+      this.maxSizeValue = this.cache.size;
+    }
+  }
+
+  /**
+   * Concept count of a single cached resource, or 0 if it doesn't expose one.
+   * @param {Object} resource
+   * @returns {number}
+   */
+  _conceptsOf(resource) {
+    return resource && typeof resource.conceptCount === 'function' ? resource.conceptCount() : 0;
   }
 
   /**
@@ -70,8 +102,10 @@ class ResourceCache {
     const entry = this.cache.get(cacheId);
     if (entry) {
       entry.lastUsed = Date.now();
+      this.log.info(`cache-id '${cacheId}': hit, returning ${entry.resources.length} resource(s): ${entry.resources.map(r => this._resourceKey(r)).join(', ')}`);
       return [...entry.resources]; // Return a copy
     }
+    this.log.info(`cache-id '${cacheId}': miss (no entry)`);
     return [];
   }
 
@@ -92,22 +126,32 @@ class ResourceCache {
   add(cacheId, resources) {
     if (!resources || resources.length === 0) return;
 
-    const entry = this.cache.get(cacheId) || { resources: [], lastUsed: Date.now() };
+    const entry = this.cache.get(cacheId) || { resources: [], lastUsed: Date.now(), concepts: 0 };
 
-    // Merge resources, avoiding duplicates by url+version
+    // Merge resources, avoiding duplicates by url+version. Keep the entry's concept
+    // subtotal and the cache-wide total in step with each insertion/replacement.
     for (const resource of resources) {
       const key = this._resourceKey(resource);
+      const newConcepts = this._conceptsOf(resource);
       const existingIndex = entry.resources.findIndex(r => this._resourceKey(r) === key);
       if (existingIndex >= 0) {
-        // Replace existing
+        // Replace existing: adjust by the difference
+        const delta = newConcepts - this._conceptsOf(entry.resources[existingIndex]);
         entry.resources[existingIndex] = resource;
+        entry.concepts += delta;
+        this.totalConcepts += delta;
+        this.log.info(`cache-id '${cacheId}': replaced ${key}`);
       } else {
         entry.resources.push(resource);
+        entry.concepts += newConcepts;
+        this.totalConcepts += newConcepts;
+        this.log.info(`cache-id '${cacheId}': added ${key}`);
       }
     }
 
     entry.lastUsed = Date.now();
     this.cache.set(cacheId, entry);
+    this._trackMax();
   }
 
   /**
@@ -116,10 +160,23 @@ class ResourceCache {
    * @param {Array} resources - Resources to set
    */
   set(cacheId, resources) {
+    this.log.info(`cache-id '${cacheId}': set (replace all) with ${resources.length} resource(s): ${resources.map(r => this._resourceKey(r)).join(', ')}`);
+    // Drop the old entry's contribution, then count the replacement.
+    const existing = this.cache.get(cacheId);
+    if (existing) {
+      this.totalConcepts -= existing.concepts || 0;
+    }
+    let concepts = 0;
+    for (const resource of resources) {
+      concepts += this._conceptsOf(resource);
+    }
+    this.totalConcepts += concepts;
     this.cache.set(cacheId, {
       resources: [...resources],
-      lastUsed: Date.now()
+      lastUsed: Date.now(),
+      concepts
     });
+    this._trackMax();
   }
 
   /**
@@ -127,6 +184,10 @@ class ResourceCache {
    * @param {string} cacheId - The cache identifier
    */
   clear(cacheId) {
+    const entry = this.cache.get(cacheId);
+    if (entry) {
+      this.totalConcepts -= entry.concepts || 0;
+    }
     this.cache.delete(cacheId);
   }
 
@@ -135,6 +196,7 @@ class ResourceCache {
    */
   clearAll() {
     this.cache.clear();
+    this.totalConcepts = 0;
   }
 
   /**
@@ -150,6 +212,7 @@ class ResourceCache {
     for (const [cacheId, entry] of this.cache.entries()) {
       if (now - entry.lastUsed > maxAge) {
         i++;
+        this.totalConcepts -= entry.concepts || 0;
         this.cache.delete(cacheId);
       }
     }
@@ -166,6 +229,41 @@ class ResourceCache {
     return this.cache.size;
   }
 
+  /**
+   * Total number of concepts held across every entry in the cache. Maintained
+   * incrementally, so this is O(1).
+   * @returns {number}
+   */
+  conceptCount() {
+    return this.totalConcepts;
+  }
+
+  /**
+   * Highest number of concepts this cache has held at once (high-water mark).
+   * @returns {number}
+   */
+  maxConceptCount() {
+    return this.maxConcepts;
+  }
+
+  /**
+   * Highest number of caches (cache-ids) this cache has held at once.
+   * @returns {number}
+   */
+  maxSize() {
+    return this.maxSizeValue;
+  }
+
+  /**
+   * Number of concepts held under a single cache-id (0 if unknown).
+   * @param {string} cacheId
+   * @returns {number}
+   */
+  conceptCountFor(cacheId) {
+    const entry = this.cache.get(cacheId);
+    return entry ? (entry.concepts || 0) : 0;
+  }
+
   /**
    * Generate a key for a resource based on url and version
    * @param {Object} resource - The resource
@@ -437,6 +535,12 @@ class OperationContext {
     this.logEntries = [];
     this.resourceCache = resourceCache;
     this.expansionCache = expansionCache;
+    // Server-issued cache-id carried on the request (X-Cache-Id header). Set once
+    // per request from the header so every worker can consult it uniformly via
+    // setupAdditionalResources, regardless of how that worker assembles its
+    // Parameters (buildParameters, raw req.body, query/form). An explicit
+    // cache-id *parameter* still takes precedence over this.
+    this.cacheId = null;
     this.debugging = isDebugging();
     // Providers opened during this operation that need their underlying
     // resources (sqlite connections, etc.) released when the operation ends.
@@ -470,6 +574,7 @@ class OperationContext {
     newContext.timeTracker = this.timeTracker.link();
     newContext.logEntries = [...this.logEntries];
     newContext.debugging = this.debugging;
+    newContext.cacheId = this.cacheId;
     newContext.usageTracker = this.usageTracker;
     // Share the same provider-cleanup list so providers opened by the copy
     // are released when the parent operation ends.

package/tx/provider.js

@@ -231,8 +231,8 @@ class Provider {
         return vs;
       }
     }
-    let vs = await this.findKnownValueSet(url, version);
-    return vs;
+    let vs1 = await this.findKnownValueSet(url, version);
+    return vs1;
   }
 
   async getConceptMapById(opContext, id) {
@@ -381,7 +381,7 @@ class Provider {
     if (vs) {
       return {
         link: this.path+"/ValueSet/"+vs.id,
-        description: (vs.title ? vs.title : vs.name)+(version ? " v"+version : "")
+        description: (vs.title ? vs.title : vs.name)+(version ? " v"+version : vs.version ?  " v"+vs.version : "")
       };
     }
     let cm = await this.findConceptMap(opContext, system, version);

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/vs/vs-database.js

@@ -7,6 +7,30 @@ const ValueSet = require("../library/valueset");
 // Columns that can be returned directly without parsing JSON
 const INDEXED_COLUMNS = ['id', 'url', 'version', 'date', 'description', 'name', 'publisher', 'status', 'title'];
 
+/**
+ * Is `candidate` a newer version than `current`? Used to keep the version-less
+ * (bare-url) and url|major.minor map keys pointing at the latest version when several
+ * versions of the same value set are present. Handles both semver (IG/package value
+ * sets) and VSAC-style YYYYMMDD date versions (not semver, but fixed-width so they
+ * order correctly numerically).
+ * @param {string|null|undefined} candidate
+ * @param {string|null|undefined} current
+ * @returns {boolean}
+ */
+function isNewerVersion(candidate, current) {
+  if (current == null) return true;
+  if (candidate == null) return false;
+  if (candidate === current) return false;
+  if (VersionUtilities.isSemVer(candidate) && VersionUtilities.isSemVer(current)) {
+    return VersionUtilities.isThisOrLater(current, candidate); // candidate >= current (semver-aware)
+  }
+  if (/^\d+$/.test(candidate) && /^\d+$/.test(current)) {
+    // e.g. VSAC YYYYMMDD - compare numerically (handles differing widths too)
+    return Number(candidate) > Number(current);
+  }
+  return candidate > current; // best-effort lexical fallback
+}
+
 /**
  * Shared database layer for ValueSet providers
  * Handles SQLite operations for indexing and searching ValueSets
@@ -737,21 +761,22 @@ class ValueSetDatabase {
   }
 
   addToMap(valueSetMap, id, url, version, valueSet) {
-    valueSetMap.set(url, valueSet);
-    valueSetMap.set(id, valueSet);
+    // The bare-url key must resolve to the *latest* version, but rows arrive in no
+    // particular order (and several versions of the same url coexist - e.g. VSAC, where
+    // each date-version is its own row). So only overwrite it when this version is newer.
+    this._setIfNewer(valueSetMap, url, version, valueSet);
+    valueSetMap.set(id, valueSet); // id is unique per version
 
     if (version) {
-      // Store by url|version
-      const versionKey = `${url}|${version}`;
-      valueSetMap.set(versionKey, valueSet);
+      // Store by url|version (exact - unique per version, always set)
+      valueSetMap.set(`${url}|${version}`, valueSet);
 
-      // If version is semver, also store by url|major.minor
+      // If version is semver, also store by url|major.minor, keeping the latest patch
       try {
         if (VersionUtilities.isSemVer(version)) {
           const majorMinor = VersionUtilities.getMajMin(version);
           if (majorMinor) {
-            const majorMinorKey = `${url}|${majorMinor}`;
-            valueSetMap.set(majorMinorKey, valueSet);
+            this._setIfNewer(valueSetMap, `${url}|${majorMinor}`, version, valueSet);
           }
         }
       } catch (error) {
@@ -760,6 +785,14 @@ class ValueSetDatabase {
     }
   }
 
+  // Set map[key] = valueSet only if `version` is newer than the version already there.
+  _setIfNewer(valueSetMap, key, version, valueSet) {
+    const existing = valueSetMap.get(key);
+    if (!existing || isNewerVersion(version, existing.version)) {
+      valueSetMap.set(key, valueSet);
+    }
+  }
+
   /**
    * Search for ValueSets based on criteria
    * @param {Array<{name: string, value: string}>} searchParams - Search criteria

package/tx/vs/vs-package.js

@@ -26,6 +26,9 @@ class PackageValueSetProvider extends AbstractValueSetProvider {
     this.sourcePackageCode = packageLoader.id();
   }
 
+  code() {
+    return this.sourcePackageCode;
+  }
   sourcePackage() {
     return this.sourcePackageCode;
   }

package/tx/vs/vs-vsac.js

@@ -66,6 +66,10 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
     });
   }
 
+  code() {
+    return "vsac";
+  }
+
   sourcePackage() {
     return "vsac";
   }