fhirsmith 0.18.1 → 1.0.0

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-template.html

@@ -55,8 +55,6 @@
 		<div class="container">  <!-- container -->
 		<div style="background-color: #ad1f2f; padding: 6px; color: white;">  <!-- container -->
 
-  <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org &nbsp;|&nbsp;
-  <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a> [%ver%] &nbsp;|&nbsp;
   <a href="/" style="color: gold"> Server Home</a> &nbsp;|&nbsp;
   <a href="/tx-reg" style="color: gold">Registry Home</a>  &nbsp;|&nbsp;
   <a href="/tx-reg/resolve" style="color: gold">Resolve</a>  &nbsp;|&nbsp;
@@ -75,7 +73,7 @@
             	<div class="inner-wrapper">
  <div class="col-9">
 
-  <h2><img border="0" src="../FHIRsmith32.png" style="vertical-align: text-bottom"/> [%title%] </h2>
+  <h2><a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" title="FHIRsmith [%ver%]"><img border="0" src="/FHIRsmith32.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/></a> [%title%] </h2>
 
 [%content%]
 
@@ -93,8 +91,7 @@
 		<div class="container">  <!-- container -->
 			<div class="inner-wrapper">
 				<p>
-                    <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
-                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
+                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
        Terminology Registry [%crawler-status%] &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
@@ -118,10 +115,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->

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
@@ -90,6 +91,7 @@ class RegistryModule {
         timeout: config.timeout || 30000,
         userAgent: config.userAgent || 'FHIRRegistryServer/1.0',
         apiKeys: config.apiKeys || {},
+        oauth: config.oauth || {},
         maxResponseMB: config.maxResponseMB,
         uptimeWindowDays: config.uptimeWindowDays,
         uptimeRetentionDays: config.uptimeRetentionDays
@@ -325,6 +327,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 +811,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,13 +1514,53 @@ 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 = '';
 
     // Query information section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Query Information</h2>';
+    html += '<h3 class="card-title">Query Information</h3>';
     html += '</div>';
     html += '<div class="card-body">';
     html += `<p><strong>FHIR Version:</strong> ${escape(fhirVersion)}</p>`;
@@ -1527,7 +1578,7 @@ class RegistryModule {
     // Authoritative servers section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Authoritative Servers</h2>';
+    html += '<h3 class="card-title">Authoritative Servers</h3>';
     html += '</div>';
     html += '<div class="card-body">';
 
@@ -1566,7 +1617,7 @@ class RegistryModule {
     // Candidate servers section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Candidate Servers</h2>';
+    html += '<h3 class="card-title">Candidate Servers</h3>';
     html += '</div>';
     html += '<div class="card-body">';
 
@@ -1817,7 +1868,7 @@ class RegistryModule {
           case 'error': levelStyle = 'color: #d9534f; font-weight: bold;'; break;
           case 'warn': levelStyle = 'color: #f0ad4e;'; break;
           case 'debug': levelStyle = 'color: #5cb85c;'; break;
-          default: levelStyle = 'color: #0275d8;'; // info
+          default: levelStyle = 'color: #0056b3;'; // info
         }
 
         // Format: [time] [LEVEL] message
@@ -1833,6 +1884,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/root-bare-template.html

@@ -71,9 +71,12 @@
 
 <body style="margin-left: 10px">
 
-<h2>[%title%] </h2>
+<!-- the page's one h1, the size of an h2 as before -->
+<h1 style="font-size:1.5em;margin:0.83em 0">[%title%] </h1>
 
+<main>
 [%content%]
+</main>
 
 
       <!-- JS and analytics only. -->
@@ -81,10 +84,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->

package/root-template.html

@@ -53,8 +53,6 @@
 		<div id="stripe"> </div>
 		<div class="container">  <!-- container -->
 		<div style="background-color: #ad1f2f; padding: 6px; color: white;">  <!-- container -->
-  <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org &nbsp;|&nbsp;
-  <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a> [%ver%] &nbsp;|&nbsp;
   <a href="/" style="color: gold"> Server Home</a>
   &nbsp;
   &nbsp;
@@ -70,7 +68,7 @@
             	<div class="inner-wrapper">
  <div class="col-9">
 
-  <h2><img border="0" src="/FHIRsmith32.png" style="vertical-align: text-bottom"/> FHIRsmith: [%title%] </h2>
+     <h2><a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" title="FHIRsmith [%ver%]"><img border="0" src="/FHIRsmith32.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/></a> FHIRsmith: [%title%] </h2>
 
 [%content%]
 
@@ -89,8 +87,7 @@
 		<div class="container">  <!-- container -->
 			<div class="inner-wrapper">
 				<p>
-                    <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
-                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|
+                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
         </p>
@@ -113,10 +110,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->