fhirsmith 0.16.1 → 0.18.0

package/utilities/make-sct-test-extension.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * Generates the "national extension" content for the SNOMED CT test edition
+ * (module 31000003106, namespace 1000003) that the tx-ecosystem tests use.
+ *
+ * The test edition at tx/data/snomed is a subontology extract of the
+ * International Edition; everything in it except the module concept itself
+ * is International content. This script adds a handful of extension concepts
+ * whose definitions are built entirely from International concepts that are
+ * in the subset, so that national -> international translation can be tested:
+ *
+ *   - one fully defined concept with a single ungrouped attribute (laterality)
+ *   - one fully defined concept with role-grouped attributes, not equivalent
+ *     to any International concept
+ *   - one fully defined concept that is exactly equivalent to an existing
+ *     International concept (same defining relationships)
+ *   - one primitive concept with only an IS A (closest ancestor only)
+ *   - one primitive concept directly under a top-level hierarchy (no useful ancestor)
+ *   - one inactive concept with no historical association (nothing to translate to)
+ *   - one inactive concept REPLACED BY an International concept
+ *
+ * Output is a set of RF2 snapshot files alongside the INT ones, with the
+ * TEST1000003 namespace tag in the filename. Rows are deterministic, so the
+ * script can be re-run safely; ids are allocated from item numbers >= 100001
+ * so they never collide with the extractor-generated ids.
+ *
+ * Usage: node utilities/make-sct-test-extension.js [tx/data/snomed]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const root = process.argv[2] || path.join(__dirname, '..', 'tx', 'data', 'snomed');
+const TAG = 'TEST1000003';
+const ET = '20250909';
+const MODULE = '31000003106';
+const NAMESPACE = '1000003';
+const EOL = '\r\n';
+
+// --- SCTID construction -------------------------------------------------
+
+// Verhoeff check digit
+const d = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5], [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+  [3, 4, 0, 1, 2, 8, 9, 5, 6, 7], [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+  [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3], [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+  [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]];
+const p = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4], [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+  [8, 9, 1, 6, 0, 4, 3, 5, 2, 7], [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+  [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 8, 1, 5, 3, 9, 2]];
+const inv = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9];
+
+function verhoeff(numStr) {
+  let c = 0;
+  const digits = numStr.split('').reverse().map(Number);
+  for (let i = 0; i < digits.length; i++) {
+    c = d[c][p[(i + 1) % 8][digits[i]]];
+  }
+  return inv[c];
+}
+
+function sctid(item, partition) {
+  const body = `${item}${NAMESPACE}${partition}`;
+  return body + verhoeff(body);
+}
+
+let nextItem = 100001;
+const conceptId = () => sctid(nextItem++, '10');
+const descriptionId = () => sctid(nextItem++, '11');
+const relationshipId = () => sctid(nextItem++, '12');
+
+// Deterministic UUID for refset members (name-based, so re-runs are stable)
+function memberId(...parts) {
+  const h = crypto.createHash('sha1').update(['sct-test-ext', ...parts].join('|')).digest('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+// --- RF2 constants ------------------------------------------------------
+
+const FULLY_DEFINED = '900000000000073002';
+const PRIMITIVE = '900000000000074008';
+const FSN = '900000000000003001';
+const SYNONYM = '900000000000013009';
+const CASE_INSENSITIVE = '900000000000448009';
+const IS_A = '116680003';
+const INFERRED = '900000000000011006';
+const EXISTENTIAL = '900000000000451002';
+const EN_GB = '900000000000508004';
+const EN_US = '900000000000509007';
+const PREFERRED = '900000000000548007';
+const ACCEPTABLE = '900000000000549004';
+const OWL_AXIOM_REFSET = '733073007';
+const ROLE_GROUP = '609096000';
+const REPLACED_BY = '900000000000526001';   // the SAME AS refset concept is not in the subset
+
+// --- The extension content ---------------------------------------------
+
+// All destination/attribute ids below are International concepts present in
+// the test subset. Each concept: fsn, synonyms (first is preferred),
+// parents, groups (array of arrays of [typeId, destinationId]; group 0 =
+// ungrouped), definition status, and the stated OWL axiom.
+const concepts = [
+  {
+    key: 'right-kidney',
+    // shape 1: fully defined, one ungrouped attribute (Laterality is never grouped)
+    fsn: 'Structure of kidney adjacent to liver (body structure)',
+    synonyms: ['Right kidney (the one under the liver)', 'Liver-side kidney'],
+    parents: ['64033007'],                                  // Kidney structure
+    ungrouped: [['272741003', '24028007']],                 // Laterality = Right
+    groups: [],
+    status: FULLY_DEFINED,
+    owl: (id) => `EquivalentClasses(:${id} ObjectIntersectionOf(:64033007 ObjectSomeValuesFrom(:272741003 :24028007)))`
+  },
+  {
+    key: 'pate-hepatitis',
+    // shape 2: fully defined, role-grouped, no International equivalent
+    fsn: 'Acute toxic hepatitis caused by liver pate (disorder)',
+    synonyms: ['Pate-induced hepatitis', 'Revenge of the liver'],
+    parents: ['4896000'],                                   // Acute toxic hepatitis
+    ungrouped: [],
+    groups: [
+      [['116676008', '4532008'],                            // Associated morphology = Acute inflammation
+       ['246075003', '227014008'],                          // Causative agent = Liver pate
+       ['363698007', '10200004']],                          // Finding site = Liver structure
+      [['263502005', '424124008']]                          // Clinical course = Sudden onset AND/OR short duration
+    ],
+    status: FULLY_DEFINED,
+    // Same shape as the International axiom for 4896000, with the causative agent refined
+    owl: (id) => `EquivalentClasses(:${id} ObjectIntersectionOf(:75478009 ObjectSomeValuesFrom(:${ROLE_GROUP} ObjectIntersectionOf(ObjectSomeValuesFrom(:116676008 :4532008) ObjectSomeValuesFrom(:246075003 :227014008) ObjectSomeValuesFrom(:363698007 :10200004))) ObjectSomeValuesFrom(:${ROLE_GROUP} ObjectSomeValuesFrom(:263502005 :424124008))))`
+  },
+  {
+    key: 'us-liver-biopsy',
+    // shape 3: fully defined, exactly equivalent to 438300009 |Biopsy of liver using ultrasound guidance|
+    fsn: 'Liver biopsy using the ultrasound thingy (procedure)',
+    synonyms: ['Ultrasound-guided liver biopsy (local dialect)'],
+    parents: ['105377009', '86259008'],                     // Ultrasonography of liver, Biopsy of liver
+    ungrouped: [],
+    groups: [
+      [['260686004', '129314006'],                          // Method = Biopsy - action
+       ['405813007', '10200004']],                          // Procedure site - Direct = Liver structure
+      [['260686004', '278292003'],                          // Method = Ultrasound imaging - action
+       ['363703001', '429892002'],                          // Has intent = Guidance intent
+       ['405813007', '10200004']]                           // Procedure site - Direct = Liver structure
+    ],
+    status: FULLY_DEFINED,
+    owl: (id) => `EquivalentClasses(:${id} :438300009)`
+  },
+  {
+    key: 'liverish',
+    // shape 4: primitive, IS A only
+    fsn: 'Feeling liverish (finding)',
+    synonyms: ['Liverish', 'Bit liverish this morning'],
+    parents: ['300338006'],                                 // Liver problem
+    ungrouped: [],
+    groups: [],
+    status: PRIMITIVE,
+    owl: (id) => `SubClassOf(:${id} :300338006)`
+  },
+  {
+    key: 'vaguely-unwell',
+    // shape 5: primitive, directly under a top-level hierarchy - the only International
+    // ancestor carries no information, so there is no useful translation
+    fsn: 'Feeling vaguely unwell about the liver (finding)',
+    synonyms: ['Vaguely unwell about the liver'],
+    parents: ['404684003'],                                 // Clinical finding
+    ungrouped: [],
+    groups: [],
+    status: PRIMITIVE,
+    owl: (id) => `SubClassOf(:${id} :404684003)`
+  },
+  {
+    key: 'dropsy',
+    // shape 6: inactive, no relationships, no historical association - nothing at all
+    fsn: 'Dropsy of the liver (disorder)',
+    synonyms: ['Hepatic dropsy'],
+    parents: [], ungrouped: [], groups: [],
+    status: PRIMITIVE,
+    active: false
+  },
+  {
+    key: 'hepatic-revenge',
+    // shape 7: inactive, REPLACED BY an International concept
+    fsn: 'Hepatic revenge syndrome (disorder)',
+    synonyms: ['Hepatic revenge'],
+    parents: [], ungrouped: [], groups: [],
+    status: PRIMITIVE,
+    active: false,
+    replacedBy: '4896000'                                   // Acute toxic hepatitis
+  }
+];
+
+// --- Row builders -------------------------------------------------------
+
+const conceptRows = [];
+const descriptionRows = [];
+const relationshipRows = [];
+const languageRows = [];
+const owlRows = [];
+const associationRows = [];
+const summary = [];
+
+for (const c of concepts) {
+  const id = conceptId();
+  const active = c.active === false ? '0' : '1';
+  conceptRows.push([id, ET, active, MODULE, c.status]);
+
+  const terms = [[FSN, c.fsn, PREFERRED], ...c.synonyms.map((t, i) => [SYNONYM, t, i === 0 ? PREFERRED : ACCEPTABLE])];
+  for (const [typeId, term, acceptability] of terms) {
+    const did = descriptionId();
+    descriptionRows.push([did, ET, '1', MODULE, id, 'en', typeId, term, CASE_INSENSITIVE]);
+    for (const refset of [EN_GB, EN_US]) {
+      languageRows.push([memberId('lang', refset, did), ET, '1', MODULE, refset, did, acceptability]);
+    }
+  }
+
+  for (const parent of c.parents) {
+    relationshipRows.push([relationshipId(), ET, '1', MODULE, id, parent, '0', IS_A, INFERRED, EXISTENTIAL]);
+  }
+  for (const [typeId, dest] of c.ungrouped) {
+    relationshipRows.push([relationshipId(), ET, '1', MODULE, id, dest, '0', typeId, INFERRED, EXISTENTIAL]);
+  }
+  c.groups.forEach((group, gi) => {
+    for (const [typeId, dest] of group) {
+      relationshipRows.push([relationshipId(), ET, '1', MODULE, id, dest, String(gi + 1), typeId, INFERRED, EXISTENTIAL]);
+    }
+  });
+
+  if (c.owl) {
+    owlRows.push([memberId('owl', id), ET, '1', MODULE, OWL_AXIOM_REFSET, id, c.owl(id)]);
+  }
+  if (c.replacedBy) {
+    associationRows.push([memberId('assoc', REPLACED_BY, id), ET, '1', MODULE, REPLACED_BY, id, c.replacedBy]);
+  }
+  summary.push(`${id}  ${c.fsn}${c.active === false ? '  (inactive)' : ''}`);
+}
+
+// --- Write files --------------------------------------------------------
+
+function write(rel, header, rows) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, [header, ...rows.map(r => r.join('\t'))].join(EOL) + EOL, 'utf8');
+  console.log(`${rows.length.toString().padStart(3)} rows  ${rel}`);
+}
+
+write(`Terminology/sct2_Concept_Snapshot_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\tdefinitionStatusId', conceptRows);
+write(`Terminology/sct2_Description_Snapshot-en_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\tconceptId\tlanguageCode\ttypeId\tterm\tcaseSignificanceId', descriptionRows);
+write(`Terminology/sct2_Relationship_Snapshot_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\tsourceId\tdestinationId\trelationshipGroup\ttypeId\tcharacteristicTypeId\tmodifierId', relationshipRows);
+write(`Terminology/sct2_sRefset_OWLExpressionSnapshot_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\trefsetId\treferencedComponentId\towlExpression', owlRows);
+// the IG master keeps the content refsets under Refset/Content; FHIRsmith's copy has them in Refset/
+const contentDir = fs.existsSync(path.join(root, 'Refset', 'Content')) ? 'Refset/Content' : 'Refset';
+write(`${contentDir}/der2_cRefset_AssociationSnapshot_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\trefsetId\treferencedComponentId\ttargetComponentId', associationRows);
+write(`Refset/Language/der2_cRefset_LanguageSnapshot-en_${TAG}_${ET}.txt`,
+  'id\teffectiveTime\tactive\tmoduleId\trefsetId\treferencedComponentId\tacceptabilityId', languageRows);
+
+console.log('\nConcepts:');
+for (const s of summary) console.log('  ' + s);

package/utilities/submit-test-report.js

@@ -11,7 +11,7 @@
  *
  *   node utilities/submit-test-report.js [-server url] [-file path] [-token token] [-header name]
  *
- *   -server  the /testing base; default https://testing.fhir.org/testing
+ *   -server  the /testing base; default https://npm.fhir.org/testing
  *   -file    default test-cases-report.json in the FHIRsmith root
  *   -token   if the server requires one; or set FHIRSMITH_TESTING_TOKEN
  *   -header  the header the token goes in; default Authorization (sent as "Bearer <token>")

package/xig/xig.js

@@ -19,12 +19,14 @@ const escape = require('escape-html');
 
 const Logger = require('../library/logger');
 const {describeCron} = require("../library/cron-utilities");
+const {tokenMatches, tokenConfigured} = require('../library/request-token');
 const xigLog = Logger.getInstance().child({ module: 'xig' });
 
 const router = express.Router();
 
 // Configuration
-const XIG_DB_URL = 'http://fhir.org/guides/stats/xig.db';
+// https: the database is trusted content (its HTML is shown as is), so it must come from fhir.org
+const XIG_DB_URL = 'https://fhir.org/guides/stats/xig.db';
 const XIG_DB_PATH = folders.filePath('xig', 'xig.db');
 const TEMPLATE_PATH = path.join(__dirname, 'xig-template.html');
 
@@ -1718,6 +1720,11 @@ function downloadFile(url, destination, maxRedirects = 5) {
               }
             }
 
+            // never be redirected off https
+            if (new URL(redirectUrl).protocol !== 'https:') {
+              reject(Object.assign(new Error(`Refused a redirect to ${redirectUrl}: the database is only downloaded over https`), { downloadMeta }));
+              return;
+            }
             attemptDownload(redirectUrl, redirectCount + 1);
             return;
           }
@@ -2203,6 +2210,23 @@ function getDatabaseAgeInfo() {
   };
 }
 
+// The form on /xig/stats that starts an update (POST /xig/update), when an updateToken is configured
+function buildUpdateForm() {
+  if (!tokenConfigured(xigSettings.updateToken)) {
+    return '<p class="text-muted">An update can be started from here when an updateToken is set in the xig configuration.</p>';
+  }
+  let html = '<h4>Update the database now</h4>';
+  html += '<form method="POST" action="/xig/update" class="mb-4">';
+  html += '<p>Downloads the current database from fhir.org (about 3 GB) and switches to it. ';
+  html += updateInProgress ? '<strong>An update is running now.</strong>' : 'It takes several minutes.';
+  html += '</p>';
+  html += '<label for="xig-update-token">Update token</label> ';
+  html += '<input type="password" id="xig-update-token" name="token" required autocomplete="off" maxlength="200"> ';
+  html += '<button type="submit" class="btn btn-primary">Start the update</button>';
+  html += '</form>';
+  return html;
+}
+
 function buildStatsTable(statsData) {
   let html = '<table class="table table-striped table-bordered">';
   html += '<thead class="table-dark">';
@@ -2429,16 +2453,25 @@ router.get('/', async (req, res) => {
       const title = 'FHIR Resources';
 
       // Parse query parameters
+      // Each a string: a repeated parameter (?text=a&text=b) arrives as an array, which
+      // the filters and SQL builders would fail on. Capped in length
+      const qp = (name, dflt = '') => {
+        let v = req.query[name];
+        if (Array.isArray(v)) {
+          v = v[0];
+        }
+        return typeof v === 'string' && v !== '' ? v.substring(0, 200) : dflt;
+      };
       const queryParams = {
-        ver: req.query.ver || '',
-        auth: req.query.auth || '',
-        realm: req.query.realm || '',
-        type: req.query.type || '',
-        rt: req.query.rt || '',
-        text: req.query.text || '',
-        pkg: req.query.pkg || '',
-        onlyUsed: req.query.onlyUsed || '',
-        offset: req.query.offset || '0'
+        ver: qp('ver'),
+        auth: qp('auth'),
+        realm: qp('realm'),
+        type: qp('type'),
+        rt: qp('rt'),
+        text: qp('text'),
+        pkg: qp('pkg'),
+        onlyUsed: qp('onlyUsed'),
+        offset: qp('offset', '0')
       };
 
       // Parse offset for pagination
@@ -2600,7 +2633,7 @@ router.get('/stats', async (req, res) => {
         introContent += `</div>`;
       }
 
-      const fullContent = introContent + content;
+      const fullContent = introContent + content + buildUpdateForm();
 
       const stats = await gatherPageStatistics();
       stats.processingTime = Date.now() - startTime;
@@ -3125,8 +3158,44 @@ router.get('/cache', async (req, res) => {
   }
 });
 
-router.post('/update', async (req, res) => {
+// POST /xig/update re-downloads the database (about 3 GB), so it needs the updateToken from
+// the xig config: in the x-update-token header, or (from the form on /xig/stats) in a
+// "token" form field. With no updateToken it is disabled.
+//
+// The form gets a page back straight away, while the update runs on (it takes minutes);
+// /xig/stats shows how it went. Other callers wait for the update and get JSON.
+router.post('/update', express.urlencoded({ extended: false, limit: '2kb' }), async (req, res) => {
+  const fromForm = !!req.is('application/x-www-form-urlencoded');
+  const page = (status, alert, message) => {
+    const content = `<div class="alert alert-${alert}">${escape(message)}</div><p><a href="/xig/stats">Back to the status page</a></p>`;
+    res.status(status).setHeader('Content-Type', 'text/html');
+    res.send(renderPage('Update the XIG database', content));
+  };
+  const refuse = (message) => fromForm ? page(403, 'danger', message) : res.status(403).json({ status: 'ERROR', error: 'forbidden: ' + message });
+
   try {
+    if (!tokenConfigured(xigSettings.updateToken)) {
+      refuse('no updateToken is configured, so this endpoint is disabled');
+      return;
+    }
+    const supplied = req.headers['x-update-token'] ?? req.body?.token;
+    if (!tokenMatches(xigSettings.updateToken, supplied)) {
+      xigLog.warn('Rejected /xig/update: missing or invalid token (from ' + req.ip + ')');
+      refuse('missing or invalid x-update-token');
+      return;
+    }
+
+    if (fromForm) {
+      if (updateInProgress) {
+        page(200, 'info', 'An update is already running. The status page shows how it is going.');
+        return;
+      }
+      xigLog.info('Manual update triggered from the status page');
+      updateXigDatabase().catch((err) => xigLog.error('XIG database update failed: ' + err.message));
+      page(202, 'success', 'The update has started. It takes several minutes; the status page shows how it is going.');
+      return;
+    }
+
     xigLog.info('Manual update triggered via API');
     await updateXigDatabase();
     res.json({
@@ -3143,10 +3212,16 @@ router.post('/update', async (req, res) => {
 });
 
 let globalStats;
+let xigSettings = {};
+// The xig section of the config (initializeXigModule; tests set it directly)
+function setXigSettings(xigConfig) {
+  xigSettings = xigConfig || {};
+}
 // Initialize the XIG module
 async function initializeXigModule(stats, xigConfig) {
   try {
     globalStats = stats;
+    setXigSettings(xigConfig);
     loadTemplate();
 
     await initializeDatabase();
@@ -3176,6 +3251,37 @@ async function initializeXigModule(stats, xigConfig) {
 }
 
 // Graceful shutdown
+/**
+ * The paragraph for the server's daily report: pages served, and whether the
+ * database can be read (it's downloaded afresh each day, and a failed download
+ * or an unreadable file is what this is for).
+ */
+async function dailyReport({since, now}) {
+  const {plural} = require('../library/daily-report');
+  const sentences = [];
+  if (globalStats) {
+    const counts = globalStats.countsSince(since, now);
+    sentences.push(`${plural(counts.total, 'page')} ${counts.total === 1 ? 'was' : 'were'} served.`);
+  }
+  if (!xigDb) {
+    sentences.push('The database is not open: it could not be accessed.');
+  } else {
+    try {
+      const row = await new Promise((resolve, reject) =>
+        xigDb.get('SELECT COUNT(*) AS n FROM Resources', [], (err, row) => err ? reject(err) : resolve(row)));
+      sentences.push(`The database holds ${plural(row.n, 'resource')}.`);
+    } catch (e) {
+      sentences.push(`The database could not be accessed: ${e.message}.`);
+    }
+  }
+  const last = getLastUpdateAttempt();
+  if (last && last.status === 'failed') {
+    const when = last.timestamp instanceof Date ? last.timestamp.toISOString().substring(0, 16).replace('T', ' ') : String(last.timestamp);
+    sentences.push(`The last database update (${when}) failed${last.error ? ': ' + last.error : ''}.`);
+  }
+  return sentences.join(' ');
+}
+
 function shutdown() {
   return new Promise((resolve) => {
     if (xigDb) {
@@ -3196,9 +3302,11 @@ function shutdown() {
 // Export everything
 module.exports = {
   router,
+  setXigSettings,
   updateXigDatabase,
   getDatabaseInfo,
   shutdown,
+  dailyReport,
   initializeXigModule,
 
   // Cache functions

package/gr.sh

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash 
-git tag v$1
-git push origin v$1

package/registry/readme.md

@@ -1,124 +0,0 @@
-# Terminology Server Registry
-
-The coordination server of a terminology server ecosystem, as described by the
-[terminology ecosystem IG](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html).
-It regularly scans the servers listed in the ecosystem's master registration file, and tells
-clients which terminology server to use for a code system or value set. It runs at
-http://tx.fhir.org/tx-reg for the HL7 ecosystem.
-
-Its main client is the HL7 Java tooling (`TerminologyClientManager` in org.hl7.fhir.r5),
-which calls `/resolve` to route each terminology operation to the right server.
-
-## API
-
-The public API is described by an OpenAPI 3.1 spec:
-
-| URL | |
-|---|---|
-| `/tx-reg/openapi` | Browsable reference (HTML), with a "try it" form for each GET operation |
-| `/tx-reg/openapi.json` | The spec as JSON |
-| `/tx-reg/openapi.yaml` | The spec as YAML (the source file, [openapi.yaml](openapi.yaml)) |
-
-Every response carries a `Link: </tx-reg/openapi.json>; rel="service-desc"` header
-(RFC 8631), and the HTML pages carry the matching `<link>` element.
-
-| Endpoint | Purpose |
-|---|---|
-| `GET /tx-reg/` | **Discovery**: the server endpoints in the ecosystem. Filters: `registry`, `server`, `fhirVersion`, `url`, `authoritativeOnly`, `language` |
-| `GET /tx-reg/resolve` | **Resolution**: which endpoints to use for a code system (`url`) or value set (`valueSet`) at a `fhirVersion`. Also `authoritativeOnly`, `language`, `usage`, `version` |
-
-Both return an HTML page instead of JSON when the request's `Accept` header contains
-`text/html`. `/tx-reg/resolve` without parameters is a form for trying it out.
-`/tx-reg/log` (the crawler log) is operational, and not in the spec.
-
-Parameters are read leniently: unknown parameters are ignored, and a repeated parameter
-takes its first value.
-
-### How resolution decides
-
-* An endpoint is only returned for content it actually hosts, as reported by its
-  TerminologyCapabilities (code systems) and ValueSet search (value sets).
-* A SNOMED CT edition (`http://snomed.info/sct|http://snomed.info/sct/{edition}`) is hosted
-  by any endpoint that hosts a version of that edition. Otherwise SNOMED CT versions match
-  exactly; for other code systems, a server that hosts the code system hosts all its
-  versions.
-* Endpoints whose server claims authority (the `authoritative` masks in its registration)
-  are listed as `authoritative`; the others as `candidates`.
-* With `language`, servers with a matching language specific claim (`languages` in the
-  registration) come first, most specific tag first; candidates are marked
-  `language-support: unknown`.
-* A server with a `usage` list is only returned when the request's `usage` is in it.
-* A server's `exclusions` hide the matching content from it entirely.
-* FHIR versions can be given as release codes (`R4`, `R4B`, `R5`, `R6` ...) or numbers
-  (`4.0.1`, `4.0`).
-
-### Differences from the ecosystem IG
-
-* Discovery: without `url`, a row's `authoritative`/`authoritative-valuesets` are the
-  server's claim masks, and there are no candidate lists. With `url`, `candidate` is
-  `[url]` when the endpoint hosts it without claiming authority.
-* Entries carry the IG's security flags (`open`, `token`...) and also a `security` string
-  (`open` or `api-key`). Note that this records how the *registry* reaches the server: an
-  endpoint is `api-key` when the registry is configured with a key for it (`apiKeys`), and
-  `open` otherwise.
-* Resolve takes a `version` parameter, as an alternative to `url|version`.
-* Resolve omits `authoritative` and `candidates` when they are empty.
-
-### Keeping the spec honest
-
-[openapi.yaml](openapi.yaml) is maintained by hand. `tests/registry/openapi.test.js` fails
-if a route is added without being described (or listed in the test's `EXCLUDED` table), if
-the spec describes a route the router doesn't have, or if the documented query parameters
-differ from `DISCOVERY_PARAMS` and `RESOLVE_PARAMS` in `registry.js`. So when you change a
-route or a parameter, change `openapi.yaml` with it.
-
-## Configuration
-
-In the server config, under `modules.registry`:
-
-```json
-"registry": {
-  "enabled": true,
-  "masterUrl": "https://fhir.github.io/ig-registry/tx-servers.json",
-  "crawlInterval": 30,
-  "timeout": 30000,
-  "userAgent": "YourServer/1.0",
-  "apiKeys": {}
-}
-```
-
-| Setting | |
-|---|---|
-| `masterUrl` | The ecosystem's master registration file. Defaults to the HL7 one. |
-| `crawlInterval` | Minutes between scans. 0 or absent: no scanning. |
-| `timeout` | Per-request timeout for scanning, in milliseconds. |
-| `userAgent` | The User-Agent the scanner sends. |
-| `apiKeys` | API keys for servers that need one, by server code. |
-
-## Scanning
-
-Each scan reads the master registration file, each registry it lists, and then, for each
-server endpoint:
-
-* `/metadata` (the CapabilityStatement, for the software name and version)
-* `/metadata?mode=terminology` (the TerminologyCapabilities, for the code systems and
-  versions it hosts)
-* `/ValueSet?_elements=url,version` (the value sets it hosts)
-
-An endpoint that fails keeps the content found by its last successful scan, and reports the
-error. The scanner refuses to fetch from private or loopback addresses (SSRF protection).
-
-The results are saved to `[data]/registry/registry-data.json` after each scan, and loaded at
-startup, so the registry can answer immediately after a restart.
-
-## Code
-
-| File | |
-|---|---|
-| `registry.js` | The module: routes, HTML pages, scan scheduling |
-| `api.js` | Discovery and resolution |
-| `crawler.js` | Scanning |
-| `model.js` | The data model, and mask and version matching |
-| `openapi.yaml`, `openapi.js` | The API description |
-
-Tests are in `tests/registry`.