From 212c421680e55adcf3c5de83e1a2fa65bed4cbe9 Mon Sep 17 00:00:00 2001 From: bota Date: Fri, 5 Sep 2025 11:31:38 +0300 Subject: [PATCH 1/5] Issue #10: added documentation for dlq and messenger configuration Signed-off-by: bota --- docs/book/v1/control-commands.md | 7 ++-- docs/book/v1/messenger-configuration.md | 53 +++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 58 insertions(+), 3 deletions(-) create mode 100644 docs/book/v1/messenger-configuration.md diff --git a/docs/book/v1/control-commands.md b/docs/book/v1/control-commands.md index 44e862b..24e92a5 100644 --- a/docs/book/v1/control-commands.md +++ b/docs/book/v1/control-commands.md @@ -4,7 +4,7 @@ The commands available are: 1. `GetFailedMessagesCommand.php (failed)` - returns logs with messages that failed to process (levelName:error) 2. `GetProcessedMessagesCommand.php (processed)` - returns logs with messages that were successfully processed (levelName:info) -3. `GetQueuedMessagesCommand (inventory)` - returns all queued messages from Redis stream 'messages' +3. `GetQueuedMessagesCommand (inventory)` - returns all queued messages from Redis streams, in this case `messages` or `failed` The commands can be run in two different ways: @@ -21,7 +21,7 @@ php bin/cli.php processed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int ``` ```shell -php bin/cli.php inventory +php bin/cli.php inventory --stream="messages or failed" ``` ## TCP message @@ -47,5 +47,6 @@ echo "control" | socat -t1 - TCP:host:port > Using `-t1` flag is not necessary but can be useful, it is used to set a timeout of n seconds for both reading and writing; after n second of inactivity, socat will terminate the connection. If the timeout is not set and the server does not respond or keep the connection open, the socat process could freeze indefinitely. ```shell -echo "inventory" | socat -t1 - TCP:host:port +echo "inventory stream=messages or failed" | socat -t1 - TCP:host:port ``` +> **Note:** `stream` flag is mandatory and must be filled in. \ No newline at end of file diff --git a/docs/book/v1/messenger-configuration.md b/docs/book/v1/messenger-configuration.md new file mode 100644 index 0000000..8ffc624 --- /dev/null +++ b/docs/book/v1/messenger-configuration.md @@ -0,0 +1,53 @@ +# Messenger Configuration + +```php +return [ + 'symfony' => [ + 'messenger' => [ + 'transports' => [ + 'redis_transport' => [ + // specifies the Redis server and stream/key + // messages is the main stream where new messages are initially stored + 'dsn' => 'redis://127.0.0.1:6379/messages', + // defines which serializer to use to encode/decode messages + 'serializer' => SymfonySerializer::class, + 'retry_strategy' => [ + // maximum number of retry attempts before moving a message to the failure transport + 'max_retries' => 3, + // initial delay before retrying a failed message, in milliseconds + 'delay' => 1000, + // each retry’s delay is multiplied by this factor + 'multiplier' => 2, + // maximum delay allowed between retries, 0 means unlimited or default behavior + 'max_delay' => 0, + ], + ], + // defines a transport named failed, used to store messages that cannot be delivered after retries. + 'failed' => [ + // specifies the Redis server and stream/key + 'dsn' => 'redis://127.0.0.1:6379/failed', + // defines which serializer to use to encode/decode messages + 'serializer' => SymfonySerializer::class, + ], + ], + // tells Symfony Messenger to send messages that exceed retry limits to the failed transport + 'failure_transport' => 'failed', + ], + ], + 'dependencies' => [ + 'factories'> [ + 'redis_transport' => [TransportFactory::class, 'redis_transport'], + 'failed' => [TransportFactory::class, 'failed'], + SymfonySerializer::class => fn(ContainerInterface $container) => new PhpSerializer(), + ], + ], +]; +``` + +## Main queue stream (`messages`) + +`messages` stream is the main queue where all new messages are initially stored. The Messenger worker consume messages from this stream and attempt to process them according to the application logic. + +## Dead Letter Queue (DLQ) + +DLQ is a dedicated transport where messages are sent when they fail to be processed after a configured number of retries. Each transport can define a retry_strategy specifying the maximum number of retry attempts, delays between retries, and exponential backoff rules. When a message exceeds the allowed retries, it is automatically forwarded to the failure transport and stored in `failed` stream, ensuring that failed messages do not block the queue. diff --git a/mkdocs.yml b/mkdocs.yml index f3aa499..81bcb21 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,7 @@ nav: - "Understanding the Queue": v1/what-is-queue.md - Server Setup: v1/server-setup.md - Installation: v1/installation.md + - Messenger Configuration: v1/messenger-configuration.md - Control Commands: v1/control-commands.md - Valkey: v1/valkey.md - How to: From f1f5c742b81cb2103f4983cec1fc165ae19b84e3 Mon Sep 17 00:00:00 2001 From: bota Date: Fri, 5 Sep 2025 11:33:51 +0300 Subject: [PATCH 2/5] linting Signed-off-by: bota --- docs/book/v1/control-commands.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/book/v1/control-commands.md b/docs/book/v1/control-commands.md index 24e92a5..95dcc53 100644 --- a/docs/book/v1/control-commands.md +++ b/docs/book/v1/control-commands.md @@ -49,4 +49,5 @@ echo "control" | socat -t1 - TCP:host:port ```shell echo "inventory stream=messages or failed" | socat -t1 - TCP:host:port ``` + > **Note:** `stream` flag is mandatory and must be filled in. \ No newline at end of file From 46b2c1a6c9bf2ede38182485861c3c6b49ac5234 Mon Sep 17 00:00:00 2001 From: bota Date: Fri, 5 Sep 2025 11:35:15 +0300 Subject: [PATCH 3/5] new line Signed-off-by: bota --- docs/book/v1/control-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v1/control-commands.md b/docs/book/v1/control-commands.md index 95dcc53..a4d6e27 100644 --- a/docs/book/v1/control-commands.md +++ b/docs/book/v1/control-commands.md @@ -50,4 +50,4 @@ echo "control" | socat -t1 - TCP:host:port echo "inventory stream=messages or failed" | socat -t1 - TCP:host:port ``` -> **Note:** `stream` flag is mandatory and must be filled in. \ No newline at end of file +> **Note:** `stream` flag is mandatory and must be filled in. From 8e2687500a8adbff74c2c92df824a1f30e1b0a99 Mon Sep 17 00:00:00 2001 From: bota Date: Tue, 9 Sep 2025 12:07:44 +0300 Subject: [PATCH 4/5] revert control commands page changes Signed-off-by: bota --- docs/book/v1/control-commands.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/book/v1/control-commands.md b/docs/book/v1/control-commands.md index a4d6e27..1d3dc2c 100644 --- a/docs/book/v1/control-commands.md +++ b/docs/book/v1/control-commands.md @@ -4,7 +4,7 @@ The commands available are: 1. `GetFailedMessagesCommand.php (failed)` - returns logs with messages that failed to process (levelName:error) 2. `GetProcessedMessagesCommand.php (processed)` - returns logs with messages that were successfully processed (levelName:info) -3. `GetQueuedMessagesCommand (inventory)` - returns all queued messages from Redis streams, in this case `messages` or `failed` +3. `GetQueuedMessagesCommand (inventory)` - returns all queued messages from Redis stream 'messages' The commands can be run in two different ways: @@ -21,7 +21,7 @@ php bin/cli.php processed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int ``` ```shell -php bin/cli.php inventory --stream="messages or failed" +php bin/cli.php inventory ``` ## TCP message @@ -47,7 +47,7 @@ echo "control" | socat -t1 - TCP:host:port > Using `-t1` flag is not necessary but can be useful, it is used to set a timeout of n seconds for both reading and writing; after n second of inactivity, socat will terminate the connection. If the timeout is not set and the server does not respond or keep the connection open, the socat process could freeze indefinitely. ```shell -echo "inventory stream=messages or failed" | socat -t1 - TCP:host:port +echo "inventory" | socat -t1 - TCP:host:port ``` > **Note:** `stream` flag is mandatory and must be filled in. From 6a28e6af17f28825308f078c1264658728c9474b Mon Sep 17 00:00:00 2001 From: bota Date: Tue, 9 Sep 2025 12:11:50 +0300 Subject: [PATCH 5/5] removed unnecesary doc Signed-off-by: bota --- docs/book/v1/control-commands.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/book/v1/control-commands.md b/docs/book/v1/control-commands.md index 1d3dc2c..44e862b 100644 --- a/docs/book/v1/control-commands.md +++ b/docs/book/v1/control-commands.md @@ -49,5 +49,3 @@ echo "control" | socat -t1 - TCP:host:port ```shell echo "inventory" | socat -t1 - TCP:host:port ``` - -> **Note:** `stream` flag is mandatory and must be filled in.