Updated docs with correct default values for SQS and new properties retain_failed_jobs and error_visibility_timeout

Author: nickdnk

queues/sqs.md

@@ -38,6 +38,7 @@ sqs:
   # Default: empty
   endpoint: ""
 ```
+
 {% endcode %}
 
 ### Examples
@@ -52,12 +53,14 @@ If you access your AWS SQS queue from inside AWS via a service that supports dyn
 queue is in the same region.
 
 {% code title=".rr.yaml" %}
+
 ```yaml
 sqs:
-  # No parameters are required. Normally, if your IAM role has the required permissions and your service endpoint
-  # is in the same region, the environment variables associated with your instance/task will resolve all the 
-  # configuration for you. You must provide the parent sqs key to enable SQS, even if you want to use the defaults.
+# No parameters are required. Normally, if your IAM role has the required permissions and your service endpoint
+# is in the same region, the environment variables associated with your instance/task will resolve all the 
+# configuration for you. You must provide the parent sqs key to enable SQS, even if you want to use the defaults.
 ```
+
 {% endcode %}
 
 #### AWS SQS in different region with dynamic IAM
@@ -66,11 +69,13 @@ If you access your AWS SQS queue from inside AWS via a service that supports dyn
 queue is in a different region.
 
 {% code title=".rr.yaml" %}
+
 ```yaml
 sqs:
   # Only region is required
   region: eu-central-1
 ```
+
 {% endcode %}
 
 #### AWS SQS without dynamic IAM
@@ -80,6 +85,7 @@ an access key and secret. If you access the service from outside AWS, you must a
 You may also use this option if your service *does* support dynamic IAM, but you want to use explicit access keys.
 
 {% code title=".rr.yaml" %}
+
 ```yaml
 sqs:
   key: ASIAIOSFODNN7EXAMPLE
@@ -88,17 +94,20 @@ sqs:
   # If in a different region *or* if outside AWS, provide the correct region.
   region: eu-west-1 
 ```
+
 {% endcode %}
 
 #### Self-hosted (ElasticMQ)
 
 If you self-host your SQS-compatible queue, only the endpoint is required.
 
 {% code title=".rr.yaml" %}
+
 ```yaml
 sqs:
   endpoint: http://127.0.0.1:9324
 ```
+
 {% endcode %}
 
 After you have configured the driver, you should configure the queue that will use this connection.
@@ -171,18 +180,48 @@ Default: `10`
 
 ### Visibility Timeout
 
-`visibility_timeout` - The duration (in seconds) that the received messages are hidden from subsequent retrieve requests
-after being retrieved by a `ReceiveMessage` request. Max value is `43200` seconds (12 hours).
+`visibility_timeout` - The duration (in seconds) that received messages are hidden from subsequent retrieve requests
+after being retrieved by a consumer. This value should be **longer** than the time you expect each job to take, or the
+job may run multiple times. You should rarely set this value to zero, as that will cause the same job to be delivered to
+**all** consumers of the queue each time they request messages from it. If you do not provide a value for this
+parameter, the `VisibilityTimeout` attribute of the queue is used, which defaults to 30 seconds. For more
+information, see the documentation on
+[visibility timeouts](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html).
+
+Max value is `43200` seconds (12 hours).
+Default: `null`
+
+### Error Visibility Timeout
+
+`error_visibility_timeout` - If `retain_failed_jobs` is enabled, this is the duration (in seconds) that `NACK`'ed (or
+failed) jobs will have their visibility timeout changed to. Note that you cannot have a message remain invisible for
+more than the maximum value in cases where it fails multiple times, so setting this value to the maximum is error-prone.
+This parameter is ignored if `retain_failed_jobs` is `false`, and it must be larger than zero to apply.
 
+Max value is `43200` seconds (12 hours).
 Default: `0`
 
+### Retain Failed Jobs
+
+`retain_failed_jobs` - If enabled, jobs will not be deleted and requeued if they fail. Instead, RoadRunner will
+simply let them be processed again after `visibility_timeout` has passed. If you set `error_visibility_timeout` and
+enable this feature, RoadRunner will change the timeout to the value of `error_visibility_timeout`. This lets you
+customize the timeout for errors specifically. If you enable this feature, you can configure SQS to automatically
+move jobs that fail multiple times to a
+[dead-letter queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html).
+
+Default: `false`
+
 ### Wait Time
 
 `wait_time_seconds` - The duration (in seconds) for which the call waits for a message to arrive in the queue before
 returning. If a message is available, the call returns sooner than `wait_time_seconds`. If no messages are available and
-the wait time expires, the call returns successfully with an empty list of messages.
+the wait time expires, the call returns successfully with an empty list of messages. If you do not provide a value for
+this parameter, the `ReceiveMessageWaitTimeSeconds` attribute of the queue is used, which defaults to 0, and you will be
+using short polling. See the documentation on the differences between
+[short and long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html).
 
-Default: `5`
+Default: `null`
 
 ### Queue
 
@@ -195,7 +234,8 @@ Default: `default`
 
 `message_group_id` - Message group ID is required for FIFO queues. Messages that belong to the same message group are
 processed in a FIFO manner.
-More info: [link](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html#SQS-SendMessage-request-MessageGroupId)
+More info:
+[link](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html#SQS-SendMessage-request-MessageGroupId)
 
 ### Skip Queue Declaration