NEXT-31249 - async low priority queue documentation

guides/hosting/infrastructure/message-queue.md

@@ -41,6 +41,12 @@ You can configure the command just to run a certain amount of time and to stop i
 bin/console messenger:consume async --time-limit=60 --memory-limit=128M
 ```
 
+You can also configure the command to consume messages from multiple transports as it is recommended:
+
+```bash
+bin/console messenger:consume async async_low_priority
+```
+
 For more information about the command and its configuration, use the -h option:
 
 ```bash
@@ -77,7 +83,7 @@ User=www-data # Change this to webserver's user name
 Restart=always
 # Change the path to your shop path
 WorkingDirectory=/var/www/html
-ExecStart=php /var/www/html/bin/console messenger:consume --time-limit=60 --memory-limit=512M async
+ExecStart=php /var/www/html/bin/console messenger:consume --time-limit=60 --memory-limit=512M async async_low_priority
 
 [Install]
 WantedBy=shopware_consumer.target
@@ -116,7 +122,7 @@ shopware:
     admin_worker:
         enable_admin_worker: true
         poll_interval: 30
-        transports: ["async"]
+        transports: ["async", "async_low_priority"]
 ```
 
 ## Sending mails over the message queue
@@ -143,6 +149,7 @@ You can find all available transport options in the Symfony Messenger documentat
 Following environment variables are in use out of the box:
 
 * `MESSENGER_TRANSPORT_DSN` - The DSN to the transport to use (e.g. `doctrine://default`).
+* `MESSENGER_TRANSPORT_LOW_PRIORITY_DSN` - The DSN to the transport to use for low priority messages (e.g. `doctrine://default?queue_name=async_low_priority`).
 * `MESSENGER_TRANSPORT_FAILURE_DSN` - The DSN to the transport to use for failed messages (e.g. `doctrine://default?queue_name=failed`).
 
 ## Worker count for efficient message processing

guides/plugins/plugins/framework/message-queue/add-message-handler.md

@@ -49,7 +49,14 @@ There is a console command to start a worker that will receive incoming messages
 bin/console messenger:consume async
 ```
 
-Where `async` is the transport you want to consume message from. There is also an API-Route that lets you consume messages for a given transport. Just post to the route `/api/_action/message-queue/consume` and define the transport from which you want to consume:
+You can also append more transports to the command, so the worker will consume messages from multiple transports:
+
+```bash
+// 
+bin/console messenger:consume async async_low_priority
+```
+
+Where `async` and `async_low_priority` are the transports you want to consume messages from. There is also an API-Route that lets you consume messages for a given transport. Just post to the route `/api/_action/message-queue/consume` and define the transport from which you want to consume:
 
 ```js
 // on
@@ -77,12 +84,12 @@ The recommended way to consume messages is through the cli command. You can conf
 
 ```bash
 // 
-bin/console messenger:consume async --time-limit=60
+bin/console messenger:consume async async_low_priority --time-limit=60
 ```
 
 ```bash
 // 
-bin/console messenger:consume async --memory-limit=128M
+bin/console messenger:consume async async_low_priority --memory-limit=128M
 ```
 
 For more information about the command and its configuration use the `-h` option:
@@ -172,7 +179,7 @@ shopware:
     admin_worker:
         enable_admin_worker: true
         poll_interval: 30
-        transports: ["async"]
+        transports: ["async", "async_low_priority"]
 ```
 
 ## Next steps

guides/plugins/plugins/framework/message-queue/add-message-to-queue.md

@@ -23,7 +23,7 @@ As most guides, this guide is also built upon the [Plugin base guide](../../plug
 
 ## Create a message
 
-First, we have to create a new message class in the directory `<plugin root>/MessageQueue/Message`. In this example, we create a `SmsNotification` that contains a string with content. By default, all messages are handled synchronously, to change the behavior to asynchronously we have to implement the `AsyncMessageInterface` interface.  
+First, we have to create a new message class in the directory `<plugin root>/MessageQueue/Message`. In this example, we create a `SmsNotification` that contains a string with content. By default, all messages are handled synchronously, to change the behavior to asynchronously we have to implement the `AsyncMessageInterface` interface. For more information about asynchronous messages, have a look at our guide about [Handling asynchronous messages](handle-asynchronous-messages.md). 
 
 Here's an example:
 

guides/plugins/plugins/framework/message-queue/handle-asynchronous-messages.md

@@ -0,0 +1,57 @@
+---
+nav:
+  title: Handle asynchronous messages
+  position: 40
+
+---
+
+# Handle asynchronous messages
+
+## Overview
+
+In this guide you will learn how to handle asynchronous messages and the difference between the asynchronous queues.
+
+## Prerequisites
+
+This guide is built upon the [Add message to queue guide](add-message-to-queue), so you should have read that first.
+
+## Different queues
+
+Currently, there are two different queues for asynchronous messages. The first one is the "async" queue which can be used if a message implements the `AsyncMessageInterface` as mentioned in [Create a message](add-message-to-queue#create-a-message).  
+
+The second queue is the "async_low_priority" queue which will also handle the messages asynchronously, but with a lower priority, as this queue should be handled once the "async" queue is empty. This queue can be used if a message implements the `AsyncLowPriorityMessageInterface`.  
+
+Here's an example:
+
+```php
+// <plugin root>/src/MessageQueue/Message/EmailNotification.php
+<?php declare(strict_types=1);
+
+namespace Swag\BasicExample\MessageQueue\Message;
+
+use Shopware\Core\Framework\MessageQueue\AsyncLowPriorityMessageInterface;
+
+class EmailNotification implements AsyncLowPriorityMessageInterface
+{
+    private string $content;
+
+    public function __construct(string $content)
+    {
+        $this->content = $content;
+    }
+
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+}
+```
+
+## Retry strategies
+
+Both queues have the same retry strategy. If a message fails to be handled, it will be retried up to 3 times with a starting delay of 1 second, doubling after each retry. After the third retry, the message will be moved to the "failed" queue. 
+
+## More interesting topics
+
+* [Message Queue](add-message-to-queue)
+* [Message Handler](add-message-handler)