fhirsmith 0.9.6 → 0.10.0

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;
@@ -382,16 +389,10 @@ class TXModule {
       next();
     });
 
-    // CORS headers
-    router.use((req, res, next) => {
-      res.header('Access-Control-Allow-Origin', '*');
-      res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept');
-      res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-      if (req.method === 'OPTIONS') {
-        return res.sendStatus(200);
-      }
-      next();
-    });
+    // CORS is handled once at the app level (server.js, from config.server.cors).
+    // Do not set Access-Control-* headers here - doing so stacks a second
+    // CORS layer and produces duplicate, conflicting headers that browsers
+    // reject.
 
     // JSON body parsing - accept both application/json and application/fhir+json
     // Handle body that may already be read as a Buffer by app-level middleware
@@ -601,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);
       }
     });
 
@@ -661,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();
@@ -785,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);
       }
     });
 
@@ -980,7 +1001,9 @@ class TXModule {
     });
 
     // External source info pages
-    router.get('/info/:id', async (req, res) => {
+    // GET renders the info page; POST lets a source's info() handle a form
+    // submission (e.g. VSAC on-demand resync) and re-renders the same page.
+    const infoHandler = async (req, res) => {
       const start = Date.now();
       try {
         const source = req.txEndpoint.provider.externalSources.find(s => s.id() === req.params.id);
@@ -1000,7 +1023,9 @@ class TXModule {
       } finally {
         this.countRequest('info', Date.now() - start);
       }
-    });
+    };
+    router.get('/info/:id', infoHandler);
+    router.post('/info/:id', infoHandler);
   }
 
   /**
@@ -1131,8 +1156,9 @@ class TXModule {
 
   convertResourceToXml(res) {
     switch (res.resourceType) {
-      case "CodeSystem" : return CodeSystemXML._jsonToXml(res);
+      case "CodeSystem" : return CodeSystemXML.toXml(res);
       case "ValueSet" : return ValueSetXML.toXml(res);
+      case "ConceptMap" : return ConceptMapXML.toXml(res);
       case "Bundle" : return BundleXML.toXml(res, this.fhirVersion);
       case "CapabilityStatement" : return CapabilityStatementXML.toXml(res, "R5");
       case "TerminologyCapabilities" : return TerminologyCapabilitiesXML.toXml(res, "R5");
@@ -1178,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-vsac.js

@@ -7,6 +7,12 @@ const { VersionUtilities } = require('../../library/version-utilities');
 const folders = require('../../library/folder-setup');
 const {debugLog} = require("../operation-context");
 
+// Persisted watermark for the phase-1b _lastUpdated scan.
+const VSAC_LAST_UPDATED_KEY = 'vsac_last_updated_date';
+
+// Canonical URL prefix for VSAC value sets, so operators can enter a bare OID.
+const VSAC_VALUESET_URL_PREFIX = 'http://cts.nlm.nih.gov/fhir/ValueSet/';
+
 /**
  * VSAC (Value Set Authority Center) ValueSet provider
  * Fetches and caches ValueSets from the NLM VSAC FHIR server
@@ -21,6 +27,8 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
    * @param {number} [config.refreshIntervalHours=24] - Hours between refresh scans
    * @param {string} [config.baseUrl='http://cts.nlm.nih.gov/fhir'] - Base URL for VSAC FHIR server
    * @param {number} [config.timeoutMs=120000] - HTTP request timeout in milliseconds
+   * @param {string} [config.resyncPassword] - If set, enables the operator "resync a ValueSet"
+   *   form on the /info page, gated by this password. If unset, the form is not offered.
    */
   constructor(config, stats) {
     super();
@@ -31,6 +39,8 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
     }
 
     this.apiKey = config.apiKey;
+    // Optional operator password for the on-demand resync form (see info()).
+    this.resyncPassword = config.resyncPassword || null;
     this.cacheFolder = folders.ensureFilePath("terminology-cache/vsac");
     this.baseUrl = config.baseUrl || 'http://cts.nlm.nih.gov/fhir';
     this.refreshIntervalHours = config.refreshIntervalHours || 24;
@@ -127,6 +137,7 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
       return;
     }
     this.queue = [];
