Allow grouping topics across multiple broker clusters

[lwielek]

Scenario
A single application connects to 2 (or more) broker clusters.
It publishes/subscribes to topics maintained by both broker clusters.
Topics are not being shared among brokers - a topic that exists on broker 1, does not exist on broker 2.

Problem
It is not possible to document the application's APIs in a single Async-API specification.
From the spec, it is not possible to know, which topic is maintained on which broker cluster.

Proposal
Extend the specification with 2 additional fields.

• server.group (string) - all servers that belong to a single cluster can be identifier by the group (cluster) name. Optional field. If not present, the server is assigned to a default group.
• topic.serverGroup (string) - the broker group (cluster) name, where the topic exists. Optional field. If not present, the default group is assumed.

Example:

servers:
  - url: api.streetlights.smartylighting.com:1234
    scheme: mqtt
    description: API broker
    group: api
  - url: audit.streetlights.smartylighting.com:1234
    scheme: mqtt
    description: Audit broker
    group: audit
  
topics:
  event.{streetlightId}.lighting.measured:
    serverGroup: api
    publish:
      $ref: '#/components/messages/lightMeasured'
  event.lighting.audit:
    serverGroup: audit
    publish:
      $ref: '#/components/messages/auditMessage'

Workaround
Possible workaround is to create 2 separate specifications - separate for broker 1 topics, and broker 2 topics.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

I'm paying out with websocket atm. I have an API that has 2 different connection points, we can call it private and public. One server is opened, and the other one is secured with token. As typical Websocket, there is one channel, one endpoint. There are messages in the API that can go only to private server.

So I don't even need to wire a topic (channel) with the server, but actually a message with the server.

Possible mitigation, I can have 2 AsyncAPI files of course that share messages/schemas with $ref. Nevertheless would be nice to look more into the subject

[derberg]

possible with AsyncAPI 2.2 🥳