Add ttl documentation to bindings (#516)

* Add ttl documentation to bindings

* Add information for RabbitMQ message level ttl

* Add ttl for Service Bus and Storage Queues

* Update rabbitmq.md

* Update servicebusqueues.md

* Update rabbitmq.md

* Update storagequeues.md

Co-authored-by: Mark Fussell <mfussell@microsoft.com>

reference/api/bindings_api.md

@@ -201,3 +201,11 @@ curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
         }
       }'
 ```
+
+### Common metadata values
+
+There are common metadata properties which are support accross multiple binding components. The list below illustrates them:
+
+|Property|Description|Binding definition|Available in
+|-|-|-|-|
+|ttlInSeconds|Defines the time to live in seconds for the message|If set in the binding definition will cause all messages to have a default time to live. The message ttl overrides any value in the binding definition.|RabbitMQ, Azure Service Bus, Azure Storage Queue|

reference/specs/bindings/rabbitmq.md

@@ -16,11 +16,37 @@ spec:
     value: true
   - name: deleteWhenUnused
     value: false
+  - name: ttlInSeconds
+    value: 60
 ```
 
 - `queueName` is the RabbitMQ queue name.
 - `host` is the RabbitMQ host address.
 - `durable` tells RabbitMQ to persist message in storage.
 - `deleteWhenUnused` enables or disables auto-delete.
+- `ttlInSeconds` is an optional parameter to set the [default message time to live at RabbitMQ queue level](https://www.rabbitmq.com/ttl.html). If this parameter is omitted, messages won't expire, continuing to exist on the queue until processed.
 
-> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
+> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
+
+## Specifying a time to live on message level
+
+Time to live can be defined on queue level (as illustrated above) or at the message level. The value defined at message level overwrites any value set at queue level.
+
+To set time to live at message level use the `metadata` section in the request body during the binding invocation.
+
+The field name is `ttlInSeconds`.
+
+Example:
+
+```shell
+curl -X POST http://localhost:3500/v1.0/bindings/myRabbitMQ \
+  -H "Content-Type: application/json" \
+  -d '{
+        "data": {
+          "message": "Hi"
+        },
+        "metadata": {
+          "ttlInSeconds": "60"
+        }
+      }'
+```

reference/specs/bindings/servicebusqueues.md

@@ -12,9 +12,35 @@ spec:
     value: "sb://************"
   - name: queueName
     value: queue1
+  - name: ttlInSeconds
+    value: 60
 ```
 
 - `connectionString` is the Service Bus connection string.
 - `queueName` is the Service Bus queue name.
+- `ttlInSeconds` is an optional parameter to set the default message [time to live](https://docs.microsoft.com/azure/service-bus-messaging/message-expiration). If this parameter is omitted, messages will expire after 14 days.
 
 > **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
+
+## Specifying a time to live on message level
+
+Time to live can be defined on queue level (as illustrated above) or at the message level. The value defined at message level overwrites any value set at queue level.
+
+To set time to live at message level use the `metadata` section in the request body during the binding invocation.
+
+The field name is `ttlInSeconds`.
+
+Example:
+
+```shell
+curl -X POST http://localhost:3500/v1.0/bindings/myServiceBusQueue \
+  -H "Content-Type: application/json" \
+  -d '{
+        "data": {
+          "message": "Hi"
+        },
+        "metadata": {
+          "ttlInSeconds": "60"
+        }
+      }'
+```

reference/specs/bindings/storagequeues.md

@@ -14,10 +14,36 @@ spec:
     value: "***********"
   - name: queue
     value: "myqueue"
+  - name: ttlInSeconds
+    value: 60
 ```
 
 - `storageAccount` is the Azure Storage account name.
 - `storageAccessKey` is the Azure Storage access key.
 - `queue` is the name of the Azure Storage queue.
+- `ttlInSeconds` is an optional parameter to set the default message time to live. If this parameter is omitted, messages will expire after 10 minutes.
 
-> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
+> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
+
+## Specifying a time to live on message level
+
+Time to live can be defined on queue level (as illustrated above) or at the message level. The value defined at message level overwrites any value set at queue level.
+
+To set time to live at message level use the `metadata` section in the request body during the binding invocation.
+
+The field name is `ttlInSeconds`.
+
+Example:
+
+```shell
+curl -X POST http://localhost:3500/v1.0/bindings/myStorageQueue \
+  -H "Content-Type: application/json" \
+  -d '{
+        "data": {
+          "message": "Hi"
+        },
+        "metadata": {
+          "ttlInSeconds": "60"
+        }
+      }'
+```