feat: add new channels object #827
Conversation
fmvilas
requested review from
derberg,
dalelane and
asyncapi-bot-eve
as code owners
|
@GreenRover this PR should unblock your request/reply work. |
|
/progress 60 New |
| @@ -162,7 +162,7 @@ Field Name | Type | Description | |||
| <a name="A2SInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. | |||
| <a name="A2SServers"></a>servers | [Servers Object](#serversObject) | Provides connection details of servers. | |||
| <a name="A2SDefaultContentType"></a>defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. | |||
| <a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API. | |||
| <a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). | |||
There was a problem hiding this comment.
Notice channels is not required anymore.
| <a name="channelItemObjectPublish"></a>publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. | ||
| <a name="channelItemObjectParameters"></a>parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). | ||
| <a name="channelItemObjectBindings"></a>bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. | ||
| <a name="channelObjectAddress"></a>address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). |
There was a problem hiding this comment.
Address is no longer a URL template and, instead, it's just a plain string that supports Channel Address Expressions.
|
|
||
|
|
||
| Using explicit by-name references to the servers on which the channel is available: | ||
| #### <a name="channelAddressExpressions"></a>Channel Address Expressions |
There was a problem hiding this comment.
I went all-in defining our own templating rules here. I don't know what I was thinking when I defined the channel address as a URL template in version 2.0.0 😅 Have a look: https://www.rfc-editor.org/rfc/rfc6570#section-2.4.2.
spec/asyncapi.md
Outdated
|
|
||
| Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. | ||
|
|
||
| When the channel address contains [delimiters](#channelObjectAddressDelimiter), the expressions MUST be surrounded by either the delimiters, the beginning of the string, or the end of the string. E.g., assuming a `.` (dot) delimiter, `users.{userId}` is correct but `users.id{userId}` is not. |
There was a problem hiding this comment.
This is covering most of the protocols supporting any form of wildcards: AMQP, MQTT, NATS, etc. It's still missing a Kafka feature that lets you subscribe to a regular expression. I tried to map it here but it's too complex and therefore left it out.
If you got any ideas on how to do it, I'm all ears. Otherwise, I'll open a follow-up issue and this can be included in future versions.
If you're curious, I came up with a solution like users_{userId:/[\w\d]{8}/i} but quickly got trapped in the differences between regular expression engines hole.
Kafka protocol doesn't define anything so it's hard for us to make a commitment here. Maybe go for the engine with fewer features, just to make sure everything is supported in every engine? Coming up with a subset ourselves? Should we just forget about it? Hot topic!
|
@derberg I addressed all the feedback. Let me know what you think now. |
|
|
||
| Describes the operations available on a single channel. | ||
| Describes a shared communication channel. |
There was a problem hiding this comment.
A shared communication channel with who? Am I the only one who feels like this sentence is incomplete in some way... 🤔
There was a problem hiding this comment.
We don't know in advance. We only know it's gonna be shared 🤷
|
Kudos, SonarCloud Quality Gate passed!
|
|
/rtm |
|
😱 😄 |
|
@derberg It didn't create any release candidate. Is it expected? |
|
no, mainly because the fix I did in release pipeline did not go to |
Related issue(s):
#663
#682
#618