[tipatterson-dev]

Serves an AsyncAPI 3.0 description of the MQTT binding, as CS API Part 3 and OGC API Pub/Sub discovery ask.

Closes #256. Part of #249.

Stacked on #261 (base feature/cs-api-mqtt/250-topic-scheme). Merge #261 first; this PR then moves to master.

Changes

• New AsyncApiHandler at {apiRoot}/asyncapi/mqtt, one document per binding.
  • f=yaml or application/asyncapi+yaml gives YAML. Other clients get YAML by default.
  • A browser, or f=html, gets an HTML page. It loads the AsyncAPI viewer from a CDN and shows the YAML text if the viewer cannot load (5 s timeout, load error, or no viewer URL).
  • Other formats give 400.
• The document is a template (asyncapi-mqtt.yaml) filled per request: nodeId, API root, module version, servers, and the format names of the node.
• Servers come from config:
  • brokerAddress (default: the HTTP host and port 1883, the port of the bundled HiveMQ config)
  • webSocketAddress (optional; ws:// or wss://, with a path)
  • asyncApiViewerUrl (default @asyncapi/react-component 3.2.2 on unpkg; empty means YAML text only)
• Each server is listed for MQTT 5 and MQTT 3.1.1.
• README: setup fields, the service description, and its known limits.

Known limits

• The CS API landing page does not link to the document yet. That needs an osh-core change (a shared /asyncapi container and service-desc links).
• The HTML page has no DOCTYPE, like the CS API pages: OSH serves /static CSS as application/json, which browsers accept only in quirks mode.
• The module cannot read the HiveMQ settings, so the delivery settings stated are those of the bundled config. Authentication is not stated.
• YAML and HTML only, no JSON.

Testing

• TestAsyncApiHandler: rendering, TCP and WebSocket servers, live config changes, HTML page and escaping, format selection.
• On a test node: the YAML passes a structure check (refs resolve, channel parameters match addresses, servers and bindings valid). The HTML page renders with the CDN viewer, and falls back to the YAML text with the CDN blocked and with no viewer URL.

Stack

1. csapi-mqtt: Part 3 topic scheme (new module, 0.1.0) #261 Part 3 topic scheme
2. This PR
3. csapi-mqtt: Resource Events for systems, datastreams and control streams #264 Resource Events, based on this branch

[alexrobin]

@tipatterson-dev Can you resolve these merge conflicts?

[tipatterson-dev]

@alexrobin yes, I'll fix it. I thought I had them all sorted to be clean. I'll fix what I missed on this one.

[tipatterson-dev]

I think that each PR will end up with conflicts because of the squash commit.

I have a few options. I can fix them one at a time, we can use a merge commit for the stack each time, or I can re-target this all into a branch where the PRs can be reviewed as is and there is a merge commit each time then we can merge that into master and squash it.