Support for custom/undocumented binding models

[dpwdec]

As I understand it, the models that can be used in the bindings property of a channel/publish/subscribe are defined in the AsyncAPI Bindings repo (please correct me if this is not the process for adding binding models to this project). Furthermore, if a user has a spec that makes use of bindings that are not part of these officially defined bindings (and therefore not part of the models) then these bindings will not be parsed at all.

There are three ways that this manifests:

1. Bindings in wide circulation that are not yet finalised. For example, we are using sns and sqs bindings in anger in our specs, however the PR to finalise them as part of the AsyncAPI bindings spec has been open for almost two years after much discussion, I'm currently working to close it but its a long road for these sorts of widely used bindings and in the mean time being locked out of any use in a project like this is a big discouragement to migrate
2. Proprietary bindings For example, we use bindings to define mirror topics in Kafka. This is a confluent specific technology so I believe there's an open question about whether these are appropriate to be defined as part of the main binding definitions. Irregardless, again, this type of infrastructure definition is wide spread and people are using it, not be able to parse it in a library like this is problematic.
3. Custom Internal Bindings For example, we have some internal bindings used for defining configuration specific to internal events tooling we have developed for our own engineers, these are an essential part of the spec for our use case, but this can never be official supported by a binding definition. Still, we make use of them in almost every events based infrastructure definition and would like to parse them using the AsyncAPI.NET library.

At the moment the work around for this, I believe, would be the very confusing route of using x- extension objects outside of the bindings object due to the fact that it seems bindings does not support extensions. This is confusing for users and does not match the spec in any reasonable way.

My question then: Is there currently a better way to parse bindings that are not part of the official AsyncAPI binding definitions and by extension not included in the models that make up binding definitions in AsyncAPI.NET?

If not, is it appropriate to add this to the project in a similar way to how x- extension properties are handled in the rest of the spec?

[VisualBean]

To answer your question briefly.
There is currently no way to do this.
We, in my team, has been using extensions extensively (no pun intended) for this, but later contributed specific bindings for the technology we are using (Apache Pulsar), to get the support we needed.

For AsyncAPI.Net, we only support the binding types that have been added specifically to the project, which at this point, is not a lot. - Its on the todo to be feature complete with the asyncapi bindings repo, though.

I want to do 2 things (The second based slightly off this issue, but it fits nicely into the bigger picture);

1. Put bindings in a separate package altogether. This hooks nicely into the second thing.
2. Provide an extensibility hook for custom bindings.

[dpwdec]

@VisualBean

we only support the binding types that have been added specifically to the project

Just for complete clarity, do you expect these to match up with what is documented in AsyncAPI bindings repo? Or could I just contribute sns/sqs bindings now before the specification for AsyncAPI is merged? (Similar for things like mirror topics that might never get an official binding but are sort of "semi-official")

I want to do 2 things (The second based slightly off this issue, but it fits nicely into the bigger picture);

1. Put bindings in a separate package altogether. This hooks nicely into the second thing.
2. Provide an extensibility hook for custom bindings.

Do you have a road map for this? My team is pretty keen in migrating and I have capacity to put work into this. So if you can point me in the right direction I could probably justify doing some of the work to facilitate this if there's currently a path open for it.

[VisualBean]

.. Do you expect these to match up with what is documented in AsyncAPI bindings repo?

I don't mind them getting into this repo, before they are merged - we did the same with the Pulsar Bindings, as long as they are 'stable' and just waiting for final confirmation.

Do you have a road map for this? My team is pretty keen in migrating and I have capacity to put work into this.

I do not, I can however safely say that it will be the next that will be done.
I plan on spending some time this weekend to figure out how we can safely manage this move, as currently we are fairly hard coupled to an Enum for the bindings, but it shouldn't be massively complex, as we already have parsing hooks for the extensions (as mentioned).

I think you can safely contribute the bindings in question, to this repository.

[dpwdec]

Thank you so much for speedy and helpful responses. I will move towards adding bindings to the repo for now, and keep an eye on the hooks stuff!

[VisualBean]

@dpwdec

Ive made a draft PR with how I think its going to end up
You can take a look at the Test I wrote for the custom bindings
https://github.com/LEGO/AsyncAPI.NET/blob/ce579127634ba25a6ede158cb5551d5b214fc5ad/test/LEGO.AsyncAPI.Tests/Bindings/CustomBinding_Should.cs

Effectively all bindings will be implemented like this. Where the official ones will live in a Bindings package, and they can be added to reading by pushing them to the bindings list in ReaderSettings. Or they can be written, by simply using them.

Let me know what you think.

[dpwdec]

@VisualBean Looks great!! Thank you so much for doing this. 🙏

So essentially the workflow would be to define a new binding with a generic T that matches whatever additional binding you want to introduce and then register that with the AsyncApiReaderSettings or my adding to the appropriate AsyncAPI model?

Also, one question I have is Do these generic bindings support x- extension properties automatically? I'm still getting to grips with the code base and I couldn't tell just from looking through your PR?

[VisualBean]

Exactly
class HttpChannelBinding : ChannelBinding<HttpChannelBinding> and you are ready to implement.
This mostly to get around the FixedFieldMap typing. - although it does look a bit odd, from an API point of view.

They will automatically work for Writing, but you will have to call writer.WriteExtensions(this.Extensions) in SerializeV2WithoutReference() for the reads.

Im still trying to figure out if we can make it neater still though.

[VisualBean]

This has been fixed