fhirsmith 0.11.1 → 0.12.0

package/publisher/validation.js

@@ -0,0 +1,198 @@
+/**
+ * Validation for the fields a user types into the publication task form.
+ *
+ * None of these values can cause command injection - they're passed to spawn()
+ * as argv, and nothing goes near a shell - but they do end up in git command
+ * lines, in URLs, and in file names, so they're checked at the boundary rather
+ * than trusted to be harmless everywhere they're later used.
+ *
+ * The rules are the ones GitHub and git themselves enforce (see
+ * git-check-ref-format(1) for the branch rules): anything rejected here would
+ * have failed at clone time anyway, with a much worse error.
+ */
+
+// GitHub owner names: letters, digits and single hyphens, no hyphen at either
+// end, 39 characters at most.
+const MAX_OWNER = 39;
+// Repository names: letters, digits, dot, hyphen, underscore, 100 at most.
+const MAX_REPO = 100;
+// git imposes no length limit on a ref, but a branch name past this is a
+// filesystem problem waiting to happen.
+const MAX_BRANCH = 255;
+const MAX_PACKAGE_ID = 128;
+const MAX_VERSION = 64;
+
+/**
+ * A GitHub organisation or user name.
+ */
+function validateGithubOwner(value) {
+  if (!value) {
+    return 'GitHub org is required';
+  }
+  if (value.length > MAX_OWNER) {
+    return `GitHub org must be ${MAX_OWNER} characters or less`;
+  }
+  if (!/^[A-Za-z0-9](?:-?[A-Za-z0-9])*$/.test(value)) {
+    return 'GitHub org may only contain letters, digits and single hyphens, and may not start or end with a hyphen';
+  }
+  return null;
+}
+
+/**
+ * A GitHub repository name.
+ */
+function validateGithubRepo(value) {
+  if (!value) {
+    return 'GitHub repo is required';
+  }
+  if (value.length > MAX_REPO) {
+    return `GitHub repo must be ${MAX_REPO} characters or less`;
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    return 'GitHub repo may only contain letters, digits, dots, hyphens and underscores';
+  }
+  if (value === '.' || value === '..') {
+    return 'GitHub repo is not a valid name';
+  }
+  // the code appends '.git' when it builds the clone URL, and GitHub won't
+  // create a repository with that suffix anyway
+  if (value.toLowerCase().endsWith('.git')) {
+    return 'GitHub repo should not include the .git suffix';
+  }
+  return null;
+}
+
+/**
+ * A branch name, by the rules in git-check-ref-format(1). Slashes are fine -
+ * that's how branches are grouped - but the characters git reserves for
+ * revision syntax are not. Note that git itself rejects a backslash in a ref
+ * name, so this does too.
+ */
+function validateGitBranch(value) {
+  if (!value) {
+    return 'Branch is required';
+  }
+  if (value.length > MAX_BRANCH) {
+    return `Branch must be ${MAX_BRANCH} characters or less`;
+  }
+  // space, the ASCII control characters, and DEL
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001F\u007F ]/.test(value)) {
+    return 'Branch may not contain spaces or control characters';
+  }
+  // the characters git reserves for revision syntax
+  if (/[~^:?*[\\]/.test(value)) {
+    return 'Branch may not contain any of ~ ^ : ? * [ \\';
+  }
+  if (value.includes('..')) {
+    return 'Branch may not contain ..';
+  }
+  if (value.includes('@{')) {
+    return 'Branch may not contain @{';
+  }
+  if (value === '@') {
+    return 'Branch may not be @';
+  }
+  if (value.startsWith('-')) {
+    return 'Branch may not start with a hyphen';
+  }
+  if (value.startsWith('/') || value.endsWith('/') || value.includes('//')) {
+    return 'Branch may not start or end with /, or contain //';
+  }
+  if (value.endsWith('.')) {
+    return 'Branch may not end with .';
+  }
+  for (const part of value.split('/')) {
+    if (part.startsWith('.')) {
+      return 'No part of a branch name may start with .';
+    }
+    if (part.endsWith('.lock')) {
+      return 'No part of a branch name may end with .lock';
+    }
+  }
+  return null;
+}
+
+/**
+ * An NPM package id. This one is not about git at all: the package id and the
+ * version are concatenated into file names under the zips directory
+ * (<id>#<version>.log, <id>#<version>-announcement.txt), so a value containing
+ * a path separator would look outside that directory.
+ */
+function validatePackageId(value) {
+  if (!value) {
+    return 'NPM package id is required';
+  }
+  if (value.length > MAX_PACKAGE_ID) {
+    return `NPM package id must be ${MAX_PACKAGE_ID} characters or less`;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    return 'NPM package id may only contain letters, digits, dots, hyphens and underscores, and must start with a letter or digit';
+  }
+  if (value.includes('..')) {
+    return 'NPM package id may not contain ..';
+  }
+  return null;
+}
+
+/**
+ * A package version. Loose enough for semver with pre-release and build
+ * metadata, tight enough that it can't become a path.
+ */
+function validateVersion(value) {
+  if (!value) {
+    return 'Version is required';
+  }
+  if (value.length > MAX_VERSION) {
+    return `Version must be ${MAX_VERSION} characters or less`;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9.+-]*$/.test(value)) {
+    return 'Version may only contain letters, digits, dots, hyphens and plus signs, and must start with a letter or digit';
+  }
+  if (value.includes('..')) {
+    return 'Version may not contain ..';
+  }
+  return null;
+}
+
+/**
+ * Validate everything the task form collects.
+ * @returns {string[]} the problems found, empty if the input is acceptable
+ */
+function validateTaskInput(input) {
+  const errors = [];
+  const checks = [
+    validateGithubOwner(input.github_org),
+    validateGithubRepo(input.github_repo),
+    validateGitBranch(input.git_branch),
+    validatePackageId(input.npm_package_id),
+    validateVersion(input.version)
+  ];
+  for (const error of checks) {
+    if (error) {
+      errors.push(error);
+    }
+  }
+  return errors;
+}
+
+// Patterns for the HTML form, so the browser objects before the round trip.
+// Deliberately a subset of the checks above - the server is what decides -
+// but they catch the obvious mistakes as the user types.
+const HTML_PATTERNS = {
+  github_org: '[A-Za-z0-9](-?[A-Za-z0-9])*',
+  github_repo: '[A-Za-z0-9._-]+',
+  git_branch: '[^\\\\ ~^:?*\\[]+',
+  npm_package_id: '[A-Za-z0-9][A-Za-z0-9._-]*',
+  version: '[A-Za-z0-9][A-Za-z0-9.+-]*'
+};
+
+module.exports = {
+  validateGithubOwner,
+  validateGithubRepo,
+  validateGitBranch,
+  validatePackageId,
+  validateVersion,
+  validateTaskInput,
+  HTML_PATTERNS
+};

