Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: introducing request/reply #2071

Closed
wants to merge 16 commits into from

Conversation

jonaslagoni
Copy link
Member

Description
This PR adds a page introducing request/reply concept with AsyncAPI

Related issue(s)

Related to #1434

@netlify
Copy link

netlify bot commented Aug 16, 2023

Deploy Preview for shimmering-choux-eb0798 ready!

Name Link
🔨 Latest commit 85238db
🔍 Latest deploy log https://app.netlify.com/sites/shimmering-choux-eb0798/deploys/64ef3740c4f3e4000771cae1
😎 Deploy Preview https://deploy-preview-2071--shimmering-choux-eb0798.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@jonaslagoni jonaslagoni changed the title feat: add request and reply getting started feat: add getting started with request and reply Aug 16, 2023
@akshatnema akshatnema linked an issue Aug 16, 2023 that may be closed by this pull request
@quetzalliwrites
Copy link
Member

quetzalliwrites commented Aug 17, 2023

  1. This is not a tutorial, so we must move this to an appropriate content bucket. 🙂
  2. Great info! This seems more relevant for the concept or guide content buckets in docs.
  3. Because this doesn't fit the flow and steps we have in our "Getting Started" quickstart, the title of this PR also needs adjustment. (fixed this PR title accordingly)
  4. It's not feat but docs for this PR title, since you're submitting documentation.

@quetzalliwrites quetzalliwrites changed the title feat: add getting started with request and reply docs: introducing request/reply Aug 17, 2023
@quetzalliwrites quetzalliwrites added 📑 docs area/docs Specify what technical area given issue relates to. Its goal is to ease filtering good first issues. labels Aug 17, 2023
Copy link
Member

@quetzalliwrites quetzalliwrites left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a few corrections for you to address in my preliminary review, make sure to leave you detailed feedback to help get you started. Thank you for your contribution! ✨

jonaslagoni and others added 8 commits August 17, 2023 11:53
Co-authored-by: Alejandra Quetzalli  <alejandra.olvera.novack@gmail.com>
Co-authored-by: Alejandra Quetzalli  <alejandra.olvera.novack@gmail.com>
Co-authored-by: Sergio Moya <1083296+smoya@users.noreply.github.com>
@jonaslagoni
Copy link
Member Author

jonaslagoni commented Aug 17, 2023

  1. Great info! This seems more relevant for the concept or guide content buckets in docs.
  2. Because this doesn't fit the flow and steps we have in our "Getting Started" quickstart, the title of this PR also needs adjustment. (fixed this PR title accordingly)

@alequetzalli Hmm, I kinda disagree with you here, cause it is getting started with request/reply in a similar fashion as https://www.asyncapi.com/docs/tutorials/getting-started/asyncapi-documents is.

Concept does not make much sense as this is ONLY related to how you do it AsyncAPI and not explaining the underlying concept of how request/reply works 🤔

Guide could be yea, we just don't have anything yet that details how to use specific features in AsyncAPI documents, so it might seem misplaced a bit 🤔

But you have a better overview of the docs and what needs to be where, so just let me know where I should move it to and I will do it 👍

Copy link
Contributor

@AnimeshKumar923 AnimeshKumar923 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I have reviewed this from my end.
  • Had some difficulties and have pinged Alejandra and Fran for the same.
  • Please provide your feedback. 🙏 @alequetzalli @fmvilas

pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved
pages/docs/tutorials/getting-started/request-reply.md Outdated Show resolved Hide resolved

## Multiple messages over the same channel with request/reply

In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation.
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to explicitly define your operations and which messages are used for each operation.

I'm having difficulty re-wording this. Please take a look @alequetzalli @fmvilas

jonaslagoni and others added 2 commits August 29, 2023 15:00
weight: 20
---

A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier** which receives the request and responds with a reply.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier** which receives the request and responds with a reply.
A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier**, which receives the request and responds with a reply.


## Describing a requester

We are going to use a very simple ping and pong example where a requester sends the ping and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We are going to use a very simple ping and pong example where a requester sends the ping and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`.
We are going to use a very simple ping and pong example where a requester sends the ping, and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`.

$ref: '#/channels/pong'
```

The `reply` section defines all the necessary information to properly reply to the request, such as where to, and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `reply` section defines all the necessary information to properly reply to the request, such as where to, and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject)
The `reply` section defines all the necessary information to properly reply to the request, such as where to and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object.](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject)


In the simple example above, we saw how you could set up a request/reply pattern across two applications where one application is the requester and the other is the replier.

However, in an protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
However, in an protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables.
However, in a protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables.


The request/reply can also occur over the same channel (for example `/`), which could be HTTP or WebSocket.

To do this it's as simple as having both channels use the same address.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To do this it's as simple as having both channels use the same address.
To do this, it's as simple as having both channels use the same address.

Copy link
Contributor

@AnimeshKumar923 AnimeshKumar923 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Just had a look at the document.
  • Some minor corrections (and a confusion from my end at line 207)


In some cases, we do not know the reply channel at design time, but instead, it's dynamically determined at runtime. This could, for example, be using the request message payload or header to dictate the response address.

Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes as you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of where to send the reply is located dynamically in the message header under `replyTo`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes as you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of where to send the reply is located dynamically in the message header under `replyTo`.
Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes, but you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of 'where to send the reply' is located dynamically in the message header under `replyTo`.
  • Is this format appropriate? I think the where to send the reply can be wrapped in some quotations or some sort of re-wording can be done but I'm not sure how to approach it.
  • Requesting your assistance @alequetzalli


In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation.

The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defined the request message among the available channel messages and the same for the reply.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defined the request message among the available channel messages and the same for the reply.
The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defines the request message among the available channel messages and the same for the reply.

defined or defines? @alequetzalli

Copy link

@GreenRover GreenRover left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a technical point of view, it looks very good. Unfortunately I can't check the spelling.


## Request/reply with dynamic response channel

In some cases, we do not know the reply channel at design time, but instead, it's dynamically determined at runtime. This could, for example, be using the request message payload or header to dictate the response address.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May be mention that this pattern is mostly used when:
You have multiple possible requestor ant want archive that you only receive responses your requested.
With an static response address all possible requestor will receive the responses from every one and need to filter by correlation id, if the received response is one that match a question of your self.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hint there are even 2 sub types.
Type 1: The process defines an inbox on process startup to receive only responses where it self didt the request for. But also need an correlationId to assign the response to the correct Programm thread. Assuming that the application is not single threaded and blocking.
Type 2: The inbox will be created dedicated for each requests. Than there is no need for an correlationId.

@jonaslagoni jonaslagoni closed this Oct 9, 2023
@jonaslagoni jonaslagoni reopened this Oct 9, 2023
@jonaslagoni
Copy link
Member Author

jonaslagoni commented Oct 9, 2023

There are plans to rewrite the entire thing into something different by Rohit and @alequetzalli, so I am closing the PR and releasing the content (almost) as is, on my own website so it's not goes to waste and creates a bit of hype 🙂

@jonaslagoni jonaslagoni closed this Oct 9, 2023
@jonaslagoni jonaslagoni deleted the request_reply branch October 16, 2024 09:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/docs Specify what technical area given issue relates to. Its goal is to ease filtering good first issues. 📑 docs
Projects
Status: Community PR under Review 🧐
Development

Successfully merging this pull request may close these issues.

docs: request/reply
6 participants