From 7477345b643472ac1855f7a554e3501efd9a0948 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 10 Mar 2021 14:48:05 +0100 Subject: [PATCH 01/37] added Anypoint MQ skeleton --- anypointmq/README.md | 312 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 anypointmq/README.md diff --git a/anypointmq/README.md b/anypointmq/README.md new file mode 100644 index 00000000..8ccd776a --- /dev/null +++ b/anypointmq/README.md @@ -0,0 +1,312 @@ +# Anypoint MQ Bindings + +This document defines how to describe Anypoint MQ-specific information with AsyncAPI. +[Anypoint MQ](https://docs.mulesoft.com/mq/) is MuleSoft's multi-tenant, cloud messaging service and is fully integrated with [Anypoint Platform](https://www.mulesoft.com/platform/enterprise-integration). + + + +## Version + +Current version is `0.0.1`. + +## Terminology + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). + +## AsyncAPI considerations + +This specification binding builds on the use of the `anypointmq` protocol within the AsyncAPI specification to allow connections to Anypoint MQ messaging brokers to be defined within the server object. + +AsyncAPI Object Fixed Field Name | Reserved Value for Anypoint MQ Protocol | Description +---|:---|:--- +`server.protocol` | `anypointmq` | Anypoint MQ protocol based on the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). + +## URI scheme considerations + +For the purposes of establishing an IBM MQ binding for use within AsyncAPI, this document defines the URI scheme `ibmmq://` consisting of components and generic URI syntax as specified in [RFC3986](https://tools.ietf.org/html/rfc3986) + +### Defining an IBM MQ queue manager endpoint in the server object `url` field + +When defining an IBM MQ `url` for a queue manager endpoint, the `ibmmq://` URI scheme MUST be used. IBM MQ URIs are defined using the following components. + +URI Component | IBM MQ reference | Applicability | Description | +---|:---|:--|:-- +`scheme` | `ibmmq://` | REQUIRED | The URI scheme used to represent an IBM MQ endpoint. +`authority` | `:port` | REQUIRED | The network IP address or hostname and port of the queue manager endpoint. | +`path` | `queueManager` | OPTIONAL | The queue manager name. If no queue manager name is specified this segment is left undefined, for example `ibmmq://hostname:{port}//CHANNEL.NAME` +`path` | `mqChannelName` | REQUIRED | The `SVRCONN` channel to use for communication with an IBM MQ queue manager. When connecting to a queue manager, IBM MQ partitions this communication into logical channels. + +URI `query` or `fragment` components MUST NOT be used within the `ibmmq://` scheme. Path components that contain characters reserved by RFC2936 such as `/` MUST be percent encoded as defined in [Section 2.2 of RFC2936](https://tools.ietf.org/html/rfc3986#section-2.2). `port` MUST be specified as part of the authority component in the `ibmmq://` scheme. + + +### Defining IBM MQ queue manager endpoints with the AsyncAPI Server Object + +This section defines the convention for how IBM MQ queue manager endpoints are encoded within the AsyncAPI Server Object fields. A `groupId` field has been made available on the IBM MQ AsyncAPI server binding object to allow server objects to be defined as a related collection. This is necessary to group, or cluster, IBM MQ queue manager endpoints within the AsyncAPI specification and where a Client Channel Definition Table ([CCDT](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.con.doc/q132905_.html)) reference is not appropriate. + + +##### Example of two possible MQ servers defined using ibmmq url syntax +```yaml +servers: + production1: + url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN + protocol: ibmmq + production2: + url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN + protocol: ibmmq +``` + +##### Example of single MQ server defined using ibmmq url syntax and with no queue manager name specified +```yaml +servers: + production: + url: ibmmq://qmgr1host:1414//DEV.APP.SVRCONN + protocol: ibmmq +``` + +## Defining an IBM MQ queue manager endpoint CCDT in the `url` field +When defining a connection to IBM MQ, a CCDT connection file can be specified. The server url will specify the location of the file with additional information contained within the server binding to specify its usage. + +##### Example using an IBM MQ CCDT file url + +```yaml +servers: + production1: + url: 'http://my-ccdt-json-file' + protocol: ibmmq + production2: + url: 'file://myccdt.json' + protocol: ibmmq +``` + + + +## Server Binding Object + +This object contains server connection information about the IBM MQ server, referred to as an IBM MQ queue manager. This object contains additional connectivity information not possible to represent within the core AsyncAPI specification. + +##### Fixed Fields + + +Field Name | Type | Description | Applicability \[default\] | Constraints +---|:---:|---|:---|:--- +`groupId` | string | Defines a logical group of IBM MQ server objects. This is necessary to specify multi-endpoint configurations used in high availability deployments. If omitted, the server object is not part of a group. | OPTIONAL | MUST NOT be specified for URI Scheme `http://` or `file://` +`ccdtQueueManagerName` | string | The name of the IBM MQ queue manager to bind to in the CCDT file. | OPTIONAL [`*`] | MUST NOT be specified for URI Scheme `ibmmq://` +`cipherSpec` | string | The recommended cipher specification used to establish a TLS connection between the client and the IBM MQ queue manager. More information on SSL/TLS cipher specifications supported by IBM MQ can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.dev.doc/q113220_.html) in the IBM MQ Knowledge Center. | OPTIONAL [`ANY`] | MUST NOT be specified for protocol `ibmmq` or URI Scheme `file://` or `http://` +`multiEndpointServer` | boolean | If `multiEndpointServer` is `true` then multiple connections can be workload balanced and applications should not make assumptions as to where messages are processed. Where message ordering, or affinity to specific message resources is necessary, a single endpoint (`multiEndpointServer` = `false`) may be required. | OPTIONAL [`false`] | MUST NOT be specified for URI Scheme `file://` or `http://` +`heartBeatInterval` | integer | The recommended value (in seconds) for the heartbeat sent to the queue manager during periods of inactivity. A value of zero means that no heart beats are sent. A value of `1` means that the client will use the value defined by the queue manager. More information on heart beat interval can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q108450_.html) in the IBM MQ Knowledge Center. | OPTIONAL [`300`] | MUST be `0-999999` +`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - + +This object MUST contain only the properties defined above. + +##### Example for multiple endpoints defined in the AsyncAPI configuration + +```yaml +servers: + production1: + url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN + protocol: ibmmq-secure + description: Production Instance 1 + bindings: + ibmmq: + groupId: PRODCLSTR1 + cipherSpec: ANY_TLS12_OR_HIGHER + bindingVersion: 0.1.0 + production2: + url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN + protocol: ibmmq-secure + description: Production Instance 2 + bindings: + ibmmq: + groupId: PRODCLSTR1 + bindingVersion: 0.1.0 +``` + +##### Example using combined strategy + +```yaml +servers: + production: + url: 'http://my-ccdt-json-file' + protocol: ibmmq-secure + description: Production MQ Instance + bindings: + ibmmq: + ccdtQueueManagerName: qm1 + test: + url: ibmmq://qmgrtest:1414/qm2/DEV.APP.SVRCONN + protocol: ibmmq-secure + description: Test MQ Instance + bindings: + ibmmq: + cipherSpec: ANY_TLS12_OR_HIGHER + bindingVersion: 0.1.0 +``` + + + +## Channel Binding Object + +This object contains information about the channel representation in IBM MQ. Each channel corresponds to a Queue or Topic within IBM MQ. + +##### Fixed Fields + +Field Name | Type | Description | Applicability [default] | Constraints +---|:---:|---|:---|:--- +`destinationType` | string | Defines the type of AsyncAPI channel. | OPTIONAL [`topic`] | MUST be either `topic` or `queue`. For type `topic`, the AsyncAPI channel name MUST be assumed for the IBM MQ topic string unless overridden. +`queue` | Map[string, any] | Defines the properties of a queue. | REQUIRED if `destinationType` = `queue` | `queue` and `topic` fields MUST NOT coexist within a channel binding +`queue.`
`objectName`
| string | Defines the name of the IBM MQ queue associated with the channel. | REQUIRED | A value MUST be specified. MUST NOT exceed 48 characters in length. MUST be a valid IBM MQ queue name +`queue.`
`isPartitioned`
| boolean | Defines if the queue is a cluster queue and therefore partitioned. If `true`, a binding option MAY be specified when accessing the queue. More information on binding options can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q101870_.html#q101870___BIND_ON_OPEN) in the IBM MQ Knowledge Center. | OPTIONAL [`false`] | If `false`, binding options SHOULD NOT be specified when accessing the queue. +`queue.`
`exclusive`
| boolean | Specifies if it is recommended to open the queue exclusively. | OPTIONAL [`false`] | - +`topic` | Map[string, any] | Defines the properties of a topic. | OPTIONAL if `destinationType` = `topic` | `queue` and `topic` fields MUST NOT coexist within a channel binding. +`topic.`
`string`
| string | The value of the IBM MQ topic string to be used. | OPTIONAL *
Note: if specified, SHALL override AsyncAPI channel name.
* | MUST NOT exceed 10240 characters in length. MAY coexist with `topic.objectName` +`topic.`
`objectName`
| string | The name of the IBM MQ topic object. | OPTIONAL *
Note: if specified, SHALL override AsyncAPI channel name.
*| MUST NOT exceed 48 characters in length. MAY coexist with `topic.string` +`topic.`
`durablePermitted`
| boolean | Defines if the subscription may be durable. | OPTIONAL [`true`] | - +`topic.`
`lastMsgRetained`
| boolean | Defines if the last message published will be made available to new subscriptions. | OPTIONAL [`false`] | - +`maxMsgLength` | integer | The maximum length of the physical message (in bytes) accepted by the Topic or Queue. Messages produced that are greater in size than this value may fail to be delivered. More information on the maximum message length can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.adm.doc/q085520_.html#q085520___maxmsgl) in the IBM MQ Knowledge Center. | OPTIONAL [negotiated on IBM MQ channel]| MUST be `0-104,857,600` bytes (100 MB). +`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - + + +This object MUST contain only the properties defined above. + +##### Example for an IBM MQ Topic where topic string is defined by AsyncAPI channel + +```yaml +channels: + user/signedup: +``` + +##### Example for AsyncAPI channel mapping to an IBM MQ topic with a specified MQ Topic object + +```yaml +channels: + user/signedup: + bindings: + ibmmq: + destinationType: topic + topic: + objectName: myTopicName + bindingVersion: 0.1.0 +``` + +##### Example for AsyncAPI channel mapping to an IBM MQ Queue + +```yaml +channels: + user/signedup: + bindings: + ibmmq: + destinationType: queue + queue: + objectName: myQueueName + exclusive: true + bindingVersion: 0.1.0 +``` + + + + +## Message Binding Object + +This object contains information about the message representation in IBM MQ. + +##### Fixed Fields + +Field Name | Type | Description | Applicability [default] | Constraints +---|:---:|---|:---|:--- +`type` | string | The type of the message. | OPTIONAL [`string`] | MUST be either `string`, `jms` or `binary` +`headers` | string | Defines the IBM MQ message headers to include with this message. More than one header can be specified as a comma separated list. Supporting information on IBM MQ message formats can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q097520_.html) in the IBM MQ Knowledge Center. | OPTIONAL if `type` = `binary` | `headers` MUST NOT be specified if `type` = `string` or `jms` +`description` | string1 | Provides additional information for application developers: describes the message type or format. | OPTIONAL | - +`expiry` | integer | The recommended setting the client should use for the TTL (Time-To-Live) of the message. This is a period of time expressed in milliseconds and set by the application that puts the message. `expiry` values are API dependant e.g., MQI and JMS use different units of time and default values for *`unlimited`*. General information on IBM MQ message expiry can be found on this [page](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q097490_.html) in the IBM MQ Knowledge Center. | OPTIONAL [*`unlimited`*] | `expiry` value MUST be either `zero` (*`unlimited`*) or greater than zero. +`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - + +This object MUST contain only the properties defined above. + +### Rich Text Formatting + +1 The `description` field of the IBM MQ message binding object MAY include CommonMark markdown formatting. A minimum markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/) is assumed. + +##### Example for plain text message + +```yaml +channels: + user/signup: + publish: + message: + bindings: + ibmmq: + type: text + bindingVersion: 0.1.0 +``` + +##### Example for IBM MQ message using JMS + +```yaml +channels: + user/signup: + publish: + message: + bindings: + ibmmq: + type: jms + description: JMS stream message + bindingVersion: 0.1.0 +``` + +# AsyncAPI example with IBM MQ binding + +##### Example for AsyncAPI user signup + +```yaml +asyncapi: 2.0.0 +info: + title: Account Service + version: 1.0.0 + description: This service is in charge of processing user signups +servers: + production1: + url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN + protocol: ibmmq-secure + description: Production Instance 1 + bindings: + ibmmq: + groupId: PRODCLSTR1 + cipherSpec: ANY_TLS12_OR_HIGHER + bindingVersion: 0.1.0 + production2: + url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN + protocol: ibmmq-secure + description: Production Instance 2 + bindings: + ibmmq: + groupId: PRODCLSTR1 + cipherSpec: ANY_TLS12_OR_HIGHER + bindingVersion: 0.1.0 +channels: + user/signedup: + bindings: + ibmmq: + topic: + durablePermitted: true + bindingVersion: 0.1.0 + subscribe: + message: + $ref: '#/components/messages/UserSignedUp' + bindings: + ibmmq: + type: jms + description: JMS bytes message + bindingVersion: 0.1.0 +components: + messages: + UserSignedUp: + payload: + type: object + properties: + displayName: + type: string + description: Name of the user + email: + type: string + format: email + description: Email of the user +``` \ No newline at end of file From 9fbdb65017c4a4defb6c8dcdbad50fb5a2a4924d Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 10 Mar 2021 14:52:00 +0100 Subject: [PATCH 02/37] refined wording --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 8ccd776a..92146163 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -15,7 +15,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## AsyncAPI considerations -This specification binding builds on the use of the `anypointmq` protocol within the AsyncAPI specification to allow connections to Anypoint MQ messaging brokers to be defined within the server object. +This specification binding uses the `anypointmq` protocol in AsyncAPI documents to allow connections to Anypoint MQ messaging brokers to be defined within the `server` object. AsyncAPI Object Fixed Field Name | Reserved Value for Anypoint MQ Protocol | Description ---|:---|:--- From 5057fca9ee9240fc705a4df7241f349917b91c9b Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 11 Mar 2021 18:27:05 +0100 Subject: [PATCH 03/37] draft of server binding object --- anypointmq/README.md | 314 +++--------------- ...ypointmq-server-binding-object.schema.json | 170 ++++++++++ 2 files changed, 213 insertions(+), 271 deletions(-) create mode 100644 anypointmq/anypointmq-server-binding-object.schema.json diff --git a/anypointmq/README.md b/anypointmq/README.md index 92146163..fb48975f 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -1,10 +1,10 @@ # Anypoint MQ Bindings -This document defines how to describe Anypoint MQ-specific information with AsyncAPI. +This document defines how to describe Anypoint MQ-specific information in AsyncAPI documents. + [Anypoint MQ](https://docs.mulesoft.com/mq/) is MuleSoft's multi-tenant, cloud messaging service and is fully integrated with [Anypoint Platform](https://www.mulesoft.com/platform/enterprise-integration). - ## Version Current version is `0.0.1`. @@ -13,300 +13,72 @@ Current version is `0.0.1`. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). -## AsyncAPI considerations - -This specification binding uses the `anypointmq` protocol in AsyncAPI documents to allow connections to Anypoint MQ messaging brokers to be defined within the `server` object. - -AsyncAPI Object Fixed Field Name | Reserved Value for Anypoint MQ Protocol | Description ----|:---|:--- -`server.protocol` | `anypointmq` | Anypoint MQ protocol based on the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). - -## URI scheme considerations - -For the purposes of establishing an IBM MQ binding for use within AsyncAPI, this document defines the URI scheme `ibmmq://` consisting of components and generic URI syntax as specified in [RFC3986](https://tools.ietf.org/html/rfc3986) - -### Defining an IBM MQ queue manager endpoint in the server object `url` field - -When defining an IBM MQ `url` for a queue manager endpoint, the `ibmmq://` URI scheme MUST be used. IBM MQ URIs are defined using the following components. - -URI Component | IBM MQ reference | Applicability | Description | ----|:---|:--|:-- -`scheme` | `ibmmq://` | REQUIRED | The URI scheme used to represent an IBM MQ endpoint. -`authority` | `:port` | REQUIRED | The network IP address or hostname and port of the queue manager endpoint. | -`path` | `queueManager` | OPTIONAL | The queue manager name. If no queue manager name is specified this segment is left undefined, for example `ibmmq://hostname:{port}//CHANNEL.NAME` -`path` | `mqChannelName` | REQUIRED | The `SVRCONN` channel to use for communication with an IBM MQ queue manager. When connecting to a queue manager, IBM MQ partitions this communication into logical channels. +## Protocol -URI `query` or `fragment` components MUST NOT be used within the `ibmmq://` scheme. Path components that contain characters reserved by RFC2936 such as `/` MUST be percent encoded as defined in [Section 2.2 of RFC2936](https://tools.ietf.org/html/rfc3986#section-2.2). `port` MUST be specified as part of the authority component in the `ibmmq://` scheme. +These bindings use the `anypointmq` protocol in AsyncAPI documents to denote connections to Anypoint MQ message brokers. +The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). -### Defining IBM MQ queue manager endpoints with the AsyncAPI Server Object - -This section defines the convention for how IBM MQ queue manager endpoints are encoded within the AsyncAPI Server Object fields. A `groupId` field has been made available on the IBM MQ AsyncAPI server binding object to allow server objects to be defined as a related collection. This is necessary to group, or cluster, IBM MQ queue manager endpoints within the AsyncAPI specification and where a Client Channel Definition Table ([CCDT](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.con.doc/q132905_.html)) reference is not appropriate. - - -##### Example of two possible MQ servers defined using ibmmq url syntax -```yaml -servers: - production1: - url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN - protocol: ibmmq - production2: - url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN - protocol: ibmmq -``` - -##### Example of single MQ server defined using ibmmq url syntax and with no queue manager name specified -```yaml -servers: - production: - url: ibmmq://qmgr1host:1414//DEV.APP.SVRCONN - protocol: ibmmq -``` +## Server Object -## Defining an IBM MQ queue manager endpoint CCDT in the `url` field -When defining a connection to IBM MQ, a CCDT connection file can be specified. The server url will specify the location of the file with additional information contained within the server binding to specify its usage. +The fields of the standard [Server Object](https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#serverObject) are constrained and interpreted as follows: -##### Example using an IBM MQ CCDT file url +- `protocol` is *required* and MUST be `anypointmq` for the scope of this specification. +- `url` is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`), e.g., `https://mq-${REGION_ID}.anypoint.mulesoft.com/api`. MUST NOT use a scheme other than `https` or `http` (as supported by the Broker REST API endpoint). +- `protocolVersion` is *optional* and if present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. Defaults to `v1` if absent. -```yaml -servers: - production1: - url: 'http://my-ccdt-json-file' - protocol: ibmmq - production2: - url: 'file://myccdt.json' - protocol: ibmmq -``` +TODO: +- authentication is by Anypoint MQ client ID and secret, which implies the Anypoint Platform organization ID and environment (ID) +- capture this as security scheme and Security Requirement Object - ## Server Binding Object -This object contains server connection information about the IBM MQ server, referred to as an IBM MQ queue manager. This object contains additional connectivity information not possible to represent within the core AsyncAPI specification. - -##### Fixed Fields - +TODO -Field Name | Type | Description | Applicability \[default\] | Constraints ----|:---:|---|:---|:--- -`groupId` | string | Defines a logical group of IBM MQ server objects. This is necessary to specify multi-endpoint configurations used in high availability deployments. If omitted, the server object is not part of a group. | OPTIONAL | MUST NOT be specified for URI Scheme `http://` or `file://` -`ccdtQueueManagerName` | string | The name of the IBM MQ queue manager to bind to in the CCDT file. | OPTIONAL [`*`] | MUST NOT be specified for URI Scheme `ibmmq://` -`cipherSpec` | string | The recommended cipher specification used to establish a TLS connection between the client and the IBM MQ queue manager. More information on SSL/TLS cipher specifications supported by IBM MQ can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.dev.doc/q113220_.html) in the IBM MQ Knowledge Center. | OPTIONAL [`ANY`] | MUST NOT be specified for protocol `ibmmq` or URI Scheme `file://` or `http://` -`multiEndpointServer` | boolean | If `multiEndpointServer` is `true` then multiple connections can be workload balanced and applications should not make assumptions as to where messages are processed. Where message ordering, or affinity to specific message resources is necessary, a single endpoint (`multiEndpointServer` = `false`) may be required. | OPTIONAL [`false`] | MUST NOT be specified for URI Scheme `file://` or `http://` -`heartBeatInterval` | integer | The recommended value (in seconds) for the heartbeat sent to the queue manager during periods of inactivity. A value of zero means that no heart beats are sent. A value of `1` means that the client will use the value defined by the queue manager. More information on heart beat interval can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q108450_.html) in the IBM MQ Knowledge Center. | OPTIONAL [`300`] | MUST be `0-999999` -`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - - -This object MUST contain only the properties defined above. - -##### Example for multiple endpoints defined in the AsyncAPI configuration +### Example ```yaml servers: - production1: - url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN - protocol: ibmmq-secure - description: Production Instance 1 - bindings: - ibmmq: - groupId: PRODCLSTR1 - cipherSpec: ANY_TLS12_OR_HIGHER - bindingVersion: 0.1.0 - production2: - url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN - protocol: ibmmq-secure - description: Production Instance 2 - bindings: - ibmmq: - groupId: PRODCLSTR1 - bindingVersion: 0.1.0 -``` - -##### Example using combined strategy + development: + url: https://mq-us-east-1.anypoint.mulesoft.com/api + description: Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane + protocol: anypointmq + protocolVersion: v1 -```yaml -servers: production: - url: 'http://my-ccdt-json-file' - protocol: ibmmq-secure - description: Production MQ Instance - bindings: - ibmmq: - ccdtQueueManagerName: qm1 - test: - url: ibmmq://qmgrtest:1414/qm2/DEV.APP.SVRCONN - protocol: ibmmq-secure - description: Test MQ Instance + url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api + description: Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane + protocol: anypointmq + protocolVersion: v1 bindings: - ibmmq: - cipherSpec: ANY_TLS12_OR_HIGHER - bindingVersion: 0.1.0 + anypointmq: + bindingVersion: 0.0.1 + proxy: + host: proxy.corporate.com + port: 80 + username: proxy-user + password: passwd-of-proxy-user + sendBufferSize: 1024 + receiveBufferSize: 2048 + clientTimeout: 1000 + sendTCPWithNoDelay: true + linger: 1000 + keepAlive: true + connectionTimeout: 30000 ``` - ## Channel Binding Object -This object contains information about the channel representation in IBM MQ. Each channel corresponds to a Queue or Topic within IBM MQ. - -##### Fixed Fields - -Field Name | Type | Description | Applicability [default] | Constraints ----|:---:|---|:---|:--- -`destinationType` | string | Defines the type of AsyncAPI channel. | OPTIONAL [`topic`] | MUST be either `topic` or `queue`. For type `topic`, the AsyncAPI channel name MUST be assumed for the IBM MQ topic string unless overridden. -`queue` | Map[string, any] | Defines the properties of a queue. | REQUIRED if `destinationType` = `queue` | `queue` and `topic` fields MUST NOT coexist within a channel binding -`queue.`
`objectName`
| string | Defines the name of the IBM MQ queue associated with the channel. | REQUIRED | A value MUST be specified. MUST NOT exceed 48 characters in length. MUST be a valid IBM MQ queue name -`queue.`
`isPartitioned`
| boolean | Defines if the queue is a cluster queue and therefore partitioned. If `true`, a binding option MAY be specified when accessing the queue. More information on binding options can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q101870_.html#q101870___BIND_ON_OPEN) in the IBM MQ Knowledge Center. | OPTIONAL [`false`] | If `false`, binding options SHOULD NOT be specified when accessing the queue. -`queue.`
`exclusive`
| boolean | Specifies if it is recommended to open the queue exclusively. | OPTIONAL [`false`] | - -`topic` | Map[string, any] | Defines the properties of a topic. | OPTIONAL if `destinationType` = `topic` | `queue` and `topic` fields MUST NOT coexist within a channel binding. -`topic.`
`string`
| string | The value of the IBM MQ topic string to be used. | OPTIONAL *
Note: if specified, SHALL override AsyncAPI channel name.
* | MUST NOT exceed 10240 characters in length. MAY coexist with `topic.objectName` -`topic.`
`objectName`
| string | The name of the IBM MQ topic object. | OPTIONAL *
Note: if specified, SHALL override AsyncAPI channel name.
*| MUST NOT exceed 48 characters in length. MAY coexist with `topic.string` -`topic.`
`durablePermitted`
| boolean | Defines if the subscription may be durable. | OPTIONAL [`true`] | - -`topic.`
`lastMsgRetained`
| boolean | Defines if the last message published will be made available to new subscriptions. | OPTIONAL [`false`] | - -`maxMsgLength` | integer | The maximum length of the physical message (in bytes) accepted by the Topic or Queue. Messages produced that are greater in size than this value may fail to be delivered. More information on the maximum message length can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.adm.doc/q085520_.html#q085520___maxmsgl) in the IBM MQ Knowledge Center. | OPTIONAL [negotiated on IBM MQ channel]| MUST be `0-104,857,600` bytes (100 MB). -`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - - - -This object MUST contain only the properties defined above. - -##### Example for an IBM MQ Topic where topic string is defined by AsyncAPI channel - -```yaml -channels: - user/signedup: -``` - -##### Example for AsyncAPI channel mapping to an IBM MQ topic with a specified MQ Topic object - -```yaml -channels: - user/signedup: - bindings: - ibmmq: - destinationType: topic - topic: - objectName: myTopicName - bindingVersion: 0.1.0 -``` - -##### Example for AsyncAPI channel mapping to an IBM MQ Queue - -```yaml -channels: - user/signedup: - bindings: - ibmmq: - destinationType: queue - queue: - objectName: myQueueName - exclusive: true - bindingVersion: 0.1.0 -``` +TODO +## Operation Binding Object +TODO + ## Message Binding Object -This object contains information about the message representation in IBM MQ. - -##### Fixed Fields - -Field Name | Type | Description | Applicability [default] | Constraints ----|:---:|---|:---|:--- -`type` | string | The type of the message. | OPTIONAL [`string`] | MUST be either `string`, `jms` or `binary` -`headers` | string | Defines the IBM MQ message headers to include with this message. More than one header can be specified as a comma separated list. Supporting information on IBM MQ message formats can be found on this [page](https://www.ibm.com/support/knowledgecenter/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q097520_.html) in the IBM MQ Knowledge Center. | OPTIONAL if `type` = `binary` | `headers` MUST NOT be specified if `type` = `string` or `jms` -`description` | string1 | Provides additional information for application developers: describes the message type or format. | OPTIONAL | - -`expiry` | integer | The recommended setting the client should use for the TTL (Time-To-Live) of the message. This is a period of time expressed in milliseconds and set by the application that puts the message. `expiry` values are API dependant e.g., MQI and JMS use different units of time and default values for *`unlimited`*. General information on IBM MQ message expiry can be found on this [page](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_latest/com.ibm.mq.ref.dev.doc/q097490_.html) in the IBM MQ Knowledge Center. | OPTIONAL [*`unlimited`*] | `expiry` value MUST be either `zero` (*`unlimited`*) or greater than zero. -`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] | - - -This object MUST contain only the properties defined above. - -### Rich Text Formatting - -1 The `description` field of the IBM MQ message binding object MAY include CommonMark markdown formatting. A minimum markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/) is assumed. - -##### Example for plain text message - -```yaml -channels: - user/signup: - publish: - message: - bindings: - ibmmq: - type: text - bindingVersion: 0.1.0 -``` - -##### Example for IBM MQ message using JMS - -```yaml -channels: - user/signup: - publish: - message: - bindings: - ibmmq: - type: jms - description: JMS stream message - bindingVersion: 0.1.0 -``` - -# AsyncAPI example with IBM MQ binding - -##### Example for AsyncAPI user signup - -```yaml -asyncapi: 2.0.0 -info: - title: Account Service - version: 1.0.0 - description: This service is in charge of processing user signups -servers: - production1: - url: ibmmq://qmgr1host:1414/qm1/DEV.APP.SVRCONN - protocol: ibmmq-secure - description: Production Instance 1 - bindings: - ibmmq: - groupId: PRODCLSTR1 - cipherSpec: ANY_TLS12_OR_HIGHER - bindingVersion: 0.1.0 - production2: - url: ibmmq://qmgr2host:1414/qm2/DEV.APP.SVRCONN - protocol: ibmmq-secure - description: Production Instance 2 - bindings: - ibmmq: - groupId: PRODCLSTR1 - cipherSpec: ANY_TLS12_OR_HIGHER - bindingVersion: 0.1.0 -channels: - user/signedup: - bindings: - ibmmq: - topic: - durablePermitted: true - bindingVersion: 0.1.0 - subscribe: - message: - $ref: '#/components/messages/UserSignedUp' - bindings: - ibmmq: - type: jms - description: JMS bytes message - bindingVersion: 0.1.0 -components: - messages: - UserSignedUp: - payload: - type: object - properties: - displayName: - type: string - description: Name of the user - email: - type: string - format: email - description: Email of the user -``` \ No newline at end of file +TODO \ No newline at end of file diff --git a/anypointmq/anypointmq-server-binding-object.schema.json b/anypointmq/anypointmq-server-binding-object.schema.json new file mode 100644 index 00000000..23f86c6a --- /dev/null +++ b/anypointmq/anypointmq-server-binding-object.schema.json @@ -0,0 +1,170 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "http://asyncapi.com/anypointmq/bindings/server.json", + "type": "object", + "title": "Anypoint MQ Server Binding Object", + "examples": [ + { + "bindingVersion": "0.0.1", + "proxy": { + "host": "proxy.corporate.com", + "port": 80, + "username": "proxy-user", + "password": "passwd-of-proxy-user" + }, + "sendBufferSize": 1024, + "receiveBufferSize": 2048, + "clientTimeout": 1000, + "sendTCPWithNoDelay": true, + "linger": 1000, + "keepAlive": true, + "connectionTimeout": 30000 + } + ], + "required": [], + "properties": { + "bindingVersion": { + "$id": "#/properties/bindingVersion", + "type": "string", + "title": "The bindingVersion schema", + "description": "TODO", + "default": "", + "examples": [ + "0.0.1" + ] + }, + "proxy": { + "$id": "#/properties/proxy", + "type": "object", + "title": "The proxy schema", + "description": "TODO", + "default": {}, + "examples": [ + { + "host": "proxy.corporate.com", + "port": 80, + "username": "proxy-user", + "password": "passwd-of-proxy-user" + } + ], + "required": [ + "host", + "port" + ], + "properties": { + "host": { + "$id": "#/properties/proxy/properties/host", + "type": "string", + "title": "The host schema", + "description": "TODO", + "default": "", + "examples": [ + "proxy.corporate.com" + ] + }, + "port": { + "$id": "#/properties/proxy/properties/port", + "type": "integer", + "title": "The port schema", + "description": "TODO", + "default": 0, + "examples": [ + 80 + ] + }, + "username": { + "$id": "#/properties/proxy/properties/username", + "type": "string", + "title": "The username schema", + "description": "TODO", + "default": "", + "examples": [ + "proxy-user" + ] + }, + "password": { + "$id": "#/properties/proxy/properties/password", + "type": "string", + "title": "The password schema", + "description": "TODO", + "default": "", + "examples": [ + "passwd-of-proxy-user" + ] + } + }, + "additionalProperties": true + }, + "sendBufferSize": { + "$id": "#/properties/sendBufferSize", + "type": "integer", + "title": "The sendBufferSize schema", + "description": "TODO", + "default": 0, + "examples": [ + 1024 + ] + }, + "receiveBufferSize": { + "$id": "#/properties/receiveBufferSize", + "type": "integer", + "title": "The receiveBufferSize schema", + "description": "TODO", + "default": 0, + "examples": [ + 2048 + ] + }, + "clientTimeout": { + "$id": "#/properties/clientTimeout", + "type": "integer", + "title": "The clientTimeout schema", + "description": "TODO", + "default": 0, + "examples": [ + 1000 + ] + }, + "sendTCPWithNoDelay": { + "$id": "#/properties/sendTCPWithNoDelay", + "type": "boolean", + "title": "The sendTCPWithNoDelay schema", + "description": "TODO", + "default": false, + "examples": [ + true + ] + }, + "linger": { + "$id": "#/properties/linger", + "type": "integer", + "title": "The linger schema", + "description": "TODO", + "default": 0, + "examples": [ + 1000 + ] + }, + "keepAlive": { + "$id": "#/properties/keepAlive", + "type": "boolean", + "title": "The keepAlive schema", + "description": "TODO", + "default": false, + "examples": [ + true + ] + }, + "connectionTimeout": { + "$id": "#/properties/connectionTimeout", + "type": "integer", + "title": "The connectionTimeout schema", + "description": "TODO", + "default": 0, + "examples": [ + 30000 + ] + } + }, + "additionalProperties": false +} \ No newline at end of file From 78ab493034a1626a78cbedf3f43cc5f405b1f168 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 15 Mar 2021 12:00:10 +0100 Subject: [PATCH 04/37] tentatively complete server binding object --- anypointmq/README.md | 34 +++-- ...ypointmq-server-binding-object.schema.json | 121 ++++++------------ 2 files changed, 66 insertions(+), 89 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index fb48975f..496fb021 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -15,7 +15,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Protocol -These bindings use the `anypointmq` protocol in AsyncAPI documents to denote connections to Anypoint MQ message brokers. +These bindings use the `anypointmq` protocol in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). @@ -24,7 +24,7 @@ The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST The fields of the standard [Server Object](https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#serverObject) are constrained and interpreted as follows: - `protocol` is *required* and MUST be `anypointmq` for the scope of this specification. -- `url` is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`), e.g., `https://mq-${REGION_ID}.anypoint.mulesoft.com/api`. MUST NOT use a scheme other than `https` or `http` (as supported by the Broker REST API endpoint). +- `url` is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`), such as `https://mq-us-east-1.anypoint.mulesoft.com/api` or `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). MUST NOT use a scheme other than `https` or `http` (as supported by the Broker REST API endpoint). - `protocolVersion` is *optional* and if present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. Defaults to `v1` if absent. TODO: @@ -34,26 +34,42 @@ TODO: ## Server Binding Object -TODO +The Anypoint MQ Server Binding Object is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: + +- `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. +- `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. +- `proxy.username`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Username to authenticate against the proxy. +- `proxy.password`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Password to authenticate against the proxy. +- `sendBufferSize`: Size of the buffer (in bytes) used when sending data, set on the socket itself. +- `receiveBufferSize`: Size of the buffer (in bytes) used when receiving data. +- `clientTimeout`: SO_TIMEOUT value on sockets. Indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 indicates an indefinite wait. +- `sendTCPWithNoDelay`: If set, transmitted data is not grouped but sent immediately. +- `linger`: SO_LINGER value, which determines how long (in milliseconds) the socket takes to close so that any remaining data is transmitted correctly. +- `keepAlive`: SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled. +- `connectionTimeout`: Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout. -### Example +### Examples ```yaml servers: development: url: https://mq-us-east-1.anypoint.mulesoft.com/api - description: Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane + description: | + Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane. + Minimal configuration, using defaults for all fields of the server binding object. + Implicitly uses v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. protocol: anypointmq - protocolVersion: v1 production: url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api - description: Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane + description: | + Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane. + Complete configuration, providing explicit values for all fields of the server binding object. + Explicitly specifies the use of v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. protocol: anypointmq protocolVersion: v1 bindings: anypointmq: - bindingVersion: 0.0.1 proxy: host: proxy.corporate.com port: 80 @@ -65,7 +81,7 @@ servers: sendTCPWithNoDelay: true linger: 1000 keepAlive: true - connectionTimeout: 30000 + connectionTimeout: 10000 ``` diff --git a/anypointmq/anypointmq-server-binding-object.schema.json b/anypointmq/anypointmq-server-binding-object.schema.json index 23f86c6a..c3c6c245 100644 --- a/anypointmq/anypointmq-server-binding-object.schema.json +++ b/anypointmq/anypointmq-server-binding-object.schema.json @@ -5,7 +5,6 @@ "title": "Anypoint MQ Server Binding Object", "examples": [ { - "bindingVersion": "0.0.1", "proxy": { "host": "proxy.corporate.com", "port": 80, @@ -18,26 +17,16 @@ "sendTCPWithNoDelay": true, "linger": 1000, "keepAlive": true, - "connectionTimeout": 30000 + "connectionTimeout": 10000 } ], "required": [], "properties": { - "bindingVersion": { - "$id": "#/properties/bindingVersion", - "type": "string", - "title": "The bindingVersion schema", - "description": "TODO", - "default": "", - "examples": [ - "0.0.1" - ] - }, "proxy": { "$id": "#/properties/proxy", "type": "object", - "title": "The proxy schema", - "description": "TODO", + "title": "HTTP proxy definition", + "description": "Defines use of a HTTP proxy for interactions with the Anypoint MQ broker.", "default": {}, "examples": [ { @@ -47,50 +36,39 @@ "password": "passwd-of-proxy-user" } ], - "required": [ - "host", - "port" - ], + "required": [], "properties": { "host": { "$id": "#/properties/proxy/properties/host", "type": "string", - "title": "The host schema", - "description": "TODO", + "title": "Proxy host", + "description": "Destination host for proxy requests.", "default": "", - "examples": [ - "proxy.corporate.com" - ] + "examples": ["proxy.corporate.com"] }, "port": { "$id": "#/properties/proxy/properties/port", "type": "integer", - "title": "The port schema", - "description": "TODO", - "default": 0, - "examples": [ - 80 - ] + "title": "Proxy port", + "description": "Destination port for proxy requests.", + "default": 80, + "examples": [80,443] }, "username": { "$id": "#/properties/proxy/properties/username", "type": "string", - "title": "The username schema", - "description": "TODO", + "title": "Proxy username", + "description": "Username to authenticate against the proxy.", "default": "", - "examples": [ - "proxy-user" - ] + "examples": ["proxy-user"] }, "password": { "$id": "#/properties/proxy/properties/password", "type": "string", - "title": "The password schema", - "description": "TODO", + "title": "Proxy password", + "description": "Password to authenticate against the proxy.", "default": "", - "examples": [ - "passwd-of-proxy-user" - ] + "examples": ["passwd-of-proxy-user"] } }, "additionalProperties": true @@ -98,73 +76,56 @@ "sendBufferSize": { "$id": "#/properties/sendBufferSize", "type": "integer", - "title": "The sendBufferSize schema", - "description": "TODO", - "default": 0, - "examples": [ - 1024 - ] + "title": "Size of socket send buffer", + "description": "Size of the buffer (in bytes) used when sending data, set on the socket itself.", + "examples": [1024] }, "receiveBufferSize": { "$id": "#/properties/receiveBufferSize", "type": "integer", - "title": "The receiveBufferSize schema", - "description": "TODO", - "default": 0, - "examples": [ - 2048 - ] + "title": "Size of socket receive buffer", + "description": "Size of the buffer (in bytes) used when receiving data.", + "examples": [2048] }, "clientTimeout": { "$id": "#/properties/clientTimeout", "type": "integer", - "title": "The clientTimeout schema", - "description": "TODO", + "title": "Socket timeout", + "description": "SO_TIMEOUT value on sockets. Indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 indicates an indefinite wait.", "default": 0, - "examples": [ - 1000 - ] + "examples": [1000] }, "sendTCPWithNoDelay": { "$id": "#/properties/sendTCPWithNoDelay", "type": "boolean", - "title": "The sendTCPWithNoDelay schema", - "description": "TODO", - "default": false, - "examples": [ - true - ] + "title": "Send data immediately", + "description": "If set, transmitted data is not grouped but sent immediately.", + "default": true, + "examples": [true] }, "linger": { "$id": "#/properties/linger", "type": "integer", - "title": "The linger schema", - "description": "TODO", - "default": 0, - "examples": [ - 1000 - ] + "title": "Socket linger value", + "description": "SO_LINGER value, which determines how long (in milliseconds) the socket takes to close so that any remaining data is transmitted correctly.", + "examples": [1000] }, "keepAlive": { "$id": "#/properties/keepAlive", "type": "boolean", - "title": "The keepAlive schema", - "description": "TODO", + "title": "Keep sockets alive", + "description": "SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled.", "default": false, - "examples": [ - true - ] + "examples": [true] }, "connectionTimeout": { "$id": "#/properties/connectionTimeout", "type": "integer", - "title": "The connectionTimeout schema", - "description": "TODO", - "default": 0, - "examples": [ - 30000 - ] + "title": "Socket connection timeout", + "description": "Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout.", + "default": 30000, + "examples": [10000] } }, - "additionalProperties": false + "additionalProperties": true } \ No newline at end of file From f5d0dc6172947e09bfb48a7dc24b2935640d370a Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 15 Mar 2021 12:10:58 +0100 Subject: [PATCH 05/37] fleshed-out skeleton of remaining sections --- anypointmq/README.md | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 496fb021..6312d49d 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -7,7 +7,9 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Version -Current version is `0.0.1`. +The version of this bindings specification is `0.0.1`. + +The version of the AsyncAPI specification to which these bindings apply is `2.0.0`. ## Terminology @@ -15,7 +17,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Protocol -These bindings use the `anypointmq` protocol in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. +These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#definitionsProtocol) in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). @@ -34,7 +36,7 @@ TODO: ## Server Binding Object -The Anypoint MQ Server Binding Object is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: - `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. - `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. @@ -48,6 +50,8 @@ The Anypoint MQ Server Binding Object is defined by a [JSON Schema](anypointmq-s - `keepAlive`: SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled. - `connectionTimeout`: Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout. +Additional fields are permitted but ignored. + ### Examples ```yaml @@ -87,14 +91,44 @@ servers: ## Channel Binding Object +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#channel-bindings-object), which defines these *optional* fields: + +TODO + +Additional fields are permitted but ignored. + +### Examples + +```yaml TODO +``` ## Operation Binding Object +The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#operation-bindings-object), which defines these *optional* fields: + TODO +Additional fields are permitted but ignored. + +### Examples + +```yaml +TODO +``` + ## Message Binding Object -TODO \ No newline at end of file +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#message-bindings-object), which defines these *optional* fields: + +TODO + +Additional fields are permitted but ignored. + +### Examples + +```yaml +TODO +``` From 3c713f382e38044f1bdb13774564b0ff3ec8976e Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 15 Mar 2021 12:15:23 +0100 Subject: [PATCH 06/37] added remaining empty JSON schema docs --- anypointmq/README.md | 6 +++--- anypointmq/anypointmq-channel-binding-object.schema.json | 0 anypointmq/anypointmq-message-binding-object.schema.json | 0 anypointmq/anypointmq-operation-binding-object.schema.json | 0 4 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 anypointmq/anypointmq-channel-binding-object.schema.json create mode 100644 anypointmq/anypointmq-message-binding-object.schema.json create mode 100644 anypointmq/anypointmq-operation-binding-object.schema.json diff --git a/anypointmq/README.md b/anypointmq/README.md index 6312d49d..bedfdb41 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -91,7 +91,7 @@ servers: ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#channel-bindings-object), which defines these *optional* fields: +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json), which defines these *optional* fields: TODO @@ -106,7 +106,7 @@ TODO ## Operation Binding Object -The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#operation-bindings-object), which defines these *optional* fields: +The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](anypointmq-operation-binding-object.schema.json), which defines these *optional* fields: TODO @@ -121,7 +121,7 @@ TODO ## Message Binding Object -The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#message-bindings-object), which defines these *optional* fields: +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](anypointmq-message-binding-object.schema.json), which defines these *optional* fields: TODO diff --git a/anypointmq/anypointmq-channel-binding-object.schema.json b/anypointmq/anypointmq-channel-binding-object.schema.json new file mode 100644 index 00000000..e69de29b diff --git a/anypointmq/anypointmq-message-binding-object.schema.json b/anypointmq/anypointmq-message-binding-object.schema.json new file mode 100644 index 00000000..e69de29b diff --git a/anypointmq/anypointmq-operation-binding-object.schema.json b/anypointmq/anypointmq-operation-binding-object.schema.json new file mode 100644 index 00000000..e69de29b From 5df74b01287040b789bdc57daa4cd54fade8f1d7 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 15 Mar 2021 12:47:14 +0100 Subject: [PATCH 07/37] added backwards compatiblity --- anypointmq/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index bedfdb41..5d5337d6 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -11,6 +11,12 @@ The version of this bindings specification is `0.0.1`. The version of the AsyncAPI specification to which these bindings apply is `2.0.0`. +### Backwards Compatibility + +All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not specified in this specification. This is to ensure backwards compatibility of binding objects. + +For example, a concrete binding object valid against a newer version of this specification is likely to contain fields that were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older version of this specification, although all fields of the binding object not yet defined in this older specification version will be ignored. + ## Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -50,7 +56,7 @@ The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/ma - `keepAlive`: SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled. - `connectionTimeout`: Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout. -Additional fields are permitted but ignored. +Additional fields MAY be present but are ignored if the server binding object is interpreted according to this version of the bindings specification. ### Examples @@ -95,7 +101,7 @@ The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/m TODO -Additional fields are permitted but ignored. +Additional fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. ### Examples @@ -110,7 +116,7 @@ The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob TODO -Additional fields are permitted but ignored. +Additional fields MAY be present but are ignored if the operation binding object is interpreted according to this version of the bindings specification. ### Examples @@ -125,7 +131,7 @@ The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/m TODO -Additional fields are permitted but ignored. +Additional fields MAY be present but are ignored if the message binding object is interpreted according to this version of the bindings specification. ### Examples From d0e030912e33fcd685eecb90c52dfae07349e128 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 15 Mar 2021 12:50:02 +0100 Subject: [PATCH 08/37] better description of backwards compatibility --- anypointmq/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 5d5337d6..678f403f 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -13,9 +13,9 @@ The version of the AsyncAPI specification to which these bindings apply is `2.0. ### Backwards Compatibility -All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not specified in this specification. This is to ensure backwards compatibility of binding objects. +All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects. -For example, a concrete binding object valid against a newer version of this specification is likely to contain fields that were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older version of this specification, although all fields of the binding object not yet defined in this older specification version will be ignored. +For example, a concrete binding object valid against a newer version of this specification is likely to contain fields that were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older specification, although all fields not yet defined in this older specification version will be ignored. ## Terminology From c03161125dfdad99a405bd872e3d196b04051f5a Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 18 Mar 2021 15:15:04 +0100 Subject: [PATCH 09/37] first take on channel binding object: probably need to eliminate this --- anypointmq/README.md | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 678f403f..76d66852 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -23,7 +23,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Protocol -These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#definitionsProtocol) in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. +These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#definitionsProtocol) in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). @@ -42,7 +42,7 @@ TODO: ## Server Binding Object -The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: - `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. - `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. @@ -60,6 +60,8 @@ Additional fields MAY be present but are ignored if the server binding object is ### Examples +The following example shows a `servers` object with two server objects, both using `anypointmq` as the `protocol`, and one having a server binding object for `anypointmq`: + ```yaml servers: development: @@ -97,22 +99,36 @@ servers: ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json), which defines these *optional* fields: TODO Additional fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. +Note that + +- the type of Anypoint MQ destination (queue (FIFO or not) or Exchange) is not capture in the channel binding object. + ### Examples +The following example shows a `channels` object with a channel item object that has a channel binding object for `anypointmq`: + ```yaml -TODO +channels: + user/signedup: + description: This application sends events to this channel about users having signed up + subscribe: + bindings: + anypointmq: + is: queue + queue: + exclusive: true ``` ## Operation Binding Object -The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](anypointmq-operation-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](anypointmq-operation-binding-object.schema.json), which defines these *optional* fields: TODO @@ -127,7 +143,7 @@ TODO ## Message Binding Object -The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/versions/2.0.0/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](anypointmq-message-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](anypointmq-message-binding-object.schema.json), which defines these *optional* fields: TODO From 271567d2446f2fbe99ca45e420d03e44f13d5638 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 18 Mar 2021 15:56:28 +0100 Subject: [PATCH 10/37] empty channel binding object --- anypointmq/README.md | 26 ++++++++++--------- ...pointmq-channel-binding-object.schema.json | 12 +++++++++ 2 files changed, 26 insertions(+), 12 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 76d66852..bd921089 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -99,30 +99,32 @@ servers: ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json) that currently defines *no fields*. -TODO - -Additional fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. - -Note that +Fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. -- the type of Anypoint MQ destination (queue (FIFO or not) or Exchange) is not capture in the channel binding object. +Because an empty channel binding object does not add any information to an AsyncAPI document, it is RECOMMENDED that AsyncAPI documents omit channel binding objects for `anypointmq`. ### Examples -The following example shows a `channels` object with a channel item object that has a channel binding object for `anypointmq`: +The following example shows a `channels` object with two channel item objects, one having an empty channel binding object for `anypointmq` (which is not recommended): ```yaml channels: user/signedup: - description: This application sends events to this channel about users having signed up + description: | + This application sends events to this channel about users that have signed up. + Minimal and recommended configuration, not specifying an empty channel binding object. subscribe: + //... + user/signup: + description: | + This application receives command messages from this channel about users to sign up. + Non-recommended configuration, explicitly providing an empty channel binding object. bindings: anypointmq: - is: queue - queue: - exclusive: true + publish: + //... ``` diff --git a/anypointmq/anypointmq-channel-binding-object.schema.json b/anypointmq/anypointmq-channel-binding-object.schema.json index e69de29b..1c8b20af 100644 --- a/anypointmq/anypointmq-channel-binding-object.schema.json +++ b/anypointmq/anypointmq-channel-binding-object.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "http://asyncapi.com/anypointmq/bindings/channel.json", + "type": "object", + "title": "Anypoint MQ Channel Binding Object", + "examples": [ + {} + ], + "required": [], + "properties": {}, + "additionalProperties": true +} \ No newline at end of file From 1e7e6a2836b33091a6688b293e6149206648b77d Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 18 Mar 2021 19:12:27 +0100 Subject: [PATCH 11/37] elaborated on code generation --- anypointmq/README.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index bd921089..1617e75d 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -27,6 +27,15 @@ These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/ The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). +## Code Generation + +An AsyncAPI document defines a machine-readable contract for the message-driven API of an application. That application is expected to adhere to that contract. Code generation can be used to + +- generate a skeleton of that application (this is common), or +- generate a stub of an "interaction partner application" that interacts with that application (this is less common). + +Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then apply to the type of application that is being generated (the application described by the AsyncAPI document, or its "interaction partner"). + ## Server Object The fields of the standard [Server Object](https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#serverObject) are constrained and interpreted as follows: @@ -58,9 +67,11 @@ The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/ma Additional fields MAY be present but are ignored if the server binding object is interpreted according to this version of the bindings specification. +Note that all of these fields serve _code generation_ based on the AsyncAPI document, rather than defining the contract of the message-driven API. + ### Examples -The following example shows a `servers` object with two server objects, both using `anypointmq` as the `protocol`, and one having a server binding object for `anypointmq`: +The following example shows a `servers` object with two servers, both using `anypointmq` as the `protocol`, and one having a server binding object for `anypointmq`: ```yaml servers: @@ -107,7 +118,7 @@ Because an empty channel binding object does not add any information to an Async ### Examples -The following example shows a `channels` object with two channel item objects, one having an empty channel binding object for `anypointmq` (which is not recommended): +The following example shows a `channels` object with two channels, one having an empty channel binding object for `anypointmq` (which is not recommended): ```yaml channels: @@ -138,8 +149,30 @@ Additional fields MAY be present but are ignored if the operation binding object ### Examples +The following example shows a `channels` object with two channels, each having one operation. Only one operation has an operation binding object for `anypointmq`: + ```yaml -TODO +channels: + user/signedup: + subscribe: + operationId: userHasSignedUp + description: | + TODO + bindings: + anypointmq: + ack: TODO + message: + //... + user/signup: + publish: + operationId: signUpUser + description: | + TODO + bindings: + anypointmq: + ack: TODO + message: + //... ``` From 20ebdd4aa4db6fecee79ace042180c65a9946f34 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 18 Mar 2021 19:21:05 +0100 Subject: [PATCH 12/37] elaborated on code generation --- anypointmq/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 1617e75d..94113139 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -29,12 +29,14 @@ The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST ## Code Generation -An AsyncAPI document defines a machine-readable contract for the message-driven API of an application. That application is expected to adhere to that contract. Code generation can be used to +An AsyncAPI document defines a machine-readable contract for the message-driven API exposed by an application. The application promises to adhere to that contract, and its "interaction partners" can send and/or receive messages accordingly. -- generate a skeleton of that application (this is common), or -- generate a stub of an "interaction partner application" that interacts with that application (this is less common). +Code generation based on an AsyncAPI document can be used to -Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then apply to the type of application that is being generated (the application described by the AsyncAPI document, or its "interaction partner"). +- generate a skeleton of the application that exposes the message-driven API (this is common), or +- generate a stub of an "interaction partner" application that interacts with that application via this API (this is less common). + +Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then apply to the application that is being generated (the application described by the AsyncAPI document, or its "interaction partner"). ## Server Object From 620a780e731f4d05be24ab72ed3fe906aab97bb5 Mon Sep 17 00:00:00 2001 From: asyncapi-bot <61865014+asyncapi-bot@users.noreply.github.com> Date: Mon, 29 Mar 2021 21:04:34 +0200 Subject: [PATCH 13/37] ci: update global workflows (#57) ci: update global workflows --- .github/workflows/if-go-pr-testing.yml | 58 ++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .github/workflows/if-go-pr-testing.yml diff --git a/.github/workflows/if-go-pr-testing.yml b/.github/workflows/if-go-pr-testing.yml new file mode 100644 index 00000000..4a4078ff --- /dev/null +++ b/.github/workflows/if-go-pr-testing.yml @@ -0,0 +1,58 @@ +#This action is centrally managed in https://github.com/asyncapi/.github/ +#Don't make changes to this file in this repo as they will be overwritten with changes made to the same file in above mentioned repo +#It does magic only if there is go.mod file in the root of the project +name: PR testing - if Go project + +on: + pull_request: + types: [opened, reopened, synchronize, ready_for_review] + +jobs: + lint: + if: github.event.pull_request.draft == false + name: lint + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + - name: Check if Go project and has go.mod + id: gomod + run: test -e ./go.mod && echo "::set-output name=exists::true" || echo "::set-output name=exists::false" + shell: bash + - if: steps.gomod.outputs.exists == 'true' + name: Setup Go + uses: actions/setup-go@v2.1.3 + with: + go-version: 1.16 + - if: steps.gomod.outputs.exists == 'true' + name: golangci-lint + uses: golangci/golangci-lint-action@v2 # golangci-lint version extracted from go.mod. `latest` if missing. + with: + skip-go-installation: true # we wanna control the version of Go in use + + test: + if: github.event.pull_request.draft == false + name: ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + steps: + - name: Checkout repository + uses: actions/checkout@v2 + - name: Check if Go project and has go.mod + id: gomod + run: test -e ./go.mod && echo "::set-output name=exists::true" || echo "::set-output name=exists::false" + shell: bash + - if: steps.gomod.outputs.exists == 'true' + name: Setup Go + uses: actions/setup-go@v2.1.3 + with: + go-version: 1.16 + - if: steps.gomod.outputs.exists == 'true' + name: Build + run: go build -v ./... + - if: steps.gomod.outputs.exists == 'true' + name: Test + run: go test -v ./... + From 18cbb5c9cde649289803c32a24d028a05d6a5c47 Mon Sep 17 00:00:00 2001 From: asyncapi-bot <61865014+asyncapi-bot@users.noreply.github.com> Date: Fri, 2 Apr 2021 15:32:21 +0200 Subject: [PATCH 14/37] ci: update global workflows (#58) Co-authored-by: asyncapi-bot --- .github/workflows/automerge.yml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml index d9685646..5700012d 100644 --- a/.github/workflows/automerge.yml +++ b/.github/workflows/automerge.yml @@ -4,7 +4,7 @@ name: Automerge release bump PR on: - pull_request: + pull_request_target: types: - labeled - unlabeled @@ -17,10 +17,6 @@ on: pull_request_review: types: - submitted - check_suite: - types: - - completed - status: {} jobs: @@ -29,7 +25,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Autoapproving - uses: hmarr/auto-approve-action@v2.0.0 + uses: hmarr/auto-approve-action@v2 if: github.actor == 'asyncapi-bot' || github.actor == 'dependabot[bot]' || github.actor == 'dependabot-preview[bot]' with: github-token: "${{ secrets.GITHUB_TOKEN }}" From 8146e1db0c2606dc4b3b0ca0209d5d26305b7899 Mon Sep 17 00:00:00 2001 From: asyncapi-bot <61865014+asyncapi-bot@users.noreply.github.com> Date: Tue, 6 Apr 2021 19:27:08 +0200 Subject: [PATCH 15/37] ci: update global workflows (#59) Co-authored-by: asyncapi-bot --- .github/workflows/automerge.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml index 5700012d..19c8d189 100644 --- a/.github/workflows/automerge.yml +++ b/.github/workflows/automerge.yml @@ -35,7 +35,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Automerging - uses: pascalgn/automerge-action@v0.7.5 + uses: pascalgn/automerge-action@v0.13.0 if: github.actor == 'asyncapi-bot' || github.actor == 'dependabot[bot]' || github.actor == 'dependabot-preview[bot]' env: GITHUB_TOKEN: "${{ secrets.GH_TOKEN }}" From 312d58e42704d378b6018c7e0ab61f88716e9f6c Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 9 Apr 2021 18:47:44 +0200 Subject: [PATCH 16/37] progressing... --- anypointmq/README.md | 45 ++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 94113139..3bbb2286 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -13,9 +13,9 @@ The version of the AsyncAPI specification to which these bindings apply is `2.0. ### Backwards Compatibility -All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects. +All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects, and also to allow code generators to require their own, specific fields which are not defined in this bindings specification. -For example, a concrete binding object valid against a newer version of this specification is likely to contain fields that were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older specification, although all fields not yet defined in this older specification version will be ignored. +As an example of backwards compatibility, consider a concrete binding object valid against a newer version of this specification. This binding object may contain fields specific to that newer version, which were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older specification, although all fields not yet defined in this older specification version will be ignored. ## Terminology @@ -34,13 +34,13 @@ An AsyncAPI document defines a machine-readable contract for the message-driven Code generation based on an AsyncAPI document can be used to - generate a skeleton of the application that exposes the message-driven API (this is common), or -- generate a stub of an "interaction partner" application that interacts with that application via this API (this is less common). +- generate a stub of an "interaction partner" application that interacts with that application via its message-driven API (this is less common). -Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then apply to the application that is being generated (the application described by the AsyncAPI document, or its "interaction partner"). +Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then influence the application code that is being generated. ## Server Object -The fields of the standard [Server Object](https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#serverObject) are constrained and interpreted as follows: +The fields of the standard [Server Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverObject) are constrained and interpreted as follows: - `protocol` is *required* and MUST be `anypointmq` for the scope of this specification. - `url` is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`), such as `https://mq-us-east-1.anypoint.mulesoft.com/api` or `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). MUST NOT use a scheme other than `https` or `http` (as supported by the Broker REST API endpoint). @@ -78,7 +78,7 @@ The following example shows a `servers` object with two servers, both using `any ```yaml servers: development: - url: https://mq-us-east-1.anypoint.mulesoft.com/api + url: https://mq-us-east-1.anypoint.mulesoft.com/api description: | Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane. Minimal configuration, using defaults for all fields of the server binding object. @@ -86,27 +86,27 @@ servers: protocol: anypointmq production: - url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api + url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api description: | Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane. Complete configuration, providing explicit values for all fields of the server binding object. Explicitly specifies the use of v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. - protocol: anypointmq + protocol: anypointmq protocolVersion: v1 bindings: anypointmq: proxy: - host: proxy.corporate.com - port: 80 + host: proxy.corporate.com + port: 80 username: proxy-user password: passwd-of-proxy-user - sendBufferSize: 1024 - receiveBufferSize: 2048 - clientTimeout: 1000 + sendBufferSize: 1024 + receiveBufferSize: 2048 + clientTimeout: 1000 sendTCPWithNoDelay: true - linger: 1000 - keepAlive: true - connectionTimeout: 10000 + linger: 1000 + keepAlive: true + connectionTimeout: 10000 ``` @@ -151,7 +151,7 @@ Additional fields MAY be present but are ignored if the operation binding object ### Examples -The following example shows a `channels` object with two channels, each having one operation. Only one operation has an operation binding object for `anypointmq`: +The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`). Only the `publish` operation has an operation binding object for `anypointmq`: ```yaml channels: @@ -172,7 +172,16 @@ channels: TODO bindings: anypointmq: - ack: TODO + // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, or if the channel name is not a valid destination name in Anypoint MQ. + destination: user-signup-queue + consumer: + // or manual | default immediate | Acknowledgment mode to use for the messages retrieved + acknowledgmentMode: immediate + // Duration in milliseconds that a message is held by a consumer waiting for an acknowledgment or not acknowledgment. After that duration elapses, the message is again available to any consumer. + acknowledgmentTimeout: 10000 + // default 10000 | Time in milliseconds to wait for a message to be ready for consumption + pollingTime: 10000 + producer: message: //... ``` From 778d43a36071e2df5503d4332588b6bba7b11980 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 26 Apr 2021 10:54:15 +0200 Subject: [PATCH 17/37] switching to new schema naming convention --- anypointmq/README.md | 8 ++++---- .../channel.json} | 0 .../message.json} | 0 .../operation.json} | 0 .../server.json} | 0 5 files changed, 4 insertions(+), 4 deletions(-) rename anypointmq/{anypointmq-channel-binding-object.schema.json => json_schemas/channel.json} (100%) rename anypointmq/{anypointmq-message-binding-object.schema.json => json_schemas/message.json} (100%) rename anypointmq/{anypointmq-operation-binding-object.schema.json => json_schemas/operation.json} (100%) rename anypointmq/{anypointmq-server-binding-object.schema.json => json_schemas/server.json} (100%) diff --git a/anypointmq/README.md b/anypointmq/README.md index 3bbb2286..a8531456 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -53,7 +53,7 @@ TODO: ## Server Binding Object -The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](anypointmq-server-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](json_schemas/server.json), which defines these *optional* fields: - `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. - `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. @@ -112,7 +112,7 @@ servers: ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](anypointmq-channel-binding-object.schema.json) that currently defines *no fields*. +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json) that currently defines *no fields*. Fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. @@ -143,7 +143,7 @@ channels: ## Operation Binding Object -The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](anypointmq-operation-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](json_schemas/operation.json), which defines these *optional* fields: TODO @@ -189,7 +189,7 @@ channels: ## Message Binding Object -The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](anypointmq-message-binding-object.schema.json), which defines these *optional* fields: +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](json_schemas/message.json), which defines these *optional* fields: TODO diff --git a/anypointmq/anypointmq-channel-binding-object.schema.json b/anypointmq/json_schemas/channel.json similarity index 100% rename from anypointmq/anypointmq-channel-binding-object.schema.json rename to anypointmq/json_schemas/channel.json diff --git a/anypointmq/anypointmq-message-binding-object.schema.json b/anypointmq/json_schemas/message.json similarity index 100% rename from anypointmq/anypointmq-message-binding-object.schema.json rename to anypointmq/json_schemas/message.json diff --git a/anypointmq/anypointmq-operation-binding-object.schema.json b/anypointmq/json_schemas/operation.json similarity index 100% rename from anypointmq/anypointmq-operation-binding-object.schema.json rename to anypointmq/json_schemas/operation.json diff --git a/anypointmq/anypointmq-server-binding-object.schema.json b/anypointmq/json_schemas/server.json similarity index 100% rename from anypointmq/anypointmq-server-binding-object.schema.json rename to anypointmq/json_schemas/server.json From 14dfc5855623dfa2f870a0addcad9c649202b452 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 26 Apr 2021 11:40:15 +0200 Subject: [PATCH 18/37] added bindingVersion --- anypointmq/README.md | 9 +++++++-- anypointmq/json_schemas/channel.json | 30 +++++++++++++++++++++++++--- anypointmq/json_schemas/server.json | 24 +++++++++++++++++++++- 3 files changed, 57 insertions(+), 6 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index a8531456..d692ca1b 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -8,6 +8,8 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Version The version of this bindings specification is `0.0.1`. +This is also the `bindingVersion` for all Binding Objects defined by this specification. +In any given Binding Object, `latest` can alternatively be used as long as this version of the bindings specification remains the latest published version. The version of the AsyncAPI specification to which these bindings apply is `2.0.0`. @@ -95,6 +97,7 @@ servers: protocolVersion: v1 bindings: anypointmq: + bindingVersion: 0.0.1 proxy: host: proxy.corporate.com port: 80 @@ -120,7 +123,7 @@ Because an empty channel binding object does not add any information to an Async ### Examples -The following example shows a `channels` object with two channels, one having an empty channel binding object for `anypointmq` (which is not recommended): +The following example shows a `channels` object with two channels, one having a semantically empty channel binding object for `anypointmq` (which is not recommended): ```yaml channels: @@ -133,9 +136,10 @@ channels: user/signup: description: | This application receives command messages from this channel about users to sign up. - Non-recommended configuration, explicitly providing an empty channel binding object. + Non-recommended configuration, explicitly providing a semantically empty channel binding object. bindings: anypointmq: + bindingVersion: 0.0.1 publish: //... ``` @@ -172,6 +176,7 @@ channels: TODO bindings: anypointmq: + bindingVersion: 0.0.1 // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, or if the channel name is not a valid destination name in Anypoint MQ. destination: user-signup-queue consumer: diff --git a/anypointmq/json_schemas/channel.json b/anypointmq/json_schemas/channel.json index 1c8b20af..9e92b4d3 100644 --- a/anypointmq/json_schemas/channel.json +++ b/anypointmq/json_schemas/channel.json @@ -4,9 +4,33 @@ "type": "object", "title": "Anypoint MQ Channel Binding Object", "examples": [ - {} + {}, + { + "bindingVersion": "latest" + } ], "required": [], - "properties": {}, - "additionalProperties": true + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "#/definitions/specificationExtension" + } + }, + "properties": { + "bindingVersion": { + "$id": "#/properties/bindingVersion", + "type": "string", + "title": "Anypoint MQ bindings specification version", + "description": "The version of the Anypoint MQ bindings specification that defines the content of this Binding Object.", + "default": "latest", + "examples": ["latest", "0.0.1"] + } + }, + "additionalProperties": true, + "definitions": { + "specificationExtension": { + "description": "Any property starting with x- is valid.", + "additionalProperties": true, + "additionalItems": true + } + } } \ No newline at end of file diff --git a/anypointmq/json_schemas/server.json b/anypointmq/json_schemas/server.json index c3c6c245..b606c048 100644 --- a/anypointmq/json_schemas/server.json +++ b/anypointmq/json_schemas/server.json @@ -4,7 +4,9 @@ "type": "object", "title": "Anypoint MQ Server Binding Object", "examples": [ + {}, { + "bindingVersion": "latest", "proxy": { "host": "proxy.corporate.com", "port": 80, @@ -21,7 +23,20 @@ } ], "required": [], + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "#/definitions/specificationExtension" + } + }, "properties": { + "bindingVersion": { + "$id": "#/properties/bindingVersion", + "type": "string", + "title": "Anypoint MQ bindings specification version", + "description": "The version of the Anypoint MQ bindings specification that defines the content of this Binding Object.", + "default": "latest", + "examples": ["latest", "0.0.1"] + }, "proxy": { "$id": "#/properties/proxy", "type": "object", @@ -127,5 +142,12 @@ "examples": [10000] } }, - "additionalProperties": true + "additionalProperties": true, + "definitions": { + "specificationExtension": { + "description": "Any property starting with x- is valid.", + "additionalProperties": true, + "additionalItems": true + } + } } \ No newline at end of file From 5e8aed9b2e28bd638ab0c0759a0b2f5dacdf77c0 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Mon, 26 Apr 2021 11:50:46 +0200 Subject: [PATCH 19/37] fine-tuning --- anypointmq/README.md | 10 +++++----- anypointmq/json_schemas/channel.json | 2 +- anypointmq/json_schemas/server.json | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index d692ca1b..aee6a684 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -8,16 +8,16 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Version The version of this bindings specification is `0.0.1`. -This is also the `bindingVersion` for all Binding Objects defined by this specification. -In any given Binding Object, `latest` can alternatively be used as long as this version of the bindings specification remains the latest published version. +This is also the `bindingVersion` for all binding objects defined by this specification. +In any given binding object, `latest` can alternatively be used as long as this version of the bindings specification remains the latest published version. The version of the AsyncAPI specification to which these bindings apply is `2.0.0`. ### Backwards Compatibility -All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects, and also to allow code generators to require their own, specific fields which are not defined in this bindings specification. +All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects, and also to allow code generators to define their own, specific fields which are not defined in this bindings specification. -As an example of backwards compatibility, consider a concrete binding object valid against a newer version of this specification. This binding object may contain fields specific to that newer version, which were not yet defined in an older version of this specification. However, because additional fields are allowed, this binding object is also valid against the older specification. The binding object can therefore be used in a system that is only aware of the older specification, although all fields not yet defined in this older specification version will be ignored. +As an example of backwards compatibility, consider a concrete binding object valid against version `1.1.0` of this specification. This binding object may specify `bindingVersion: 1.1.0`. This binding object may contain fields specific to version `1.1.0`, which were not yet defined in, say, version `1.0.5` of this specification. However, because additional fields are allowed, this binding object is also valid against version `1.0.5` of this specification. The binding object valid against version `1.1.0` can therefore be used in a system that is only aware of version `1.0.5`, although all fields not yet defined in version `1.0.5` of this specification will be ignored. ## Terminology @@ -177,7 +177,7 @@ channels: bindings: anypointmq: bindingVersion: 0.0.1 - // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, or if the channel name is not a valid destination name in Anypoint MQ. + // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ. destination: user-signup-queue consumer: // or manual | default immediate | Acknowledgment mode to use for the messages retrieved diff --git a/anypointmq/json_schemas/channel.json b/anypointmq/json_schemas/channel.json index 9e92b4d3..f64c7b5a 100644 --- a/anypointmq/json_schemas/channel.json +++ b/anypointmq/json_schemas/channel.json @@ -20,7 +20,7 @@ "$id": "#/properties/bindingVersion", "type": "string", "title": "Anypoint MQ bindings specification version", - "description": "The version of the Anypoint MQ bindings specification that defines the content of this Binding Object.", + "description": "The version of the Anypoint MQ bindings specification that defines the content of this binding object.", "default": "latest", "examples": ["latest", "0.0.1"] } diff --git a/anypointmq/json_schemas/server.json b/anypointmq/json_schemas/server.json index b606c048..1f92b7f2 100644 --- a/anypointmq/json_schemas/server.json +++ b/anypointmq/json_schemas/server.json @@ -33,7 +33,7 @@ "$id": "#/properties/bindingVersion", "type": "string", "title": "Anypoint MQ bindings specification version", - "description": "The version of the Anypoint MQ bindings specification that defines the content of this Binding Object.", + "description": "The version of the Anypoint MQ bindings specification that defines the content of this binding object.", "default": "latest", "examples": ["latest", "0.0.1"] }, From b179ca9c5019faf42f47443a0b5dbdc75b7d06d1 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 26 May 2021 16:14:38 +0200 Subject: [PATCH 20/37] moving towards minimalistic bindings spec --- anypointmq/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index aee6a684..ccba5225 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -38,7 +38,7 @@ Code generation based on an AsyncAPI document can be used to - generate a skeleton of the application that exposes the message-driven API (this is common), or - generate a stub of an "interaction partner" application that interacts with that application via its message-driven API (this is less common). -Some of the fields in the bindings defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while other fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then influence the application code that is being generated. +Only a few fields of the binding objects defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while most fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then influence the application code that is being generated. ## Server Object @@ -57,6 +57,7 @@ TODO: The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](json_schemas/server.json), which defines these *optional* fields: +- `bindingVersion`: The version of the Anypoint MQ bindings specification that defines the content of this server binding object. - `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. - `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. - `proxy.username`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Username to authenticate against the proxy. @@ -115,11 +116,13 @@ servers: ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json) that currently defines *no fields*. +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json), which currently defines only the *optional* `bindingVersion` field: -Fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. +- `bindingVersion`: The version of the Anypoint MQ bindings specification that defines the content of this channel binding object. -Because an empty channel binding object does not add any information to an AsyncAPI document, it is RECOMMENDED that AsyncAPI documents omit channel binding objects for `anypointmq`. +Additional fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. + +Because a channel binding object just containing `bindingVersion` does not add any information to an AsyncAPI document, it is RECOMMENDED that AsyncAPI documents omit channel binding objects for `anypointmq`. ### Examples From 290395dcb7c1e50f07d18df8b10a6586c1479006 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 27 May 2021 13:40:02 +0200 Subject: [PATCH 21/37] simplified up to server object --- anypointmq/README.md | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index ccba5225..db82b249 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -7,11 +7,11 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Version -The version of this bindings specification is `0.0.1`. +The version of this bindings specification is `0.1.0`. This is also the `bindingVersion` for all binding objects defined by this specification. In any given binding object, `latest` can alternatively be used as long as this version of the bindings specification remains the latest published version. -The version of the AsyncAPI specification to which these bindings apply is `2.0.0`. +The version of the AsyncAPI specification to which these bindings apply is `2.1.0`. ### Backwards Compatibility @@ -29,28 +29,18 @@ These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/ The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). -## Code Generation - -An AsyncAPI document defines a machine-readable contract for the message-driven API exposed by an application. The application promises to adhere to that contract, and its "interaction partners" can send and/or receive messages accordingly. - -Code generation based on an AsyncAPI document can be used to - -- generate a skeleton of the application that exposes the message-driven API (this is common), or -- generate a stub of an "interaction partner" application that interacts with that application via its message-driven API (this is less common). - -Only a few fields of the binding objects defined in this specification serve to more clearly define the contract of an API in the presence of an Anypoint MQ message broker, while most fields are useful primarily for code generation. The latter fields can be used in both code generation scenarios, and will then influence the application code that is being generated. - ## Server Object The fields of the standard [Server Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverObject) are constrained and interpreted as follows: -- `protocol` is *required* and MUST be `anypointmq` for the scope of this specification. -- `url` is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`), such as `https://mq-us-east-1.anypoint.mulesoft.com/api` or `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). MUST NOT use a scheme other than `https` or `http` (as supported by the Broker REST API endpoint). -- `protocolVersion` is *optional* and if present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. Defaults to `v1` if absent. +Server Object Field Name | Values for Anypoint MQ Protocol | Description +---|:---|:--- +`protocol` | `anypointmq` | Is *required* and MUST be `anypointmq` for the scope of this specification. +`url` | for example `https://mq-us-east-1.anypoint.mulesoft.com/api` | Is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com/api` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). +`protocolVersion` | for example `v1` | Is *optional* and if present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. Defaults to `v1` if absent. +`security` | suitably configured OAuth 2.0 client credentials grant type | Currently, authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object must correctly match these constraints. -TODO: -- authentication is by Anypoint MQ client ID and secret, which implies the Anypoint Platform organization ID and environment (ID) -- capture this as security scheme and Security Requirement Object +Please note that the choice of a particular Anypoint MQ client app (and its client ID and secret) imply an implicit choice of the Anypoint Platform organization ID and environment (ID), namely those in which this client app is defined. See the [Anypoint MQ documentation](https://docs.mulesoft.com/mq/mq-client-apps) for details on how to configure Anypoint MQ client apps. ## Server Binding Object @@ -98,7 +88,7 @@ servers: protocolVersion: v1 bindings: anypointmq: - bindingVersion: 0.0.1 + bindingVersion: 0.1.0 proxy: host: proxy.corporate.com port: 80 @@ -142,7 +132,7 @@ channels: Non-recommended configuration, explicitly providing a semantically empty channel binding object. bindings: anypointmq: - bindingVersion: 0.0.1 + bindingVersion: 0.1.0 publish: //... ``` @@ -179,7 +169,7 @@ channels: TODO bindings: anypointmq: - bindingVersion: 0.0.1 + bindingVersion: 0.1.0 // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ. destination: user-signup-queue consumer: From 33405de8c20e89b428458afbd5917b087b0520d6 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 27 May 2021 15:30:45 +0200 Subject: [PATCH 22/37] working on channel --- anypointmq/README.md | 99 ++++++++++++++++---------------------------- 1 file changed, 36 insertions(+), 63 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index db82b249..39f7ad45 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -13,12 +13,6 @@ In any given binding object, `latest` can alternatively be used as long as this The version of the AsyncAPI specification to which these bindings apply is `2.1.0`. -### Backwards Compatibility - -All bindings defined in this specification allow additional, unspecified fields, so that a concrete instance of a binding object MAY contain arbitrary fields not defined in this specification. This is to ensure backwards compatibility of binding objects, and also to allow code generators to define their own, specific fields which are not defined in this bindings specification. - -As an example of backwards compatibility, consider a concrete binding object valid against version `1.1.0` of this specification. This binding object may specify `bindingVersion: 1.1.0`. This binding object may contain fields specific to version `1.1.0`, which were not yet defined in, say, version `1.0.5` of this specification. However, because additional fields are allowed, this binding object is also valid against version `1.0.5` of this specification. The binding object valid against version `1.1.0` can therefore be used in a system that is only aware of version `1.0.5`, although all fields not yet defined in version `1.0.5` of this specification will be ignored. - ## Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -35,38 +29,25 @@ The fields of the standard [Server Object](https://github.com/asyncapi/spec/blob Server Object Field Name | Values for Anypoint MQ Protocol | Description ---|:---|:--- -`protocol` | `anypointmq` | Is *required* and MUST be `anypointmq` for the scope of this specification. -`url` | for example `https://mq-us-east-1.anypoint.mulesoft.com/api` | Is *required* and MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com/api` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). -`protocolVersion` | for example `v1` | Is *optional* and if present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. Defaults to `v1` if absent. -`security` | suitably configured OAuth 2.0 client credentials grant type | Currently, authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object must correctly match these constraints. +`protocol` | `anypointmq` | **Required**. MUST be `anypointmq` for the scope of this specification. +`url` | e.g., `https://mq-us-east-1.anypoint.mulesoft.com/api` | **Required**. MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com/api` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). +`protocolVersion` | e.g., `v1` | **Optional**, defaults to `v1`. If present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. +`security` | suitably configured OAuth 2.0 client credentials grant type | **Required**. Currently, authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object MUST correctly match these constraints. -Please note that the choice of a particular Anypoint MQ client app (and its client ID and secret) imply an implicit choice of the Anypoint Platform organization ID and environment (ID), namely those in which this client app is defined. See the [Anypoint MQ documentation](https://docs.mulesoft.com/mq/mq-client-apps) for details on how to configure Anypoint MQ client apps. +Note that the choice of a particular Anypoint MQ client app (and its client ID and secret) imply an implicit choice of the Anypoint Platform organization ID and environment (ID), namely those in which this client app is defined. See the [Anypoint MQ documentation](https://docs.mulesoft.com/mq/mq-client-apps) for details on how to configure Anypoint MQ client apps. ## Server Binding Object -The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](json_schemas/server.json), which defines these *optional* fields: - -- `bindingVersion`: The version of the Anypoint MQ bindings specification that defines the content of this server binding object. -- `proxy.host`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination host for proxy requests. -- `proxy.port`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Destination port for proxy requests. -- `proxy.username`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Username to authenticate against the proxy. -- `proxy.password`: Defines use of a HTTP proxy for interactions with the Anypoint MQ broker: Password to authenticate against the proxy. -- `sendBufferSize`: Size of the buffer (in bytes) used when sending data, set on the socket itself. -- `receiveBufferSize`: Size of the buffer (in bytes) used when receiving data. -- `clientTimeout`: SO_TIMEOUT value on sockets. Indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 indicates an indefinite wait. -- `sendTCPWithNoDelay`: If set, transmitted data is not grouped but sent immediately. -- `linger`: SO_LINGER value, which determines how long (in milliseconds) the socket takes to close so that any remaining data is transmitted correctly. -- `keepAlive`: SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled. -- `connectionTimeout`: Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout. - -Additional fields MAY be present but are ignored if the server binding object is interpreted according to this version of the bindings specification. +The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](json_schemas/server.json), which currently defines only the *optional* `bindingVersion` field: -Note that all of these fields serve _code generation_ based on the AsyncAPI document, rather than defining the contract of the message-driven API. +Field Name | Type | Description +---|:---:|--- +`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. ### Examples -The following example shows a `servers` object with two servers, both using `anypointmq` as the `protocol`, and one having a server binding object for `anypointmq`: +The following example shows a `servers` object with two servers, both using `anypointmq` as the `protocol`, the second having a server binding object for `anypointmq`: ```yaml servers: @@ -74,77 +55,69 @@ servers: url: https://mq-us-east-1.anypoint.mulesoft.com/api description: | Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane. - Minimal configuration, using defaults for all fields of the server binding object. Implicitly uses v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. + Minimal configuration, omitting a server binding object. protocol: anypointmq production: url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api description: | Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane. - Complete configuration, providing explicit values for all fields of the server binding object. Explicitly specifies the use of v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. + Explicitly provides a server binding object. protocol: anypointmq protocolVersion: v1 bindings: anypointmq: - bindingVersion: 0.1.0 - proxy: - host: proxy.corporate.com - port: 80 - username: proxy-user - password: passwd-of-proxy-user - sendBufferSize: 1024 - receiveBufferSize: 2048 - clientTimeout: 1000 - sendTCPWithNoDelay: true - linger: 1000 - keepAlive: true - connectionTimeout: 10000 + bindingVersion: "0.1.0" ``` ## Channel Binding Object -The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json), which currently defines only the *optional* `bindingVersion` field: +The Anypoint MQ [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json), which defines these fields: -- `bindingVersion`: The version of the Anypoint MQ bindings specification that defines the content of this channel binding object. +Field Name | Type | Description +---|:---:|--- +`destination` | string | **Optional**, defaults to the channel name. The destination (queue or exchange) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ. +`destinationType` | string | **Optional**, defaults to `queue`. The type of destination, which MUST be either `exchange` or `queue` or `fifo-queue`. SHOULD be specified to document the messaging model (publish/subscribe, point-to-point, strict message ordering) supported by this channel. +`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. -Additional fields MAY be present but are ignored if the channel binding object is interpreted according to this version of the bindings specification. - -Because a channel binding object just containing `bindingVersion` does not add any information to an AsyncAPI document, it is RECOMMENDED that AsyncAPI documents omit channel binding objects for `anypointmq`. +Note that an Anypoint MQ exchange can only be sent to, not received from. To receive messages sent to an exchange, an intermediary queue must be [defined and bound to the exchange](https://docs.mulesoft.com/mq/mq-understanding#message-exchanges). In this bindings specification, these intermediary queues are not exposed in the AsyncAPI document. Instead, it is simply assumed that whenever messages must be received from an exchange, such an unnamed (in the AsyncAPI document) intermediary queue is involved. ### Examples -The following example shows a `channels` object with two channels, one having a semantically empty channel binding object for `anypointmq` (which is not recommended): +The following example shows a `channels` object with two channels, the second having a channel binding object for `anypointmq`: ```yaml channels: - user/signedup: - description: | - This application sends events to this channel about users that have signed up. - Minimal and recommended configuration, not specifying an empty channel binding object. - subscribe: - //... user/signup: description: | This application receives command messages from this channel about users to sign up. - Non-recommended configuration, explicitly providing a semantically empty channel binding object. + Minimal configuration, omitting a channel binding object. + publish: + //... + user/signedup: + description: | + This application sends events to this channel about users that have signed up. + Explicitly provides a channel binding object. bindings: anypointmq: - bindingVersion: 0.1.0 - publish: + destination: user-signup-exchg + destinationType: exchange + bindingVersion: "0.1.0" + subscribe: //... ``` ## Operation Binding Object -The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](json_schemas/operation.json), which defines these *optional* fields: - -TODO +The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](json_schemas/operation.json), which currently defines only the *optional* `bindingVersion` field: -Additional fields MAY be present but are ignored if the operation binding object is interpreted according to this version of the bindings specification. +Field Name | Type | Description +---|:---:|--- +`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. ### Examples From 14c9864f23e7ec1caa280231008267a72ef816bb Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 27 May 2021 20:15:00 +0200 Subject: [PATCH 23/37] up to message binding --- anypointmq/README.md | 81 +++++++++++++++++++++++++++++--------------- 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 39f7ad45..2b53464b 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -83,7 +83,7 @@ Field Name | Type | Description `destinationType` | string | **Optional**, defaults to `queue`. The type of destination, which MUST be either `exchange` or `queue` or `fifo-queue`. SHOULD be specified to document the messaging model (publish/subscribe, point-to-point, strict message ordering) supported by this channel. `bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. -Note that an Anypoint MQ exchange can only be sent to, not received from. To receive messages sent to an exchange, an intermediary queue must be [defined and bound to the exchange](https://docs.mulesoft.com/mq/mq-understanding#message-exchanges). In this bindings specification, these intermediary queues are not exposed in the AsyncAPI document. Instead, it is simply assumed that whenever messages must be received from an exchange, such an unnamed (in the AsyncAPI document) intermediary queue is involved. +Note that an Anypoint MQ exchange can only be sent to, not received from. To receive messages sent to an exchange, [an intermediary queue must be defined and bound to the exchange](https://docs.mulesoft.com/mq/mq-understanding#message-exchanges). In this bindings specification, these intermediary queues are not exposed in the AsyncAPI document. Instead, it is simply assumed that whenever messages must be received from an exchange, such an intermediary queue is involved yet invisible in the AsyncAPI document. ### Examples @@ -121,38 +121,27 @@ Field Name | Type | Description ### Examples -The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`). Only the `publish` operation has an operation binding object for `anypointmq`: +The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`). Only the `subscribe` operation has an operation binding object for `anypointmq`: ```yaml channels: - user/signedup: - subscribe: - operationId: userHasSignedUp - description: | - TODO - bindings: - anypointmq: - ack: TODO - message: - //... user/signup: publish: operationId: signUpUser description: | - TODO + This application receives command messages via this operation about users to sign up. + Minimal configuration, omitting an operation binding object. + message: + //... + user/signedup: + subscribe: + operationId: userHasSignedUp + description: | + This application sends events via this operation about users that have signed up. + Explicitly provides an operation binding object. bindings: anypointmq: - bindingVersion: 0.1.0 - // Destination (Queue or Exchange) name for this channel. Defaults to the channel name. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ. - destination: user-signup-queue - consumer: - // or manual | default immediate | Acknowledgment mode to use for the messages retrieved - acknowledgmentMode: immediate - // Duration in milliseconds that a message is held by a consumer waiting for an acknowledgment or not acknowledgment. After that duration elapses, the message is again available to any consumer. - acknowledgmentTimeout: 10000 - // default 10000 | Time in milliseconds to wait for a message to be ready for consumption - pollingTime: 10000 - producer: + bindingVersion: "0.1.0" message: //... ``` @@ -160,14 +149,50 @@ channels: ## Message Binding Object -The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](json_schemas/message.json), which defines these *optional* fields: +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](json_schemas/message.json), which defines these fields: -TODO +Field Name | Type | Description +---|:---:|--- +`messageId` | string | **Optional**. The unique ID of the message. When publishing the message, if not specified, the broker creates a unique essage ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. +`messageGroupId` | string | **Optional**. ID of the message group to which the published message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. +`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. -Additional fields MAY be present but are ignored if the message binding object is interpreted according to this version of the bindings specification. +Note that message headers, which are specified in the `headers` field of the standard [Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObject), are transmitted in the [Anypoint MQ message `properties` section](https://docs.mulesoft.com/mq/mq-apis#example-publish-a-message). In AsyncAPI, this `headers` field does not include protocol headers such as `messageId` or `messageGroupId`, which are transmitted in the [Anypoint MQ message `headers` section](https://docs.mulesoft.com/mq/mq-apis#postsetup). ### Examples +The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`) with one message. Only the message of the `subscribe` operation has a message binding object for `anypointmq`: + ```yaml -TODO +channels: + user/signup: + publish: + message: + //... + user/signedup: + subscribe: + message: + headers: + type: object + properties: + correlationId: + description: Correlation ID set by application + type: string + payload: + type: object + properties: + //... + correlationId: + description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section + location: $message.header#/correlationId + bindings: + anypointmq: + bindingVersion: "0.1.0" + examples: + - messageId: "e0c62826-52d9-4d64-bdd8-a7c415917acf" + messageGroupId: "42" + headers: + correlationId: "6e343f8c-bf0d-11eb-8529-0242ac130003" + payload: + //... ``` From bc950584596a7a86af0c337e9a848100d388b14d Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 27 May 2021 21:04:01 +0200 Subject: [PATCH 24/37] refining --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 2b53464b..d700b26e 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -9,7 +9,7 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA The version of this bindings specification is `0.1.0`. This is also the `bindingVersion` for all binding objects defined by this specification. -In any given binding object, `latest` can alternatively be used as long as this version of the bindings specification remains the latest published version. +In any given binding object, `latest` MAY alternatively be used to refer to the currently latest published version of this bindings specification. The version of the AsyncAPI specification to which these bindings apply is `2.1.0`. From d55f6f297720770f69f2e864241a022e288df964 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 27 May 2021 21:56:21 +0200 Subject: [PATCH 25/37] refining --- anypointmq/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index d700b26e..7ed49290 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -5,7 +5,7 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA [Anypoint MQ](https://docs.mulesoft.com/mq/) is MuleSoft's multi-tenant, cloud messaging service and is fully integrated with [Anypoint Platform](https://www.mulesoft.com/platform/enterprise-integration). -## Version +## Versions The version of this bindings specification is `0.1.0`. This is also the `bindingVersion` for all binding objects defined by this specification. @@ -32,9 +32,9 @@ Server Object Field Name | Values for Anypoint MQ Protocol | Description `protocol` | `anypointmq` | **Required**. MUST be `anypointmq` for the scope of this specification. `url` | e.g., `https://mq-us-east-1.anypoint.mulesoft.com/api` | **Required**. MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com/api` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). `protocolVersion` | e.g., `v1` | **Optional**, defaults to `v1`. If present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. -`security` | suitably configured OAuth 2.0 client credentials grant type | **Required**. Currently, authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object MUST correctly match these constraints. +`security` | suitably configured OAuth 2.0 client credentials grant type | **Required**. Authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object MUST correctly match these constraints. -Note that the choice of a particular Anypoint MQ client app (and its client ID and secret) imply an implicit choice of the Anypoint Platform organization ID and environment (ID), namely those in which this client app is defined. See the [Anypoint MQ documentation](https://docs.mulesoft.com/mq/mq-client-apps) for details on how to configure Anypoint MQ client apps. +Note that the choice of a particular Anypoint MQ client app (via its client ID and secret) decides the Anypoint Platform organization ID and environment (ID) to be those in which this client app is defined. See the [Anypoint MQ documentation](https://docs.mulesoft.com/mq/mq-client-apps) for details on how to configure Anypoint MQ client apps. ## Server Binding Object From 548f92da5f2d6a4e917fbf23e45549577d3fd9c6 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 28 May 2021 07:41:16 +0200 Subject: [PATCH 26/37] add complete example --- anypointmq/README.md | 126 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 106 insertions(+), 20 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 7ed49290..82562c9e 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -7,7 +7,7 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Versions -The version of this bindings specification is `0.1.0`. +The version of this bindings specification is `0.0.1`. This is also the `bindingVersion` for all binding objects defined by this specification. In any given binding object, `latest` MAY alternatively be used to refer to the currently latest published version of this bindings specification. @@ -69,7 +69,7 @@ servers: protocolVersion: v1 bindings: anypointmq: - bindingVersion: "0.1.0" + bindingVersion: '0.0.1' ``` @@ -96,7 +96,7 @@ channels: This application receives command messages from this channel about users to sign up. Minimal configuration, omitting a channel binding object. publish: - //... + #... user/signedup: description: | This application sends events to this channel about users that have signed up. @@ -105,9 +105,9 @@ channels: anypointmq: destination: user-signup-exchg destinationType: exchange - bindingVersion: "0.1.0" + bindingVersion: '0.0.1' subscribe: - //... + #... ``` @@ -132,7 +132,7 @@ channels: This application receives command messages via this operation about users to sign up. Minimal configuration, omitting an operation binding object. message: - //... + #... user/signedup: subscribe: operationId: userHasSignedUp @@ -141,9 +141,9 @@ channels: Explicitly provides an operation binding object. bindings: anypointmq: - bindingVersion: "0.1.0" + bindingVersion: '0.0.1' message: - //... + #... ``` @@ -153,8 +153,8 @@ The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/m Field Name | Type | Description ---|:---:|--- -`messageId` | string | **Optional**. The unique ID of the message. When publishing the message, if not specified, the broker creates a unique essage ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. -`messageGroupId` | string | **Optional**. ID of the message group to which the published message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. +`messageId` | string | **Optional**. The unique ID of the message. When publishing the message, if not specified, the broker creates a unique message ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. +`messageGroupId` | string | **Optional**. The ID of the message group to which the message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. `bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. Note that message headers, which are specified in the `headers` field of the standard [Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObject), are transmitted in the [Anypoint MQ message `properties` section](https://docs.mulesoft.com/mq/mq-apis#example-publish-a-message). In AsyncAPI, this `headers` field does not include protocol headers such as `messageId` or `messageGroupId`, which are transmitted in the [Anypoint MQ message `headers` section](https://docs.mulesoft.com/mq/mq-apis#postsetup). @@ -168,7 +168,7 @@ channels: user/signup: publish: message: - //... + #... user/signedup: subscribe: message: @@ -181,18 +181,104 @@ channels: payload: type: object properties: - //... + #... + correlationId: + description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section + location: $message.header#/correlationId + bindings: + anypointmq: + messageId: 'e0c62826-52d9-4d64-bdd8-a7c415917acf' + messageGroupId: '42' + bindingVersion: '0.0.1' +``` + +## Complete Example + +The following is a complete, simple AsyncAPI document illustrating the usage of all binding objects defined in this bindings specification, with all their fields. + +``` +asyncapi: '2.0.0' +info: + title: Example with Anypoint MQ + version: '1.0.0' + +servers: + development: + protocol: anypointmq + protocolVersion: v1 + url: https://mq-us-east-1.anypoint.mulesoft.com/api + description: | + Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane + under management of the US control plane. + security: + - oauthDev: [] + bindings: + anypointmq: + bindingVersion: '0.1.0' + production: + protocol: anypointmq + protocolVersion: v1 + url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api + description: | + Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane + under management of the EU control plane. + security: + - oauthProd: [] + bindings: + anypointmq: + bindingVersion: '0.1.0' + +channels: + user/signup: + description: | + This application receives command messages from this channel about users to sign up. + bindings: + anypointmq: + destination: user-signup-queue + destinationType: fifo-queue + bindingVersion: '0.1.0' + publish: + operationId: signUpUser + description: | + This application receives command messages via this operation about users to sign up. + bindings: + anypointmq: + bindingVersion: '0.1.0' + message: + contentType: application/json + headers: + type: object + properties: + correlationId: + description: Correlation ID set by application + type: string + payload: + type: object + properties: + username: + type: string + minLength: 3 correlationId: description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section location: $message.header#/correlationId bindings: anypointmq: - bindingVersion: "0.1.0" - examples: - - messageId: "e0c62826-52d9-4d64-bdd8-a7c415917acf" - messageGroupId: "42" - headers: - correlationId: "6e343f8c-bf0d-11eb-8529-0242ac130003" - payload: - //... + messageId: 'e0c62826-52d9-4d64-bdd8-a7c415917acf' + messageGroupId: '42' + bindingVersion: '0.1.0' + +components: + securitySchemes: + oauthDev: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize + scopes: {} + oauthProd: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize + scopes: {} ``` From 9fc597aabba2e66af6035241c80280d684ebe1cf Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 28 May 2021 07:42:58 +0200 Subject: [PATCH 27/37] refining --- anypointmq/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 82562c9e..c3060633 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -196,11 +196,11 @@ channels: The following is a complete, simple AsyncAPI document illustrating the usage of all binding objects defined in this bindings specification, with all their fields. -``` +```yaml asyncapi: '2.0.0' info: title: Example with Anypoint MQ - version: '1.0.0' + version: '0.0.1' servers: development: From 210d17b10bf153e0d2efd12c367e3cf66864d865 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 28 May 2021 07:48:12 +0200 Subject: [PATCH 28/37] refining --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index c3060633..6597401f 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -266,7 +266,7 @@ channels: messageId: 'e0c62826-52d9-4d64-bdd8-a7c415917acf' messageGroupId: '42' bindingVersion: '0.1.0' - + components: securitySchemes: oauthDev: From 08eff62048bbe3e2b65338dfb687f47afac3c3f3 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 28 May 2021 08:28:56 +0200 Subject: [PATCH 29/37] refining --- anypointmq/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/anypointmq/README.md b/anypointmq/README.md index 6597401f..8f0c9617 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -159,6 +159,8 @@ Field Name | Type | Description Note that message headers, which are specified in the `headers` field of the standard [Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObject), are transmitted in the [Anypoint MQ message `properties` section](https://docs.mulesoft.com/mq/mq-apis#example-publish-a-message). In AsyncAPI, this `headers` field does not include protocol headers such as `messageId` or `messageGroupId`, which are transmitted in the [Anypoint MQ message `headers` section](https://docs.mulesoft.com/mq/mq-apis#postsetup). +Please note that the definition of this message binding object is likely to change in future versions of this bindings specification to better describe the mapping of the fields of the AsyncAPI standard message object to the various parts of the Anypoint MQ message as it is exchanged as an HTTP body with the Anypoint MQ Broker REST API. + ### Examples The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`) with one message. Only the message of the `subscribe` operation has a message binding object for `anypointmq`: From 6c12809e3c6241682aa2ff9f49c3739bc95b7eb7 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Fri, 28 May 2021 08:59:43 +0200 Subject: [PATCH 30/37] schemata --- anypointmq/json_schemas/channel.json | 68 +++++----- anypointmq/json_schemas/message.json | 38 ++++++ anypointmq/json_schemas/operation.json | 27 ++++ anypointmq/json_schemas/server.json | 176 ++++--------------------- 4 files changed, 126 insertions(+), 183 deletions(-) diff --git a/anypointmq/json_schemas/channel.json b/anypointmq/json_schemas/channel.json index f64c7b5a..eece0c50 100644 --- a/anypointmq/json_schemas/channel.json +++ b/anypointmq/json_schemas/channel.json @@ -1,36 +1,40 @@ { - "$schema": "http://json-schema.org/draft-07/schema", - "$id": "http://asyncapi.com/anypointmq/bindings/channel.json", - "type": "object", - "title": "Anypoint MQ Channel Binding Object", - "examples": [ - {}, - { - "bindingVersion": "latest" - } - ], - "required": [], - "patternProperties": { - "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "#/definitions/specificationExtension" - } + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/anypointmq/channel.json", + "title": "Channel Schema", + "description": "This object contains configuration for describing an Anypoint MQ exchange, queue, or FIFO queue as an AsyncAPI channel. This objects only contains configuration that can not be provided in the AsyncAPI standard channel object.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "destination": { + "type": "string", + "description": "The destination (queue or exchange) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name in Anypoint MQ. Defaults to the channel name." }, - "properties": { - "bindingVersion": { - "$id": "#/properties/bindingVersion", - "type": "string", - "title": "Anypoint MQ bindings specification version", - "description": "The version of the Anypoint MQ bindings specification that defines the content of this binding object.", - "default": "latest", - "examples": ["latest", "0.0.1"] - } + "destinationType": { + "type": "string", + "enum": ["exchange", "queue", "fifo-queue"], + "default": "queue", + "description": "The type of destination. SHOULD be specified to document the messaging model (publish/subscribe, point-to-point, strict message ordering) supported by this channel." }, - "additionalProperties": true, - "definitions": { - "specificationExtension": { - "description": "Any property starting with x- is valid.", - "additionalProperties": true, - "additionalItems": true - } + "bindingVersion": { + "type": "string", + "enum": [ + "0.0.1" + ], + "description": "The version of this binding. If omitted, 'latest' MUST be assumed." + } + + }, + "examples": [ + { + "destination": "user-signup-exchg", + "destinationType": "exchange", + "bindingVersion": "0.0.1" } -} \ No newline at end of file + ] +} diff --git a/anypointmq/json_schemas/message.json b/anypointmq/json_schemas/message.json index e69de29b..83b03a95 100644 --- a/anypointmq/json_schemas/message.json +++ b/anypointmq/json_schemas/message.json @@ -0,0 +1,38 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/anypointmq/message.json", + "title": "Message Schema", + "description": "This object contains configuration for describing an Anypoint MQ message as an AsyncAPI message. This objects only contains configuration that can not be provided in the AsyncAPI standard message object.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "messageId": { + "type": "string", + "description": "The unique ID of the message. When publishing the message, if not specified, the broker creates a unique message ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section." + }, + "messageGroupId": { + "type": "string", + "description": "The ID of the message group to which the message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section." + }, + "bindingVersion": { + "type": "string", + "enum": [ + "0.0.1" + ], + "description": "The version of this binding. If omitted, 'latest' MUST be assumed." + } + + }, + "examples": [ + { + "messageId": "e0c62826-52d9-4d64-bdd8-a7c415917acf", + "messageGroupId": "42", + "bindingVersion": "0.0.1" + } + ] +} diff --git a/anypointmq/json_schemas/operation.json b/anypointmq/json_schemas/operation.json index e69de29b..90eb0fc3 100644 --- a/anypointmq/json_schemas/operation.json +++ b/anypointmq/json_schemas/operation.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/anypointmq/operation.json", + "title": "Operation Schema", + "description": "This object contains configuration for describing sending or receiving an Anypoint MQ message as an AsyncAPI operation. This objects only contains configuration that can not be provided in the AsyncAPI standard operation object.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "bindingVersion": { + "type": "string", + "enum": [ + "0.0.1" + ], + "description": "The version of this binding. If omitted, 'latest' MUST be assumed." + } + }, + "examples": [ + { + "bindingVersion": "0.0.1" + } + ] +} diff --git a/anypointmq/json_schemas/server.json b/anypointmq/json_schemas/server.json index 1f92b7f2..7fc62633 100644 --- a/anypointmq/json_schemas/server.json +++ b/anypointmq/json_schemas/server.json @@ -1,153 +1,27 @@ { - "$schema": "http://json-schema.org/draft-07/schema", - "$id": "http://asyncapi.com/anypointmq/bindings/server.json", - "type": "object", - "title": "Anypoint MQ Server Binding Object", - "examples": [ - {}, - { - "bindingVersion": "latest", - "proxy": { - "host": "proxy.corporate.com", - "port": 80, - "username": "proxy-user", - "password": "passwd-of-proxy-user" - }, - "sendBufferSize": 1024, - "receiveBufferSize": 2048, - "clientTimeout": 1000, - "sendTCPWithNoDelay": true, - "linger": 1000, - "keepAlive": true, - "connectionTimeout": 10000 - } - ], - "required": [], - "patternProperties": { - "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "bindingVersion": { - "$id": "#/properties/bindingVersion", - "type": "string", - "title": "Anypoint MQ bindings specification version", - "description": "The version of the Anypoint MQ bindings specification that defines the content of this binding object.", - "default": "latest", - "examples": ["latest", "0.0.1"] - }, - "proxy": { - "$id": "#/properties/proxy", - "type": "object", - "title": "HTTP proxy definition", - "description": "Defines use of a HTTP proxy for interactions with the Anypoint MQ broker.", - "default": {}, - "examples": [ - { - "host": "proxy.corporate.com", - "port": 80, - "username": "proxy-user", - "password": "passwd-of-proxy-user" - } - ], - "required": [], - "properties": { - "host": { - "$id": "#/properties/proxy/properties/host", - "type": "string", - "title": "Proxy host", - "description": "Destination host for proxy requests.", - "default": "", - "examples": ["proxy.corporate.com"] - }, - "port": { - "$id": "#/properties/proxy/properties/port", - "type": "integer", - "title": "Proxy port", - "description": "Destination port for proxy requests.", - "default": 80, - "examples": [80,443] - }, - "username": { - "$id": "#/properties/proxy/properties/username", - "type": "string", - "title": "Proxy username", - "description": "Username to authenticate against the proxy.", - "default": "", - "examples": ["proxy-user"] - }, - "password": { - "$id": "#/properties/proxy/properties/password", - "type": "string", - "title": "Proxy password", - "description": "Password to authenticate against the proxy.", - "default": "", - "examples": ["passwd-of-proxy-user"] - } - }, - "additionalProperties": true - }, - "sendBufferSize": { - "$id": "#/properties/sendBufferSize", - "type": "integer", - "title": "Size of socket send buffer", - "description": "Size of the buffer (in bytes) used when sending data, set on the socket itself.", - "examples": [1024] - }, - "receiveBufferSize": { - "$id": "#/properties/receiveBufferSize", - "type": "integer", - "title": "Size of socket receive buffer", - "description": "Size of the buffer (in bytes) used when receiving data.", - "examples": [2048] - }, - "clientTimeout": { - "$id": "#/properties/clientTimeout", - "type": "integer", - "title": "Socket timeout", - "description": "SO_TIMEOUT value on sockets. Indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 indicates an indefinite wait.", - "default": 0, - "examples": [1000] - }, - "sendTCPWithNoDelay": { - "$id": "#/properties/sendTCPWithNoDelay", - "type": "boolean", - "title": "Send data immediately", - "description": "If set, transmitted data is not grouped but sent immediately.", - "default": true, - "examples": [true] - }, - "linger": { - "$id": "#/properties/linger", - "type": "integer", - "title": "Socket linger value", - "description": "SO_LINGER value, which determines how long (in milliseconds) the socket takes to close so that any remaining data is transmitted correctly.", - "examples": [1000] - }, - "keepAlive": { - "$id": "#/properties/keepAlive", - "type": "boolean", - "title": "Keep sockets alive", - "description": "SO_KEEPALIVE behavior on open sockets, which automatically checks open socket connections that are unused for long periods, and closes them if the connection becomes unavailable. This is a property on the socket itself and is used by a server socket to control whether connections to the server are kept alive before they are recycled.", - "default": false, - "examples": [true] - }, - "connectionTimeout": { - "$id": "#/properties/connectionTimeout", - "type": "integer", - "title": "Socket connection timeout", - "description": "Number of milliseconds to wait until an outbound connection to a remote server is successfully created, before failing with a timeout.", - "default": 30000, - "examples": [10000] - } - }, - "additionalProperties": true, - "definitions": { - "specificationExtension": { - "description": "Any property starting with x- is valid.", - "additionalProperties": true, - "additionalItems": true - } + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/anypointmq/server.json", + "title": "Server Schema", + "description": "This object contains configuration for describing an Anypoint MQ broker as an AsyncAPI server. This objects only contains configuration that can not be provided in the AsyncAPI standard server object.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" } -} \ No newline at end of file + }, + "properties": { + "bindingVersion": { + "type": "string", + "enum": [ + "0.0.1" + ], + "description": "The version of this binding. If omitted, 'latest' MUST be assumed." + } + }, + "examples": [ + { + "bindingVersion": "0.0.1" + } + ] +} From c327d2ef9a11b8f31f48c8482f419774dd24c39c Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 10 Jun 2021 11:25:30 +0200 Subject: [PATCH 31/37] corrected message binding object to use schema for headers; fixed some URLs --- anypointmq/README.md | 34 ++++++++++++++++------------ anypointmq/json_schemas/message.json | 14 ++++++++++-- 2 files changed, 31 insertions(+), 17 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 8f0c9617..3737da0f 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -21,7 +21,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S These bindings use the `anypointmq` [protocol](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#definitionsProtocol) in AsyncAPI documents to denote connections to and interactions with Anypoint MQ message brokers. -The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://docs.mulesoft.com/mq/mq-apis#mqbrokerapi). +The Anypoint MQ protocol is based on invocations of the [Anypoint MQ Broker REST API](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-broker/). ## Server Object @@ -153,13 +153,11 @@ The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/m Field Name | Type | Description ---|:---:|--- -`messageId` | string | **Optional**. The unique ID of the message. When publishing the message, if not specified, the broker creates a unique message ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. -`messageGroupId` | string | **Optional**. The ID of the message group to which the message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section. +`headers` | [Schema Object][schemaObject] | **Optional**. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of Anypoint MQ protocol headers are `messageId` and `messageGroupId`. `bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. -Note that message headers, which are specified in the `headers` field of the standard [Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObject), are transmitted in the [Anypoint MQ message `properties` section](https://docs.mulesoft.com/mq/mq-apis#example-publish-a-message). In AsyncAPI, this `headers` field does not include protocol headers such as `messageId` or `messageGroupId`, which are transmitted in the [Anypoint MQ message `headers` section](https://docs.mulesoft.com/mq/mq-apis#postsetup). - -Please note that the definition of this message binding object is likely to change in future versions of this bindings specification to better describe the mapping of the fields of the AsyncAPI standard message object to the various parts of the Anypoint MQ message as it is exchanged as an HTTP body with the Anypoint MQ Broker REST API. +Note that application headers must be specified in the [`headers` field of the standard Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObjectHeaders) and are transmitted in the [`properties` section of the Anypoint MQ message](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-broker/). +In contrast, protocol headers such as `messageId` must be specified in the [`headers` field of the message binding object](#messageBindingObjectHeaders) and are transmitted in the [`headers` section of the Anypoint MQ message](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-broker/). ### Examples @@ -189,8 +187,11 @@ channels: location: $message.header#/correlationId bindings: anypointmq: - messageId: 'e0c62826-52d9-4d64-bdd8-a7c415917acf' - messageGroupId: '42' + headers: + type: object + properties: + messageId: + type: string bindingVersion: '0.0.1' ``` @@ -216,7 +217,7 @@ servers: - oauthDev: [] bindings: anypointmq: - bindingVersion: '0.1.0' + bindingVersion: '0.0.1' production: protocol: anypointmq protocolVersion: v1 @@ -228,7 +229,7 @@ servers: - oauthProd: [] bindings: anypointmq: - bindingVersion: '0.1.0' + bindingVersion: '0.0.1' channels: user/signup: @@ -238,14 +239,14 @@ channels: anypointmq: destination: user-signup-queue destinationType: fifo-queue - bindingVersion: '0.1.0' + bindingVersion: '0.0.1' publish: operationId: signUpUser description: | This application receives command messages via this operation about users to sign up. bindings: anypointmq: - bindingVersion: '0.1.0' + bindingVersion: '0.0.1' message: contentType: application/json headers: @@ -265,9 +266,12 @@ channels: location: $message.header#/correlationId bindings: anypointmq: - messageId: 'e0c62826-52d9-4d64-bdd8-a7c415917acf' - messageGroupId: '42' - bindingVersion: '0.1.0' + headers: + type: object + properties: + messageId: + type: string + bindingVersion: '0.0.1' components: securitySchemes: diff --git a/anypointmq/json_schemas/message.json b/anypointmq/json_schemas/message.json index 83b03a95..2969b01d 100644 --- a/anypointmq/json_schemas/message.json +++ b/anypointmq/json_schemas/message.json @@ -11,6 +11,10 @@ } }, "properties": { + "headers": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "description": "A Schema object containing the definitions for Anypoint MQ-specific headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of Anypoint MQ protocol headers are 'messageId' and 'messageGroupId'." + }, "messageId": { "type": "string", "description": "The unique ID of the message. When publishing the message, if not specified, the broker creates a unique message ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section." @@ -30,8 +34,14 @@ }, "examples": [ { - "messageId": "e0c62826-52d9-4d64-bdd8-a7c415917acf", - "messageGroupId": "42", + "headers": { + "type": "object", + "properties": { + "messageId": { + "type": "string" + } + } + }, "bindingVersion": "0.0.1" } ] From a8de5daa849b5cb0876f7ef949d5b2153b07d9c6 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 10 Jun 2021 11:29:38 +0200 Subject: [PATCH 32/37] fixed schema object link --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 3737da0f..8db8b790 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -153,7 +153,7 @@ The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/m Field Name | Type | Description ---|:---:|--- -`headers` | [Schema Object][schemaObject] | **Optional**. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of Anypoint MQ protocol headers are `messageId` and `messageGroupId`. +`headers` | [Schema Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject) | **Optional**. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of Anypoint MQ protocol headers are `messageId` and `messageGroupId`. `bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. Note that application headers must be specified in the [`headers` field of the standard Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObjectHeaders) and are transmitted in the [`properties` section of the Anypoint MQ message](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-broker/). From bba62d0fc284d2c7834350eceef1b32edb84977f Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Thu, 10 Jun 2021 12:27:16 +0200 Subject: [PATCH 33/37] fix leftover props --- anypointmq/json_schemas/message.json | 8 -------- 1 file changed, 8 deletions(-) diff --git a/anypointmq/json_schemas/message.json b/anypointmq/json_schemas/message.json index 2969b01d..fa63cb5d 100644 --- a/anypointmq/json_schemas/message.json +++ b/anypointmq/json_schemas/message.json @@ -15,14 +15,6 @@ "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", "description": "A Schema object containing the definitions for Anypoint MQ-specific headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of Anypoint MQ protocol headers are 'messageId' and 'messageGroupId'." }, - "messageId": { - "type": "string", - "description": "The unique ID of the message. When publishing the message, if not specified, the broker creates a unique message ID. This is transmitted as a protocol header in the Anypoint MQ message `headers` section." - }, - "messageGroupId": { - "type": "string", - "description": "The ID of the message group to which the message belongs. Applies only to FIFO queues. Message group IDs can contain up to 128 alphanumeric and punctuation characters. This is transmitted as a protocol header in the Anypoint MQ message `headers` section." - }, "bindingVersion": { "type": "string", "enum": [ From 0b7b79688a7b540e0091c30eb9082923ec8ad9ef Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Tue, 27 Jul 2021 12:16:30 +0200 Subject: [PATCH 34/37] removing mention of AsyncAPI version As requested, removing mention of AsyncAPI version (`2.1.0`) this binding spec was developed against/for. --- anypointmq/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 8db8b790..44d53067 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -11,8 +11,6 @@ The version of this bindings specification is `0.0.1`. This is also the `bindingVersion` for all binding objects defined by this specification. In any given binding object, `latest` MAY alternatively be used to refer to the currently latest published version of this bindings specification. -The version of the AsyncAPI specification to which these bindings apply is `2.1.0`. - ## Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). From e1b1abf2571a7e8a3c8ff4dae65c841dd31fda1a Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 25 Aug 2021 18:23:38 +0200 Subject: [PATCH 35/37] eliminated server and operation binding objects as demanded by @derberg --- anypointmq/README.md | 72 ++------------------------------------------ 1 file changed, 2 insertions(+), 70 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 44d53067..196df062 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -37,38 +37,7 @@ Note that the choice of a particular Anypoint MQ client app (via its client ID a ## Server Binding Object -The Anypoint MQ [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverBindingsObject) is defined by a [JSON Schema](json_schemas/server.json), which currently defines only the *optional* `bindingVersion` field: - -Field Name | Type | Description ----|:---:|--- -`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. - -### Examples - -The following example shows a `servers` object with two servers, both using `anypointmq` as the `protocol`, the second having a server binding object for `anypointmq`: - -```yaml -servers: - development: - url: https://mq-us-east-1.anypoint.mulesoft.com/api - description: | - Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane under management of the US control plane. - Implicitly uses v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. - Minimal configuration, omitting a server binding object. - protocol: anypointmq - - production: - url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api - description: | - Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane under management of the EU control plane. - Explicitly specifies the use of v1 of the anypointmq protocol and hence the Anypoint MQ Broker REST API. - Explicitly provides a server binding object. - protocol: anypointmq - protocolVersion: v1 - bindings: - anypointmq: - bindingVersion: '0.0.1' -``` +This object MUST NOT contain any properties. Its name is reserved for future use. ## Channel Binding Object @@ -111,38 +80,7 @@ channels: ## Operation Binding Object -The Anypoint MQ [Operation Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#operation-bindings-object) is defined by a [JSON Schema](json_schemas/operation.json), which currently defines only the *optional* `bindingVersion` field: - -Field Name | Type | Description ----|:---:|--- -`bindingVersion` | string | **Optional**, defaults to `latest`. The version of this binding. - -### Examples - -The following example shows a `channels` object with two channels, each having one operation (`subscribe` or `publish`). Only the `subscribe` operation has an operation binding object for `anypointmq`: - -```yaml -channels: - user/signup: - publish: - operationId: signUpUser - description: | - This application receives command messages via this operation about users to sign up. - Minimal configuration, omitting an operation binding object. - message: - #... - user/signedup: - subscribe: - operationId: userHasSignedUp - description: | - This application sends events via this operation about users that have signed up. - Explicitly provides an operation binding object. - bindings: - anypointmq: - bindingVersion: '0.0.1' - message: - #... -``` +This object MUST NOT contain any properties. Its name is reserved for future use. ## Message Binding Object @@ -213,9 +151,6 @@ servers: under management of the US control plane. security: - oauthDev: [] - bindings: - anypointmq: - bindingVersion: '0.0.1' production: protocol: anypointmq protocolVersion: v1 @@ -242,9 +177,6 @@ channels: operationId: signUpUser description: | This application receives command messages via this operation about users to sign up. - bindings: - anypointmq: - bindingVersion: '0.0.1' message: contentType: application/json headers: From b9c46ed9b8cf7ed833c6fe0ca6212d0561fd2ff7 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 25 Aug 2021 18:24:37 +0200 Subject: [PATCH 36/37] Delete server.json --- anypointmq/json_schemas/server.json | 27 --------------------------- 1 file changed, 27 deletions(-) delete mode 100644 anypointmq/json_schemas/server.json diff --git a/anypointmq/json_schemas/server.json b/anypointmq/json_schemas/server.json deleted file mode 100644 index 7fc62633..00000000 --- a/anypointmq/json_schemas/server.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "http://asyncapi.com/bindings/anypointmq/server.json", - "title": "Server Schema", - "description": "This object contains configuration for describing an Anypoint MQ broker as an AsyncAPI server. This objects only contains configuration that can not be provided in the AsyncAPI standard server object.", - "type": "object", - "additionalProperties": false, - "patternProperties": { - "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" - } - }, - "properties": { - "bindingVersion": { - "type": "string", - "enum": [ - "0.0.1" - ], - "description": "The version of this binding. If omitted, 'latest' MUST be assumed." - } - }, - "examples": [ - { - "bindingVersion": "0.0.1" - } - ] -} From 03cf86591e0ebffed997d715c5cb0bf0286514d1 Mon Sep 17 00:00:00 2001 From: Gerald Loeffler Date: Wed, 25 Aug 2021 18:25:14 +0200 Subject: [PATCH 37/37] Delete operation.json --- anypointmq/json_schemas/operation.json | 27 -------------------------- 1 file changed, 27 deletions(-) delete mode 100644 anypointmq/json_schemas/operation.json diff --git a/anypointmq/json_schemas/operation.json b/anypointmq/json_schemas/operation.json deleted file mode 100644 index 90eb0fc3..00000000 --- a/anypointmq/json_schemas/operation.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "http://asyncapi.com/bindings/anypointmq/operation.json", - "title": "Operation Schema", - "description": "This object contains configuration for describing sending or receiving an Anypoint MQ message as an AsyncAPI operation. This objects only contains configuration that can not be provided in the AsyncAPI standard operation object.", - "type": "object", - "additionalProperties": false, - "patternProperties": { - "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" - } - }, - "properties": { - "bindingVersion": { - "type": "string", - "enum": [ - "0.0.1" - ], - "description": "The version of this binding. If omitted, 'latest' MUST be assumed." - } - }, - "examples": [ - { - "bindingVersion": "0.0.1" - } - ] -}