From 46106a2ecb9289850a89cd2dfcd99287f1482a80 Mon Sep 17 00:00:00 2001
From: Maksim Kotlyar <kotlyar.maksim@gmail.com>
Date: Mon, 26 Nov 2018 15:36:04 +0200
Subject: [PATCH] [docs][skip ci] Update amqp and redis doc.

---
 docs/transport/amqp_lib.md | 70 ++++++++++++++++++++++++++++++++++++++
 docs/transport/redis.md    | 12 ++++++-
 2 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/docs/transport/amqp_lib.md b/docs/transport/amqp_lib.md
index 13c27c6e1..2d8e03866 100644
--- a/docs/transport/amqp_lib.md
+++ b/docs/transport/amqp_lib.md
@@ -12,6 +12,15 @@ Enqueue is an MIT-licensed open source project with its ongoing development made
 Implements [AMQP specifications](https://www.rabbitmq.com/specification.html) and implements [amqp interop](https://github.com/queue-interop/amqp-interop) interfaces.
 Build on top of [php amqp lib](https://github.com/php-amqplib/php-amqplib).
 
+Features:
+* Configure with DSN string
+* Delay strategies out of the box
+* Interchangeable with other AMQP Interop implementations
+* Fixes AMQPIOWaitException when signal is sent.
+* More reliable heartbeat implementations.   
+* Supports Subscription consumer
+
+Parts:
 * [Installation](#installation)
 * [Create context](#create-context)
 * [Declare topic](#declare-topic)
@@ -25,6 +34,7 @@ Build on top of [php amqp lib](https://github.com/php-amqplib/php-amqplib).
 * [Consume message](#consume-message)
 * [Subscription consumer](#subscription-consumer)
 * [Purge queue messages](#purge-queue-messages)
+* [Long running task, heartbeat, timeouts](#long-running-task,-heartbeat,-timeouts)
 
 ## Installation
 
@@ -275,4 +285,64 @@ $queue = $context->createQueue('aQueue');
 $context->purgeQueue($queue);
 ```
 
+## Long running task, heartbeat, timeouts
+
+AMQP relies on heartbeat feature to make sure consumer is still there. 
+Basically consumer is expected to send heartbeat frames from time to time to RabbitMQ broker.
+It is not possible to implement heartbeat feature in PHP, due to its synchronous nature. 
+You could read more about the issues in post: [Keeping RabbitMQ connections alive in PHP](https://blog.mollie.com/keeping-rabbitmq-connections-alive-in-php-b11cb657d5fb).
+
+`enqueue/amqp-lib` address the issue by registering heartbeat call as a [tick callbacks](http://php.net/manual/en/function.register-tick-function.php).
+To make it work you have to wrapp your long running task by `decalre(ticks=1) {}`. 
+The number of ticks could be adjusted to your needs. 
+Calling it at every tick is not good. 
+
+Please note that it does not fix heartbeat issue if you spent most of the time on IO operation.
+
+Example:
+
+```php
+<?php
+
+use Enqueue\AmqpLib\AmqpConnectionFactory;
+use Interop\Amqp\AmqpConsumer;
+use Interop\Amqp\AmqpMessage;
+
+$context = (new AmqpConnectionFactory('amqp:?heartbeat_on_tick=1'))->createContext();
+
+$queue = $context->createQueue('a_queue');
+$consumer = $context->createConsumer($queue);
+
+$subscriptionConsumer = $context->createSubscriptionConsumer();
+$subscriptionConsumer->subscribe($consumer, function(AmqpMessage $message, AmqpConsumer $consumer) {
+    // ticks number should be adjusted.
+    declare(ticks=1) {
+        foreach (fetchHugeSet() as $item) {
+            // cycle does something for a long time, much longer than amqp heartbeat.
+        }
+    }
+
+    $consumer->acknowledge($message);
+
+    return true;
+});
+
+$subscriptionConsumer->consume(10000);
+
+
+function fetchHugeSet(): array {};
+``` 
+
+Fixes partly `Invalid frame type 65` issue. 
+
+```
+Error: Uncaught PhpAmqpLib\Exception\AMQPRuntimeException: Invalid frame type 65 in /some/path/vendor/php-amqplib/php-amqplib/PhpAmqpLib/Connection/AbstractConnection.php:528
+```
+
+Fixes partly `Broken pipe or closed connection` issue.
+
+```
+PHP Fatal error: Uncaught exception 'PhpAmqpLib\Exception\AMQPRuntimeException' with message 'Broken pipe or closed connection' in /some/path/vendor/php-amqplib/php-amqplib/PhpAmqpLib/Wire/IO/StreamIO.php:190
+```
+
 [back to index](../index.md)
\ No newline at end of file
diff --git a/docs/transport/redis.md b/docs/transport/redis.md
index 2621b562c..f4c84e29a 100644
--- a/docs/transport/redis.md
+++ b/docs/transport/redis.md
@@ -12,8 +12,18 @@ Enqueue is an MIT-licensed open source project with its ongoing development made
 The transport uses [Redis](https://redis.io/) as a message broker. 
 It creates a collection (a queue or topic) there. Pushes messages to the tail of the collection and pops from the head.
 The transport works with [phpredis](https://github.com/phpredis/phpredis) php extension or [predis](https://github.com/nrk/predis) library. 
-Make sure you installed either of them 
+Make sure you installed either of them
+
+Features:
+* Configure with DSN string
+* Delay strategies out of the box
+* Recovery&Redelivery support
+* Expiration support
+* Delaying support
+* Interchangeable with other Queue Interop implementations   
+* Supports Subscription consumer
  
+Parts: 
 * [Installation](#installation)
 * [Create context](#create-context)
 * [Send message to topic](#send-message-to-topic)