+    this._pendingLastUpdated = null;
 
     this.isRefreshing = true;
     const runId = await this.database.startRun();
@@ -185,6 +196,9 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
       this.queue = [...new Set(this.queue)];
 
       let tracking = { totalFetched: 0, totalNew: 0, totalUpdated: 0, count: 0, newCount : 0 };
+      // URLs that fail even after a requeue are permanently dropped this run; we
+      // hold the watermark back when this is non-zero so they get re-scanned.
+      let permanentFailures = 0;
       // phase 2: query for history & content
       this.requeue = [];
       for (let q of this.queue) {
@@ -204,6 +218,7 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
         try {
           await this.processContentAndHistory(q, tracking, this.requeue.length);
         } catch (error) {
+          permanentFailures++;
           debugLog(error);
           this.stats.task('VSAC Sync', error.message);
         }
@@ -212,6 +227,20 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
 
       // Reload map with fresh data
       await this._reloadMap();
+
+      // Commit the _lastUpdated watermark only now that phase 2 has durably
+      // written everything. Hold it back if any URL was permanently dropped, so
+      // those URLs are re-scanned next run (never advance past un-applied
+      // changes). If the run threw or the process restarted before this point,
+      // the watermark is left untouched and the window is re-scanned.
+      if (this._pendingLastUpdated && permanentFailures === 0) {
+        await this.database.setSetting(VSAC_LAST_UPDATED_KEY, this._pendingLastUpdated);
+      } else if (permanentFailures > 0) {
+        const holdMsg = `Holding _lastUpdated watermark: ${permanentFailures} URL(s) failed after retry; will re-scan next run`;
+        console.log(holdMsg);
+        this.stats.task('VSAC Sync', holdMsg);
+      }
+
       let msg = `VSAC refresh completed. Total: ${tracking.totalFetched} ValueSets, New: ${tracking.totalNew}, Updated: ${tracking.totalUpdated}`;
       this.stats.taskDone('VSAC Sync', msg);
       console.log(msg);
@@ -579,9 +608,7 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
    * @private
    */
   async _scanLastUpdated() {
-    const SETTING_KEY = 'vsac_last_updated_date';
-
-    let sinceDate = await this.database.getSetting(SETTING_KEY);
+    let sinceDate = await this.database.getSetting(VSAC_LAST_UPDATED_KEY);
     if (!sinceDate) {
       // No stored date — default to 10 days ago
       const d = new Date();
@@ -615,10 +642,13 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
       url = this._getNextUrl(bundle);
     }
 
-    // Store the server date for next run
-    if (serverDate) {
-      await this.database.setSetting(SETTING_KEY, serverDate);
-    }
+    // Capture the server's date but do NOT commit the watermark here. It must
+    // only advance once phase 2 has durably upserted the queued URLs; committing
+    // it now (before phase 2) means a phase-2 failure or a process restart would
+    // move the watermark past URLs that were never written, stranding them
+    // permanently. refreshValueSets() commits this._pendingLastUpdated after
+    // phase 2 completes with no dropped URLs.
+    this._pendingLastUpdated = serverDate;
 
     return count;
   }
@@ -631,8 +661,123 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
     return "history";
   }
 
