fhirsmith 0.18.2 → 1.0.0

package/token/token-template.html

@@ -128,8 +128,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;
   <a href="/token" style="color: gold">Token Home</a> 
 		</div>  <!-- /container -->
@@ -144,7 +142,7 @@
             	<div class="inner-wrapper">
  <div class="col-9">
 
-  <h2><img border="0" src="../FHIRsmith32.png" style="vertical-align: text-bottom"/> Token Server: [%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> Token Server: [%title%] </h2>
 
 [%content%]
 
@@ -183,8 +181,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;
                      ([%ms%] ms)
 
         </p>

package/token/token.js

@@ -20,6 +20,7 @@ const lusca = require('lusca');
 const folders = require('../library/folder-setup');
 const { SqliteSessionStore } = require('../library/sqlite-session-store');
 const escape = require('escape-html');
+const { guarded } = require('../library/sqlite-utilities');
 
 
 const Logger = require('../library/logger');
@@ -74,7 +75,7 @@ class TokenModule {
         }
 
         // Create tables
-        this.db.serialize(() => {
+        this.db.serialize(guarded(reject, () => {
           // Users table - enhanced with OAuth data
           this.db.run(`
             CREATE TABLE IF NOT EXISTS users (
@@ -146,7 +147,7 @@ class TokenModule {
           this.db.run(`CREATE INDEX IF NOT EXISTS idx_usage_date ON usage_stats(date)`);
           this.db.run(`CREATE INDEX IF NOT EXISTS idx_security_log_user ON security_log(user_id)`);
           this.db.run(`CREATE INDEX IF NOT EXISTS idx_security_log_event ON security_log(event_type)`);
-        });
+        }));
 
         this.log.info(`Token database initialized: ${dbPath}`);
         resolve();
@@ -166,7 +167,10 @@ class TokenModule {
       saveUninitialized: false,
       rolling: true, // Reset expiration on each request
       cookie: {
-        secure: process.env.NODE_ENV === 'production', // HTTPS only in production
+        // Secure when the request came over https: 'auto' asks req.secure, which (with
+        // server.trustProxy) follows nginx's X-Forwarded-Proto. It used to depend on NODE_ENV,
+        // which nothing sets, so the cookie was never Secure. config.cookieSecure overrides
+        secure: this.config.cookieSecure ?? 'auto',
         httpOnly: true, // Prevent XSS
         maxAge: 24 * 60 * 60 * 1000, // 24 hours
         sameSite: 'lax' // CSRF protection
@@ -780,7 +784,7 @@ class TokenModule {
       this.db.get(
         'SELECT id FROM users WHERE (email = ?) OR (provider = ? AND provider_id = ?)',
         [userData.email, userData.provider, userData.provider_id],
-        (err, row) => {
+        guarded(reject, (err, row) => {
           if (err) {
             reject(err);
             return;
@@ -791,29 +795,29 @@ class TokenModule {
             this.db.run(
               'UPDATE users SET email = ?, name = ?, profile_data = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?',
               [userData.email, userData.name, userData.profile_data, row.id],
-              (err) => {
+              guarded(reject, (err) => {
                 if (err) {
                   reject(err);
                 } else {
                   resolve(row.id);
                 }
-              }
+              })
             );
           } else {
             // Create new user
             this.db.run(
               'INSERT INTO users (email, name, provider, provider_id, profile_data) VALUES (?, ?, ?, ?, ?)',
               [userData.email, userData.name, userData.provider, userData.provider_id, userData.profile_data],
-              function(err) {
+              guarded(reject, function(err) {
                 if (err) {
                   reject(err);
                 } else {
                   resolve(this.lastID);
                 }
-              }
+              })
             );
           }
-        }
+        })
       );
     });
   }
@@ -823,10 +827,10 @@ class TokenModule {
       this.db.get(
         'SELECT * FROM users WHERE id = ? AND is_active = 1',
         [userId],
-        (err, row) => {
+        guarded(reject, (err, row) => {
           if (err) reject(err);
           else resolve(row);
-        }
+        })
       );
     });
   }
@@ -836,10 +840,10 @@ class TokenModule {
       this.db.run(
         'UPDATE users SET last_login = CURRENT_TIMESTAMP WHERE id = ?',
         [userId],
-        (err) => {
+        guarded(reject, (err) => {
           if (err) reject(err);
           else resolve();
-        }
+        })
       );
     });
   }
@@ -852,10 +856,10 @@ class TokenModule {
          WHERE user_id = ? 
          ORDER BY created_at DESC`,
         [userId],
-        (err, rows) => {
+        guarded(reject, (err, rows) => {
           if (err) reject(err);
           else resolve(rows || []);
-        }
+        })
       );
     });
   }
@@ -870,10 +874,10 @@ class TokenModule {
         `INSERT INTO api_keys (user_id, key_hash, key_prefix, name, scopes, expires_at, created_ip) 
          VALUES (?, ?, ?, ?, ?, ?, ?)`,
         [userId, keyHash, keyPrefix, name, scopes, expiresAt, ip],
-        function(err) {
+        guarded(reject, function(err) {
           if (err) reject(err);
           else resolve(this.lastID);
-        }
+        })
       );
     });
   }
