fhirsmith 0.18.1 → 0.18.2

package/registry/api.js

@@ -27,6 +27,20 @@ function securityFlags(security) {
   }
 }
 
+// Code systems that tx.fhir.org handles specially. When the registry doesn't settle where
+// a request involving one of these goes, it goes to the primary server (see chooseServer)
+const SNOMED_CT = 'http://snomed.info/sct';
+const PRIMARY_SERVER_SYSTEMS = ['http://unitsofmeasure.org', 'http://loinc.org', SNOMED_CT,
+  'http://www.nlm.nih.gov/research/umls/rxnorm', 'http://hl7.org/fhir/sid/cvx', 'urn:ietf:bcp:13', 'urn:ietf:bcp:47',
+  'urn:ietf:rfc:3986', 'http://www.ama-assn.org/go/cpt', 'urn:oid:1.2.36.1.2001.1005.17', 'urn:iso:std:iso:3166',
+  'http://varnomen.hgvs.org', 'http://unstats.un.org/unsd/methods/m49/m49.htm', 'urn:iso:std:iso:4217',
+  'http://hl7.org/fhir/sid/ndc', 'http://fhir.ohdsi.org/CodeSystem/concepts', 'http://fdasis.nlm.nih.gov', 'https://www.usps.com/'];
+
+function isTxFhirOrg(server) {
+  const s = server.replace('http://', 'https://');
+  return s.startsWith('https://tx.fhir.org/') || s.startsWith('https://tx-dev.fhir.org/');
+}
+
 class RegistryAPI {
   constructor(crawler) {
     this.crawler = crawler;
@@ -592,6 +606,170 @@ class RegistryAPI {
     };
   }
 
+  /**
+   * Choose one server for a request that involves a set of code systems.
+   *
+   * This is a server side copy of the routing logic in the HL7 Java tooling
+   * (TerminologyClientManager.chooseServer in org.hl7.fhir.core), for clients that aren't
+   * Java. It doesn't replace that code. The Java client does the work that needs its own
+   * context before routing, and so must the caller here:
+   *
+   * - systems: the code systems involved, as url or url|version, from the codings and the
+   *   value set's includes and excludes, following imported value sets. Versions fixed by
+   *   expansion parameters (system-version, force-system-version) should already be applied.
+   *   If the caller couldn't follow an import, it should just use its default server.
+   * - language: only for language sensitive requests (see resolveCodeSystem).
+   *
+   * Differences from the Java code:
+   * - 'Does a candidate really have the code system' is answered from the content mode the
+   *   server reported in its TerminologyCapabilities, not by searching the server. If it
+   *   didn't report one, the candidate is assumed to be usable.
+   * - The 'primary server' for the systems tx.fhir.org handles specially is the default.
+   * - The value set's source server is found by resolving the value set here.
+   * - Ties are broken by order (the first system, then registration order), not hash order.
+   *
+   * @returns {{server: string, log: string[]}} the server to use, and why
+   */
+  chooseServer(fhirVersion, systems, defaultServer, valueSet = '', usage = '', language = '') {
+    if (!fhirVersion) {
+      throw new Error('A FHIR version is required');
+    }
+    if (!defaultServer) {
+      throw new Error('A default server is required');
+    }
+    const log = [];
+    const list = [...new Set((systems || []).filter(s => s))];
+    if (valueSet) {
+      log.push(`Value set: ${valueSet}`);
+    }
+    if (list.length === 0) {
+      log.push('No code systems: using the default server');
+      return { server: defaultServer, log };
+    }
+    const server = this._chooseServer(fhirVersion, list, defaultServer, valueSet, usage, language, log);
+    return { server, log };
+  }
+
+  _chooseServer(fhirVersion, systems, defaultServer, valueSet, usage, language, log) {
+    // what the registry says about each system on its own
+    const choices = systems.map(system => {
+      const r = this.resolveCodeSystem(fhirVersion, system, false, usage, language).result;
+      const choice = { system, authoritative: [], candidates: [], content: {} };
+      for (const e of r.authoritative || []) {
+        if (!choice.authoritative.includes(e.url)) choice.authoritative.push(e.url);
+      }
+      for (const e of r.candidates || []) {
+        if (!choice.candidates.includes(e.url)) {
+          choice.candidates.push(e.url);
+          choice.content[e.url] = e.content;
+        }
+      }
+      log.push(`${system}: authoritative [${choice.authoritative.join(', ')}], candidates [${choice.candidates.join(', ')}]`);
+      return choice;
+    });
+    // the registry knows no server at all for the system
+    const unresolved = c => c.authoritative.length === 0 && c.candidates.length === 0;
+
+    // 1. a server that's authoritative for all of them
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => t.authoritative.includes(s))) {
+          log.push(`Found authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 2. a server that's authoritative for one of them, and a candidate for the others. A
+    // system that no server is known for doesn't constrain the choice
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => unresolved(t) || t.authoritative.includes(s) || t.candidates.includes(s))) {
+          log.push(`Found partially authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 3. code systems with special handling on tx.fhir.org, that might not be resolved above.
+    // We don't want them going to secondary servers by accident
+    const bases = systems.map(s => s.includes('|') ? s.substring(0, s.indexOf('|')) : s);
+    if (systems.length > 1 && bases.includes(SNOMED_CT)) {
+      log.push(`Several code systems including SNOMED CT: choosing for SNOMED CT alone`);
+      return this._chooseServer(fhirVersion, [SNOMED_CT], defaultServer, valueSet, usage, language, log);
+    }
+    const special = bases.find(b => PRIMARY_SERVER_SYSTEMS.includes(b));
+    if (special) {
+      log.push(`Use primary server (the default) for ${special}`);
+      return defaultServer;
+    }
+
+    // 4. a server that's a candidate for all of them (again, systems no server is known for
+    // don't constrain the choice), and that has a usable copy of the code systems
+    for (const c of choices) {
+      for (const s of c.candidates) {
+        if (choices.every(t => unresolved(t) || t.candidates.includes(s)) &&
+          this._supportsAll(s, choices, unresolved, log)) {
+          log.push(`Found candidate server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 5. no agreement - take the one that is most authoritative
+    const counts = new Map();
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        counts.set(s, (counts.get(s) || 0) + 1);
+      }
+    }
+    let max = null;
+    for (const [s, n] of counts) {
+      if (max === null || n > counts.get(max)) max = s;
+    }
+    if (max !== null) {
+      log.push(`Found most authoritative server ${max}`);
+      return max;
+    }
+
+    // 6. nothing. Use the server the value set comes from, if it comes from one, else the default
+    const why = systems.length === 1 ? 'Not handled by any servers' : 'Handled by multiple servers';
+    if (valueSet) {
+      const r = this.resolveValueSet(fhirVersion, valueSet, false, usage).result;
+      let source = (r.authoritative || []).concat(r.candidates || []).map(e => e.url)[0];
+      if (source === 'https://vsac.nlm.nih.gov') {
+        source = defaultServer;
+      }
+      if (source) {
+        log.push(`${why}. Using source @ '${source}'`);
+        return source;
+      }
+    }
+    log.push(`${why}. Using the default server`);
+    return defaultServer;
+  }
+
+  /**
+   * Whether a candidate server has a usable copy (complete or fragment) of each code system
+   * it's a candidate for. Systems for which tx.fhir.org is a candidate aren't checked
+   */
+  _supportsAll(server, choices, unresolved, log) {
+    if (isTxFhirOrg(server)) {
+      return true;
+    }
+    for (const t of choices) {
+      if (unresolved(t) || !t.candidates.includes(server) || t.candidates.some(isTxFhirOrg)) {
+        continue;
+      }
+      const content = t.content[server];
+      if (content && content !== 'complete' && content !== 'fragment') {
+        log.push(`Candidate server ${server} dropped for ${t.system}: its copy of the code system is '${content}'`);
+        return false;
+      }
+    }
+    return true;
+  }
+
   /**
    * The ecosystem Discovery API (GET {root} as JSON): one row per server endpoint.
    *
@@ -774,7 +952,7 @@ class RegistryAPI {
       }
       html += '</td>\n';
 
-      html += `<td>${row.security}/td>\n`;
+      html += `<td>${escape(row.security)}</td>\n`;
 
       html += '</tr>\n';
     }

package/registry/crawler.js

@@ -160,6 +160,8 @@ class RegistryCrawler {
       }
       
       newData.doco = masterJson.documentation || '';
+      newData.registration = masterJson.registration || '';
+      newData.ecosystemDoco = masterJson['ecosystem-documentation'] || '';
       
       // Process each registry
       const registries = masterJson.registries || [];

package/registry/documentation/api.md

@@ -15,12 +15,13 @@ contract:
 Every response carries `Link: </tx-reg/openapi.json>; rel="service-desc"` (RFC 8631), and the
 HTML pages the matching `<link>` element.
 
-There are two operations, both `GET`:
+There are two operations from the ecosystem IG, and one extension, all `GET`:
 
 | Endpoint | |
 |---|---|
 | `/tx-reg/` | **Discovery** - the server endpoints in the ecosystem |
 | `/tx-reg/resolve` | **Resolution** - which endpoints to use for a code system or value set |
+| `/tx-reg/choose-server` | **Server choice** - which one server to use for a request involving several code systems (JSON only; [below](#server-choice-get-tx-regchoose-server)) |
 
 Both answer JSON, or an HTML page when the request's `Accept` header contains `text/html`.
 `/tx-reg/resolve` in a browser without parameters is a form for trying it. Parameters are read
@@ -143,7 +144,72 @@ when empty, so an empty object means nobody hosts it.
 * Resolve takes `version` as an alternative to `url|version`.
 * Resolve omits `authoritative` and `candidates` when they are empty.
 
-## Operational pages
+## Server choice: `GET /tx-reg/choose-server`
+
+Not in the ecosystem IG. A request often involves several code systems - a value set that
+includes LOINC and a national code system, a CodeableConcept with codings from three - and
+resolution answers for one at a time. The HL7 Java tooling combines the answers into a choice
+of one server (`TerminologyClientManager.chooseServer` in org.hl7.fhir.core); this makes the
+same choice here for clients that aren't Java. It doesn't replace the Java code, which still
+does its own choosing.
+
+| Parameter | |
+|---|---|
+| `fhirVersion` | Required, as for resolve |
+| `system` | A code system the request involves, `url` or `url\|version`. Repeat it for each (`system=a&system=b`) - the one parameter that isn't first-value-only |
+| `default` | Required. The client's default terminology server: the fallback, and the server for the code systems tx.fhir.org handles specially |
+| `valueSet` | The value set the request is about, `url` or `url\|version`, if there is one |
+| `language` | As for resolve, but only for language sensitive requests (an expansion where the display language matters, a validation that checks a display, a lookup that returns designations) |
+| `usage` | As for resolve |
+
+```json
+{
+  "server": "https://tx.ontoserver.csiro.au/fhir",
+  "log": [
+    "https://healthterminologies.gov.au/fhir/CodeSystem/x: authoritative [https://tx.ontoserver.csiro.au/fhir], candidates []",
+    "http://terminology.hl7.org/CodeSystem/v2-0203: authoritative [http://tx.fhir.org/r4], candidates [https://tx.ontoserver.csiro.au/fhir]",
+    "Found partially authoritative server https://tx.ontoserver.csiro.au/fhir"
+  ]
+}
+```
+
+`log` is for people: what resolution says about each code system, then the rule that decided.
+
+### What the client does first
+
+What the Java tooling works out before it chooses, a client must too:
+
+* The code systems: from the codings, and from the value set's includes and excludes,
+  following imported value sets. The imports are often only in the client's own context (the
+  IG being built), so the registry can't follow them. If the client can't follow one, it
+  should use its default server without asking.
+* Versions: those fixed by the expansion parameters (`system-version`,
+  `force-system-version`) applied to the systems.
+* Language: for an expansion, the `displayLanguage` of the expansion parameters if no other.
+
+### How the choice is made
+
+In order:
+
+1. A server authoritative for all the code systems.
+2. A server authoritative for one, and authoritative or a candidate for each of the others.
+3. Several code systems including SNOMED CT: the choice for SNOMED CT alone. Otherwise, if a
+   code system is one tx.fhir.org handles specially (LOINC, UCUM, RxNorm, CVX, NDC, CPT,
+   BCP-13/47, ISO 3166/4217 ...): the default.
+4. A server that is a candidate for all of them, and has a usable copy of each - its
+   TerminologyCapabilities says `complete` or `fragment`, or gives no content mode. Not
+   checked for a code system tx.fhir.org is also a candidate for.
+5. The server authoritative for the most of them (the first, on a tie).
+6. The server the value set comes from (by resolving `valueSet`), else the default.
+
+In 2 and 4, a code system that no server hosts doesn't count against a server.
+
+Where this differs from the Java tooling: step 4 uses the content mode the registry scanned
+instead of searching the server, and trusts a server that didn't say; the special handling in
+step 3 sends to `default` rather than to whichever of tx.fhir.org / tx-dev the client has used;
+ties go to the first rather than to hash order. Step 3 is tx.fhir.org specific, and applies to
+any ecosystem for now.
+
 
 These are HTML, not part of the API, and never secured:
 

package/registry/documentation/internals.md

@@ -28,7 +28,10 @@ How the module works, for anyone changing it. The user-facing behaviour is in
 `RegistryCrawler.crawl()` runs every `crawlInterval` minutes (first 5 seconds after start),
 and never concurrently with itself. A scan builds a fresh `ServerRegistries` from scratch:
 
-1. fetch the master registration file (`formatVersion` must be `"1"`);
+1. fetch the master registration file (`formatVersion` must be `"1"`); its optional
+   `registration` and `ecosystem-documentation` URLs are the "Register your own server" and
+   "Documentation" links on the home page (each is omitted if the file doesn't give it), since
+   they depend on the ecosystem;
 2. for each registry it lists, fetch the registry file and build a `ServerRegistry`;
 3. for each server, a `ServerInformation` with its claims (`authoritative`,
    `authoritative-valuesets`, `languages`, `usage`, `exclusions`), and for each of its

package/registry/documentation/readme.md

@@ -27,8 +27,9 @@ it, [api.md](api.md) says so.
 
 **The registration files.** The ecosystem is declared by a *master registration file* that
 lists *registries*, each of which lists *servers*, each of which lists its endpoints (one per
-FHIR version) and its claims. The format is documented in the ig-registry repository's
-[tx-registry-doco.md](https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md).
+FHIR version) and its claims. The format is documented on the IG's ecosystem page; HL7's own
+ecosystem (its locations, and how to register a server in it) is documented in the ig-registry
+repository's [tx-registry-doco.md](https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md).
 HL7's master file is https://fhir.github.io/ig-registry/tx-servers.json, and its registries
 are the per-affiliate `*-tx-servers.json` files in the same repository (HL7 International,
 HL7 Australia, HL7 Europe, and so on). A server's registration carries:

package/registry/model.js

@@ -362,6 +362,8 @@ class ServerRegistries {
   constructor() {
     this.address = '';
     this.doco = '';
+    this.registration = ''; // URL: how to register your own server in this ecosystem
+    this.ecosystemDoco = ''; // URL: documentation for this ecosystem
     this.lastRun = null; // Date object
     this.outcome = '';
     this.registries = []; // Array of ServerRegistry
@@ -386,6 +388,8 @@ class ServerRegistries {
     this.lastRun = source.lastRun;
     this.outcome = source.outcome;
     this.doco = source.doco;
+    this.registration = source.registration;
+    this.ecosystemDoco = source.ecosystemDoco;
     
     source.registries.forEach(sourceRegistry => {
       const existing = this.getRegistry(sourceRegistry.code);
@@ -402,6 +406,8 @@ class ServerRegistries {
       version: '1',
       address: this.address,
       doco: this.doco,
+      registration: this.registration,
+      'ecosystem-documentation': this.ecosystemDoco,
       'last-run': this.lastRun?.toISOString() || '',
       outcome: this.outcome,
       registries: this.registries.map(r => r.toJSON())
@@ -416,6 +422,8 @@ class ServerRegistries {
     const instance = new ServerRegistries();
     instance.address = json.address || '';
     instance.doco = json.doco || '';
+    instance.registration = json.registration || '';
+    instance.ecosystemDoco = json['ecosystem-documentation'] || '';
     instance.lastRun = json['last-run'] ? new Date(json['last-run']) : null;
     instance.outcome = json.outcome || '';
     instance.registries = (json.registries || []).map(r => ServerRegistry.fromJSON(r));

package/registry/openapi.yaml

@@ -25,6 +25,9 @@ info:
     * **Resolution** (`GET /resolve`): which server should be used for this code system
       or value set?
 
+    It also offers **server choice** (`GET /choose-server`): given all the code systems a
+    request involves, and the client's default server, which one server should it go to?
+
     Servers can claim to be **authoritative** for code systems and value sets (by URL
     mask) in their registration. A server that hosts the content but makes no claim is a
     **candidate**. A server is only ever returned for content it actually hosts.
@@ -182,6 +185,77 @@ paths:
               schema: { $ref: '#/components/schemas/Error' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  /choose-server:
+    get:
+      tags: [resolution]
+      operationId: chooseServer
+      summary: Choose one server for a request involving several code systems
+      description: |
+        For clients that aren't the HL7 Java tooling: the same choice the Java tooling makes
+        (TerminologyClientManager.chooseServer), made from the registry's own data. Returns
+        the server to send the request to, and a log of how it was chosen.
+
+        The client works out the code systems the request involves - from the codings, and
+        the value set's includes and excludes, following imported value sets - and applies
+        any versions fixed by expansion parameters. If it can't follow an import, it should
+        use its default server without asking.
+
+        In order, the choice is:
+
+        1. a server authoritative for all the code systems
+        2. a server authoritative for one, and authoritative or a candidate for the others
+        3. for several code systems including SNOMED CT, the choice for SNOMED CT alone; for
+           a code system tx.fhir.org handles specially (LOINC, UCUM, RxNorm ...), the default
+        4. a server that is a candidate for all of them, and reports a usable (complete or
+           fragment) copy of each, or no content mode at all
+        5. the server authoritative for the most of them
+        6. the server the value set comes from (resolved by `valueSet`), else the default
+
+        In 2 and 4, a code system that no server hosts doesn't count against a server.
+      parameters:
+        - name: fhirVersion
+          in: query
+          required: true
+          description: The FHIR version, as a release code (`R4`, `R4B`, `R5` ...) or a version (`4.0.1`, `4.0`).
+          schema: { type: string }
+          example: R4
+        - name: system
+          in: query
+          description: |
+            A code system the request involves, `url` or `url|version`. Repeat for each one
+            (`system=a&system=b`). With none, the answer is the default server.
+          schema: { type: array, items: { type: string } }
+          style: form
+          explode: true
+          example: [http://loinc.org, http://snomed.info/sct|http://snomed.info/sct/32506021000036107]
+        - name: default
+          in: query
+          required: true
+          description: The client's default terminology server (the one it would use without the ecosystem).
+          schema: { type: string, format: uri }
+          example: http://tx.fhir.org/r4
+        - name: valueSet
+          in: query
+          description: The value set the request is about, `url` or `url|version`, if there is one. Used for the log, and in step 6.
+          schema: { type: string }
+        - $ref: '#/components/parameters/language'
+        - name: usage
+          in: query
+          description: What the client is doing, for servers that restrict their use (as for `/resolve`).
+          schema: { type: string }
+      responses:
+        '200':
+          description: The chosen server
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChooseServerResult' }
+        '400':
+          description: A required parameter is missing, or a URL is malformed
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
 components:
   securitySchemes:
     bearer:
@@ -311,6 +385,16 @@ components:
           type: array
           items: { $ref: '#/components/schemas/ResolvedServer' }
 
+    ChooseServerResult:
+      type: object
+      required: [server, log]
+      properties:
+        server: { type: string, format: uri, description: The FHIR endpoint to send the request to }
+        log:
+          type: array
+          items: { type: string }
+          description: How the server was chosen - what the registry says about each code system, then the rule that decided. For people, not for parsing
+
     ResolvedServer:
       allOf:
         - $ref: '#/components/schemas/SecurityFlags'

package/registry/registry.js

@@ -20,6 +20,7 @@ const { RegistryAuth } = require('./auth');
 // parameters are ignored) because existing ecosystem clients rely on that.
 const DISCOVERY_PARAMS = ['registry', 'server', 'fhirVersion', 'url', 'authoritativeOnly', 'language'];
 const RESOLVE_PARAMS = ['fhirVersion', 'url', 'version', 'valueSet', 'authoritativeOnly', 'language', 'usage'];
+const CHOOSE_SERVER_PARAMS = ['fhirVersion', 'system', 'default', 'valueSet', 'usage', 'language'];
 
 // A link to a URL from a registry list or a crawled server: those are other people's
 // content, so only an http(s) URL is linked, and it is escaped
@@ -325,6 +326,8 @@ class RegistryModule {
     // Main registry page
     this.router.get('/', apiLimiter, apiGuard, session, this.handleMainPage.bind(this));
     this.router.get('/resolve', apiLimiter, apiGuard, session, this.handleResolveEndpoint.bind(this));
+    // JSON only - there's no page for a browser, so it's always guarded
+    this.router.get('/choose-server', apiLimiter, guard, this.handleChooseServerEndpoint.bind(this));
     this.router.get('/log', session, this.handleLogEndpoint.bind(this));
     this.router.get('/software', session, this.handleSoftwarePage.bind(this));
 
@@ -807,8 +810,15 @@ class RegistryModule {
       const lastRunDate = new Date(stats.lastRun);
       lastUpdatedText = `Last Updated: ${lastRunDate.toLocaleString()}`;
     }
-    html += `<p>${lastUpdatedText}. <a href="https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md">Register your own server</a>`+
-      ` - see <a href="https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html">Documentation</a></p>`;
+    // what goes here depends on the ecosystem, so it comes from the master registration file
+    html += `<p>${lastUpdatedText}.`;
+    if (data.registration) {
+      html += ` <a href="${safeHref(data.registration)}">Register your own server</a>`;
+    }
+    if (data.ecosystemDoco) {
+      html += `${data.registration ? ' -' : ''} see <a href="${safeHref(data.ecosystemDoco)}">Documentation</a>`;
+    }
+    html += '</p>';
 
     html += '<table class="grid">';
     html += '<thead><tr>';
@@ -1503,6 +1513,46 @@ class RegistryModule {
     }
   }
 
+  /**
+   * GET /choose-server: which one server to use for a request involving a set of code
+   * systems (see RegistryAPI.chooseServer). system repeats; the other parameters take their
+   * first value
+   */
+  handleChooseServerEndpoint(req, res) {
+    const start = Date.now();
+    try {
+      const params = this._normalizeQueryParams(req.query);
+      const {fhirVersion, valueSet, usage, language} = params;
+      const defaultServer = params.default;
+      const raw = req.query.system;
+      const systems = (raw == null ? [] : Array.isArray(raw) ? raw : [raw]).map(String).filter(s => s);
+
+      if (!fhirVersion) {
+        return res.status(400).json({error: 'A FHIR version is required'});
+      }
+      if (!defaultServer || !this._isValidUrl(defaultServer, ['http:', 'https:'])) {
+        return res.status(400).json({error: 'A default server (an http or https URL) is required'});
+      }
+      for (const system of systems) {
+        if (!this._isValidUrl(system.split('|')[0])) {
+          return res.status(400).json({error: 'Invalid code system URL format'});
+        }
+      }
+      if (valueSet && !this._isValidUrl(valueSet.split('|')[0])) {
+        return res.status(400).json({error: 'Invalid value set URL format'});
+      }
+
+      const result = this.api.chooseServer(fhirVersion, systems, defaultServer, valueSet, usage, language);
+      this.logger.info(`Chose ${result.server} for ${systems.join(', ') || '(no systems)'} (FHIR ${fhirVersion}, usage=${usage}, language=${language || 'none'})`);
+      res.json(result);
+    } catch (error) {
+      this.logger.error('Error in choose-server endpoint:', error);
+      res.status(400).json({error: error.message});
+    } finally {
+      this.stats.countRequest('choose-server', Date.now() - start);
+    }
+  }
+
   buildResolveResultContent(result, fhirVersion, resourceUrl, usage, language) {
     let html = '';
 
@@ -1833,6 +1883,7 @@ class RegistryModule {
 
 RegistryModule.DISCOVERY_PARAMS = DISCOVERY_PARAMS;
 RegistryModule.RESOLVE_PARAMS = RESOLVE_PARAMS;
+RegistryModule.CHOOSE_SERVER_PARAMS = CHOOSE_SERVER_PARAMS;
 
 module.exports = RegistryModule;
 module.exports.commonBaseUrl = commonBaseUrl;

package/tx/README.md

@@ -312,6 +312,10 @@ THO's v3-ActCode code system is `CodeSystem/tho-v3-ActCode`. No resource is serv
 - `core` is the FHIR core package each endpoint loads for its FHIR version (`CodeSystem/core-administrative-gender`), and `x` is the code systems the server implements natively (`CodeSystem/x-...`); neither can be given as a prefix
 - Sources that only provide code systems natively (`internal`, `snomed`, `loinc` etc.) don't serve resources by id, so a prefix does nothing for them
 
+#### hl7.terminology and the FHIR core packages
+
+Much of the content of the FHIR core packages has moved to terminology.hl7.org (`hl7.terminology`), and its versions were reset when it moved (`coverage-selfpay` is 4.0.1 in `hl7.fhir.r4.core`, and 1.0.1 in `hl7.terminology`), so version order can't decide between the two. Where `hl7.terminology` provides a code system, value set or concept map with the same url as the endpoint's core package, THO's is always the one a reference with no version gets. The core package's versions are still available to a reference that names them (`http://hl7.org/fhir/concept-property-type|5.0.0`), unless THO provides that same version itself. Core value sets and concept maps that THO also provides are not read by id, found by search, or used for `$translate` unless asked for by version.
+
 ### Source Types
 
 #### `internal` - Built-in Code Systems

package/tx/cm/cm-package.js

@@ -8,6 +8,7 @@ const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 const {ConceptMap} = require("../library/conceptmap");
 const { applyIdPrefix, stripIdPrefix } = require('../library/resource-ids');
+const { keepForPinnedReference } = require('../library/tho-precedence');
 
 /**
  * Package-based ConceptMap provider using shared database layer
@@ -169,7 +170,7 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
         // Only process each ConceptMap once (use URL to deduplicate)
         const vsUrl = json.url;
-        if (seen.has(vsUrl)) {
+        if (seen.has(vsUrl) || this.#pinnedOnly.has(vs)) {
           continue;
         }
 
@@ -330,35 +331,39 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     return this.packageLoader.id();
   }
 
-  // the concept maps left out by excludeUrls, by their own (unprefixed) id
+  // the concept maps that keepPinnedOnly restricted, by their own (unprefixed) id, and themselves
   #excludedIds = new Set();
+  #pinnedOnly = new Set();
 
   /**
-   * Leave out the concept maps with any of these urls: they can't be fetched, they aren't
-   * found by search, and they aren't used for translation. The FHIR core package's concept
-   * maps are left out where hl7.terminology provides the same url (see
-   * Provider.applyTHOPrecedence). Must be called once the provider is initialized - the
-   * database is shared, so it isn't changed.
+   * The concept maps with these urls are hl7.terminology's to provide (see
+   * Provider.applyTHOPrecedence): from this (core) package they are only available to a
+   * reference that names their version, where THO doesn't provide that version itself. They
+   * aren't the default for their url, can't be read by id, aren't found by search, and aren't
+   * used for translation unless asked for. Must be called once the provider is initialized -
+   * the database is shared, so it isn't changed.
    *
-   * @param {Set<string>} urls
+   * @param {Map<string, Set<string>>} thoVersions - url -> the versions hl7.terminology provides
    */
-  excludeUrls(urls) {
-    const excluded = new Set();
+  keepPinnedOnly(thoVersions) {
+    const affected = new Set();
     for (const cm of this.conceptMapMap.values()) {
-      if (cm && urls.has(cm.url)) {
-        excluded.add(cm);
+      if (cm && thoVersions.has(cm.url)) {
+        affected.add(cm);
       }
     }
     for (const [key, cm] of [...this.conceptMapMap]) {
-      if (excluded.has(cm)) {
+      if (affected.has(cm) && !keepForPinnedReference(key, cm, thoVersions.get(cm.url))) {
         this.conceptMapMap.delete(key);
       }
     }
-    for (const cm of excluded) {
+    for (const cm of affected) {
+      this.#pinnedOnly.add(cm);
       this.#excludedIds.add(stripIdPrefix(cm.id, this.spaceId) ?? cm.id);
     }
   }
 
+
   prefixIds() {
     this.#applyIdPrefix();
   }
@@ -371,7 +376,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
   async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem) {
     for (let cm of this.conceptMapMap.values()) {
-      if (cm.providesTranslation(sourceSystem, sourceScope, targetScope, targetSystem)) {
+      // a concept map that THO also provides is only used when it's asked for by version
+      if (!this.#pinnedOnly.has(cm) && cm.providesTranslation(sourceSystem, sourceScope, targetScope, targetSystem)) {
         conceptMaps.push(cm);
       }
     }