e12c65a369
The queue in Zaqar will support to encrypt messages before storing them into storage backends, also could support to decrypt messages when those are claimed by consumer. This feature will enhance the security of messaging service. Implements: blueprint encrypted-messages-in-queue Signed-off-by: wanghao <sxmatch1986@gmail.com> Change-Id: Icecfb9a232cfeefc2f9603934696bb2dcd56bc9c
619 lines
17 KiB
YAML
619 lines
17 KiB
YAML
# variables in header
|
|
|
|
client_id:
|
|
type: string
|
|
in: header
|
|
description: |
|
|
The identification for each client instance. The format of client id is
|
|
UUID by default, but Zaqar also supports a Non-UUID string by setting
|
|
configuration "client_id_uuid_safe=off". The UUID must be submitted in its
|
|
canonical form (for example, 3381af92-2b9e-11e3-b191-71861300734c). The
|
|
string must be longer than "min_length_client_id=20" and smaller than
|
|
"max_length_client_id=300" by default. User can control the length of
|
|
client id by using those two options. The client generates the Client-ID
|
|
once. Client-ID persists between restarts of the client so the client
|
|
should reuse that same Client-ID. Note: All message-related operations
|
|
require the use of ``Client-ID`` in the headers to ensure that messages
|
|
are not echoed back to the client that posted them, unless the client
|
|
explicitly requests this.
|
|
|
|
# variables in path
|
|
|
|
claim_id:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The id of the claim.
|
|
|
|
flavor_name_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description:
|
|
The name of the flavor.
|
|
|
|
message_id:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The ID of the message.
|
|
|
|
pool_name_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description:
|
|
The name of the pool.
|
|
|
|
queue_name:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The name of the queue.
|
|
|
|
subscription_id_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The id of the subscription.
|
|
|
|
# variables in query
|
|
|
|
claim_limit:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The ``limit`` specifies up to 20 messages (configurable) to claim. If not
|
|
specified, limit defaults to 10. Note that claim creation is best-effort,
|
|
meaning the server may claim and return less than the requested number of
|
|
messages.
|
|
|
|
detailed:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'detailed' specifies if showing the detailed information when querying
|
|
queues, flavors and pools.
|
|
|
|
echo:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description:
|
|
Indicate if the messages can be echoed back to the client that posted
|
|
them.
|
|
|
|
ids:
|
|
type: list
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A list of the messages ids. ``pop`` & ``ids`` parameters are mutually
|
|
exclusive. Using them together in a request will result in HTTP 400.
|
|
|
|
NOTE: Actually, it's not a real list, it's string combined with many
|
|
message ids separated with comma, for example:
|
|
/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f
|
|
|
|
include_claimed:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
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
|
|
required: false
|
|
description: |
|
|
Requests a page size of items. Returns a number of items up to a limit
|
|
value. Use the ``limit`` parameter to make an initial limited request and
|
|
use the ID of the last-seen item from the response as the ``marker``
|
|
parameter value in a subsequent limited request.
|
|
|
|
marker:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The ID of the last-seen item. Use the ``limit`` parameter to make an
|
|
initial limited request and use the ID of the last-seen item from the
|
|
response as the ``marker`` parameter value in a subsequent limited request.
|
|
|
|
name:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'name' specifies if filter the queues by queue's name when querying
|
|
queues.
|
|
|
|
pop:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The ``pop`` specifies how many messages will be popped up from the queue.
|
|
``pop`` & ``ids`` parameters are mutually exclusive. Using them together
|
|
in a request will result in HTTP 400.
|
|
|
|
with_count:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'with_count' specifies if showing the amount of queues when querying
|
|
them.
|
|
|
|
# variables in body
|
|
|
|
_dead_letter_queue:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The target the message will be moved to when the message can't processed
|
|
successfully after meet the max claim count. It's not supported to add
|
|
queue C as the dead letter queue for queue B where queue B has been set
|
|
as a dead letter queue for queue A. There is no default value for this
|
|
attribute. If it's not set explicitly, then that means there is no dead
|
|
letter queue for current queue. It is one of the ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_messages_ttl:
|
|
type: integer
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The new TTL setting for messages when moved to dead letter queue. If it's
|
|
not set, current TTL will be kept. It is one of the ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_messages_ttl_response:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The new TTL setting for messages when moved to dead letter queue. If it's
|
|
not set, current TTL will be kept. It is one of the ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_response:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The target the message will be moved to when the message can't processed
|
|
successfully after meet the max claim count. It's not supported to add
|
|
queue C as the dead letter queue for queue B where queue B has been set
|
|
as a dead letter queue for queue A. There is no default value for this
|
|
attribute. If it's not set explicitly, then that means there is no dead
|
|
letter queue for current queue. It is one of the ``reserved attributes``
|
|
|
|
_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. It is one of the ``reserved attributes`` of Zaqar
|
|
queues.
|
|
|
|
_default_message_delay_response:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
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. It is one of the ``reserved attributes`` of Zaqar
|
|
|
|
_default_message_ttl:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The default TTL of messages defined for a queue, which will effect for
|
|
any messages posted to the queue. So when there is no TTL defined for a
|
|
message, the queue's _default_message_ttl will be used. By default, the
|
|
value is the same value defined as ''max_message_ttl'' in zaqar.conf. It is
|
|
one of the ``reserved attributes`` of Zaqar queues. The value will be
|
|
reverted to the default value after deleting it explicitly.
|
|
|
|
_enable_encrypt_messages:
|
|
type: boolean
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The switch of encrypting messages for a queue, which will effect for
|
|
any messages posted to the queue. By default, the value is False. It is
|
|
one of the ``reserved attributes`` of Zaqar queues.
|
|
|
|
_flavor:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The flavor name which can tell Zaqar which storage pool will be used to
|
|
create the queue. It is one of the ``reserved attributes`` of Zaqar
|
|
queues.
|
|
|
|
_max_claim_count:
|
|
type: integer
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The max number the message can be claimed. Generally,
|
|
it means the message cannot be processed successfully. There is no default
|
|
value for this attribute. If it's not set, then that means this feature
|
|
won't be enabled for current queue. It is one of the
|
|
``reserved attributes`` of Zaqar queues.
|
|
|
|
_max_claim_count_response:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The max number the message can be claimed. Generally,
|
|
it means the message cannot be processed successfully. There is no default
|
|
value for this attribute. If it's not set, then that means this feature
|
|
won't be enabled for current queue. It is one of the
|
|
``reserved attributes`` of Zaqar queues.
|
|
|
|
_max_messages_post_size:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The max post size of messages defined for a queue, which will effect for
|
|
any messages posted to the queue. So user can define a queue's level
|
|
cap for post size which can't bigger than the max_messages_post_size
|
|
defined in zaqar.conf. It is one of the ``reserved attributes`` of Zaqar
|
|
queues. The value will be reverted to the default value after deleting it
|
|
explicitly.
|
|
|
|
capabilities:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
Capabilities describe what this flavor is capable of base on the storage
|
|
capabilities. They are used to inform the final user such capabilities.
|
|
|
|
catalog_reachable:
|
|
type: boolean
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A boolean value to indicate if the management(catalog) datatabse is
|
|
reachable or not.
|
|
|
|
claim_grace:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``grace`` attribute specifies the message grace period in seconds. The
|
|
value of ``grace`` value must be between 60 and 43200 seconds (12 hours).
|
|
You must include a value for this attribute in your request. To deal with
|
|
workers that have stopped responding (for up to 1209600 seconds or 14 days,
|
|
including claim lifetime), the server extends the lifetime of claimed
|
|
messages to be at least as long as the lifetime of the claim itself, plus
|
|
the specified grace period. If a claimed message would normally live longer
|
|
than the claim's live period, its expiration is not adjusted.
|
|
|
|
claim_ttl:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``ttl`` attribute specifies how long the server waits before releasing
|
|
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
|
|
You must include a value for this attribute in your request.
|
|
|
|
count:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``count`` attribute specifies how many queus in current project.
|
|
|
|
flavor_href:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The url of the flavor.
|
|
|
|
flavor_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the flavors. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
flavor_name:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The name of the flavor.
|
|
|
|
flavor_pool_group:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``pool_group`` attribute specifies the name of the pool group
|
|
this flavor sits on top of.
|
|
NOTE: Remove pool_group in Rocky release and use pool_list instead
|
|
for flavor.
|
|
|
|
flavor_pool_list:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of pools in the flavor.
|
|
NOTE: Suggest config pool_list in stead of pool_group from the
|
|
beginning of Queens.
|
|
|
|
flavors:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the flaovrs.
|
|
|
|
links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the queues. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
messages:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A list of the messages.
|
|
|
|
messages_resources:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the URL to messages.
|
|
|
|
operation_status:
|
|
type: dict
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A dict which will contain the status for many different actions/operations.
|
|
For example, post_messages, delete_messages, delete queue, etc. And each
|
|
status is a dict which contains three items: ``seconds``, ``ref`` and
|
|
``succeeded``. Seconds means how long the operation took and succeeded will
|
|
indicate if the actions was successful or not. Ref may contain the
|
|
information if the succeeded is False, otherwise it's null.
|
|
|
|
pool_flavor:
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``flavor`` attribute specifies a tag to given to more than one pool
|
|
so that it keeps user remind the purpose/capabilities of all pools that
|
|
falls under that flavor.
|
|
NOTE: Suggest config flavor in stead of group from the beginning of queen.
|
|
|
|
pool_group:
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``group`` attribute specifies a tag to given to more than one pool
|
|
so that it keeps user remind the purpose/capabilities of all pools that
|
|
falls under that group.
|
|
NOTE: Remove group in Rocky release and use flavor instead for pool.
|
|
|
|
pool_href:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The url of the pool.
|
|
|
|
pool_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the pools. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
pool_name:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The name of the pool.
|
|
|
|
pool_options:
|
|
type: dict
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``options`` attribute gives storage-specific options used by storage
|
|
driver implementations. The value must be a dict and valid key-value come
|
|
from the registered options for a given storage backend.
|
|
|
|
pool_uri:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``uri`` attribute specifies a connection string compatible with a
|
|
storage client (e.g., pymongo) attempting to connect to that pool.
|
|
|
|
pool_weight:
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``weight`` attribute specifies the likelihood that this pool will be
|
|
selected for the next queue allocation. The value must be an integer
|
|
greater than -1.
|
|
|
|
pools:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the pools.
|
|
|
|
pre_signed_queue_expires:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The time to indicate when the pre-signed will be expired.
|
|
|
|
pre_signed_queue_methods:
|
|
type: list
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A list of HTTP methods. The HTTP method(s) this URL was created for. By
|
|
selecting the HTTP method, it's possible to give either read or read/write
|
|
access to a specific resource.
|
|
|
|
pre_signed_queue_paths:
|
|
type: list
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A list of paths the pre-signed queue can support. It could be a set of
|
|
``messages``, ``subscriptions``, ``claims``.
|
|
|
|
pre_signed_queue_signature:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The signature is generated after create the pre-signed URL. It can be
|
|
consumed by adding below to HTTP headers:
|
|
|
|
URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799
|
|
URL-Expires: 2015-05-31T19:00:17Z
|
|
|
|
project_id:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The ID of current project/tenant.
|
|
|
|
queue_metadata:
|
|
type: dict
|
|
in: body
|
|
description: |
|
|
Metadata of queue.
|
|
|
|
queues:
|
|
type: list
|
|
in: body
|
|
required: true
|
|
description: |
|
|
A list of the queues.
|
|
|
|
resource_types:
|
|
type: list
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``resource_types`` attribute allows user to purge particular resource
|
|
of the queue.
|
|
|
|
storage_reachable:
|
|
type: boolean
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A boolean value to indicate if the messages(pool) datatabse is
|
|
reachable or not.
|
|
|
|
subscriber:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The ``subscriber`` attribute specifies the destination where the message
|
|
notify to. It has been designed to match the Internet RFC on Relative
|
|
Uniform Resource Locators. Zaqar now support two kinds of subscribers:
|
|
http/https and email. The http/https subscriber should start with
|
|
``http/https``. The email subscriber should start with ``mailto``.
|
|
|
|
subscription_age:
|
|
type: integer
|
|
in: body
|
|
description: |
|
|
How long the subscription has be existed.
|
|
|
|
subscription_id:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The id of the subscription.
|
|
|
|
subscription_options:
|
|
type: dict
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``options`` attribute specifies the extra metadata for the subscription
|
|
. The value must be a dict and could contain any key-value. If the
|
|
subscriber is "mailto". The ``options`` can contain ``from`` and
|
|
``subject`` to indicate the email's author and title.
|
|
|
|
subscription_source:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The queue name which the subscription is registered on.
|
|
|
|
subscription_ttl:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``ttl`` attribute specifies how long the subscription be alive. The ttl
|
|
value must be great than 60 seconds. The default value is 3600 seconds.
|
|
|
|
subscriptions:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the subscriptions.
|
|
|
|
versions:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A list of supported major API versions.
|