@@ -887,7 +891,7 @@ class TokenModule {
         FROM api_keys ak 
         JOIN users u ON ak.user_id = u.id 
         WHERE ak.key_prefix = ? AND ak.is_active = 1 AND u.is_active = 1
-      `, [keyPrefix], async (err, rows) => {
+      `, [keyPrefix], guarded(reject, async (err, rows) => {
         if (err) {
           reject(err);
           return;
@@ -911,7 +915,7 @@ class TokenModule {
         } catch (error) {
           reject(error);
         }
-      });
+      }));
     });
   }
 
@@ -920,13 +924,13 @@ class TokenModule {
       this.db.run(
         'UPDATE api_keys SET is_active = 0 WHERE id = ? AND user_id = ?',
         [keyId, userId],
-        function(err) {
+        guarded(reject, function(err) {
           if (err) {
             reject(err);
           } else {
             resolve(this.changes > 0);
           }
-        }
+        })
       );
     });
   }
@@ -937,10 +941,10 @@ class TokenModule {
       this.db.run(
         'UPDATE api_keys SET last_used = CURRENT_TIMESTAMP WHERE id = ?',
         [keyId],
-        (err) => {
+        guarded(reject, (err) => {
           if (err) reject(err);
           else resolve();
-        }
+        })
       );
     });
   }
@@ -956,10 +960,10 @@ class TokenModule {
           request_count = request_count + ?,
           last_request_ip = ?,
           updated_at = CURRENT_TIMESTAMP
-      `, [keyId, today, count, ip, count, ip], function(err) {
+      `, [keyId, today, count, ip, count, ip], guarded(reject, function(err) {
         if (err) reject(err);
         else resolve();
-      });
+      }));
     });
   }
 
@@ -970,10 +974,10 @@ class TokenModule {
       this.db.get(
         'SELECT request_count FROM usage_stats WHERE api_key_id = ? AND date = ?',
         [keyId, today],
-        (err, row) => {
+        guarded(reject, (err, row) => {
           if (err) reject(err);
           else resolve(row ? row.request_count : 0);
-        }
+        })
       );
     });
   }
@@ -986,10 +990,10 @@ class TokenModule {
         JOIN api_keys ak ON us.api_key_id = ak.id
         WHERE ak.user_id = ? AND us.date >= date('now', '-30 days')
         ORDER BY us.date DESC
-      `, [userId], (err, rows) => {
+      `, [userId], guarded(reject, (err, rows) => {
         if (err) reject(err);
         else resolve(rows || []);
-      });
+      }));
     });
   }
 
@@ -1000,10 +1004,10 @@ class TokenModule {
         FROM usage_stats 
         WHERE api_key_id = ? AND date >= date('now', '-${days} days')
         ORDER BY date DESC
-      `, [keyId], (err, rows) => {
+      `, [keyId], guarded(reject, (err, rows) => {
         if (err) reject(err);
         else resolve(rows || []);
-      });
+      }));
     });
   }
 
@@ -1013,13 +1017,13 @@ class TokenModule {
       this.db.run(
         'INSERT INTO security_log (user_id, event_type, ip_address, user_agent, details) VALUES (?, ?, ?, ?, ?)',
         [userId, eventType, ip, userAgent, JSON.stringify(details)],
-        function(err) {
+        guarded(reject, function(err) {
           if (err) {
             // Don't fail the main operation if logging fails
             console.error('Failed to log security event:', err);
           }
           resolve();
-        }
+        })
       );
     });
   }
