fhirsmith 0.14.0 → 0.14.2

package/testing/openapi.js

@@ -0,0 +1,15 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+// The testing module's OpenAPI description: openapi.yaml (the paths, written by hand) plus
+// openapi-schemas.json (the FHIR resource schemas, generated from the R5 StructureDefinitions
+// by utilities/generate-openapi-schemas.js - see openapi-schemas.config.js).
+
+const path = require('path');
+const { createOpenApiDoc } = require('../library/openapi-doc');
+
+module.exports = createOpenApiDoc(path.join(__dirname, 'openapi.yaml'), '/testing',
+  { schemasPath: path.join(__dirname, 'openapi-schemas.json') });

package/testing/openapi.yaml

@@ -0,0 +1,273 @@
+# OpenAPI description of the FHIRsmith testing module (/testing): a FHIR API for TestReports.
+#
+# The paths are maintained here by hand. The FHIR resource schemas (TestReport,
+# OperationOutcome, Bundle, the datatypes they use, and TestReportSearchBundle) are generated
+# from the R5 StructureDefinitions into openapi-schemas.json, and merged into
+# components.schemas when the spec is served - see openapi-schemas.config.js.
+#
+# tests/testing/openapi.test.js keeps this honest: every route must be described here or
+# explicitly excluded, the search parameters must be the ones search.js understands, and
+# the TestReport schema must require everything validateReport() in testing.js requires.
+#
+# Administrative routes (DELETE, the login and admin pages) are deliberately not described.
+# info.version is filled in from package.json when the spec is served.
+
+openapi: 3.1.0
+info:
+  title: FHIRsmith Test Reports
+  version: "0.0.0"
+  summary: A FHIR repository for TestReports
+  description: |
+    Receives FHIR TestReports - from TxTester, and from any other tool that produces them -
+    and makes them available for reading and searching. This is a small FHIR R5 server with
+    one resource type, TestReport, and three interactions: create, read and search.
+
+    * **R4 and R5** TestReports are accepted alike (they differ only in `testScript`).
+    * **Reports are immutable**: the server assigns the id and `meta.lastUpdated`, drops
+      `meta.versionId`, and each POST is a new report, even of the same report.
+    * **Contained resources are not accepted.**
+    * The server checks only what the TestReport schema marks as required (and that
+      `issued` is a valid dateTime and `score` a number). The schema describes a valid
+      report; reports that don't conform to it in other ways may still be accepted, but
+      shouldn't be sent.
+
+    **Content negotiation.** Read and search return an HTML page to a browser (an
+    `Accept` containing `text/html`); `_format=json` or `_format=html` overrides that.
+  license:
+    name: BSD-3-Clause
+    url: https://opensource.org/license/bsd-3-clause
+externalDocs:
+  description: The TestReport resource (FHIR R5)
+  url: https://hl7.org/fhir/R5/testreport.html
+servers:
+  - url: /testing
+
+paths:
+  /TestReport:
+    post:
+      tags: [TestReport]
+      operationId: createTestReport
+      summary: Submit a report
+      description: |
+        Stores the report and returns it with its new id and `meta.lastUpdated`. Reports
+        are limited in size (500 KB by default) and submissions are rate limited.
+
+        If the server is configured with a token, every submission must carry it, in the
+        `Authorization` header by default (`Bearer <token>`; the header is configurable).
+      security:
+        - {}
+        - submitToken: []
+      parameters:
+        - name: Prefer
+          in: header
+          description: '`return=minimal` (no body), `return=representation` (the default), or `return=OperationOutcome`.'
+          schema: { type: string }
+          example: return=minimal
+      requestBody:
+        required: true
+        content:
+          application/fhir+json:
+            schema: { $ref: '#/components/schemas/TestReport' }
+          application/json:
+            schema: { $ref: '#/components/schemas/TestReport' }
+      responses:
+        '201':
+          description: Stored. The body is the stored report, nothing, or an OperationOutcome, as `Prefer` asks.
+          headers:
+            Location:
+              description: The new report's URL
+              schema: { type: string, format: uri }
+            Last-Modified:
+              schema: { type: string }
+          content:
+            application/fhir+json:
+              schema:
+                anyOf:
+                  - $ref: '#/components/schemas/TestReport'
+                  - $ref: '#/components/schemas/OperationOutcome'
+        '400': { $ref: '#/components/responses/Invalid' }
+        '401':
+          description: A token is required and wasn't supplied, or is wrong
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '413':
+          description: The report is too big
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '415':
+          description: The body isn't JSON
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '429':
+          description: Too many submissions; try again later
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+
+    get:
+      tags: [TestReport]
+      operationId: searchTestReports
+      summary: Search reports
+      description: |
+        Returns a searchset Bundle, newest received first unless `_sort` says otherwise.
+        `total` is always present.
+
+        Comma separated values are ORed; repeated parameters are ANDed. The search
+        parameters aren't yet formally defined as SearchParameter resources; their
+        behaviour is as described here. Modifiers are written after the name
+        (`name:exact=...`).
+
+        Unknown parameters are ignored, with a warning OperationOutcome entry
+        (`search.mode = outcome`) in the Bundle - unless the request has
+        `Prefer: handling=strict`, when they're a 400. Values that can't be understood (a
+        bad date or number) are always a 400.
+      parameters:
+        - name: _id
+          in: query
+          description: The report's id.
+          schema: { type: string }
+        - name: name
+          in: query
+          description: '`name` starts with this, case-insensitively. Modifiers: `:exact`, `:contains`, `:missing`.'
+          schema: { type: string }
+          example: tx-ecosystem
+        - name: tester
+          in: query
+          description: '`tester` starts with this, case-insensitively. Modifiers: `:exact`, `:contains`, `:missing`.'
+          schema: { type: string }
+        - name: status
+          in: query
+          description: '`status`, exactly (a `system|` prefix is ignored). Modifiers: `:not`, `:missing`.'
+          schema: { type: string }
+          example: completed
+        - name: result
+          in: query
+          description: '`result`, exactly. Modifiers: `:not`, `:missing`.'
+          schema: { type: string }
+          example: fail
+        - name: testscript
+          in: query
+          description: '`testScript` (the R5 canonical, or the R4 reference), exactly. Modifiers: `:below` (starts with), `:missing`.'
+          schema: { type: string }
+        - name: participant
+          in: query
+          description: 'The `uri` of any participant, exactly. Modifier: `:below` (starts with).'
+          schema: { type: string }
+          example: http://tx.fhir.org/r4
+        - name: score
+          in: query
+          description: '`score`, with a prefix (`eq` `ne` `gt` `lt` `ge` `le` `sa` `eb` `ap`); `eq` has implicit precision (`90` means 89.5 to 90.5). Modifier: `:missing`.'
+          schema: { type: string }
+          example: ge90
+        - name: issued
+          in: query
+          description: '`issued`, with a prefix; dates are ranges (`issued=2026-09` is all of September).'
+          schema: { type: string }
+          example: ge2026-09
+        - name: _lastUpdated
+          in: query
+          description: When the report was received, with a prefix.
+          schema: { type: string }
+        - name: _sort
+          in: query
+          description: Any of the parameters above except `_id`, comma separated, `-` for descending.
+          schema: { type: string }
+          example: -issued
+        - name: _count
+          in: query
+          description: Page size; defaults to 50, at most 500. `0` returns just the total.
+          schema: { type: integer, minimum: 0, maximum: 500 }
+        - name: _offset
+          in: query
+          description: Where the page starts. The Bundle has first, previous, next and last links.
+          schema: { type: integer, minimum: 0 }
+        - name: _summary
+          in: query
+          description: '`count` returns just the total.'
+          schema: { type: string, enum: [count] }
+        - name: _format
+          in: query
+          description: '`json` or `html`, overriding the `Accept` header.'
+          schema: { type: string }
+        - name: _total
+          in: query
+          description: Accepted, and has no effect - the total is always returned.
+          schema: { type: string }
+        - name: _pretty
+          in: query
+          description: Accepted, and has no effect - responses are always indented.
+          schema: { type: string }
+        - name: Prefer
+          in: header
+          description: '`handling=strict` makes unknown parameters an error.'
+          schema: { type: string }
+      responses:
+        '200':
+          description: The matching reports
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/TestReportSearchBundle' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/Invalid' }
+
+  /TestReport/{id}:
+    get:
+      tags: [TestReport]
+      operationId: readTestReport
+      summary: Read a report
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: The report, or a rendering of it for a browser
+          headers:
+            Last-Modified:
+              schema: { type: string }
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/TestReport' }
+            text/html:
+              schema: { type: string }
+        '404':
+          description: No such report
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+
+  /metadata:
+    get:
+      tags: [server]
+      operationId: capabilities
+      summary: The server's CapabilityStatement
+      description: |
+        Lists the interactions and search parameters. The search parameters have no
+        definitions (see the search operation for what they do).
+      responses:
+        '200':
+          description: A CapabilityStatement
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/AnyResource' }
+
+components:
+  securitySchemes:
+    submitToken:
+      type: http
+      scheme: bearer
+      description: |
+        Required for submitting reports if the server is configured with a token. Sent in the
+        `Authorization` header by default; a server can be configured to use another header.
+
+  responses:
+    Invalid:
+      description: The request isn't acceptable - the issues say why
+      content:
+        application/fhir+json:
+          schema: { $ref: '#/components/schemas/OperationOutcome' }

