feat: request/response support

[GreenRover]

Title: "Request/Response paradigm support in operation"
Related issue(s): #94 #558
Champion: @GreenRover

---

Explanation of Problem & Solution:
Very common type of operation is currently missing in specification per discussion in referenced (related) issues. Operation that results in direct or indirect response to the caller.
The most basic example is publishing a message, where the result of publish operation should be known as soon as possible to the caller. Eg. invoking operation on given channel will return the specific message (or oneOf messages) right away to the caller.
The complicated example is correlation of the request and response, where publish/subscribe operation with given message will result in the specific message to be delivered back to the caller via different channel.

Solution has two parts:

1. Allowing referencing single or multiple messages as a result to operation (indifferent to whether the operation is server or client initiated)
2. Allowing hinting single or multiple messages that can be expected by other party to be received as a result to using specific message in any kind of operation

---

Please consume before take part to discussion:

• https://www.youtube.com/watch?v=koLWWoBnIMo

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[GreenRover]

@smarek Do you like to review this pr?

[smarek]

@GreenRover thank you for tagging me, but i've lost interest long time ago, because the whole process (discussion, calls, revisions...) took too long and in the end my proposal was discarded in favor of writing the whole thing over in next major version of AsyncAPI. I wish you all the luck in progressing with this feature.

[GreenRover]

@smarek I know, this is the attempt for the next major. Only wanted to ask you this pr would match all your requirements.

irony: And its is not take this long, we only started discussions 5 month ago.

[derberg]

left some comments, I'm basically full of doubts 😄

[derberg]

@GreenRover

Hey, I have few requests:

• please solve merge conflicts
• remove message.type from kraken example
• please remove the headers that you added to this example, and showcase of replyChannel. Kraken is websocket example, where headers are not present, so it will be super confusing. Try to modify existing Kafka example, streetlight maybe, to showcase the new feature. Maybe you want to use this real example from Adeo -> https://github.com/asyncapi/website/pull/921/files#diff-302cb646d6acc811c39f82cf0045abcad5d4dd223635c0520d37660df218b857 that uses req/reply with workaround description

[GreenRover]

@derberg

• remove message.type from kraken example
  done.

so for websocket use case replyChannel do not help much, as there is one channel anyway
ok i will remove this but in case of websocket is a correlationId also not überfüll (not added by me)

migrate streetlight-kafak to async api v3
I can not do that i have no idea how to migrate the channel traits. Some one else need to migrate the examples first.

adeo
sorry i dont see there a proper sample. Dont like to add this by my own, this will end in having this pr open for ever.
Just add the samples to the next-major-spect branch and i will add async api related parts.

[GreenRover]

Branch is merge ready again

[derberg]

@GreenRover

ok i will remove this but in case of websocket is a correlationId also not überfüll (not added by me)

sorry I didn't get it. CorrelationId example was not added originally to Kraken example -> https://www.asyncapi.com/blog/websocket-part2#lets-have-a-look-at-the-final-document

I can not do that i have no idea how to migrate the channel traits. Some one else need to migrate the examples first.

fair point. You contribute a feature to 3.0, but there are other features already and examples are not adjusted accordingly. I forgot about it.

sorry i dont see there a proper sample. Dont like to add this by my own, this will end in having this pr open for ever.
Just add the samples to the next-major-spect branch and i will add async api related parts.

the point is that I would like us to make sure that we merge req/rep when we have it presented in real life examples, to make sure they actually make point. I'm happy to help with Adeo. I know how they workaround req/rep there, and also have direct contact with owners. So I definitely would love to take up a challenge to take Adeo's file and migrate to current 3.0 with reg/repl

[fmvilas]

We had a great conversation in the Spec 3.0 meeting yesterday. If you're interested, here's the recording: https://www.youtube.com/watch?v=koLWWoBnIMo.

Summary of the meeting

We tried many different approaches to define request/reply interactions but we weren't happy with any of them. @GreenRover kindly added a few more examples to this PR so we can improve the discussion here.

[char0n]

Great significant work here!

[char0n]

I have NOTE regarding description wording:

This PR introduces following sentence (among others)

A list of $ref pointers pointing to the supported

Although this is consistent with other descriptions within the spec (search for "$ref point" string), wouldn't better wording be?:

A list of Reference Objects referencing supported

Reasoning:

We should refer to things as they are defined within the spec. Reference Object is Reference Object, and we should probably not introduce new synonymous nomenclature like $ref pointer. Reference Object references other components and not points to them.

This is something to be discussed in separated issue, if it is agreed that this is something that we want to address.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[GreenRover]

@fmvilas Please approve again. Thant i have 3 contributor and can merge.

[fmvilas]

I completely agree, @char0n. Let's do it in a separate PR.

[fmvilas]

Great work, @GreenRover! Feel free to merge now! 🚀

[GreenRover]

/ready-to-merge

[asyncapi-bot]

🎉 This PR is included in version 3.0.0-next-major-spec.10 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[jonaslagoni]

😱 It's merged!? 😆

Finally 🔥! Well done @GreenRover and what a patience 😄

[smoya]

Correct me if I'm wrong @GreenRover.

I noticed we still have this PR pending with changes in JSON Schema files #847
Also, we need to update the parser in https://github.com/asyncapi/parser-js/tree/next-major-spec

Are you going to work on it?

[GreenRover]

@smoya Currently i focus on next spec 3.0 feature, #622.
And waiting for spec.json 3.0. (No idea how i can contribute to spec.json)
Than i plan to contribute to parser-js.
Maybe later to modelina but have a need to get asyncapi-react 3.0 ready soon.
So if you like to boostrap me some how. Please do so.

[jonaslagoni]

Added an issue for the parser here: asyncapi/parser-js#732