fhirsmith 0.14.0 → 0.14.2

package/registry/openapi.yaml

@@ -0,0 +1,311 @@
+# OpenAPI description of the FHIRsmith terminology server registry (/tx-reg) - the
+# coordination server of the HL7 terminology ecosystem.
+#
+# The normative description of this API is the ecosystem page of the terminology
+# ecosystem IG (https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html); this
+# file describes what this server implements, including its extensions. It is maintained by
+# hand, and tests/registry/openapi.test.js keeps it honest: every route the router registers
+# must be described here or explicitly excluded, and the documented query parameters must
+# be the ones the handlers read (DISCOVERY_PARAMS, RESOLVE_PARAMS in registry.js).
+#
+# info.version is filled in from package.json when the spec is served.
+
+openapi: 3.1.0
+info:
+  title: FHIRsmith Terminology Server Registry
+  version: "0.0.0"
+  summary: Find the right terminology server for a code system or value set
+  description: |
+    The coordination server of a terminology server ecosystem. It regularly scans the
+    servers listed in the ecosystem's master registration file - their
+    CapabilityStatement, TerminologyCapabilities and ValueSets - and answers two
+    questions:
+
+    * **Discovery** (`GET /`): which terminology server endpoints are there?
+    * **Resolution** (`GET /resolve`): which server should be used for this code system
+      or value set?
+
+    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.
+
+    **Content negotiation.** If the request's `Accept` header contains `text/html`, these
+    endpoints return a browsable HTML page instead of JSON. The JSON form is the contract.
+
+    **Parameters are read leniently**: unknown parameters are ignored, and a repeated
+    parameter takes its first value.
+  license:
+    name: BSD-3-Clause
+    url: https://opensource.org/license/bsd-3-clause
+externalDocs:
+  description: Terminology ecosystem IG - the ecosystem and the coordination server API
+  url: https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html
+servers:
+  - url: /tx-reg
+tags:
+  - name: discovery
+    description: List the servers in the ecosystem
+  - name: resolution
+    description: Choose a server for a code system or value set
+
+paths:
+  /:
+    get:
+      tags: [discovery]
+      operationId: discover
+      summary: List terminology server endpoints
+      description: |
+        Lists the server endpoints in the ecosystem, one entry per server per FHIR
+        version, optionally filtered.
+
+        With `url`, only endpoints that host that code system are listed, those
+        authoritative for it first, and each entry's `candidate` list says whether the
+        endpoint hosts it without claiming authority. A server that excludes the code
+        system is not listed.
+
+        Without `url`, each entry's `authoritative` and `authoritative-valuesets` are the
+        server's claim masks, and there are no candidate lists (listing everything a server
+        hosts would make the response very large).
+      parameters:
+        - name: registry
+          in: query
+          description: Only endpoints from this registry (its code in the master registration file).
+          schema: { type: string }
+        - name: server
+          in: query
+          description: Only endpoints of this server (its code in its registry).
+          schema: { type: string }
+          example: tx.fhir.org
+        - $ref: '#/components/parameters/fhirVersionOptional'
+        - name: url
+          in: query
+          description: Only endpoints that host this code system (`url` or `url|version`).
+          schema: { type: string }
+          example: http://loinc.org
+        - name: authoritativeOnly
+          in: query
+          description: With `url`, only endpoints that are authoritative for it.
+          schema: { type: string, enum: ['true', 'false'], default: 'false' }
+        - $ref: '#/components/parameters/language'
+      responses:
+        '200':
+          description: The matching endpoints
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DiscoveryResult' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /resolve:
+    get:
+      tags: [resolution]
+      operationId: resolve
+      summary: Choose a server for a code system or value set
+      description: |
+        Returns the endpoints to use for a code system (`url`) or a value set (`valueSet`)
+        at a FHIR version: those authoritative for it, then the other candidates that host
+        it. Choosing between several is up to the client.
+
+        * An endpoint is only listed if it hosts the code system (+version). A SNOMED CT
+          edition (`http://snomed.info/sct|http://snomed.info/sct/{edition}`) is hosted by an
+          endpoint that hosts any version of that edition.
+        * An endpoint listed as authoritative is not also listed as a candidate.
+        * A server whose registration has a `usage` list is only returned if the request's
+          `usage` is in it.
+        * A server that excludes the code system or value set is never returned.
+        * `authoritative` and `candidates` are omitted when empty.
+
+        With `language`, endpoints matched on a language specific claim come first in
+        `authoritative`, and candidates are marked `language-support: unknown`. Value set
+        resolution has no language dimension.
+
+        A browser request (`Accept: text/html`) without the required parameters returns a
+        form for making the request.
+      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: url
+          in: query
+          description: The code system, `url` or `url|version`. One of `url` and `valueSet` is required.
+          schema: { type: string }
+          example: http://snomed.info/sct|http://snomed.info/sct/32506021000036107
+        - name: version
+          in: query
+          description: |
+            A version for `url`, as an alternative to `url|version`. Ignored if `url` already
+            has a version. (An extension to the ecosystem IG.)
+          schema: { type: string }
+        - name: valueSet
+          in: query
+          description: The value set, `url` or `url|version`.
+          schema: { type: string }
+          example: http://hl7.org/fhir/ValueSet/observation-codes
+        - name: authoritativeOnly
+          in: query
+          description: Only return authoritative endpoints (no candidates).
+          schema: { type: string, enum: ['true', 'false'], default: 'false' }
+        - $ref: '#/components/parameters/language'
+        - name: usage
+          in: query
+          description: |
+            What the client is doing, for servers that restrict their use. The HL7 Java
+            tools send `publication`, `validation` or `code-generation`.
+          schema: { type: string }
+          example: publication
+      responses:
+        '200':
+          description: The endpoints to use
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ResolveResult' }
+            text/html:
+              schema: { type: string }
+        '400':
+          description: A required parameter is missing, or a URL is malformed
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+components:
+  parameters:
+    fhirVersionOptional:
+      name: fhirVersion
+      in: query
+      description: Only endpoints for this FHIR version, as a release code (`R4`, `R4B`, `R5` ...) or a version (`4.0.1`, `4.0`).
+      schema: { type: string }
+      example: R4
+    language:
+      name: language
+      in: query
+      description: |
+        The language of the request being routed, in Accept-Language syntax: one BCP-47
+        tag, or a weighted list (`de-AT, de;q=0.9, en;q=0.1`). Pass it only when the
+        operation is language-sensitive. With discovery, only meaningful with `url`.
+      schema: { type: string }
+      example: de
+
+  responses:
+    BadRequest:
+      description: A parameter is malformed
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+    ServerError:
+      description: The server failed to process the request
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+
+  schemas:
+    SecurityFlags:
+      type: object
+      description: |
+        How the endpoint can be accessed, as the boolean flags of the ecosystem IG (`open`
+        for unauthenticated use; an API key is reported as `token`), plus the scanner's own
+        `security` string (`open` or `api-key`), kept for existing clients.
+      properties:
+        security: { type: string, enum: [open, api-key] }
+        open: { type: boolean, const: true }
+        password: { type: boolean, const: true }
+        token: { type: boolean, const: true }
+        oauth: { type: boolean, const: true }
+        smart: { type: boolean, const: true }
+        cert: { type: boolean, const: true }
+
+    DiscoveryResult:
+      type: object
+      required: [last-update, master-url, results]
+      properties:
+        last-update:
+          type: [string, 'null']
+          format: date-time
+          description: When the ecosystem was last scanned
+        master-url: { type: string, format: uri, description: The master registration file that was scanned }
+        results:
+          type: array
+          items: { $ref: '#/components/schemas/DiscoveryEntry' }
+
+    DiscoveryEntry:
+      allOf:
+        - $ref: '#/components/schemas/SecurityFlags'
+        - type: object
+          required: [server-name, server-code, registry-name, registry-code, url, fhirVersion, systems, authoritative, authoritative-valuesets]
+          properties:
+            server-name: { type: string }
+            server-code: { type: string }
+            registry-name: { type: string }
+            registry-code: { type: string }
+            registry-url: { type: string, format: uri }
+            url: { type: string, format: uri, description: The FHIR endpoint }
+            fhirVersion: { type: string, example: 4.0.1 }
+            error:
+              type: [string, 'null']
+              description: What went wrong the last time the endpoint was scanned; null if it worked
+            last-success:
+              type: [integer, 'null']
+              description: Milliseconds since the endpoint was last scanned successfully; null if never
+            systems: { type: integer, description: Number of code systems the endpoint hosts }
+            authoritative:
+              type: array
+              items: { type: string }
+              description: The code system masks the server claims authority for
+            authoritative-valuesets:
+              type: array
+              items: { type: string }
+              description: The value set masks the server claims authority for
+            candidate:
+              type: array
+              items: { type: string }
+              description: With `url`, present when the endpoint hosts it without claiming authority
+            languages:
+              type: array
+              items: { type: string }
+              description: With `url` and `language`, the language tag of the claim the endpoint matched on
+
+    ResolveResult:
+      type: object
+      required: [formatVersion, registry-url]
+      properties:
+        formatVersion: { type: string, const: '1' }
+        registry-url: { type: string, format: uri, description: The master registration file }
+        authoritative:
+          type: array
+          items: { $ref: '#/components/schemas/ResolvedServer' }
+        candidates:
+          type: array
+          items: { $ref: '#/components/schemas/ResolvedServer' }
+
+    ResolvedServer:
+      allOf:
+        - $ref: '#/components/schemas/SecurityFlags'
+        - type: object
+          required: [server-name, url, fhirVersion]
+          properties:
+            server-name: { type: string }
+            url: { type: string, format: uri, description: The FHIR endpoint to use }
+            fhirVersion: { type: string, example: 4.0.1 }
+            access_info: { type: string, description: How to get access (markdown), from the server's registration }
+            content:
+              type: string
+              enum: [not-present, example, fragment, complete, supplement]
+              description: Candidates only - the content mode of the code system on this server, if it says
+            languages:
+              type: array
+              items: { type: string }
+              description: Authoritative entries matched on a language specific claim - that claim's language tag
+            language-support:
+              type: string
+              const: unknown
+              description: Candidates, when the request had a language - the ecosystem can't say whether this server has it
+
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error: { type: string }

package/registry/readme.md

@@ -1,225 +1,124 @@
 # Terminology Server Registry
 
-A Node.js module for crawling and querying FHIR terminology servers. This module maintains a registry of terminology servers, periodically crawls them to gather capability information, and provides an API to find the best server for specific code systems or value sets.
-
-## Architecture
-
-The module consists of three main components:
-
-### 1. Data Model (`registry-model.js`)
-- **ServerRegistries**: Top-level container for all registry data
-- **ServerRegistry**: Individual registry containing multiple servers
-- **ServerInformation**: Server metadata and authoritative designations
-- **ServerVersionInformation**: Version-specific server capabilities
-- **ServerRow**: Flattened representation for API responses
-- **ServerRegistryUtilities**: Helper functions for matching and filtering
-
-### 2. Crawler (`registry-crawler.js`)
-- Periodically fetches capability statements from configured servers
-- Extracts security models, supported code systems, and value sets
-- Handles retries and error recovery
-- Maintains current state of all servers
-
-### 3. API Processor (`registry-api.js`)
-- Provides query endpoints for finding servers
-- Ranks servers based on:
-  - Authoritative designation
-  - Availability (no errors)
-  - Recency of successful connection
-  - Number of resources available
-- Supports filtering by registry, server, version, and resource
-
-## Installation
-
-```bash
-npm install
-```
-
-## Usage
-
-### Basic Server Setup
-
-```javascript
-const express = require('express');
-const RegistryCrawler = require('./crawler');
-const RegistryAPI = require('./api');
-
-// Configure crawler
-const crawler = new RegistryCrawler({
-  timeout: 30000,
-  crawlInterval: 5 * 60 * 1000, // 5 minutes
-  registryConfigs: [
-    {
-      code: 'main',
-      name: 'Main Registry',
-      servers: [
-        {
-          code: 'tx1',
-          name: 'TX Server',
-          authCSList: ['http://loinc.org*'],
-          versions: [
-            {
-              version: '4.0.1',
-              address: 'https://tx.fhir.org/r4'
-            }
-          ]
-        }
-      ]
-    }
-  ]
-});
-
-// Create API
-const api = new RegistryAPI(crawler);
-
-// Set up Express
-const app = express();
-api.registerRoutes(app);
-
-// Start crawler and server
-crawler.start();
-app.listen(3000);
-```
-
-### API Endpoints
-
-#### Query Endpoints
-
-**Find servers for a code system:**
-```
-GET /api/query/codesystem?system=http://loinc.org&version=4.0
-```
-
-**Find servers for a value set:**
-```
-GET /api/query/valueset?valueset=http://hl7.org/fhir/ValueSet/observation-codes
-```
-
-**Find the best server:**
-```
-GET /api/best-server/codesystem?url=http://snomed.info/sct
-```
-
-#### Registry Information
-
-**Get statistics:**
-```
-GET /api/registry/stats
-```
-
-**List all registries:**
-```
-GET /api/registry
-```
-
-**Get servers in a registry:**
-```
-GET /api/registry/main/servers
-```
-
-#### Admin Endpoints
-
-**Trigger manual crawl:**
-```
-POST /api/admin/crawl
-```
-
-**Export/Import data:**
-```
-GET /api/admin/data
-POST /api/admin/data
-```
+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
 
-### Registry Configuration
-
-```javascript
-{
-  code: 'main',           // Unique registry identifier
-  name: 'Main Registry',  // Display name
-  address: 'https://...',  // Registry URL
-  authority: 'HL7',       // Managing authority
-  servers: [...]          // Array of server configs
-}
-```
-
-### Server Configuration
-
-```javascript
-{
-  code: 'tx1',            // Unique server identifier
-  name: 'TX Server',      // Display name
-  address: 'https://...', // Base server URL
-  accessInfo: '...',      // Access information
-  authCSList: [           // Authoritative code systems
-    'http://loinc.org*',  // Supports wildcards
-    'http://snomed.info/sct'
-  ],
-  authVSList: [...],      // Authoritative value sets
-  usageList: ['public'],  // Usage tags
-  versions: [...]         // Array of version configs
-}
-```
-
-### Version Configuration
+In the server config, under `modules.registry`:
 
-```javascript
-{
-  version: '4.0.1',       // FHIR version
-  address: 'https://...'  // Version-specific endpoint
+```json
+"registry": {
+  "enabled": true,
+  "masterUrl": "https://fhir.github.io/ig-registry/tx-servers.json",
+  "crawlInterval": 30,
+  "timeout": 30000,
+  "userAgent": "YourServer/1.0",
+  "apiKeys": {}
 }
 ```
 
-## Authoritative Designations
+| 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. |
 
-Servers can be marked as authoritative for specific code systems or value sets. This affects ranking:
+## Scanning
 
-- Authoritative servers are always ranked first
-- Wildcards are supported (e.g., `http://loinc.org*`)
-- Non-authoritative servers are still returned but ranked lower
-- Language specific claims (`languages`: BCP-47 tag -> mask list) make a server authoritative for
-  requests in that language only; matched entries rank ahead of language independent claims
-- `exclusions` hides matching code systems/value sets from the ecosystem entirely (never
-  authoritative, never a candidate)
+Each scan reads the master registration file, each registry it lists, and then, for each
+server endpoint:
 
-## Testing
-
-Run the test suite:
-
-```bash
-npm test
-```
-
-Run with Jest (if installed):
-
-```bash
-npm run test:jest
-```
-
-## Data Persistence
-
-The crawler saves and loads its state in [data]/registry-data.json
-
-## Development
-
-Start development server with auto-reload:
-
-```bash
-npm run dev
-```
+* `/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)
 
-## Security Models
+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 crawler detects the following security models:
+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.
 
-- `open`: No authentication required
-- `password`: Basic authentication
-- `token`: Token-based authentication
-- `oauth`: OAuth 2.0
-- `smart`: SMART on FHIR
-- `cert`: Certificate-based authentication
+## Code
 
-## License
+| 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 |
 
-BSD-3-Clause
+Tests are in `tests/registry`.

package/registry/registry-template.html

@@ -9,6 +9,7 @@
   <meta content="http://hl7.org/fhir" name="author"/>
   <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
 
+  <link rel="service-desc" type="application/json" href="/tx-reg/openapi.json"/>
   <link rel="stylesheet" href="/fhir.css"/>
 
 
@@ -59,7 +60,9 @@
   <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;
+  <a href="/tx-reg/software" style="color: gold">Software</a>  &nbsp;|&nbsp;
   <a href="/tx-reg/log" style="color: gold">Crawler Log</a>  &nbsp;|&nbsp;
+  <a href="/tx-reg/openapi" style="color: gold">API</a>
 		</div>  <!-- /container -->
 		</div>  <!-- /container -->
 </div>
@@ -92,7 +95,7 @@
 				<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;
-       Terminology Registry last updated as of [%crawler-date%] &nbsp;|&nbsp; [%total-packages%] packages &nbsp;|
+       Terminology Registry [%crawler-status%] &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
         </p>