[tipatterson-dev]

Publishes CS API Part 3 Resource Events (CloudEvents 1.0 JSON) when a system, subsystem, datastream or control stream is created, updated or deleted.

Closes #254. Part of #249.

Stacked on #263 (AsyncAPI, #256) (base feature/cs-api-mqtt/256-asyncapi-service-desc). Merge #261 and #263 first.

Changes

• TopicMapper accepts Resource Event topics (no :data):
  • {nodeId}/systems/{id} (top-level systems)
  • {nodeId}/{systemPath}/subsystems/{id}
  • {nodeId}/{systemPath}/datastreams/{id}
  • {nodeId}/{systemPath}/controlstreams/{id}
• New ResourceEventPublisher:
  • One subscription to the osh-core system registry topic.
  • Each event goes on the designated topic of its resource only, with the full {systemPath}.
  • type is org.ogc.api.csapi.{system|datastream|controlstream}.{create|update|delete}. source is the API root. subject and resourceparent are the canonical HTTP URLs (for example {apiRoot}/datastreams/42), not the topic path. Each event has a new id. No data member.
  • A deleted subsystem keeps its topic and parent: they come from the delete event, because the system is no longer in the database.
• CsApiMqttConnector:
  • A subscription to an event topic is accepted only if the resource exists and the user can read it (a GET by ID through the CS API, as the user).
  • Client publications to event topics are rejected as not authorized.
• AsyncAPI description: four event channels, a CloudEvents payload schema, and the type values of each channel. Messages are application/cloudevents+json.
• README: Resource Events section, status, and known limits.

osh-core issues found

• A new subsystem's SystemAddedEvent carries the parent's internal ID. The publisher works around it by looking the subsystem up by UID. Without this, create events went to .../subsystems/{parentId}.
• An in-place system update (no new validTime) publishes no SystemChangedEvent, so no update event is sent.
• A cascade delete of a system publishes no events for its datastreams and control streams.
• PUT /datastreams/{id} fails with HTTP 500 on the in-memory state database, so datastream updates could not be tested live.

These are listed as known limits in the README and AsyncAPI description, and will be filed against osh-core.

Not included

• Enable and disable events are not mapped; Part 3 has only create, update and delete.
• Other resource types (observations, commands, sampling features, deployments, ...) need osh-core changes first. Part 3 allows a server to publish events for some types, if the service description lists them.
• Wildcard subscriptions (consys-mqtt: accept wildcard subscriptions #255) and batch events (consys-mqtt: publish Batch Resource Events for observations #258) build on this PR.

Testing

• TestTopicMapper: event topic templates and rejected topics.
• TestResourceEventPublisher: topic, subject and parent for top-level systems, nested subsystems (create and delete), datastreams and control streams; the CloudEvent JSON; events with no Resource Event; publish and stop.
• TestAsyncApiHandler: event channels, media type and event types.
• On a test node with CS API access control on:
  • system create, update (new validTime) and delete; subsystem create and delete; datastream create and delete; control stream create: each event on the right topic, with flat subject and resourceparent, retain false
  • anonymous subscribe: not authorized; subscribe to an unknown ID: rejected; client publish to an event topic: not authorized
  • the AsyncAPI document passes the structure check (14 channels, 17 operations, 11 messages)

Stack

1. csapi-mqtt: Part 3 topic scheme (new module, 0.1.0) #261 Part 3 topic scheme
2. csapi-mqtt: AsyncAPI service description #263 AsyncAPI service description
3. This PR