-  async info() {
+  /**
+   * Whether the on-demand resync form is enabled (a resyncPassword is configured).
+   */
+  _resyncEnabled() {
+    return !!this.resyncPassword;
+  }
+
+  /**
+   * Timing-safe comparison of a provided password against the configured one.
+   * @private
+   */
+  _passwordMatches(provided) {
+    if (!this.resyncPassword) {
+      return false;
+    }
+    const a = Buffer.from(String(provided == null ? '' : provided));
+    const b = Buffer.from(String(this.resyncPassword));
+    if (a.length !== b.length) {
+      return false;
+    }
+    return crypto.timingSafeEqual(a, b);
+  }
+
+  /**
+   * Immediately resync a single ValueSet URL (all versions): fetch from VSAC,
+   * upsert, and reload the in-memory map.
+   * @param {string} url - the ValueSet canonical url
+   * @returns {Promise<number>} number of versions fetched
+   */
+  async resyncValueSet(url) {
+    const tracking = { totalFetched: 0, totalNew: 0, totalUpdated: 0, count: 0, newCount: 0 };
+    await this.processContentAndHistory(url, tracking, 1);
+    await this._reloadMap();
+    return tracking.totalFetched;
+  }
+
+  /**
+   * Handle a POST from the resync form. Validates the password (timing-safe) and,
+   * if a full sync isn't already running, resyncs the requested URL. Returns an
+   * HTML notice. Never echoes or logs the password.
+   * @private
+   */
+  async _handleResyncRequest(req) {
+    const escape = require('escape-html');
+    if (!this._resyncEnabled()) {
+      return '';
+    }
+    const body = req.body || {};
+    const url = this._expandOidOrUrl(body.url);
+
+    if (!this._passwordMatches(body.password)) {
+      // Small delay to blunt brute-forcing; reveal nothing else.
+      await new Promise(r => setTimeout(r, 1000));
+      return '<p style="color:#a00"><strong>Incorrect password &mdash; no action taken.</strong></p>';
+    }
+    if (!url) {
+      return '<p style="color:#a00">Enter a ValueSet URL to resync.</p>';
+    }
+    if (this.isRefreshing) {
+      return '<p style="color:#a60">A full sync is currently running; please retry in a few minutes.</p>';
+    }
+    try {
+      const n = await this.resyncValueSet(url);
+      console.log(`Manual resync of ${url}: ${n} version(s)`);
+      this.stats.task('VSAC Sync', `Manual resync of ${url}: ${n} version(s)`);
+      return `<p style="color:#070"><strong>Resynced ${escape(url)}: ${n} version(s).</strong></p>`;
+    } catch (error) {
+      debugLog(error);
+      return `<p style="color:#a00">Resync of ${escape(url)} failed: ${escape(error.message)}</p>`;
+    }
+  }
+
+  /**
+   * Accept either a full canonical URL or a bare VSAC OID. A dotted-decimal OID
+   * (optionally with a urn:oid: prefix) is expanded to the VSAC ValueSet URL.
+   * @private
+   */
+  _expandOidOrUrl(input) {
+    let s = (input == null ? '' : String(input)).trim();
+    if (s.toLowerCase().startsWith('urn:oid:')) {
+      s = s.substring('urn:oid:'.length);
+    }
+    if (/^[0-9]+(\.[0-9]+)+$/.test(s)) {
+      return VSAC_VALUESET_URL_PREFIX + s;
+    }
+    return s;
+  }
+
+  /**
+   * The resync form HTML, or '' when the feature is disabled (no password set).
+   * @private
+   */
+  _resyncFormHtml() {
+    if (!this._resyncEnabled()) {
+      return '';
+    }
+    return `<form method="post" autocomplete="off" style="margin:0 0 1em 0; padding:0.75em; border:1px solid #ccc; background:#f7f7f7">
+  <strong>Resync a ValueSet</strong>
+  <div style="margin-top:0.5em">
+    <label>ValueSet URL or OID: <input type="text" name="url" size="70" autocomplete="off"></label>
+  </div>
+  <div style="margin-top:0.5em">
+    <label>Password: <input type="password" name="password" autocomplete="off"></label>
+    <button type="submit">Resync</button>
+  </div>
+</form>`;
+  }
+
+  async info(req) {
     const escape = require('escape-html');
+
+    // Operator action: resync a specific ValueSet (POST from the form below).
+    let resyncNotice = '';
+    if (req && req.method === 'POST') {
+      resyncNotice = await this._handleResyncRequest(req);
+    }
+
     const db = await this.database._getReadConnection();
 
     const rows = await new Promise((resolve, reject) => {
@@ -689,7 +834,10 @@ class VSACValueSetProvider extends AbstractValueSetProvider {
         ? new Date(ts * 1000).toISOString().replace('T', ' ').substring(0, 19) + ' UTC'
         : '—';
 
-    let html = '<h3>VSAC Sync History</h3>';
+    let html = '';
+    html += this._resyncFormHtml();
+    html += resyncNotice;
+    html += '<h3>VSAC Sync History</h3>';
     html += '<table class="grid">';
     html += '<thead><tr><th>Time</th><th>Event</th><th>Detail</th></tr></thead>';
     html += '<tbody>';

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 };