package/server.js

@@ -99,13 +99,13 @@ let stats = null;
 
 // Initialize modules based on configuration
 async function initializeModules() {
-  stats = new ServerStats();
+  stats = new ServerStats(config.stats, serverLog);
 
   // Initialize SHL module
   if (config.modules?.shl?.enabled) {
     try {
       serverLog.info('Initializing module: shl...');
-      modules.shl = new SHLModule(stats);
+      modules.shl = new SHLModule(stats.forModule('shl'));
       await modules.shl.initialize(config.modules.shl);
       app.use('/shl', modules.shl.router);
     } catch (error) {
@@ -118,7 +118,7 @@ async function initializeModules() {
   if (config.modules?.vcl?.enabled) {
     try {
       serverLog.info('Initializing module: vcl...');
-      modules.vcl = new VCLModule(stats);
+      modules.vcl = new VCLModule(stats.forModule('vcl'));
       await modules.vcl.initialize(config.modules.vcl);
       app.use('/VCL', modules.vcl.router);
     } catch (error) {
@@ -131,7 +131,7 @@ async function initializeModules() {
   if (config.modules?.xig?.enabled) {
     try {
       serverLog.info('Initializing module: xig...');
-      await xigModule.initializeXigModule(stats, config.modules.xig);
+      await xigModule.initializeXigModule(stats.forModule('xig'), config.modules.xig);
       app.use('/xig', xigModule.router);
       modules.xig = xigModule;
     } catch (error) {
@@ -144,7 +144,7 @@ async function initializeModules() {
   if (config.modules?.packages?.enabled) {
     try {
       serverLog.info('Initializing module: packages...');
-      modules.packages = new PackagesModule(stats);
+      modules.packages = new PackagesModule(stats.forModule('packages'));
       await modules.packages.initialize(config.modules.packages);
       app.use('/packages', modules.packages.router);
     } catch (error) {
@@ -158,7 +158,7 @@ async function initializeModules() {
   if (config.modules?.registry?.enabled) {
     try {
       serverLog.info('Initializing module: registry...');
-      modules.registry = new RegistryModule(stats);
+      modules.registry = new RegistryModule(stats.forModule('registry'));
       await modules.registry.initialize(config.modules.registry);
       app.use('/tx-reg', modules.registry.router);
     } catch (error) {
@@ -171,7 +171,7 @@ async function initializeModules() {
   if (config.modules?.publisher?.enabled) {
     try {
       serverLog.info('Initializing module: publisher...');
-      modules.publisher = new PublisherModule(stats);
+      modules.publisher = new PublisherModule(stats.forModule('publisher'));
       await modules.publisher.initialize(config.modules.publisher);
       app.use('/publisher', modules.publisher.router);
     } catch (error) {
@@ -184,7 +184,7 @@ async function initializeModules() {
   if (config.modules?.token?.enabled) {
     try {
       serverLog.info('Initializing module: token...');
-      modules.token = new TokenModule(stats);
+      modules.token = new TokenModule(stats.forModule('token'));
       await modules.token.initialize(config.modules.token);
       app.use('/token', modules.token.router);
     } catch (error) {
@@ -197,7 +197,7 @@ async function initializeModules() {
   if (config.modules?.npmprojector?.enabled) {
     try {
       serverLog.info('Initializing module: npmprojector...');
-      modules.npmprojector = new NpmProjectorModule(stats);
+      modules.npmprojector = new NpmProjectorModule(stats.forModule('npmprojector'));
       await modules.npmprojector.initialize(config.modules.npmprojector);
       const basePath = NpmProjectorModule.getBasePath(config.modules.npmprojector);
       app.use(basePath, modules.npmprojector.router);
@@ -211,7 +211,7 @@ async function initializeModules() {
   if (config.modules?.['ext-tracker']?.enabled) {
     try {
       serverLog.info('Initializing module: ext-tracker...');
-      modules.extTracker = new ExtensionTrackerModule(stats);
+      modules.extTracker = new ExtensionTrackerModule(stats.forModule('ext-tracker'));
       await modules.extTracker.initialize(config.modules['ext-tracker'], app);
     } catch (error) {
       serverLog.error('Failed to initialize extension tracker module:', error);
@@ -224,7 +224,7 @@ async function initializeModules() {
   if (config.modules?.tx?.enabled) {
     try {
       serverLog.info('Initializing module: tx...');
-      modules.tx = new TXModule(stats);
+      modules.tx = new TXModule(stats.forModule('tx'));
       await modules.tx.initialize(config.modules.tx, app);
     } catch (error) {
       serverLog.error('Failed to initialize TX module:', error);
@@ -235,7 +235,7 @@ async function initializeModules() {
   if (config.modules?.folder?.enabled) {
     try {
       serverLog.info('Initializing module: folder...');
-      modules.folder = new FolderModule(stats);
+      modules.folder = new FolderModule(stats.forModule('folder'));
       await modules.folder.initialize(config.modules.folder, app);
       // mount the router
     } catch (error) {

package/stats-db.js

@@ -0,0 +1,127 @@
+const path = require('path');
+const fs = require('fs');
+const Database = require('better-sqlite3');
+const folders = require('./library/folder-setup');
+
+/**
+ * Persistent storage for the server's request statistics (issue #255).
+ *
+ * The in-memory counters in ServerStats reset every time the server restarts,
+ * which makes them useless for anything but "what has happened since the last
+ * deploy". This class writes them to a SQLite database that outlives restarts
+ * and upgrades.
+ *
+ * One row per (module, endpoint, operation) per collection interval, holding
+ * both numbers:
+ *
+ *  - the *delta*: what happened in that interval. This is what you graph -
+ *    plot count_delta against time and you have requests per interval without
+ *    any differencing at the query end.
+ *  - the *total*: the all-time cumulative count, carried across restarts by
+ *    reloading it at startup. This is what you quote as "how much has this
+ *    endpoint ever been asked to do", and it means a restart shows up as a
+ *    flat spot in the graph rather than a cliff back to zero.
+ *
+ * Rows are only written for keys that saw traffic in the interval, so idle
+ * endpoints cost nothing. Nothing is pruned: at 10 minute intervals a
+ * continuously busy (endpoint, operation) pair produces ~52,000 rows a year,
+ * which SQLite does not notice.
+ *
+ * better-sqlite3 (rather than sqlite3) on purpose: the writes are synchronous,
+ * so the final flush in ServerStats.finishStats() lands on disk before
+ * server.js calls process.exit(). A handful of inserts every ten minutes is
+ * well under a millisecond, so this does not put the event loop at risk.
+ */
+class StatsDatabase {
+
+  constructor(config, log) {
+    this.log = log || console;
+    this.config = config || {};
+    this.db = null;
+    this.path = StatsDatabase.resolvePath(this.config);
+  }
+
+  /**
+   * Where the database lives: config.database if given (relative paths resolve
+   * under the data folder's databases directory), otherwise stats.db there.
+   */
+  static resolvePath(config) {
+    const configured = config && config.database;
+    if (!configured) {
+      return path.join(folders.databasesDir(), 'stats.db');
+    }
+    return path.isAbsolute(configured) ? configured : path.join(folders.databasesDir(), configured);
+  }
+
+  /**
+   * Open the database, creating the file and the schema if they aren't there.
+   */
+  open() {
+    fs.mkdirSync(path.dirname(this.path), {recursive: true});
+    this.db = new Database(this.path);
+    this.db.pragma('journal_mode = WAL');
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS request_counts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        time INTEGER NOT NULL,
+        interval_ms INTEGER NOT NULL,
+        module TEXT NOT NULL,
+        endpoint TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        count_delta INTEGER NOT NULL,
+        count_total INTEGER NOT NULL,
+        time_delta INTEGER NOT NULL,
+        time_total INTEGER NOT NULL
+      )
+    `);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_request_counts_time ON request_counts(time)`);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_request_counts_key ON request_counts(module, endpoint, operation, id)`);
+
+    this.insertStatement = this.db.prepare(`
+      INSERT INTO request_counts
+        (time, interval_ms, module, endpoint, operation, count_delta, count_total, time_delta, time_total)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    this.insertAll = this.db.transaction((time, intervalMs, rows) => {
+      for (const row of rows) {
+        this.insertStatement.run(time, intervalMs, row.module, row.endpoint, row.operation,
+          row.countDelta, row.countTotal, row.timeDelta, row.timeTotal);
+      }
+    });
+    return this;
+  }
+
+  /**
+   * The most recent cumulative total for each key, so counting resumes where
+   * the last run left off instead of starting again from zero.
+   */
+  loadTotals() {
+    if (!this.db) {
+      return [];
+    }
+    return this.db.prepare(`
+      SELECT module, endpoint, operation, count_total AS countTotal, time_total AS timeTotal
+      FROM request_counts
+      WHERE id IN (SELECT MAX(id) FROM request_counts GROUP BY module, endpoint, operation)
+    `).all();
+  }
+
+  /**
+   * Write one interval's worth of rows. All or nothing - if the transaction
+   * fails the caller keeps its deltas and tries again next interval.
+   */
+  write(time, intervalMs, rows) {
+    if (this.db && rows && rows.length > 0) {
+      this.insertAll(time, intervalMs, rows);
+    }
+  }
+
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+}
+
+module.exports = StatsDatabase;

package/stats.js

@@ -1,6 +1,49 @@
 const { monitorEventLoopDelay } = require('perf_hooks');
 const {Utilities} = require("./library/utilities");
 const escape = require('escape-html');
+const StatsDatabase = require('./stats-db');
+
+// Requests that aren't counted by a module (the root page, the dashboard) are
+// attributed here, and requests that have no endpoint dimension (everything
+// outside the tx module) carry NO_ENDPOINT.
+const SERVER_MODULE = '(server)';
+const NO_ENDPOINT = '';
+
+/**
+ * A per-module view of the server statistics.
+ *
+ * Modules are handed one of these instead of the ServerStats itself, so that
+ * everything they count is attributed to them without each of the ~76 call
+ * sites having to name its own module. The API is deliberately the same shape
+ * as ServerStats, so a module can't tell the difference - except that
+ * countRequest takes an optional endpoint, which is how the tx module
+ * distinguishes /tx/r4 from /tx/r5.
+ */
+class ModuleStats {
+
+  constructor(parent, module) {
+    this.parent = parent;
+    this.module = module;
+  }
+
+  countRequest(name, tat, endpoint = NO_ENDPOINT) {
+    this.parent.countRequest(name, tat, this.module, endpoint);
+  }
+
+  addTask(name, frequency) { this.parent.addTask(name, frequency); }
+  task(name, state) { this.parent.task(name, state); }
+  taskDone(name, state) { this.parent.taskDone(name, state); }
+  taskError(name, state) { this.parent.taskError(name, state); }
+
+  // Pass-throughs for the handful of properties modules read off the stats
+  // object. These have to be getters, not copies, or a module would capture
+  // the value at construction time and never see it change.
+  get cachingModules() { return this.parent.cachingModules; }
+  get requestCount() { return this.parent.requestCount; }
+  get staticRequestCount() { return this.parent.staticRequestCount; }
+  get history() { return this.parent.history; }
+  get startTime() { return this.parent.startTime; }
+}
 
 class ServerStats {
   started = false;
@@ -16,13 +59,53 @@ class ServerStats {
   timer;
   cachingModules = [];
   taskMap = new Map();
+  // key (module/endpoint/operation) -> counter. See countRequest().
+  counters = new Map();
+  db = null;
 
-  constructor() {
+  constructor(config, log) {
+    this.config = config || {};
+    this.log = log || console;
+    if (this.config.intervalMinutes) {
+      this.intervalMs = this.config.intervalMinutes * 60 * 1000;
+    }
+    this.openDatabase();
     this.timer = setInterval(() => {
       this.recordMetrics();
     }, this.intervalMs);
   }
 
+  /**
+   * Open the persistent counter store and pick up where the last run of the
+   * server left off. Statistics must never be the reason the server won't
+   * start, so a failure here is logged and then ignored: the counters carry
+   * on in memory, they just don't survive the next restart.
+   */
+  openDatabase() {
+    if (this.config.enabled === false) {
+      return;
+    }
+    try {
+      this.db = new StatsDatabase(this.config, this.log).open();
+      for (const row of this.db.loadTotals()) {
+        const counter = this.counterFor(row.module, row.endpoint, row.operation);
+        counter.countTotal = row.countTotal;
+        counter.timeTotal = row.timeTotal;
+      }
+    } catch (e) {
+      this.log.error(`Unable to open the statistics database: ${e.message}. Statistics will not be persisted`);
+      this.db = null;
+    }
+  }
+
+  /**
+   * A view of the statistics that attributes everything counted through it to
+   * the named module (see ModuleStats).
+   */
+  forModule(module) {
+    return new ModuleStats(this, module);
+  }
+
   recordMetrics() {
     if (this.started) {
       const now = Date.now();
@@ -61,9 +144,12 @@ class ServerStats {
       this.requestTime = 0;
       this.lastTime = now;
 
-      // Prune old data (keep 24 hours)
+      // Prune old data (keep 24 hours). Only the in-memory history is pruned -
+      // the per-endpoint counters are persisted and kept indefinitely.
       const cutoff = now - (24 * 60 * 60 * 1000); // 24 hours ago
       this.history = this.history.filter(m => m.time > cutoff);
+
+      this.flushCounters(now, this.intervalMs);
     }
   }
 
@@ -77,11 +163,78 @@ class ServerStats {
     this.recordMetrics();
   }
 
-  countRequest(name, tat) {
-    // we ignore name for now, but we might split the tat tracking up by name
-    // at some stage
+  /**
+   * The counter for one (module, endpoint, operation), created on first use.
+   *
+   * countDelta/timeDelta accumulate within the current interval and are reset
+   * each time they're written out; countTotal/timeTotal are cumulative for the
+   * life of the database, not the life of the process.
+   */
+  counterFor(module, endpoint, operation) {
+    const key = `${module}\u001f${endpoint}\u001f${operation}`;
+    let counter = this.counters.get(key);
+    if (!counter) {
+      counter = {
+        module: module, endpoint: endpoint, operation: operation,
+        countDelta: 0, timeDelta: 0, countTotal: 0, timeTotal: 0
+      };
+      this.counters.set(key, counter);
+    }
+    return counter;
+  }
+
+  /**
+   * Count one request. Modules go through their own ModuleStats, which fills
+   * in module (and, for tx, the endpoint) for them.
+   *
+   * @param {string} name - the operation, e.g. '$expand' or 'login'
+   * @param {number} tat - turnaround time in ms
+   * @param {string} module - the module that served it
+   * @param {string} endpoint - the endpoint within the module, where the
+   *   module has more than one (the tx module does; nothing else does yet)
+   */
+  countRequest(name, tat, module = SERVER_MODULE, endpoint = NO_ENDPOINT) {
     this.requestCount++;
     this.requestTime = this.requestTime + tat;
+
+    const counter = this.counterFor(module || SERVER_MODULE, endpoint || NO_ENDPOINT, name || '(unnamed)');
+    counter.countDelta++;
+    counter.countTotal++;
+    counter.timeDelta = counter.timeDelta + tat;
+    counter.timeTotal = counter.timeTotal + tat;
+  }
+
+  /**
+   * Write out the counters that saw traffic this interval, and start the next
+   * one. The deltas are only cleared if the write succeeded, so a transient
+   * database problem delays the numbers rather than losing them (the interval
+   * they're eventually written against is longer, which is what interval_ms on
+   * the row is for).
+   */
+  flushCounters(now, intervalMs) {
+    if (!this.db) {
+      return 0;
+    }
+    const rows = [];
+    for (const counter of this.counters.values()) {
+      if (counter.countDelta > 0) {
+        rows.push({...counter});
+      }
+    }
+    if (rows.length === 0) {
+      return 0;
+    }
+    try {
+      this.db.write(now, intervalMs, rows);
+    } catch (e) {
+      this.log.error(`Unable to write statistics: ${e.message}`);
+      return 0;
+    }
+    for (const counter of this.counters.values()) {
+      counter.countDelta = 0;
+      counter.timeDelta = 0;
+    }
+    return rows.length;
   }
 
   addTask(name, frequency) {
@@ -144,6 +297,17 @@ class ServerStats {
 
   finishStats() {
     clearInterval(this.timer);
+    // Synchronous, so the last partial interval is on disk before server.js
+    // calls process.exit().
+    this.flushCounters(Date.now(), Date.now() - (this.lastTime || this.startTime));
+    if (this.db) {
+      try {
+        this.db.close();
+      } catch (e) {
+        this.log.error(`Unable to close the statistics database: ${e.message}`);
+      }
+      this.db = null;
+    }
   }
 
   // Live cache aggregates across all registered caching modules (defensive: a
@@ -174,4 +338,6 @@ class ServerStats {
     }
   }
 }
-module.exports = ServerStats;
+module.exports = ServerStats;
+module.exports.ModuleStats = ModuleStats;
+module.exports.SERVER_MODULE = SERVER_MODULE;

package/translations/Messages.properties

@@ -1101,7 +1101,10 @@ Unable_to_resolve_system__value_set_has_multiple_matches = The System URI could
 Unable_to_resolve_system__value_set_has_no_includes_or_expansion = The System URI could not be determined for the code ''{0}'' in the ValueSet ''{1}'': value set has no includes or expansion
 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}'' is not known to this server. Caches are created with $cache-control?mode=start; this one was never created, or has expired or been released
+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_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
 Unable_to_validate_code_without_using_server = Unable to validate code without using server because: {0}
 Undefined_attribute__on__for_type__properties__ = Undefined attribute ''@{0}'' on {1} for type {2}
 Undefined_element_ = Undefined element ''{0}'' at {1}

package/tx/cs/cs-api.js

@@ -404,9 +404,15 @@ class CodeSystemProvider {
    * @param {boolean} [significantOnly=false] - when true, emit only the
    *   designations that are significant for a value set expansion (the display,
    *   and - for code systems that distinguish them - the fully specified name
-   *   and the preferred term), rather than every designation in every language.
-   *   The $expand worker passes true; $lookup uses the default (false) to return
-   *   the complete set. Providers that do not distinguish significant
+   *   and the preferred term), rather than every designation. This narrows which
+   *   designations are emitted, NOT which languages: the display for a request is
+   *   chosen downstream by preferredDesignation(displayLanguage), so a provider
+   *   that emits significant designations for one language only makes localized
+   *   expansions fall back to that language. Emit the significant designations
+   *   for every language the concept has.
+   *   The $expand worker passes true when the client did not ask for
+   *   designations; $lookup and includeDesignations=true use the default (false)
+   *   to return the complete set. Providers that do not distinguish significant
    *   designations may ignore this parameter and return all designations either
    *   way.
    * @returns {Designation[]} whatever designations exist (in all languages)