README.md

Solace Bindings

This document defines how to describe Solace-specific information with AsyncAPI.

Version

Current version is 0.4.0.

Server Binding Object

Field Name	Type	Description
bindingVersion	String	The current version is 0.4.0
msgVpn	String	The Virtual Private Network name on the Solace broker.
clientName	String	A unique client name to use to register to the appliance. If specified, it must be a valid Topic name, and a maximum of 160 bytes in length when encoded as UTF-8.

Channel Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Operation Binding Object

We need the ability to support several bindings for each operation, see the Example section below for details.

Field Name	Type	Description
bindingVersion	String	The current version is 0.4.0
destinations	List of Destination Objects	Destination Objects are described next.
timeToLive	Integer | Schema Object | Reference Object	Interval in milliseconds or a Schema Object containing the definition of the lifetime of the message.
priority	Integer | Schema Object | Reference Object	The valid priority value range is 0-255 with 0 as the lowest priority and 255 as the highest or a Schema Object containing the definition of the priority.
dmqEligible	Boolean	Set the message to be eligible to be moved to a Dead Message Queue. The default value is false.

Destination Object

Each destination has the following structure:

Field Name	Type	Description
bindingVersion	String	The current version is 0.4.0
destinationType	Enum	'queue' or 'topic'. If the type is queue, then the subscriber can bind to the queue, which in turn will subscribe to the topic as represented by the channel name or to the provided topicSubscriptions.
deliveryMode	Enum	'direct' or 'persistent'. This determines the quality of service for publishing messages as documented here. Default is 'persistent'.
queue.name	String	The name of the queue, only applicable when destinationType is 'queue'.
queue.topicSubscriptions	List of String	A list of topics that the queue subscribes to, only applicable when destinationType is 'queue'. If none is given, the queue subscribes to the topic as represented by the channel name.
queue.accessType	Enum	'exclusive' or 'nonexclusive'. This is documented here. Only applicable when destinationType is 'queue'.
queue.maxMsgSpoolSize	String	The maximum amount of message spool that the given queue may use. This is documented here. Only applicable when destinationType is 'queue'.
queue.maxTtl	String	The maximum TTL to apply to messages to be spooled. This is documented here. Only applicable when destinationType is 'queue'.
topic.topicSubscriptions	List of String	A list of topics that the client subscribes to, only applicable when destinationType is 'topic'. If none is given, the client subscribes to the topic as represented by the channel name.

Message Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Example with two destinations

Here is an example of when we could need two Solace destinations.

Imagine a system where there is a schema called Person, and there are topics:

person/{personId}/created

and

person/{personId}/updated

and you have one application that receives both events. We also want each to be on its own queue. The AsyncAPI file could look like this:

components:
  schemas:
    Person:
      type: string        
  messages:
    PersonEvent:
      payload:
        $ref: '#/components/schemas/Person'
      schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0
      contentType: application/json
operations:
  addPerson:
    action: send
    channel:
      $ref: '#/channels/address'
    messages:
      - $ref: '#/channels/address/messages/personEvent'
    bindings:
      solace:
        bindingVersion: 0.4.0
        destinations:
          - destinationType: queue
            queue:
              name: CreatedHREvents
              topicSubscriptions:
                - person/*/created
          - destinationType: queue
            queue:
              name: UpdatedHREvents
              topicSubscriptions:
                - person/*/updated
        timeToLive: 5000
        priority: 120
        dmqEligible: true

channels:
  person:
    address: person/{personId}/{eventType}
    parameters:
      personId:
        schema:
          type: string
      eventType:
        schema:
          type: string
    messages:
      personEvent:
        $ref: '#/components/messages/PersonEvent'
asyncapi: 3.0.0
info:
  title: HRApp
  version: 0.0.1

The expected behavior would be that the application binds to both queues, and each queue has its own topic subscription, one to create and one to updated events.

Example with a wildcard subscription

This example shows how a client could receive all the topics under person/ using a wildcard subscription:

components:
  schemas:
    Person:
      type: string
  messages:
    PersonEvent:
      payload:
        schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
        schema:
          $ref: '#/components/schemas/Person'
      contentType: application/json
operations:
  addPerson:
    action: send
    channel:
      $ref: '#/channels/person'
    messages:
      - $ref: '#/channels/person/messages/personEvent'
    bindings:
      solace:
        bindingVersion: 0.4.0
        destinations:
          - destinationType: queue
            queue:
              name: CreatedHREvents
              topicSubscriptions:
                - person/*/created
          - destinationType: queue
            queue:
              name: UpdatedHREvents
              topicSubscriptions:
                - person/*/updated
        timeToLive: 5000
        priority: 120
        dmqEligible: true

channels:
  person:
    address: person/{personId}/{eventType}
    parameters:
      personId:
        description: The machine readable id of the person
      eventType:
        enum:
          - create
          - delete
    messages:
      personEvent:
        $ref: '#/components/messages/PersonEvent'
asyncapi: 3.0.0
info:
  title: HRApp
  version: 0.0.1