package/testing/readme.md

@@ -13,7 +13,9 @@ makes them available through a FHIR API and a set of web pages. It runs at `/tes
 R4 and R5 TestReports are treated the same. A report is accepted if it is JSON, has
 `resourceType: TestReport`, and has `name`, `status`, `result`, `tester`, `issued` (a valid
 dateTime) and at least one `participant` with a `uri`. `score`, if present, must be a number.
-Nothing else is checked.
+Contained resources are not accepted. Nothing else is checked - but the TestReport schema in
+the OpenAPI description (below) says what a valid report looks like, and reports should
+conform to it.
 
 The server gives the report a new id (any id sent is ignored), sets `meta.lastUpdated` to the
 time it was received, and drops `meta.versionId`: reports can't be changed once received, so
@@ -65,6 +67,46 @@ Unknown parameters are ignored, with a warning OperationOutcome in the Bundle, u
 request has `Prefer: handling=strict`, in which case they're a 400. Values that can't be
 understood (a bad date or number) are always a 400.
 
+## OpenAPI description
+
+The FHIR API (create, read, search, metadata) is described by an OpenAPI 3.1 spec:
+
+| URL | |
+|---|---|
+| `/testing/openapi` | Browsable reference (HTML), with a "try it" form for each GET operation |
+| `/testing/openapi.json` | The spec as JSON |
+| `/testing/openapi.yaml` | The hand-written part, as YAML ([openapi.yaml](openapi.yaml)) |
+
+Every response carries a `Link: </testing/openapi.json>; rel="service-desc"` header (RFC 8631),
+and the HTML pages carry the matching `<link>` element. Deleting reports and the
+administration pages are deliberately not described.
+
+The spec is in two parts:
+
+* [openapi.yaml](openapi.yaml) - the paths, parameters and responses, written by hand
+* [openapi-schemas.json](openapi-schemas.json) - the FHIR schemas (TestReport, Bundle,
+  OperationOutcome, the datatypes they use, and `TestReportSearchBundle`), generated from the R5
+  StructureDefinitions by `library/fhir-openapi-schema.js`, as configured in
+  [openapi-schemas.config.js](openapi-schemas.config.js). The loader merges them into the spec.
+
+The generated schemas are closed (no properties FHIR doesn't define), include the `_x`
+siblings of primitive elements (so extensions on primitives, like `_name`, are allowed), and
+use the codes of required bindings as enums. Recursion is cut at two boundaries: an extension's
+value isn't described, and a resource inside another (`Bundle.entry.resource`) is "any resource"
+unless the config narrows it. `contained` is left out, so it isn't allowed. The config's overlay
+adds what this server requires beyond the base resource, and lets `testScript` be an R4
+Reference.
+
+After changing the config, regenerate (this needs `hl7.fhir.r5.core#5.0.0` in the
+terminology cache):
+
+    node utilities/generate-openapi-schemas.js testing
+
+`tests/testing/openapi.test.js` fails if the generated file is out of date, if a route or search
+parameter isn't described (or excluded), or if the TestReport schema doesn't require everything
+`validateReport()` requires. It also validates what the server actually returns (a stored
+report, a search Bundle, an OperationOutcome) against the schemas, using ajv.
+
 ## Web pages
 
 * `/testing` - the list of reports, with filters (these map onto the search parameters above),
