From 949d496263ee4b251013a96039dfef3dcb7416bd Mon Sep 17 00:00:00 2001
From: yangzhenyu <cdyangzhenyu@gmail.com>
Date: Thu, 19 Oct 2017 14:45:20 +0800
Subject: [PATCH] Doc of delayed queues

Tempest plugin
Depends-On: I0a15600a836f609e4b992f8a80ba887e312aa780

Implement blueprint delayed-queues
Change-Id: Iea7a68be8b20f3eb20ed035c33243cc843a22365
---
 api-ref/source/messages.inc                    |  3 +++
 api-ref/source/parameters.yaml                 | 18 ++++++++++++++++++
 api-ref/source/queues.inc                      |  4 ++++
 .../source/samples/messages-post-request.json  |  1 +
 .../source/samples/queue-create-request.json   |  1 +
 ...upport_delayed_queues-1babcaa3f056a39d.yaml |  7 +++++++
 6 files changed, 34 insertions(+)
 create mode 100644 releasenotes/notes/support_delayed_queues-1babcaa3f056a39d.yaml

diff --git a/api-ref/source/messages.inc b/api-ref/source/messages.inc
index 8bdb8e34a..4b4b6ccc2 100644
--- a/api-ref/source/messages.inc
+++ b/api-ref/source/messages.inc
@@ -53,6 +53,8 @@ be between 60 and 1209600 seconds (14 days). Note that the server might not
 actually delete the message until its age has reached up to (ttl + 60) seconds,
 to allow for flexibility in storage implementations.
 
+The ``delay`` attribute specifies how long the message can be claimed.
+The value of ``delay`` must be between 0 and 900 seconds (15 mins).
 
 Normal response codes: 201
 
@@ -133,6 +135,7 @@ Request Parameters
   - limit: limit
   - echo: echo
   - include_claimed: include_claimed
+  - include_delayed: include_delayed
 
 
 Response Parameters
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 5483ae039..17b7e5b3e 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -103,6 +103,13 @@ include_claimed:
    description:
      Indicate if the messages list should include the claimed messages.
 
+include_delayed:
+   type: boolean
+   in: query
+   required: false
+   description:
+     Indicate if the messages list should include the delayed messages.
+
 limit:
   type: integer
   in: query
@@ -155,6 +162,17 @@ _dead_letter_queue_messages_ttl:
     not set, current TTL will be kept. It is one of the ``reserved attributes``
     of Zaqar queues.
 
+_default_message_delay:
+  type: string
+  in: body
+  required: False
+  description: |
+    The delay of messages defined for a queue. When the messages send to
+    the queue, it will be delayed for some times and means it can not be
+    claimed until the delay expired. And user can define a queue's level
+    value for delay, also can define a message's level. The latter has
+    a higher priority.
+
 _default_message_ttl:
   type: integer
   in: body
diff --git a/api-ref/source/queues.inc b/api-ref/source/queues.inc
index 47ec49863..0cca41a3b 100644
--- a/api-ref/source/queues.inc
+++ b/api-ref/source/queues.inc
@@ -76,6 +76,8 @@ When create queue, user can specify metadata for the queue. Currently, Zaqar
 supports below metadata: _flavor, _max_claim_count, _dead_letter_queue and
 _dead_letter_queue_messages_ttl.
 
+In order to support the delayed queues, now add a metadata
+``_default_message_delay``.
 
 Normal response codes: 201, 204
 
@@ -94,6 +96,7 @@ Request Parameters
   - queue_name: queue_name
   - _dead_letter_queue: _dead_letter_queue
   - _dead_letter_queue_messages_ttl: _dead_letter_queue_messages_ttl
+  - _default_message_delay: _default_message_delay
   - _default_message_ttl: _default_message_ttl
   - _flavor: _flavor
   - _max_claim_count: _max_claim_count
@@ -189,6 +192,7 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
   - _max_messages_post_size: _max_messages_post_size
+  - _default_message_delay: _default_message_delay
   - _default_message_ttl: _default_message_ttl
 
 Response Example
diff --git a/api-ref/source/samples/messages-post-request.json b/api-ref/source/samples/messages-post-request.json
index 675140261..34fb4064e 100644
--- a/api-ref/source/samples/messages-post-request.json
+++ b/api-ref/source/samples/messages-post-request.json
@@ -2,6 +2,7 @@
   "messages": [
     {
       "ttl": 300,
+      "delay": 20,
       "body": {
         "event": "BackupStarted",
         "backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
diff --git a/api-ref/source/samples/queue-create-request.json b/api-ref/source/samples/queue-create-request.json
index 052ea9350..9c7a178e7 100644
--- a/api-ref/source/samples/queue-create-request.json
+++ b/api-ref/source/samples/queue-create-request.json
@@ -1,5 +1,6 @@
 {
     "_max_messages_post_size": 262144,
     "_default_message_ttl": 3600,
+    "_default_message_delay": 30,
     "description": "Queue for international traffic billing."
 }
\ No newline at end of file
diff --git a/releasenotes/notes/support_delayed_queues-1babcaa3f056a39d.yaml b/releasenotes/notes/support_delayed_queues-1babcaa3f056a39d.yaml
new file mode 100644
index 000000000..ad8c5690c
--- /dev/null
+++ b/releasenotes/notes/support_delayed_queues-1babcaa3f056a39d.yaml
@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    Support for delayed queues is added for MongoDB, Redis and Swift. With
+    this feature, if the queue is a delayed queue, its message will be
+    delayed some time to be claimed. New reseved metadata key of queue
+    is added: _default_message_delay.