@@ -1292,15 +1296,15 @@ class TokenModule {
       this.sessionStore.close();
     }
     if (this.db) {
-      await new Promise((resolve) => {
-        this.db.close((err) => {
+      await new Promise((resolve, reject) => {
+        this.db.close(guarded(reject, (err) => {
           if (err) {
             this.log.error('Error closing database:', err);
           } else {
             this.log.info('Database connection closed');
           }
           resolve();
-        });
+        }));
       });
     }
   }

package/translations/Messages.properties

@@ -159,6 +159,7 @@ CODESYSTEM_SHAREABLE_MISSING_HL7 = Code systems published by HL7 SHALL conform t
 CODESYSTEM_SUPP_NO_DISPLAY = This display (''{0}'') differs from that defined by the base code system (''{1}''). Both displays claim to be the ''primary designation'' for the same language (''{2}''), and the correct interpretation of this is undefined
 CODESYSTEM_THO_CHECK = Most code systems defined in HL7 IGs will need to move to THO later during the process. Consider giving this code system a THO URL now (See https://confluence.hl7.org/display/TSMG/Terminology+Play+Book, and/or talk to TSMG)
 CODESYSTEM_TOO_COSTLY_TIME = The operation ''{1}'' took too long to process (>{0}sec) (at {2})
+CODESYSTEM_VERSION_NEEDED = The code system ''{0}'' says that a version must be specified when it is referenced (versionNeeded = true), but this coding has no version
 CODESYSTEM_NOT_ENUMERABLE = The code system ''{0}'' cannot be expanded because its codes cannot be iterated or enumerated in any meaningful sense
 Coding_has_no_system__cannot_validate = Coding has no system. A code with no system has no defined meaning, and it cannot be validated. A system should be provided
 Coding_has_no_system_or_code__cannot_validate = Coding has neither a system nor a code, so it cannot be validated. A system and a code should be provided
@@ -1094,6 +1095,8 @@ Unable_to_handle_system__filter_with_property__ = Unable to handle system {0} fi
 UNABLE_TO_HANDLE_SYSTEM__PROPERTY_FILTER_WITH_OP__ = Unable to handle system {0} property filter with op = {1}
 UNABLE_TO_HANDLE_SYSTEM_FILTER_WITH_NO_VALUE = The system {0} filter with property = {1}, op = {2} has no value
 UNABLE_TO_INFER_CODESYSTEM = The System URI could not be determined for the code ''{0}'' in the ValueSet ''{1}''
+UNABLE_TO_INFER_CODESYSTEM_UNKNOWN_SYSTEM = The System URI could not be determined for the code ''{0}'' in the ValueSet ''{1}'': a definition for the CodeSystem ''{2}'' it includes could not be found
+VALUESET_MODIFIER_EXTENSION_UNKNOWN = The value set {0} can''t be processed: {1} has a modifier extension that isn''t understood ({2})
 Unable_to_locate_the_profile__in_order_to_validate_against_it = Unable to locate the profile ''{0}'' in order to validate against it
 Unable_to_process_request_for_resource_for___ = Unable to process request for resource for {0} / {1}
 Unable_to_resolve_ = Unable to resolve the reference {0}
@@ -1116,9 +1119,20 @@ Unable_to_resolve_system__value_set_has_no_includes_or_expansion = The System UR
 UNABLE_TO_RESOLVE_SYSTEM_SYSTEM_IS_INDETERMINATE = The code system {1} referred to from value set {0} has a grammar, and the code might be valid in it
 Unable_to_resolve_value_Set_ = A definition for the value Set ''{0}'' could not be found
 CACHE_ID_UNKNOWN = The cache ''{0}'' was never issued by this server, and this server has no record of it ever existing. Caches are created with $cache-control?mode=start, and a cache-id is only valid on the server instance and endpoint that issued it - either it was issued somewhere else, or this server has restarted since it was issued
+CACHE_ID_UNKNOWN_SHARED = The cache ''{0}'' was never issued by this server for this endpoint: this server has no record of it. Caches are created with $cache-control?mode=start, and a cache-id is only valid on the server and endpoint that issued it
+CACHE_ID_NEVER_ISSUED = The cache ''{0}'' was never issued by this server: it carries this server''s instance code and the start of this run, which began {1} ago, but this server has no record of it (it remembers the fate of the last {2} caches that ended). Caches are created with $cache-control?mode=start
+CACHE_ID_GONE_DURING_REQUEST = The cache ''{0}'' ended ({1}) while this request was using it, so {2} is no longer available. This operation has not been performed. Start a new cache with $cache-control?mode=start, and send the request again
+CACHE_ID_CHANGED_DURING_REQUEST = The cache ''{0}'' changed while this request was using it: another request replaced {1} after this one had read the list of what the cache holds. This operation has not been performed. Send the request again, to read the new contents together
+CACHE_ID_LOST_TO_RESTART = The cache ''{0}'' was lost to a server restart {1} ago. Caches are not carried over a restart, because neither the client nor the server can be sure a cache is intact across operations that were tried while the server was down. Start a new cache with $cache-control?mode=start and send the resources again
 CACHE_ID_CLOSED = The cache ''{0}'' was closed {1} ago by the client, using $cache-control?mode=end (it had been open for {2}). It did not expire and it was not idle: something in the client released this cache while this request was still using it
 CACHE_ID_EXPIRED = The cache ''{0}'' expired: it went {1} without being used, and this server closes caches that have been idle for more than {2} (this one was dropped {3} ago). Every request that uses a cache resets its idle clock, so a client that keeps using a cache will not see this
 CACHE_ID_CLEARED = The cache ''{0}'' was dropped {1} ago, when this server cleared all of its caches
+CACHE_ID_EVICTED = The cache ''{0}'' was dropped {1} ago to make room: the caches held more concepts than this server allows, and this was the one used least recently
+CACHE_ID_DISCARDED = The cache ''{0}'' was dropped {1} ago because it grew too large: a request would have taken it over {2} concepts, the most this server allows in one cache (cacheMaxConcepts). This operation has not been performed. Start a new cache, and send the request again
+CACHE_ID_DISCARDED_TOO_BIG = The cache ''{0}'' grew too large: this request would have taken it over {1} concepts, the most this server allows in one cache (cacheMaxConcepts), so the server has dropped the cache. This operation has not been performed. Start a new cache, and send the request again
+CACHE_ID_EVICTED_SIZE = The cache ''{0}'' was dropped {1} ago to make room: this server holds at most {2} of client resources across all caches, and when it is full it drops the caches that have gone longest without being used (this one had been idle for {3}). Start a new cache and send the resources again
+CACHE_REQUEST_TOO_BIG = This request''s resources hold {0} concepts, more than this server allows in one cache ({1}, cacheMaxConcepts), so no cache can hold them
+CACHE_START_TOO_BIG = The cache ''{0}'' would hold {1} concepts, more than this server allows in one cache ({2}, cacheMaxConcepts)
 CACHE_ID_OTHER_INSTANCE = The cache ''{0}'' was issued by the server instance ''{1}'', but this is instance ''{2}''. A cache only exists on the instance that issued it, so this request reached the wrong server: either the proxy in front of these servers is not routing on the cache-id, or instance ''{1}'' is unavailable
 CACHE_ID_OTHER_INSTANCE_UNNAMED = The cache ''{0}'' was issued by the server instance ''{1}'', but this server has no instance code, so it cannot have issued it. A cache only exists on the instance that issued it, so this request reached the wrong server: either the proxy in front of these servers is not routing on the cache-id, or instance ''{1}'' is unavailable
 CLOSURE_NOT_SUPPORTED = This server does not support $closure (it has to be turned on by the administrator)
@@ -1141,6 +1155,7 @@ CLOSURE_TOO_MANY_REQUEST_CONCEPTS = A single $closure request can add at most {0
 CLOSURE_TOO_MANY_ENTRIES = Adding these concepts would put more entries into the closure table ''{0}'' than this server allows, in one request or in total
 CLOSURE_CONFIG_TOO_LARGE = The configuration supplied for this closure table (mostly the tx-resource parameters) is larger than this server will keep, which is {0} bytes
 CLOSURE_TABLE_BUSY = The closure table ''{0}'' is busy with other requests. Try again shortly
+CLOSURE_TABLE_CHANGED = The closure table ''{0}'' was reset while this request was reading it. Retry the request against the new table
 SUBSUMPTION_CS_HIERARCHY_MEANING = The CodeSystem ''{0}'' has hierarchyMeaning = {1}, so its hierarchy does not describe subsumption, and subsumption cannot be tested
 SUBSUMPTION_CS_NOT_COMPLETE = The CodeSystem ''{0}'' has content = {1}, so subsumption cannot be tested (subsumption can only be tested against a code system with content = complete)
 SUBSUMPTION_CS_NOT_FOUND = A definition for the CodeSystem ''{0}'' could not be found, so subsumption cannot be tested
@@ -1283,6 +1298,7 @@ VALUESET_CONCEPT_DISPLAY_PRESENCE_MIXED = This include has some concepts with di
 VALUESET_CONCEPT_DISPLAY_SCT_TAG_MIXED = This SNOMED-CT based include has some concepts with semantic tags (FSN terms) and some without (preferred terms) - check that this is what is intended (examples for FSN: {0} and examples for no FSN: {1})
 VALUESET_EXAMPLE_SYSTEM_ERROR = Example System ''{0}'' specified, which is illegal. Concepts and Filters can''t be checked
 VALUESET_EXAMPLE_SYSTEM_HINT = Example System ''{0}'' specified, so Concepts and Filters can''t be checked
+VALUESET_EXPANSION_CODESYSTEM_LIMITED = Only {1} codes from the code system ''{0}'' can be listed in an expansion (by agreement with its publisher), so this expansion doesn''t list all the codes asked for
 VALUESET_IMPORT_UNION_INTERSECTION = This value set has a single include with multiple imported value sets. Per issue https://jira.hl7.org/browse/FHIR-25179, there has been confusion in the past whether these value sets are unioned or intersectioned. If this value set is contained in a package published prior to March 31 2022, it will be treated as a union, otherwise it will be treated as an intersection. If want a union, split the value set imports across multiple includes
 VALUESET_INC_TOO_MANY_CODES = The value set include has too many concepts to validate ({0}), so each individual code has not been checked
 VALUESET_INC_NOT_VALIDATING = The concepts in the value set include have not been validated because the validator is configured not to check them
@@ -1327,6 +1343,9 @@ VALUESET_SHAREABLE_MISSING_HL7 = Value sets published by HL7 SHALL conform to th
 VALUESET_SUPPLEMENT_MISSING_one = Required supplement not found: {1}
 VALUESET_SUPPLEMENT_MISSING_other = Required supplements not found: {1}
 VALUESET_TOO_COSTLY = The value set ''{0}'' expansion has too many codes to produce ({1})
+VALUESET_TOO_COSTLY_REQUEST = The expansion of the value set in the request has too many codes to produce ({0})
+VALUESET_TOO_COSTLY_PAGE = The value set ''{0}'' can''t be paged to offset {1} with count {2}: the server walks at most {3} codes to reach a page
+VALUESET_TOO_COSTLY_PAGE_REQUEST = The value set in the request can''t be paged to offset {0} with count {1}: the server walks at most {2} codes to reach a page
 VALUESET_TOO_COSTLY_COUNT = The value set ''{0}'' expansion has {2} codes, which is too many to display ({1})
 VALUESET_TOO_COSTLY_TIME = The value set ''{0}'' {2} took too long to process (>{1}sec)
 VALUESET_UNC_SYSTEM_WARNING = Unknown System ''{0}'' specified, so Concepts and Filters can''t be checked (Details: {1})

package/tx/README.md

@@ -27,8 +27,8 @@ Add the `tx` section to your `config.json`:
       "librarySource": "/path/to/library.yml",
       "publishLibrarySource": false,
       "cacheTimeout": 30,
-      "internalLimit" : 10000,
-      "externalLimit" : 1000,
+      "internalLimit" : 100000,
+      "externalLimit" : 10000,
       "expansionCacheSize": 1000,
       "expansionCacheMemoryThreshold": 0,
       "endpoints": [
@@ -64,13 +64,96 @@ Add the `tx` section to your `config.json`:
 |---------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------|
 | `enabled`                       | boolean | Yes      | Whether the module is enabled                                                                           |
 | `cacheTimeout`                  | integer | No       | How many minutes to keep client side caches (for cache-id parameter). Default: 30                       |
+| `cacheMaxConcepts`              | integer | No       | Concepts one client side cache (cache-id) may hold. Default: 250000, about 10x the largest IG Publisher session measured on build.fhir.org (24,048). A request that would take a cache over it is not performed: the server drops the cache and answers 404, an OperationOutcome with one issue coded `tx-issue-type#cache-id-unknown` (message id `CACHE_ID_DISCARDED_TOO_BIG`, saying the cache grew too large), as for any cache that is gone. The client starts a new cache and sends the request again; later requests with the old id get the same 404 `cache-id-unknown`, saying why it was dropped (`CACHE_ID_DISCARDED`). A request whose own resources hold more than this, so that no cache could take them, is refused instead (422 too-costly) and the cache is kept, as is a new cache too big to start. 0 = no limit |
+| `cacheMaxTotalConcepts`         | integer | No       | Concepts all the client side caches of an endpoint may hold between them (about 250 bytes of heap each). Default: 1000000, 4 full caches, about 40x the largest session measured (24,048). The least recently used caches are dropped to stay under it; a request with a dropped cache-id gets a 404 `cache-id-unknown`, saying it was dropped to make room. 0 = no limit |
+| `usageTrackerMaxCodes`          | integer | No       | Distinct codes the usage tracker (`usage-count` expansion property) keeps. Default: 1000000, 2x the about 500,000 codes the value sets of a full library list. Codes beyond it aren't counted (no error); codes already tracked still are. 0 = no limit |
+| `usageTrackerMaxCodeLength`     | integer | No       | Longest code, in characters, the usage tracker keeps. Default: 100, 2.5x the longest code those value sets list (40). Longer codes aren't counted (no error). 0 = no limit |
+| `languageTagCacheSize`          | integer | No       | Parsed language tags kept (least recently used dropped). Default: 1000; an 8 KB private use tag takes about 46 KB parsed, so at most about 46 MB. Clients see nothing but a re-parse. 0 = no limit (unique tags in requests then grow the heap forever) |
 | `expansionCacheSize`            | integer | No       | Maximum number of expanded ValueSets to cache. Default: 1000                                            |
 | `expansionCacheMemoryThreshold` | integer | No       | Heap memory usage in MB that triggers evicting oldest half of expansion cache. 0 = disabled. Default: 0 |
+| `expansionCacheMaxCodes`        | integer | No       | Most codes the expansion caches of all the endpoints hold between them; the least recently used expansions are dropped to stay under it. Default: a quarter of the heap limit at 1 KB a code (about 1 million codes with a 4 GB heap) |
 | `librarySource`                 | string  | Yes      | Path to the YAML file that defines the terminology sources to load                                      |
 | `publishLibrarySource`          | boolean | No       | Publish that YAML file at `/{path}/library`. Default: false                                             |
-| `internalLimit`                 | integer | No       | Largest number of codes in internal expansions                                                          |
-| `externalLimit`                 | integer | No       | Largest number of codes the server will return in an expansion                                          |
+| `pruneTerminologyCache`        | boolean | No       | Once the library and every endpoint's core packages have loaded, delete what in `terminology-cache` wasn't used: the `.db` and `.cache` files (the downloaded databases and SNOMED CT caches of sources no longer in the library, and the fallback of an `a\|b` source whose first file is there), with their SQLite side files; and the package folders (`id#version`: packages no longer in the library, older versions of ones that are, the core packages of FHIR versions no endpoint has, and what failed downloads left), with the value set and concept map caches in them. Other files and folders (`vsac`, `ocl`, `syndication`, `folder-source-*`) are left alone, and so is anything changed in the last day (it may be being copied in for a library that doesn't name it yet). In a cluster, only the master deletes. Default: false: everything run from the same data directory (a development server and the tests, say) shares `terminology-cache`, and what one doesn't use another may |
+| `internalLimit`                 | integer | No       | Most codes in the expansion of a value set that an `$expand` imports (`compose.include.valueSet`). Default: 100000. Over it, the `$expand` fails with 422 too-costly. Also the most the `x-too-costly-threshold` header can ask for. Other internal expansions (in `$validate-code`, for one) use 10000 and don't read the setting |
+| `externalLimit`                 | integer | No       | Most codes an `$expand` returns. Default: 10000 (or `internalLimit`, if that is less). Over it, an expansion asked for without `count` fails with 422 too-costly (`VALUESET_TOO_COSTLY`, "... has too many codes to produce (>10000)"); a `count` bigger than it is cut down to it. A request can change it with the `x-too-costly-threshold` header (see below): the tx-ecosystem tests that depend on a limit set it |
+| `walkLimit`                     | integer | No       | How far a paged `$expand` (`count` and `offset`) may walk to reach its page: the most `offset + count`. Default: 10 x `internalLimit` (1000000). Only the page is built - the codes before it are passed keeping just their keys - so a page can lie well past `externalLimit`, which still caps `count`. Over it, the `$expand` fails with 422 too-costly (`VALUESET_TOO_COSTLY_PAGE`, "... can't be paged to offset ... with count ...: the server walks at most 1000000 codes to reach a page"); a value set that ends before the offset is an empty page, not a refusal. The walk is also bounded by `operationTimeLimit`. Any page, the first too, builds only its own codes; the codes after it are counted by key for the total, which is reported only when the whole expansion is within `externalLimit`, as for an unpaged one. Not for a value set with an exclude, or a request with a text filter: there, `offset + count` must still be within `externalLimit` |
+| `operationTimeLimit`            | integer | No       | Seconds of compute one operation may use (sub-operations share it). Default: 20. Time spent waiting - for the event loop, or in a queue before the operation starts - doesn't count. Over it, the operation fails with 422 too-costly ("Operation exceeded time limit of 20 seconds at ..."). The default sits under common client timeouts (okhttp gives up after 10-30 s): with a limit at or over the client's, the client hangs up first and never sees the OperationOutcome |
+| `ecosystem`                     | object  | No       | Answering for code systems that aren't held here by asking other servers in the terminology ecosystem - see [Ecosystem Resolution](#ecosystem-resolution) below. Default: not used |
 | `endpoints`                     | array   | Yes      | List of endpoint configurations (at least one required)                                                 |
+| `vsacCfg`                       | object  | No       | Settings for the VSAC value set provider; required if the library loads VSAC (see below)              |
+
+### Ecosystem Resolution
+
+When a code system (or a version of one) isn't held here, the server can ask the terminology
+ecosystem registry which server has it, and ask that server (`cs/cs-virtual.js`). Only
+`$validate-code` against a value set is supported this way, and slowly: a `$lookup` per code, and a
+`$validate-code` per filter.
+
+```json
+"ecosystem" : {
+  "use": true,
+  "excludedServers": [ "tx.fhir.org" ],
+  "excludedPatterns": [ "http://hl7.org/*", "http://terminology.hl7.org/*" ],
+  "apiKeys": { "hl7-ca" : "xx" },
+  "oauth" : {
+    "nzhts": {
+      "tokenEndpoint" : "https://authenticate.nzhts.digital.health.nz/auth/realms/nzhts/protocol/openid-connect/token",
+      "clientId" : "hl7",
+      "clientSecret" : "xx"
+    }
+  }
+}
+```
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `use` | boolean | Turns it on. Default: false |
+| `registry` | string | The ecosystem registry. Default: `https://ecosystem.hl7.org/tx-reg` |
+| `excludedServers` | array | Servers never used, each a host (`tx.fhir.org`) or an address that the server's address starts with. tx.fhir.org (and tx-dev.fhir.org, which serves the same content) sets this to `["tx.fhir.org"]`: the registry names tx.fhir.org for what `tx.fhir.org.yml` loads, so that's this server, logically, whatever its address is, and asking it again can only give the answer this server already gave |
+| `excludedPatterns` | array | Code systems never looked for in the ecosystem, as the registry writes them: `*` matches anything, and a pattern is matched against the url, and the url\|version. These aren't even asked about, so they cost nothing: a server that knows the registry will name itself (or a server in `excludedServers`) for them should list them |
+| `apiKeys` | object | Server code (as in the registry) -> API key, sent as `Api-Key`. As for the registry module |
+| `oauth` | object | Server code -> `{ tokenEndpoint, clientId, clientSecret, scope }`: an OAuth2 client_credentials grant, the token sent as `Authorization: Bearer`. As for the registry module |
+| `allowPrivateAddresses` | boolean | Lets requests go to private, loopback and other non-public addresses. Default: false - the registry, the servers it names, and the OAuth token endpoints must all be at public addresses, because the addresses come from the registry, which may not be the public one (as for the registry module's setting of the same name). For a local registry or test servers |
+
+A server is used if it's open, or if there are credentials for it. The server must also say, in its
+TerminologyCapabilities, that it has the code system and version asked for (or, for a version that
+is a url, a release of it - a SNOMED CT edition asked for without a release date). With no version
+asked for, it's the server's only version, or the one it marks `isDefault`. Requests sent on to
+another server carry the header `X-FHIRsmith-Ecosystem-Forwarded`, and a request that arrives with
+it is never resolved through the ecosystem again.
+
+What the registry says, and what each server says it has, is kept for an hour, and then refreshed
+in the background: a request never waits for a refresh, only the first request for something does
+(if a refresh fails, the old answer is used, and the refresh tried again in five minutes). The
+other servers' answers to `$lookup` and `$validate-code` are kept for an hour too (the most recent
+10,000), so the same question is only asked once. Requests that had to ask another server are
+counted, and graphed, separately on the home page (External requests).
+
+### VSAC Configuration
+
+`vsacCfg` configures the VSAC provider (a `vsac` source in the library). The value sets are
+synced from VSAC into a SQLite database in the terminology cache folder, and read from it when
+they are asked for; only the recently used ones are kept parsed in memory.
+
+| Option                 | Type    | Required | Description                                                                                       |
+|------------------------|---------|----------|---------------------------------------------------------------------------------------------------|
+| `apiKey`               | string  | Yes      | UMLS API key for VSAC                                                                             |
+| `baseUrl`              | string  | No       | VSAC FHIR server. Default: `https://cts.nlm.nih.gov/fhir`                                         |
+| `refreshIntervalHours` | number  | No       | Hours between syncs. A failed sync is retried after 1, 5, then every 30 minutes. Default: 24      |
+| `timeoutMs`            | integer | No       | Timeout for requests to VSAC, in milliseconds. Default: 120000                                    |
+| `resyncPassword`       | string  | No       | If set, the /info page offers a form (gated by this password) to resync one value set now        |
+| `valueSetCacheMB`      | number  | No       | Size of the recently used value sets kept parsed, measured by their stored JSON; 0 keeps none. Default: 64 |
+
+`valueSetCacheMB` is measured in stored JSON, not memory: parsed value sets take several
+times as much heap as their JSON (so expect a few hundred MB of heap at the default), and in
+cluster mode every worker keeps its own.
+
+`externalLimit`, `internalLimit` and `walkLimit` are checked at startup: each, when set, must be a whole number above 0, and `externalLimit` <= `internalLimit` <= `walkLimit`; anything else stops the server with an error saying which. The limits in use are logged at startup. Every client gets the same limits: the tx-ecosystem test runner (User-Agent `Tools/Java`) used to be held to the old defaults (3000 and 10000) whatever the configuration; now the tests that depend on a limit ask for it with the header.
+
+The `x-too-costly-threshold` request header sets the `externalLimit` for that request, for any client. It is there so test cases can ask for a lower limit: it can't be more than the `internalLimit` (a bigger value is cut down to it), and a value that isn't a positive whole number is ignored, so there is always a limit.
+
+The largest request body the server accepts is a server setting, `server.maxBodyMB` (see the main README); a tx endpoint answers a bigger one with a 413 OperationOutcome (too-costly).
 
 ### Endpoint Configuration
 
@@ -84,6 +167,24 @@ Each endpoint in the `endpoints` array has:
 
 **Note:** Endpoint paths must be unique. The module will throw an error if duplicate paths are configured or if a path conflicts with another module.
 
+### Fixed limits
+
+These are constants in the code, not settings; they are listed so their effects can be recognised.
+
+| Limit | Value | What it bounds |
+|---|---|---|
+| Memory per code, for the default of `expansionCacheMaxCodes` | 1 KB | only the derived default (`operation-context.js`) |
+| Share of the heap, for the default of `expansionCacheMaxCodes` | 0.25 | a quarter of the V8 heap limit, per process |
+| Shortest expansion that is cached | 250 ms | expansions that took less are not kept in the expansion cache |
+| Longest compute before yielding the event loop | 10 ms | how long one operation can hold up the others (`operation-context.js`, `YIELD_INTERVAL`) |
+| ECL nesting depth | 100 | bracketed expressions and refinements; deeper is a parse error |
+| ECL sub-expressions | 500 | focus concepts, refinement values, ... (a long `A OR B OR ...` reaches it first); more is a parse error |
+| Resource self-nesting depth | 100 | `CodeSystem.concept` and `ValueSet.expansion.contains` (SNOMED CT is about 30 deep); deeper is a 400 |
+| XML element depth | 1000 | a deeper XML body is an error |
+| LOINC SQLite `cache_size` | 10000 pages (about 40 MB) | page cache, per database connection |
+| LOINC SQLite `mmap_size` | 256 MB | memory-mapped reads, per database connection; file-backed pages, shared between connections |
+| Forced GC back-off | 60 s at most | while the memory guard is refusing requests, the wait between forced GCs doubles up to this (server wide, `library/memory-guard.js`) |
+
 ## Supported Operations
 
 Each endpoint provides the following FHIR terminology operations:
@@ -258,6 +359,52 @@ actually returns (metadata, read and search, `$expand`, `$validate-code`, `$look
 `$subsumes`, `$batch-validate-code`, `$versions`, `$cache-control`, an error) against the
 schemas, using ajv. So a new parameter needs adding to openapi-operations.js.
 
+## Loading SNOMED CT
+
+By default each SNOMED CT cache file is read into the server process, at about its file size
+(0.6–1.2 GB an edition). A file can instead be memory-mapped read-only:
+
+- the edition loads in milliseconds;
+- only the pages that requests touch become resident, as page cache that the kernel can drop
+  and read again;
+- every server process on the machine that maps the same file shares those pages.
+
+The first request to touch a part of a mapped edition waits for the disk, unless that edition
+is *prewarmed*: mapped, then read through once in the background at startup, so its pages are
+already in the page cache when requests arrive. Startup doesn't wait for it.
+
+This is set per server, in the tx module's `snomed` block in `config.json`:
+
+```json
+"tx": {
+  "snomed": {
+    "load": "mmap",
+    "prewarm": ["http://snomed.info/sct/900000000000207008/version/20250201",
+                "sct_us_20250901b.cache"],
+    "read": []
+  }
+}
+```
+
+- **`load`** is `"read"` (the default) or `"mmap"`, for every edition not named below.
+- **`prewarm`** lists editions to prewarm (map, then read through once in the background at
+  startup), even when `load` is `"read"`.
+- **`read`** lists editions to read into the process even when `load` is `"mmap"`.
+- An entry is any of:
+  - a cache file name (`sct_us_20250901b.cache`)
+  - an edition version URI (`http://snomed.info/sct/731000124108/version/20250901`)
+  - an edition URI (`http://snomed.info/sct/731000124108`), which covers every loaded version
+    of that edition
+- `read` wins over `prewarm`.
+- Entries that match no loaded edition are warned about at startup.
+- With no `snomed` block, everything is read, as before.
+
+Mapping uses the optional `koffi` dependency. Where it is not available (Windows, 32-bit
+platforms, or koffi not installed), a mapped edition is read instead, with a warning in the
+server log. The log says, for each edition that was to be mapped, whether it really was. When
+any edition is mapped, the memory guard leaves file-backed pages out of the memory it measures
+(Linux).
+
 ## Library Configuration
 
 The library - the source to load - is configured using a YAML file.
@@ -408,6 +555,9 @@ Common edition identifiers:
 
 The file is built by importing SNOMED CT (see [documentation](importers/readme.md))
 
+How the cache files are loaded is a deployment choice, so it is set in `config.json` (the
+tx module's `snomed` block), not here - see [Loading SNOMED CT](#loading-snomed-ct).
+
 
 #### `cpt` - CPT (Current Procedural Terminology)