@@ -78,6 +120,38 @@ Everything in a report comes from whoever sent it, so all of it is escaped, and
 URLs become links. The narrative (`text.div`) is never rendered as HTML - it appears only as
 text in the raw JSON.
 
+## What the pages show
+
+The list has a column each for the test engine, client and server participants (the client
+column only appears once some report has a client; a participant of any other type is shown
+as a server). **Tests** is the number of entries in `TestReport.test`. **Run Length** is how long the run took, from the earliest `test.period.start`
+to the latest `test.period.end`; it is blank when the report's tests have no periods. Both are
+worked out when the report is received, and for reports received before they existed, the
+first time the server starts with this version.
+
+Where a test script or participant URL, ignoring any `|version`, is one of the **named
+links**, its name is shown instead of the URL - linked to the named link's link, with the
+full URL in the tooltip and the version after the name.
+
+## Administration
+
+`/testing/login`. The administrator logs in as `admin` with the `adminPassword` from the
+configuration, and manages the other users at `/testing/admin/users`. A user can have either
+or both of two rights:
+
+* **edit named links** - `/testing/admin/links`: the canonical URLs that are shown by name
+* **delete reports** - a Delete button on each report's page
+
+Logins work as the publisher's do: a session cookie (set `sessionSecret`, and `cookieSecure:
+false` if the server is reached over plain http), bcrypt password hashes, and a rate limited
+login (`loginAttemptsPerWindow`, default 20 per 15 minutes). Rights are checked on every
+request, so changing or deleting a user takes effect at once. Every form post must come from
+the server's own pages: each form carries a per-session CSRF token (lusca) that the post must
+return, the cookie is SameSite=Lax, and a post whose `Origin` is another host is refused
+(behind a proxy, that needs the proxy to pass on `Host` or `X-Forwarded-Host`). The session
+and CSRF checks are only on the web pages: the FHIR API is authenticated by the header
+token, and sets no cookie.
+
 ## Deleting
 
     DELETE /testing/TestReport/{id}