From 7093d999003d2f25c5d8fa72358bfb95e1327f3b Mon Sep 17 00:00:00 2001 From: Heiko Henning Date: Tue, 30 Jan 2024 17:47:14 +0100 Subject: [PATCH] feat: solace add per operation fields (#237) Co-authored-by: Cameron Rushton --- solace/README.md | 137 ++++++++++++++++++++++++++++++----------------- 1 file changed, 88 insertions(+), 49 deletions(-) diff --git a/solace/README.md b/solace/README.md index 56d1a404..da5b8061 100644 --- a/solace/README.md +++ b/solace/README.md @@ -6,17 +6,17 @@ This document defines how to describe Solace-specific information with AsyncAPI. ## Version -Current version is `0.3.0`. +Current version is `0.4.0`. ## Server Binding Object -Field Name | Type | Description ----|---|--- -`bindingVersion`|String|The current version is 0.3.0 -`msgVpn`|String|The Virtual Private Network name on the Solace broker. - +| 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. | @@ -32,17 +32,21 @@ This object MUST NOT contain any properties. Its name is reserved for future use We need the ability to support several bindings for each operation, see the [Example](#example) section below for details. -Field Name | Type | Description ----|---|--- -`bindingVersion`|String|The current version is 0.3.0 -`destinations`|List of Destination Objects|Destination Objects are described next. +| 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][schemaObject] \| [Reference Object][referenceObject] | Interval in milliseconds or a *Schema Object* containing the definition of the lifetime of the message. | +| `priority` | Integer \| [Schema Object][schemaObject] \| [Reference Object][referenceObject] | 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.](https://docs.solace.com/Get-Started/Core-Concepts-Message-Delivery-Modes.htm) Default is 'persistent'. | | `queue.name` | String | The name of the queue, only applicable when destinationType is 'queue'. | @@ -87,25 +91,34 @@ components: $ref: '#/components/schemas/Person' schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0 contentType: application/json -channels: - 'person/{personId}/{eventType}': - publish: - bindings: - solace: - bindingVersion: 0.3.0 - destinations: - - destinationType: queue - queue: - name: CreatedHREvents - topicSubscriptions: +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: + - destinationType: queue + queue: + name: UpdatedHREvents + topicSubscriptions: - person/*/updated - message: - $ref: '#/components/messages/PersonEvent' + timeToLive: 5000 + priority: 120 + dmqEligible: true + +channels: + person: + address: person/{personId}/{eventType} parameters: personId: schema: @@ -113,13 +126,16 @@ channels: eventType: schema: type: string -asyncapi: 2.4.0 + messages: + personEvent: + $ref: '#/components/messages/PersonEvent' +asyncapi: 3.0.0 info: title: HRApp version: 0.0.1 ``` -The expected behaviour would be that the application binds to both queues, and each queue has its own topic subscription, one to created and one to updated events. +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 ## @@ -130,34 +146,57 @@ This example shows how a client could receive all the topics under `person/` usi components: schemas: Person: - type: string + type: string messages: PersonEvent: payload: - $ref: '#/components/schemas/Person' - schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0 + schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0 + schema: + $ref: '#/components/schemas/Person' contentType: application/json -channels: - 'person/{personId}/{eventType}': - publish: - bindings: - solace: - bindingVersion: 0.3.0 - destinations: - - destinationType: topic +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/> - message: - $ref: '#/components/messages/PersonEvent' + - 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 + description: The machine readable id of the person eventType: - schema: - type: string -asyncapi: 2.4.0 + enum: + - create + - delete + messages: + personEvent: + $ref: '#/components/messages/PersonEvent' +asyncapi: 3.0.0 info: title: HRApp version: 0.0.1 ``` + +[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject +[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject