zaqar-specs

Remove V1 API Code From Zaqar

Tue, 16 Nov 2021 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/remove-v1-api-code

Now there is no need for V1 APIs, its old and could be completely replaced by V2 APIs. So it’s time to remove it from the code tree. This action is first one of steps to optimize Zaqar’s codes and functions.

Problem description

Currently, Zaqar has tree versions of APIs, V1, V1_1 and V2. The V1 is the oldest apis that there is no need for them right now. All new features are implemented under V2 APIs. So its time to remove V1 APIs and optimize the Zaqar’s codes.

Proposed change

Remove all V1 APIs codes and change the basic APIs to V1_1.
Clean the unit tests and tempest tests about V1 APIs.
Modify the API doc according the changes.

API Impact

The whole V1 APIs code will be removed from Zaqar’s service.

Drawbacks

If someone are still using V1 APIs, they must change the API version to V1_1 or V2(best to V2) after Yoga release.

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: wanghao <sxmatch1986@gmail.com>
Secondary assignee:: None

Milestones

Target Milestone for completion:: Yoga M-1

Work Items

Remove V1 api and transport code.
Remove unit and functional tests for V1.
Add release note for this feature.
Update API reference according those changes.
Change tempest tests accordingly.
remove client support.

Dependencies

None

References

None

Support Extra Specs to Subscription-confirming

Tue, 12 Jan 2021 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/support-extra-specs-to-subscription-confirming

This requirement came from a true scenariowhen people use the subscription function of Zaqar, for example, text messages, they need to return some extra information like message authentication code in confirming process. Now Zaqar still cant support it, that will impact the usage of subscription.

Problem description

Currently, Zaqar can’t support extra information in subscription confirming process. This will block user to input information that is needed when subcription is confirming. There is a true case that came from Zaqar’s user. They want to input the message authentication code into Zaqar when the subscription is confirming, the code will be used to identify the subscriber. So Zaqar should support this kind of mechanism.

Proposed change

Introduce a key-value called “extra_spec” in confirming request body.
Introduce a driver mechanism to let vendors to implement what they want to do with extra_spec information.

API Impact

Subscription confirming request:

PUT: /v2/subscriptions/subscription_id/confirm

  RESPONSE CODE: 204
  REQUEST BODY:
  {
    "confirmed": true,
    "extra_spec": {"message_authentication_code": "xxxxxx"}
  }

Drawbacks

None

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: wanghao <sxmatch1986@gmail.com>
Secondary assignee:: None

Milestones

Target Milestone for completion:: wallaby M-2

Work Items

Modify api and transport code.
Add driver mechanism to handler the extra spec.
Add release note for this feature.
Update API reference.
Change unit, functional and tempest tests accordingly.
Add client support.

Dependencies

None

References

None

Query Queues With Count

Thu, 04 Jun 2020 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/query-queues-with-count

This will support query queues with ‘with_count=true’ filter, Zaqar will return the amount of queues in backend storage. This feature will be very convenient to users to know how many resources they own.

Problem description

Currently, Zaqar can’t return the amount of queues when querying the queue. It depends on users themselves to calculate the number one by one. For other clients or applications also need to do it after invoking Zaqar’s API. Its quite inconvenient for users or developers.

Proposed change

Add a new query filter item named with_count, default value is False. When querying queues with “with_count=true” in url, Zaqar will add the function to calculate total number of queus in backend storage and return the amount of queues in response body like “count=100”.

API Impact

Query queue list:

GET: /v2/queues?with_count=true

  RESPONSE CODE: 200
  RESPONSE BODY:
  {
    "count": 100,
    "queues": [...]
  }

Drawbacks

None

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: wanghao <sxmatch1986@gmail.com>
Secondary assignee:: None

Milestones

Target Milestone for completion:: ussuri RC2

Work Items

Modify transport code.
Add release note for this feature.
Update API reference.
Change unit, functional and tempest tests accordingly.
Add client support.

Dependencies

None

References

None

Encrypted Messages in Queue

Thu, 04 Jun 2020 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/encrypted-messages-in-queue

The queue in Zaqar will support to encrypt messages before storing them into storage backends, also could support to decrypt (or not) messages when those are claimed by consumer. This feature will enhance the security of messaging service.

Problem description

Currently, Zaqar can’t encrypt any messages and just store those messages into storage backends. That’ll bring some security issues like information leakage or hacker attack.

Proposed change

Add one new metadata in queue object that will indicate how to encrypt messages:
“_enable_encrypt_messages=true/false” : this will tell Zaqar whether encrypt messages before storing them into backends or not.

Support to use algorithms to encrypt messages in transport layer before storing them into backends. In V cycle, Zaqar may just support the global key for encryption and decryption, and it will be held by Zaqar service. Users don’t need to encrypt/decypt message by themselves.
Go a step further, Zaqar also could support to let user upload their public key and hold the private key by themselves. In this case, Zaqar just need to encrypt the message by using public key and return the encrypted messages to user.
About the algorithms, in V cycle, Zaqar will introduce the AES-256 encryption at first. In next cycles, Zaqar can suppot asymmetric encryption to let user upload public key and keep the private key by their own.

Note

About the option of encryption algorithms and keys, Zaqar would support specify them throught more metadatas of queues, but it will be done in next serveral cycles. In Victoria, we will choose one algorithm (like AES256) to support and support to storage the keys by Zaqar itself or other service like Barbican.

API Impact

Create queue list:

POST: /v2/queues/queue_name

  RESPONSE CODE: 200
  REQUEST BODY:
  {
    "_enable_encrypt_messages": true
  }

Drawbacks

The ecryption algorithms will impact the performance of storing messages into backends and getting the messages from the queue.

This depends on which kind of encryption algorithms we choose and support.

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: wanghao <sxmatch1986@gmail.com>
Secondary assignee:: None

Milestones

Target Milestone for completion:: victoria M-2

Work Items

Modify api and transport code.
Add support for encryption algorithm and key management.
Add release note for this feature.
Update API reference.
Change unit, functional and tempest tests accordingly.
Add client support.

Dependencies

None

References

None

Make FIFO guarantee optional

Mon, 13 May 2019 00:00:00

FIFO has been one of Zaqar’s most wanted guarantees. Besides reliability, durability and other latency requirements, users have always requested FIFO to be there. This feature, however, has proven to be an issue for some scenarios that don’t necessarily require it, hence this proposal.

https://blueprints.launchpad.net/zaqar/+spec/make-fifo-optional

Problem description

FIFO, despite being a great guarantee to have, brings in some scale and performance issues that Zaqar is not willing to accept as the default behavior. This spec proposes making FIFO optional and letting drivers capable of supporting such scenario to do so.

Proposed change

The proposed change, as stated in previous sections, is to make FIFO optional. It is possible to do so through flavors.

Not all store drivers are capable of supporting FIFO but those who are, will have FIFO listed in their supported capabilities and such capabilities will be exposed through the flavors ones. However, it’s not as straightforward as it seems. See the Work Items section for a list of required changes that will make this possible.

Drawbacks

As a side effect of this change, we’ll have to relax the delivery guarantee for pub-sub. The reason being that walking through the queue won’t prevent consumers to skip messages.

Alternatives

Keep it as is
Remove FIFO completely

Implementation

Assignee(s)

Primary assignee: flaper87

Milestones

Target Milestone for completion: K-1

Work Items

Allow driver to expose what features they support
Each driver supporst a set of features and this set needs to be accessible from the upper layers
Standardize the supported capabilities
Make a list of supported capabilities
Add a way to pass capabilities down to the driver
We can do this when the driver is initialized since we know what the capabilities are at that time.
Support both, FIFO and non-FIFO, post methods.

Dependencies

https://review.opendev.org/#/c/126531/

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Persistent transport

Mon, 13 May 2019 00:00:00

Persistent connections allow a single TCP connection to send and receive multiple requests/responses instead of opening a new TCP connection for each pair. When an application opens fewer TCP connections and keeps them open for a longer period, it causes less network traffic, use less time establishing new connections, and allows the TCP protocol to work more efficiently.

Currently Zaqar has support for a non-persistent transport, leaving aside some use cases that would be covered in a more efficient and reliable way with a persistent transport solution.

Some use cases that will be positively impacted by this change are:

Communication with browsers: Websockets will enhance the communication between browsers and Zaqar, a key factor in the integration of Zaqar with the OpenStack Dashboard (Horizon).
Notifications: this type of transport will constitute a better protocol for notifications, a feature planned for Kilo as well.

https://blueprints.launchpad.net/zaqar/+spec/persistent-transport

Problem description

Currently there is no way to establish persistent connections in Zaqar. This spec proposes adding this feature through a websockets implementation.

Proposed change

The proposed change, as stated in previous sections, is to add a persistent transport alternative to Zaqar. This can be done by using websockets.

Websockets provide a full-duplex communication channel operating over a single socket that will remove overhead and significantly reduce complexity.

Currently the tranport layer in Zaqar is tightly bound to the WSGI transport, making this addition a complex task.

Fallback

In case WebSockets are not available, the client will fallback to short-polling the REST API.

Some of the reasons of WebSockets not being available are:

Firewalls could be configured to kill HTTP connections after a certain amount of time.
Concerns from a security standpoint will lead to killing any traffic over port 80 or 443 that doesn’t look like HTTP.

Messages serialization

A serialization technology is needed in order to transport data. There are several alternatives, including MsgPack, Protobuf, Apache Avro and Cap’n Proto.

Given that a high priority is being given to browsers compatibility, MsgPack is the best choice between those. Remaining alternatives doesn’t have out-of-the-box Javascript support, making it harder to ensure compatibility with most web applications.

Alternatives

Establish persistent connections enabling WSGI keep-alive
Long polling

Implementation

Assignee(s)

Primary assignee: vkmc

Secondary assignee: cpallares

Milestones

Target Milestone for completion: < K-1

Work Items

Implement the common API layer
Define the wire protocol for persistent transports
Implement the driver
Implement queues and messages controller
Implement claims controller
Implement pools, flavors and stats controllers

WebSocket Libraries

After discussing several alternatives, including SockJS, SocketIO, Autobahn, ws4py and Tornado, it has been decided that ws4py is going to be used to implement this feature. More details on this decision will be available in the WebSockets wiki.

Dependencies

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Mistral Notifications

Mon, 13 May 2019 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/mistral-notifications

Allow a message to a Zaqar queue to trigger a Mistral workflow via the Zaqar notification mechanism.

Problem description

Developers of cloud applications expect to be able to build autonomous applications in the cloud. That is to say, applications that manage themselves by accessing the APIs of the cloud to manipulate their own infrastructure. (Examples of this include autoscaling and autorecovery.) This is one of the primary differences between a cloud platform and a simple virtualisation platform (the other being multi-tenancy). There are two parts to this that require integration, which is the purpose of this blueprint.

The first is that the application must be able to receive information from the cloud. An example of this would be an Aodh alarm indicating that a server is overutilised. These notifications must be asynchronous, since the cloud is multitenant and cannot block waiting for any one user application to acknowledge it. They must also exhibit queueing semantics with at-least-once delivery and high durability, since the application may become unreliable if it misses notifications from the cloud. Not coincidentally, Zaqar offers exactly these semantics in a public, Keystone-authenticated API that is accessible to applications, and is therefore a natural choice. For this reason, a number of OpenStack projects have already started dispatching user notifications to Zaqar and more are expected in the near future. Already Aodh alarms support Zaqar as a target, and Heat can push stack and resources events as well as notifications about user hooks being triggered to Zaqar.

The second is that the application must be able to perform arbitrary, and arbitrarily-complex actions. This is because in practice the Right Thing to do in cases like autoscaling and autorecovery is application-specific. There is also an entire universe of application-specific actions that a user might want to create. Of course an application can run these actions on a server provisioned with Nova, but this generally makes things more complex (and usually more expensive) than they need to be. For example, it is very hard to host autorecovery code on the servers that are being autorecovered themselves and still be reliable. Finally, OpenStack makes it difficult to provide appropriate Keystone credentials to servers provisioned with Nova. Mistral solves these problems by providing a lightweight, multi-tenant way of reliably running potentially long-running processes, with access to the OpenStack APIs as well as a number of other actions (some of which, like sending email and webhooks, are similar to Zaqar’s notifications).

The missing link to build fully autonomous applications is for messages (potentially, but not necessarily originating from the OpenStack cloud itself) on Zaqar queues to be able to trigger Mistral workflows (potentially, but not necessarily calling other OpenStack APIs). This would give developers of cloud applications an extremely flexible way of plugging together event-driven, application-specific, autonomous actions.

Proposed change

Create a Zaqar notification sink plugin for Mistral. The effect of a notification to this sink would be to create a Mistral workflow Execution (i.e. to trigger a pre-existing Mistral workflow).

The subscriber URI should be the URL of the Mistral executions endpoint, with the URI scheme trust+http or trust+https. For example, trust+https://mistral.example.net/v2/executions. This scheme indicates that Zaqar should create a Keystone trust that allows it to act on behalf of the user in making API calls to Mistral in the future. The trust ID will be inserted into the URL before it is stored in the form trust+http://trust_id@host/path. This form is modelled after the one used by Aodh.

The trust lifetime should be slightly longer than the TTL of the subscription, or unlimited if there is no TTL for the subscription. Zaqar must delete the trust when deleting the subscription.

When sending a notification, Zaqar will retrieve a trust token from Keystone using its own service user token and the trust ID stored in the URL. The trust token thus obtained should contain the correct tenant information to then make the request on behalf of the original user.

Since in future Zaqar may want to make trust+http requests to other API endpoints, it should distinguish on more than just the URI scheme. When the subscription is created, Zaqar should need compare the URI with the Mistral executions endpoint URL obtained with the help of the Keystone catalog in order to distinguish between Mistral workflow triggers and ordinary webhooks. Fortunately, the URL is fixed for a given cloud, so the catalog would probably only need to be read once and it would be a straight string comparison from there.

The options dict should contain the following keys:

workflow_id - The ID of the workflow to trigger
params - a dict of parameters that varies depending on the workflow type. e.g. a “reverse workflow” takes a task_name parameter to define the target task.
input - an arbitrary dict of keys and values to be passed as input to every workflow execution triggered by this notification.

When creating the Mistral execution, the contents of the message and (later) the message ID will be passed in the environment (the env key in the params). This allows the workflow to access the message data, but does not require it to declare a particular input for it (so the notification can be used to trigger any workflow). The message contents, interpreted as JSON, will be passed in a Mistral environment variable named notification. When Zaqar supports passing the message id in a notification, it will be sent as the Mistral environment variable notification_id. If these names conflict with the env passed by the user in params, the user-provided data will be overwritten with that received in the message. Any other keys in the user’s env will be preserved. If the user does not specify an env, one will be created. The input dict, workflow_id and all other params will be passed through unmodified.

While all the data is available to do a raw HTTP request, it is preferable if these calls are made through the python-mistralclient library.

Alternatives

Instead of a push model, where Zaqar takes messages and notifies Mistral, it would also be possible to use a pull model where Mistral polls Zaqar topics for messages. However, while the Zaqar notification implementation already exists, there is no such existing component in Mistral that would be suitable for polling for triggers. It would need to poll large numbers of topics in different tenants. A similar design was considered and rejected for the notification feature of Zaqar; the same arguments apply here.

An alternative authentication method might be to use pre-signed URLs, which are on the Mistral roadmap. This might be quicker to implement, but in the longer term, Keystone trusts are probably preferable.

Instead of whitelisting the Mistral executions URL, the trust+http scheme could be used to make requests to any OpenStack endpoint. However, in general the correct method of combining static information from the options dict with the contents of the message to obtain the call parameters will be different for every API. Since Mistral can already call most OpenStack APIs and supports a language (YAQL) for calculating the arguments using data from the notification and other input, the simplest way to achieve this is for the user to encapsulate any other OpenStack API call they wish to make in a Mistral workflow (which also allows them to define custom error handling).

It would be nice if there were a way to identify an OpenStack resource with a URI without necessarily requiring a URL (containing redundant information about the location of the endpoint). AWS uses an unofficial URN-like identifier with an arn: (instead of urn:) scheme for this purpose. Something similar might be useful in other contexts in OpenStack too (for example, in Heat we would like to be able to distinguish between files in Swift containers or Glare links and ordinary HTTP URLs for the purposes of uploading user data, although there is some precedent for using swift+http as the scheme in the Swift case). However, this would require, at a minimum, wide cross-project agreement (and arguably IANA registration). There are no existing examples of anything like this in OpenStack.

Implementation

Assignee(s)

This is one of those blueprints where I’m throwing it out there to see who picks it up.

Milestones

Target Milestone for completion:: Newton-3

Work Items

Implement the Mistral notification plugin
Create a keystone trust and store its ID in the URI when setting up a trust+http(s) notification. Delete the trust again when the notification is deleted.
Add the ability to distinguish between Mistral URLs and other trust+http(s) URLs in the notification URI

Dependencies

We won’t be able to pass the message ID until https://review.opendev.org/#/c/276968/ or something equivalent merges. However, since it can be added to the Mistral environment later without rewriting any existing workflows (to declare a new input), this is in no way a blocker.

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

OSProfiler

Mon, 13 May 2019 00:00:00

OpenStack consists of multiple projects, composed of multiple services, working together to make different services available for the users. In case something is not working as expected, its a really complex task to determine what is going wrong and to locate the module causing the bottleneck.

The OSProfiler tool aims to solve this issue by making possible to generate one trace per request affecting all involved services and build a tree of calls.

More details on how OSProfiler works can be find in the OSProfiler Readme

This is even more important for a project like Zaqar in which performance in communications is a key feature.

https://blueprints.launchpad.net/zaqar/+spec/osprofiler

Problem description

Currently there is no way to easily detect Zaqar’s bottlenecks.

Now that some projects have successfully integrated with OSProfiler, it is important to enable OSProfiler for Zaqar as well and contribute by providing a continuous trace information view for a request traversing the different services.

This spec proposes adding the OSProfiler tool to Zaqar.

Proposed change

The proposed change is to integrate the OSProfiler tool to Zaqar. According to the requirements for this addition detailed in OSProfiler Readme, this shouldn’t be a complex task. The steps required to do this are detailed in the Work Items section.

Main functional change for Zaqar server: https://review.opendev.org/#/c/141356/

Alternatives

Not to add the OSProfiler tool

Implementation

Assignee(s)

Primary assignee: zhiyan

Other assignee: wangxiyuan(wxy)

Milestones

Target Milestone for completion: O-2

Work Items

Add initialization of OSProfiler when Zaqar server starts
Add tracing support for WSGI
Add tracing support for MongoDB
Add tracing support for Redis
Add tracing support for SQLAlchemy
Add tracing support for Pooling
Add profiler CONF group
- Enable or disable profiling fully
- Enable or disable MongoDB tracing
- Enable or disable Redis tracing
- Enable or disable SQLAlchemy tracing
- Enable or disable Pooling tracing
- Configure HMAC key(s) to protect trace data
Add profile support for client
Test the “resting” overhead when profiling is disabled and without feature
Update document(s) to make sure new options are well documented.

Note

Usually DB requests create a lot of trace info, so its important to be able to enable/disable those on demand

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Swift storage backend

Mon, 13 May 2019 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/swift-storage

Swift is a widely deployed object storage solution for OpenStack. While it’s not particularly designed for high throughput of lots of small objects, which is what Zaqar mostly does, it scales really well, and is highly fault tolerant. It would also provide an alternative to people that want to avoid to deploy and manage MongoDB.

Driver description

The driver only implements the data part, SQL being available for the control driver. Containers are used per entity and per project, to provide multitenancy.

Proposed change

The driver uses one global service user, and stores all messages in one project. It uses suffix on container names to scope them. It will use mostly one container per entity type, plus other for additional indexes. We may need to increase or decrease the number of containers used, to find the appropriate performance balance.

It may be worth marking the driver experimental first, so that we can change the storage model without caring about migrating data.

What are the driver’s guarantees in terms of reliability?

We rely on Swift being configured appropriately to provide message reliability. By default objects are replicated 3 times, which offers good guarantees.

What are the driver’s guarantees in terms of scalability?

Again, we rely on Swift scalability guarantees here.

What are the driver’s guarantees in terms of interoperability?

We use publicly available Swift APIs, so the data is easily auditable and recoverable behind Zaqar.

What are the driver’s guarantees in terms of openness?

We use python-swiftclient to access Swift, which uses the Apache 2.0 license.

Implementation

Assignee(s)

Primary assignee:: therve

Milestones

Target Milestone for completion:: Ocata-3

Work Items

Implement storage driver, and make unit tests pass.
Add a voting gate against Swift.
Possibly make some performance testing to tweak how objects are stored.

Dependencies

Depend on Swift fix for if-none-match: https://review.opendev.org/395582

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Support redis as mgmt storage backend

Mon, 13 May 2019 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/support-redis-as-management-storage-backend

Redis is different than other database solutions in many ways, it support two modes: memory storage and disk storage, We can select one of the two modes by modifying redis.conf. If we add save options in redis.conf, redis can cyclically save the data into disk: save 900 1 save 300 10 save 60 10000

Redis includes a fairly high performance implementation of database. Currently, zaqar supports redis, mongodb and swift as the storage backend. After performance testing, we find that the performance of redis is the highest among these storage-backend. Using Redis, we may provide a system which is very practical to use, easy to administer and scale, while providing excellent performances.

Problem description

In order to enhance the performance of zaqar, it is necessary to support redis as a management database backend.

At present, Zaqar has supported sqlalchemy and mongodb as management storage backend, that would be a good reference for redis.

Proposed change

Add CatalogueController in redis storage:

Add such functions: insert, update, delete, list, get, drop_all etc.

Add FlavorsController in redis storage:

Add such functions: insert, update, delete, list, get, drop_all etc.

Add PoolsController in redis storage:

Add such functions: insert, update, delete, list, get, drop_all etc.

Drawbacks

None

Alternatives

MongoDB SQL

Data model impact

We need to add three table models, as follows:

Redis Data Structures for table catalogue:

All Project (Redis sorted set):

Set of all queue_ids, ordered by name. Used to delete the all records of table catalogue.

Key: catalogue

Id

Value

name

<project_id>.<queue_name>
Project Index (Redis sorted set):

Set of all queue_ids for the given project, ordered by name.

Key: <project_id>.catalogue

Id

Value

name

<project_id>.<queue_name>
Queue and pool Information (Redis hash):

Key: <project_id>.<queue_name>.catalogue

Name

Field

Project

p

Queue

p_q

Pool

p_p

Id	Value
name	<project_id>.<queue_name>

Id	Value
name	<project_id>.<queue_name>

Name	Field
Project	p
Queue	p_q
Pool	p_p

Redis Data Structures for table flavor:

All flavor_ids (Redis sorted set):

Set of all flavor_ids, ordered by name. Used to delete the all records of table flavors.

Key: flavors

Id

Value

name

<flavor>
Project Index (Redis sorted set):

Set of all flavors for the given project, ordered by name.

Key: <project_id>.flavors

Id

Value

name

<flavor>
Flavor Information (Redis hash):

Key: <flavor_id>.flavors

Name

Field

flavor

f

project

p

capabilities

c

Id	Value
name	<flavor>

Id	Value
name	<flavor>

Name	Field
flavor	f
project	p
capabilities	c

Redis Data Structures for table pools:

All pool (Redis sorted set):

Set of all pool_ids, ordered by name. Used to delete the all records of table pools.

Key: pools

Id

Value

name

<pool>
Flavor Index (Redis sorted set):

Set of all pool_ids for the given flavor, ordered by name.

Key: <flavor>.pools

Id

Value

name

<pool>
Pools Information (Redis hash):

Key: <pool>.pools

Name

Field

pool

p

uri

u

weight

w

options

o

Id	Value
name	<pool>

Id	Value
name	<pool>

Name	Field
pool	p
uri	u
weight	w
options	o

Implementation

Assignee(s)

Primary assignee:: gengchc2 <geng.changcai2@zte.com.cn>
Secondary assignee:: gecong <ge.cong@zte.com.cn>

Milestones

Target Milestone for completion:: Queens-Q2

Work Items

Add CatalogueController in redis storage.
Add FlavorsController in redis storage.
Add PoolsController in redis storage.

Dependencies

[1]:https://review.opendev.org/#/c/345133/

Testing

Both unit and Tempest tests need to be created to cover the code change.

Documentation Impact

Add docs about the configuration of redis and HA.

References

None

[2]:http://paste.openstack.org/show/621298/

remove-pool-group-totally

Tue, 08 Jan 2019 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/remove-pool-group-totally

remove-pool-group-totally.

Problem description

Currently pool group is used in pool and flavor resource, but the pool group only supports a 1:1 mapping with flavor. So it’s not necessary to keep it since we can map 1 flavor : N pool directly. Another issue is currently there is no API to handle the pool group resource, which is very annoying to maintain by operators.

For making a clarification to user, this bp proposes to remove useless pool group from Zaqar, just keeps the pool resource.

For backward compatibility, we have split this work into two steps:

In Queens, we have supported the old way to use pool_group and the new way without it in Flavor both.
In Stein, we will remove the pool_group totally and only keep the new way in Flavor and Pool.

This bp will implement the second step and totally remove the pool group from zaqar.

Proposed change

Modify pool and flavor operation API:
- Remove group from flavor operation API: like creat, update, show, list.
- Remove group from pool operation API: like creat, update, show, list.
Remove the related logic codes about group in the zaqar server:
The Data model of flavor and pool resources have been changed in Queens, There is no need to discard pool_group field and Drop table PoolGroup we will just keep it in table for degrade convenience.
Modify the related logic codes about group in the zaqar client:
- openstack messaging flavor create
- openstack messaging flavor update
- openstack messaging pool create
- openstack messaging pool update

Drawbacks

None

Alternatives

None

Data model impact

None

REST API impact

1. Create flavor API The Request JSON when create flavor:

PUT: /v2/flavors/{flavor_name}

{
  "pool_list": [pool1, pool2]
}

The response JSON when Create flavor:

Normal response codes: 201

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•Forbidden (403)

2. Update flavor API The Request JSON when update flavor:

 PATCH: /v2/flavors/{flavor_name}

{
   "pool_list": [pool1, pool2, pool3]
}

The response JSON when update flavor:

{
  "href": "/v2/flavors/testflavor",
  "name": "testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_list": [pool1, pool2, pool3]
}
 Normal response codes: 200

 Error response codes:
 •BadRequest (400)
 •Unauthorized (401)
 •Forbidden (403)
 •Not Found (404)
 •ServiceUnavailable (503)

3. Shows details for a flavor API The response JSON when show details flavor:

GET: /v2/flavors/{flavor_name}

{
  "href": "/v2/flavors/testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_list": [pool1, pool2],
  "name": "testflavor"
}

The response JSON when show details flavor:

Normal response codes: 200

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•Forbidden (403)
•Not Found (404)
•ServiceUnavailable (503)

4. List flavor API The response JSON when list flavors:

GET: /v2/flavors

{
  "flavors": [
    {
      "href": "/v2/flavors/test_flavor1",
      "name": "test_flavor1",
      "pool_list": [pool1, pool2]
    },
    {
      "href": "/v2/flavors/test_flavor2",
      "name": "test_flavor2",
      "pool_list": [pool3, pool4]
    }
  ],
  "links": [
    {
      "href": "/v2/flavors?marker=test_flavor2",
      "rel": "next"
    }
  ]
}

The response JSON when list flavors:

Normal response codes: 200

Error response codes:
•Unauthorized (401)
•Forbidden (403)

5. Create pools API The Request JSON when create pools:

 PUT: /v2/pools/{pool_name}

{
    "weight": 100,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "flavor": "testflavor"
}

The response JSON when Create pools:

Normal response codes: 201

Error response codes:
•BadRequest (400)
•Unauthorized (401)
••Conflict (409)

6. Update pools API The Request JSON when update pools:

PATCH: /v2/pools/{pool_name}

{
   "weight": 60,
   "uri": "mongodb://127.0.0.1:27017",
   "options":{
       "max_retry_sleep": 1
   },
   "flavor": "testflavor1"
}

The response JSON when update pools:

{
  "href": "/v2/pools/test_pool",
  "name": "test_pool",
  "weight": 60,
  "uri": "mongodb://127.0.0.1:27017",
  "flavor": "testflavor1"
}
 Normal response codes: 200

 Error response codes:
 •BadRequest (400)
 •Unauthorized (401)
 •Not Found (404)
 •ServiceUnavailable (503)

7. Shows details for a pool API The response JSON when show details pool:

GET: /v2/pools/{pool_name}

{
  "href": "/v2/pools/test_pool",
  "flavor": "flavor1",
  "name": "test_pool",
  "weight": 100,
  "uri": "mongodb://127.0.0.1:27017"
}

The response JSON when show details pool:

Normal response codes: 200

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•ServiceUnavailable (503)

8. List pools API The response JSON when list pools:

GET: /v2/pools

{
  "pools": [
    {
      "href": "/v2/pools/test_pool1",
      "flavor": "flavor1",
      "name": "test_pool1",
      "weight": 60,
      "uri": "mongodb://192.168.1.10:27017"
    },
    {
      "href": "/v2/pools/test_pool2",
      "flavor": "flavor1",
      "name": "test_pool2",
      "weight": 40,
      "uri": "mongodb://192.168.1.20:27017"
    }
  ],
  "links": [
    {
      "href": "/v2/pools?marker=test_pool2",
      "rel": "next"
    }
  ]
}

The response JSON when list pools:

Normal response codes: 200

Error response codes:
•Unauthorized (401)
•Not Found (404)

We use the v2 interface, just add pool_list in the flavor API and add the flavor in the pool API. we will remove the old way in this bp.

Old Way:
- configure group in pool API and in flavor API;
New Way:
- configure pool_list in flavor API
- add a pool to flavor:
  1. method one: update pool_list in flavor API
  2. method two: config a pool with the flavor in pool API.

Implementation

Assignee(s)

Primary assignee:: gecong<ge.cong@zte.com.cn>

Milestones

Target Milestone for completion:: Stein

Work Items

Modify pool and flavor operation APIs.
Remove the related logic codes about group in the zaqar server.

Dependencies

None

Testing

Both unit and Tempest tests need to be created to cover the code change.

Documentation Impact

The Zaqar API documentation will need to be updated to reflect the REST API changes.

References

None

Support zaqar_sendmail

Mon, 29 Oct 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/zaqar-email-delivery

Currently the email subscription in Zaqar relay on the third part tools, such as “sendmail”. It means that deployer should install it out of Zaqar. If he forgets, Zaqar will raise internal error. This work let Zaqar support email subscription by itself using the smtp python library.

Use Cases

The modification enables users to send email subscriptions without the third part tools.

A new config option smtp_mode will be added, it has two value choices, [“third_part”, “self_local”]. third_part means Zaqar will use the tools from which smtp_command config option provides to send email subscription. self_local means Zaqar will use the smtp python library instead.

A email template file will be added as well. Some parameters in the file should be configured firstly before using. Those parameters include something like smtp service account/password, smtp service address and so on. These value should come from config options as well.

The email body in the template file should be configured as well. Currently, it can only be managed by operators out of Zaqar. In the future, we can use jinja template way to let it be configurable by Zaqar.

Once self_local is used, Zaqar will fill up the template file first, then use stmp lib to send the email subscription.

Alternatives

None

REST API impact

None

Security impact

None

Notifications impact

None

Other end user impact

None

Performance Impact

None

Other deployer impact

A new config option called smtp_mode is added. To keep backward compatibility the default behavior is keeping use third part tools to send email subscription. If you don’t want to install the third part email tools anymore, please change its value to self_local.

Developer impact

None

Assignee(s)

changyufei<changyufei@unitedstack.com>

Work Items

Add a new config option smtp_mode
Add the email template
Add the logic to use smtp python lib
The test code should be added.
Document.

Milestones

R-3

None

For functional test, here is no good way to test it in Upstream since OpenStack CI/CD environment doesn’t has a email service. Or we may ask the community for help to give Zaqar team a test account within @openstack.org email system. Or any other third part company can provide one for us. Otherwise we could only test it locally to make sure it works well.

A new send email way will be added. It should be documented.

None

Delete Message With Claim ID

Mon, 15 Oct 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/delete-message-with-claim-id

Delete Message with claim id means that when a user deletes a message, the message must be claimed. If you want to delete a message, you will have to use both message id and claim id. This can improve the security of the message.

Problem description

Currently, any client who knows the message ID can delete the message if it not be claimed. It could cause some unexpected problems. A better way to delete a message is make sure the message is deleted by the client who is claiming the message. Amazon SQS use receipt handler to delete a message[1]. Zaqar can use claim id and message id to delete messages.

Proposed change

Add a new configuration item named message_delete_with_claim_id, default value is False, means it is backwards compatible. You can modify this configuration item to decide whether to turn on the switch. If you change it to True, you need to forcibly carry the claim id when delete messages. If the claim ID is invalid, the message can not be deleted. You must re-claim the messages, and then delete it.

..note:

No matter "message_delete_with_claim_id" is True of False, admin can
always delete a message without claim_id.

API Impact

Delete single message DELETE: /v2/queues/test_queue/messages/{message_id}?claim_id={claim_id}

RESPONSE CODE: 204

Delete messages DELETE: /v2/queues/test_queue/messages?ids={messages_ids}&claim_ids={claim_ids}

RESPONSE CODE: 204

Drawbacks

None

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: cdyangzhenyu <cdyangzhenyu@gmail.com>
Secondary assignee:: gecong<ge.cong@zte.com.cn> wanghao<sxmatch1986@gmail.com>

Milestones

Target Milestone for completion:: stein RC3

Work Items

Modify message delete code.
Add release note for this feature.
Update API reference.
Add user/developer document for this feature.
Change unit, functional and tempest tests accordingly.

Dependencies

None

References

[1]:https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-queue-message-identifiers.html

Introduce Topic Resource For Notification

Fri, 28 Sep 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/introduce-topic-resource-for-notification

We want to introduce a new resource called Topic into Zaqar. Topic is a concept from AWS Simple Notification Service (SNS), it will has relevance with subscriptions. User can send message to a topic, and then the subscribers will get the message according to different protocols, like http, email, sms, etc.

Problem description

Now basically Zaqar has integrated two types of services, Messaging Queue Service and Notification Service. We create subscriptions based on queue, and also introduce retry policy for subscription and queue. It’s not very clear from the service view, especially for the users who have been used to the SNS and SQS in AWS

So in Rocky, we want to introduce the Topic resource into Zaqar, and split Messaging Queue Service and Notification Service clearly.

AWS SNS service has the resource named Topic, that would be a good reference for Zaqar[1].

Proposed change

To implement the Topic resource, one idea is to define the Topic as a special queue with some special feature that is different from common queue.

Could set the users or projects who can send topic message to this Topic
Could set the users or projects who can subscribe this Topic.
The messages will be stored in Topic but those messages could NOT be claimed since they are just used for sending to subscribers. When sending successfully, Zaqar will delete this message from topic, if not, will retry the sending process.

Besides those features, user also can set the retry policy to Topic and Subscription both.

After introducing Topic to Zaqar, we will keep the subscription of common queue for a while, but we also want to change the users’ behavior to use Topic if they want to subscribe something in Zaqar. So maybe we remove the subscription of common queue in future.

API Impact

Topic Creation:

PUT: /v2/topics/{topic_name}
BODY:
{
   "_allowed_sending_users": <List of user id, optional>,
   "_allowed_sending_projects": <List of project id, optional>,
   "_allowed_subscribe_users": <List of user id, optional>,
   "_allowed_subscribe_projects": <List of project id, optional>,
   "_allowed_subscribe_protocols": <List of string, optional>,
   "_retry_policy": <Dict, optional>
}
RESPONSE CODES: 201, 204
ERROR RESPONSE CODES:
* BadRequest (400)
* Unauthorized (401)
* ServiceUnavailable (503)

Note

“_allowed_sending_users”: define which users can send message to topic. “_allowed_sending_projects”: define which projects can send message to topic. Of course you can set the project owned this topic here too. “_allowed_subscribe_users”: define which users can subscribe topic. “_allowed_subscribe_projects”: define which projects can subscribe topic. The default behavior is allowing all the users under the project who create this topic send message, and all projects could subscribe this topic. Default subscribe protocols are email, webhook, and trust. The retry policy is same as Queue’s retry policy.

Topic Update:

PATCH: /v2/topics/{topic_name}
BODY:
[
   {
      "op": "replace",
      "path": "/metadata/allowed_sending_projects",
      "value": [pro_id1, pro_id2, ... ,pro_idN]
   }
]
RESPONSE CODE: 200
ERROR RESPONSE CODES:
* BadRequest (400)
* Unauthorized (401)
* Not Found (404)
* Conflict (409)
* ServiceUnavailable (503)

Topic Query List:

GET: /v2/topics
RESPONSE BODY:
{
   "topics": [
                {
                   "topic_name": xxx,
                   "href": xxx
                }
             ],
   "links": [
               {
                   "href": '/v2/topic?marker=wellington',
                   "rel": "next"
               }
            ]
}
RESPONSE CODE: 200
ERROR RESPONSE CODES:
* BadRequest (400)
* Unauthorized (401)
* ServiceUnavailable (503)

Topic Query Detail:

GET: /v2/topics/{topic_name}
RESPONSE BODY:
{
   "_allowed_sending_users": [user_id1, ... ,user_idN],
   "_allowed_sending_projects": [pro_id1, ... ,pro_idN],
   "_allowed_subscribe_users": [user_id1, ... ,user_idN],
   "_allowed_subscribe_projects": [pro_id1, ... ,pro_idN],
   "_allowed_subscribe_protocols": [email, webhook, trust],
   "_retry_policy": {}
}
RESPONSE CODE: 200
ERROR RESPONSE CODES:
* BadRequest (400)
* Unauthorized (401)
* ServiceUnavailable (503)

Topic Delete:

DELETE: /v2/topics/{topic_name}
RESPONSE CODE: 204
ERROR RESPONSE CODES:
* BadRequest (400)
* Unauthorized (401)
* ServiceUnavailable (503)

Drawbacks

N/A

Alternatives

N/A

Implementation

Assignee(s)

Primary assignee:: wanghao (sxmatch1986@gmail.com)

Milestones

R-3

Work Items

Implement the Topic API.
Implement the process of CRUD.
UTs for this feature.
DOC support.

Dependencies

[1]: http://docs.aws.amazon.com/sns/latest/dg/welcome.html

Remove pools group from Zaqar

Thu, 13 Sep 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/remove-pool-group-from-zaqar

Remove pool group from pool and flavor resource.

Problem description

For making a clarification to user, this bp proposes to remove useless pool group from Zaqar, just keeps the pool resource.

For backward compatibility, we will split this work into two steps:

In Queens, we support the old way to use pool_group and the new way without it in Flavor both. The pool_group will be marked to let users know it will be useless soon and remove in R release.
In Rocky, we will remove the pool_group totally and only keep the new way in Flavor and Pool.

Proposed change

Modify pool and flavor operation API:
- Remove group from flavor operation API: like creat, update, show, list.
- Remove group from pool operation API: like creat, update, show, list.

..note:

This changes isn't going to happen in Queens release for backward
compatibility, we keep the pool_group this circle and mark it will be
useless in Zaqar log and remove the pool group totally in R release.

Modify the related logic codes about group in the zaqar server:

For example, now in the creation of the queue, first we find all the pools base on group, and then select the appropriate pool (pool = select.weighted (pools)) to create the queue.

We modify as follows: Find all the pools base on flavor, and then select the appropriate pool to create a queue.

etc.
Change the Data model of flavor and pool resources, detail see Data model impact.
Modify the related logic codes about group in the zaqar client:
- openstack messaging flavor create
- openstack messaging flavor update
- openstack messaging pool create
- openstack messaging pool update

..note:

Like the changes in Zaqar APIs, this change is also going to do in R
release.

Drawbacks

None

Alternatives

None

Data model impact

For sqlalchemy:

Drop table PoolGroup in R.
Modify Flavors table:

Discard pool_group field, but do not remove the field in Q in order to be
compatible with the latter : CREATE TABLE Flavors ( name varchar(64) NOT NULL, project varchar(64) DEFAULT NULL, pool_group varchar(64) NOT NULL, capabilities text, PRIMARY KEY (name), ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Modify Pools table:

Discard group field, but do not remove the field in Q in order to be
compatible with the latter; Add flavor field, this flavor field equals name field of the flavor: CREATE TABLE Pools ( name varchar(64) NOT NULL, group varchar(64) DEFAULT NULL, uri varchar(255) NOT NULL, weight int(11) NOT NULL, options text, flavor varchar(64) DEFAULT NULL, PRIMARY KEY (name), UNIQUE KEY uri (uri), CONSTRAINT Pools_flavor_fk FOREIGN KEY (flavor) REFERENCES fla (name) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Migration strategy for Flavor and Pools table:
1. Query all the Pools, and then process every record as follows:
2. Find Flavors.name where Flavors.pool_group = Pools.group
3. Modify Pools.flavor = Flavors.name

For mongodb:

The upgrade strategy is similar. We need to introduce a script to implement the data migration.

..note:

Since we decide to remove the pool_group totally in Rocky, that then we need
to provide a script to help users to migrate the data and remove the
pool_group column from db table.

REST API impact

1. Create flavor API The Request JSON when create flavor:

PUT: /v2/flavors/{flavor_name}

{
  "pool_group": "testgroup",  # remove pool_group in Rocky release
  "pool_list": [pool1, pool2]
}

The response JSON when Create flavor:

Normal response codes: 201

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•Forbidden (403)

2. Update flavor API The Request JSON when update flavor:

 PATCH: /v2/flavors/{flavor_name}

{
   "pool_group": "testgroup",  # remove pool_group in Rocky release
   "pool_list": [pool1, pool2, pool3]
}

The response JSON when update flavor:

{
  "href": "/v2/flavors/testflavor",
  "pool_group": "testgroup",# remove pool_group in Rocky release
  "name": "testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_list": [pool1, pool2, pool3]
}
 Normal response codes: 200

 Error response codes:
 •BadRequest (400)
 •Unauthorized (401)
 •Forbidden (403)
 •Not Found (404)
 •ServiceUnavailable (503)

3. Shows details for a flavor API The response JSON when show details flavor:

GET: /v2/flavors/{flavor_name}

{
  "href": "/v2/flavors/testflavor",
  "pool_group": "testgroup", # remove pool_group in Rocky release
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_list": [pool1, pool2],
  "name": "testflavor"
}

The response JSON when show details flavor:

Normal response codes: 200

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•Forbidden (403)
•Not Found (404)
•ServiceUnavailable (503)

4. List flavor API The response JSON when list flavors:

GET: /v2/flavors

{
  "flavors": [
    {
      "href": "/v2/flavors/test_flavor1",
      "pool_group": "testgroup", # remove pool_group in Rocky release
      "name": "test_flavor1",
      "pool": "testgroup",       # remove pool_group in Rocky release
      "pool_list": [pool1, pool2]
    },
    {
      "href": "/v2/flavors/test_flavor2",
      "pool_group": "testgroup", # remove pool_group in Rocky release
      "name": "test_flavor2",
      "pool": "testgroup",       # remove pool_group in Rocky release
      "pool_list": [pool3, pool4]
    }
  ],
  "links": [
    {
      "href": "/v2/flavors?marker=test_flavor2",
      "rel": "next"
    }
  ]
}

The response JSON when list flavors:

Normal response codes: 200

Error response codes:
•Unauthorized (401)
•Forbidden (403)

5. Create pools API The Request JSON when create pools:

 PUT: /v2/pools/{pool_name}

{
    "weight": 100,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "group": "poolgroup", # remove pool_group in Rocky release
    "flavor": "testflavor"
}

The response JSON when Create pools:

Normal response codes: 201

Error response codes:
•BadRequest (400)
•Unauthorized (401)
••Conflict (409)

6. Update pools API The Request JSON when update pools:

PATCH: /v2/pools/{pool_name}

{
   "weight": 60,
   "uri": "mongodb://127.0.0.1:27017",
   "options":{
       "max_retry_sleep": 1
   },
   "group": "newpoolgroup", # remove pool_group in Rocky release
   "flavor": "testflavor1"
}

The response JSON when update pools:

{
  "href": "/v2/pools/test_pool",
  "group": "newpoolgroup", # remove pool_group in Rocky release
  "name": "test_pool",
  "weight": 60,
  "uri": "mongodb://127.0.0.1:27017",
  "flavor": "testflavor1"
}
 Normal response codes: 200

 Error response codes:
 •BadRequest (400)
 •Unauthorized (401)
 •Not Found (404)
 •ServiceUnavailable (503)

7. Shows details for a pool API The response JSON when show details pool:

GET: /v2/pools/{pool_name}

{
  "href": "/v2/pools/test_pool",
  "group": "testpoolgroup", # remove pool_group in Rocky release
  "flavor": "flavor1",
  "name": "test_pool",
  "weight": 100,
  "uri": "mongodb://127.0.0.1:27017"
}

The response JSON when show details pool:

Normal response codes: 200

Error response codes:
•BadRequest (400)
•Unauthorized (401)
•ServiceUnavailable (503)

8. List pools API The response JSON when list pools:

GET: /v2/pools

{
  "pools": [
    {
      "href": "/v2/pools/test_pool1",
      "group": "poolgroup", # remove pool_group in Rocky release
      "flavor": "flavor1",
      "name": "test_pool1",
      "weight": 60,
      "uri": "mongodb://192.168.1.10:27017"
    },
    {
      "href": "/v2/pools/test_pool2",
      "group": "poolgroup", # remove pool_group in Rocky release
      "flavor": "flavor1",
      "name": "test_pool2",
      "weight": 40,
      "uri": "mongodb://192.168.1.20:27017"
    }
  ],
  "links": [
    {
      "href": "/v2/pools?marker=test_pool2",
      "rel": "next"
    }
  ]
}

The response JSON when list pools:

Normal response codes: 200

Error response codes:
•Unauthorized (401)
•Not Found (404)

We use the v2 interface, just add pool_list in the flavor API and add the flavor in the pool API. This can be compatible with the old way.

Old Way:
- configure group in pool API and in flavor API;
New Way:
- configure pool_list in flavor API
- add a pool to flavor:
  1. method one: update pool_list in flavor API
  2. method two: config a pool with the flavor in pool API.

Implementation

Assignee(s)

Primary assignee:: wanghao<sxmatch1986@gmail.com>
Secondary assignee:: gengchc2 <geng.changcai2@zte.com.cn>

Milestones

Target Milestone for completion:: Queens and Rocky

Work Items

Modify pool and flavor operation APIs.
Modify the related logic codes about group in the zaqar server.
Modify the Data model about Flavors , Pools and PoolGroup.
Modify the related logic codes about group in the zaqar client.

Dependencies

None

Testing

Both unit and Tempest tests need to be created to cover the code change.

Documentation Impact

The Zaqar API documentation will need to be updated to reflect the REST API changes.

References

None

Queue filter support

Thu, 13 Sep 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/queue-filter-support

Metadata is a group of key-value pairs that belong to a queue. When a queue is created, the user who creates the queue can add the metadata {“keyx”: “valuex”} to distinguish it. It is necessary for zaqar to support the function of queue filter so that Users can select the queue by the specified key-value of metadata. In this blueprints, we will also add queue filter by name.

Problem description

Zaqar doesn’t support queue filter when queue listing, we may add this feature now.

Proposed change

When queue listing, we add filter option in query string parameters like this

GET /v2/queues?key1=value1&key2=value2&name=value3

If metadata of queue and name is consistent with the filter, the queues will be listed to the user, otherwise the queue will be filtered. If filter option is enabled, the metadata of the queue will be returned to user.

API Impact

Lists queues:

GET: /v2/queues?key1=value1&key2=value2

RESPONSE CODE: 200

Drawbacks

N/A

Alternatives

N/A

Implementation

Assignee(s)

gecong<ge.cong@zte.com.cn>

Milestones

Rocky-1

Work Items

#* Add filter parameter for queues listing REST API. #* Update API reference. #* Add release note for this feature. #* UTs for this feature.

Dependencies

N/A

Remove format constraint of client id

Thu, 13 Sep 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/remove-format-constraint-of-client-id

Since some clients use different format of client id not only uuid, so Zaqar will support this function. This also requires user to ensure the client id is immutable.

Problem description

Now Zaqar has format constraint to client id, must be UUID format. But this constraint is not very reasonable under some cases, like user want to use user id in LDAP as client id, but Zaqar doesn’t allow this now.

Proposed change

Add Three config options:
1. ‘client_id_uuid_safe’: Defines the format of client id, the value could be “strict” or “off”. “strict” means the format of client id must be uuid, “off” means the restriction be removed. The default value is ‘strict’.
2. ‘min_length_client_id’: Defines the minimum length of client id if remove the uuid restriction. Default value is 10.
3. ‘max_length_client_id’: Defines the maximum length of client id if remove the uuid restriction. Default value is 36.
Will change the method ‘require_client_id’ in wsgi/helpers.py to support validating the different format of client id.

API Impact

For WSGI: Will impact all APIs in v1.1 and v2 version.

For WebSocket: Will impact message list and message post in v2 version. And we will support others APIs in following patch.

Drawbacks

There may be a tiny performance impact when user uses very long client id since Zaqar need to store the client id in storage layer.

Alternatives

N/A

Implementation

Assignee(s)

wanghao<sxmatch1986@gmail.com>

Milestones

Rocky-3

Work Items

#* Change the Zaqar server code. #* Update API reference. #* Add release note for this feature. #* UTs for this feature.

Dependencies

N/A

Subscription filtering policies

Thu, 13 Sep 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/subscription-filtering-tags

By default, a subscriber of zaqar topic receives every message published to the topic. To receive only a subset of the messages, a subscriber assigns a filter policy to the topic subscription. So in this case, zaqar need to support message filtering. This function is similar to Amazon SNS message filtering[1].

This feature supports all subscription endpoint, including mail, webhook.

Problem description

The current subscription lacks flexibility due to the fact that it does not support message filtering. When a subscriber subscribes to a topic, all messages which sent to the topic will be sent to this subscriber. So, this feature is intended to solve the problem, which allows the user to specify the filter policies when creating a subscription and publish messages, and ultimately, the filter policies matching decides which subscriber will receive the message.

Proposed change

The filter policy is a simple JSON object. The policy contains attributes that define which messages the subscriber receives. When you publish a message to a topic, Zaqar compares the message attributes to the attributes in the filter policy for each of the topic’s subscriptions. If there is a match between the attributes, Zaqar sends the message to the subscriber. Otherwise, Zaqar skips the subscriber without sending the message to it.

With filter policies, you can simplify your message filtering criteria into your topic subscriptions. With this consolidation, you can offload the message filtering logic from subscribers and the message routing logic from publishers. Therefore, you do not need to filter messages by creating a separate topic for each filtering condition. Instead, you can use a single topic, and you can differentiate your messages with attributes. Each subscriber receives and processes only those messages accepted by its filter policy.

For example, you could use a single topic to publish all messages generated by transactions from your online retail site. To each message, you could assign an attribute that indicates the type of transaction, such as order_placed, order_cancelled, or order_declined. With filter policies, you can route each message to the different subscriber that is meant to process the message’s transaction type.

To do this, a new attribute named filter_policies need to be added to both the message and subscription. Note that this property is optional and does not affect existing functionality.

When you create a subscription, you can specify the filter policies, just like this:

``{'subscriber': 'http://example.com/order_placed',
   'options':{'filter_policies': ['order_placed']}}``

Then when you send a message to the topic, you can choose to add the attribute, just like this:

``{'body': 'test', 'filter_policies': ['order_placed']}``

Finally, zaqar decides which subscribers the message should be sent to according to the following rules:

If the subscriber does not have any filter_policies, all messages will be sent to the subscriber.
If the message does not contain any filter_policies, it will not be sent to the subscriber which has filter_policies.
If the message and the subscriber’s filter_policies have intersecting collections, the message will be sent to the subscriber.
If the message and the subscriber both have filter_policies, but there is no intersection set, no message will be sent to the subscriber.
The relationship of the content in order_placed is or, it means that the message will be sent to the subscriptions that match anyone filters in order_placed.

Drawbacks

N/A

Alternatives

N/A

Implementation

Assignee(s)

Primary assignee:: cdyangzhenyu <cdyangzhenyu@gmail.com>

Milestones

Target Milestone for completion:: Rocky-3

Work Items

Change the message subscription process for applying this feature.
Add release note for this feature.
Update API reference.
Add user/developer document for this feature.
Change unit, functional and tempest tests accordingly.

Dependencies

None

References

[1] https://docs.aws.amazon.com/sns/latest/dg/message-filtering.html

Delayed Queues

Wed, 04 Jul 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/delayed-queues

Delay queues can postpone the delivery of new messages in a queue for a specific number of seconds. Which is useful for an auditing observer process the auditor would be guaranteed to see messages before they were claimed, and could even edit messages if needed.

Problem description

Now one of the big function gaps of Zaqar is the delayed queue. Currently, all the message posted to the queue will be visible immediately. That’s enough for most of the user cases. However, for some user case, user want the message to be unavailable to end users for a specific period of time.

Proposed change

Generally, a new attribute of queue named _default_message_delay. If the attribute value greater than 0, then queue is a delayed queue, otherwise, it’s a normal queue.

All messages sent to the delayed queue can not be immediately claimed and must wait for a delay. The delay can be set or update as a metadata when the queue is created.

Then, when user get or claim messages on a delayed queue, Zaqar will take delay as a query condition, which is as below:

Message Create + Delay < Current Time

Basically, there are 3 scenarios:

Normal message sent to delayed queue

If a normal message without delay attribute sent to a delayed queue, then the message will use the queue’s default delay _default_message_delay.
Message with attribute delay sent to delayed queue

If message with delay attribute sent to a delayed queue, then Zaqar will use the message’s delay seconds value instead of the delayed queue’s delay seconds value.
Message sent to normal queue

A normal queue is a queue with the _default_message_delay value of 0. Whether the message is a normal message or a message with a delay attribute, it will not have a delay feature when it is sent to the normal queue. Zaqar does not perform conditional filtering on the delay attribute when get/claim messages. This means the delay feature does not affect the performance of normal queue.

Specific implementation steps:

Add a new attribute _default_message_delay for all queue’s metadata.

The attribute _default_message_delay default value is 0 means it is a normal queue. Its ranges from 0 to max_message_delay seconds, the max_message_delay is configurable and the default value is 900 seconds (15 mins).

Add a new attribute just for message’s request body: delay.

When post messages to queue, user can add delay like ttl. The message’s delay time has a higher priority than queues. If message ttl < delay, the message will never be claimed, because it is in a delay period and the message’s ttl has expired, so the message will be deleted by backend.

Add a new field d in message backend.

The field d is a delay expires timestamp. It can be saved to the backend storage. When the timestamp is less than or equal to the current time, the delay expires.

d = delay + MESSAGE_CREATED_TIMESTAMP

Make sure the message can not be claimed until the delay is expired.
If the queue is a normal queue means the ‘delayed queues’ feature wasn’t being used, it is necessary to ensure that it is close to zero overhead.
Support for mongo, redis and swift.

Drawbacks

This may introduce a little bit performance impact, because this needs another new condition for current messages query. But it will not affect the normal queue too much.

Alternatives

There is no good option for this feature. User have to wait enough seconds to get / claim messages against Zaqar.

Implementation

Assignee(s)

Primary assignee:: cdyangzhenyu <cdyangzhenyu@gmail.com>

Milestones

Target Milestone for completion:: Queens Q-2

Work Items

Add mongodb support.
Add redis support.
Add swift support.
Add release note for this feature.
Update API reference.
Add user/developer document for this feature.
Change unit, functional and tempest tests accordingly.

Dependencies

None

Support Checksum Of Message Body

Wed, 04 Jul 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/support-md5-of-body

Now, Zaqar will add a non-URL-encoded message body checksum function. This is essential for the security of the message body, it can prevent the message from being tampered.

Problem description

Currently, Zaqar has no checksum of the non-URL-encoded message body. It is a good feature for the security of the message body.

AWS SQS service has supported the function, that would be a good reference for Zaqar[1].

Proposed change

When user claim or get the messages, the checksum will be returned with message body together, So user can use it to verify that the message body is correct. Currently zaqar only support the checksum of the non-URL-encoded message body based on MD5 digests. We may support other algorithms in future versions, including SHA1, sha256, sha512, and so on. So, It is necessary to change the following:

Add new property named checksum for message. This property is a string type.

When you send a message to queue, Zaqar will use the default checksum algorithm MD5 to calculate the checksum value of the non-URL-encoded message body. Finally Zaqar will store the value on the backend. Now the backend Mongodb, Redis and Swift can be supported.
Return the property checksum for message when user claims or gets the message.

When user gets or claims the message, The API will return the k-v pair of checksum in the body of the message. The user can then use this value to verify that the body of the newly retrieved message is correct or not.
This feature is backward compatible.

For old messages that do not have the checksum attribute, the checksum will return None for both claim and get operation. This feature will also transit smoothly as the old messages gradually expire.

Add new data model for message body and queue on different backend.

MESSAGE:

+----------------------+---------+
|  Name                |  Field  |
+======================+=========+
|  checksum            |   cs   |
+----------------------+---------+
|  body                |   b     |
+----------------------+---------+
|  ...                 |   ...   |
+----------------------+---------+

Drawbacks

None

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: cdyangzhenyu <cdyangzhenyu@gmail.com>

Milestones

Target Milestone for completion:: Queens RC1

Work Items

Add message body checksum support for Mongodb, Redis and Swift.
Add release note for this feature.
Update API reference.
Add user/developer document for this feature.
Change unit, functional and tempest tests accordingly.

Dependencies

None

References

[1]:https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Message.html

The title of your blueprint

Wed, 17 Jan 2018 00:00:00

Include the URL of your launchpad blueprint:

https://blueprints.launchpad.net/zaqar/+spec/example

Introduction paragraph – why are we doing anything?

Problem description

A detailed description of the problem.

Proposed change

Here is where you cover the change you propose to make in detail. How do you propose to solve this problem?

If this is one part of a larger effort make it clear where this piece ends. In other words, what’s the scope of this effort?

Drawbacks

Are there any drawbacks in this proposal? Does it change things in the API? Will it have an impact in critical areas? Will it make other areas more complex?

Please, answer any of the questions above or elaborate on the drawbacks of this proposal if there’re any.

Alternatives

This is an optional section, where it does apply we’d just like a demonstration that some thought has been put into why the proposed approach is the best one.

Implementation

Assignee(s)

Who is leading the writing of the code? Or is this a blueprint where you’re throwing it out there to see who picks it up?

If more than one person is working on the implementation, please designate the primary author and contact.

Primary assignee:: <launchpad-id or None>

Can list additional ids if they intend on doing substantial implementation work on this blueprint.

Work Items

Work items or tasks – break the feature up into the things that need to be done to implement it. Those parts might end up being done by different people, but we’re mostly trying to understand the timeline for implementation.

Dependencies

Include specific references to specs and/or blueprints in zaqar, or in other projects, that this one either depends on or is related to.

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Email Notification Support

Wed, 17 Jan 2018 00:00:00

As a notification service, email is one of the importants subscribers we should support. Given email is the most way to get messages in the modern world .

blueprint: https://blueprints.launchpad.net/zaqar/+spec/email-notification

Problem description

Now Zaqar just introduces the notification support in Kilo, but only suppport webhook driver. The problem is users who do not have a webhook endpoint for Zaqar to hit, but do have access to email, cannot currently benefit from Zaqar notifications.

Proposed change

Add a new task driver under /notification/task, which will leverage the built-in /usr/sbin/sendmail command to send messages.

Proposed REST API request looks like:

POST /v2/queues/{queue_name}/subscriptions

{
    'subscriber': 'mailto:fake@gmail.com',
    'ttl': 3600,
    'options': {'subject': 'Alarm', 'cc': {}, 'bcc': {} }
}

The email notification driver will support the standard mailto protocol, that said, such as subject, cc and bcc could be a part of the ‘subscriber’ attribue. For example:

mailto:someone@example.com?subject=This%20is%20the%20subject&cc= someone_else@example.com&body=This%20is%20the%20body

Meanwhile, we can also support those email fields in the ‘options’ attribute.

And to avoid spam, we can send a confirmation email firstly with a confirm_token, then by default the subcription is in ‘inactive’ status, until the email owner clicked the URL in the confirmation email. The URL will be like below:

/v2/queues/{queue_name}/subscriptions?subscriber=mailto:fake@gmail.com&confirm_token=22c4f150358e4ed287fa51e050d7f024

Then Zaqar will update the subscription from ‘inactive’ to ‘active’.

Alternatives

From the design/architecture perspective, if we don’t have an email driver for notification, that means we may need a email-sending-as-a-service to achieve the same goal. It doesn’t make much sense to do that given we can easily do that by leveraging the mailto in Zaqar’s notification service.

Data model impact

None.

REST API impact

None.

Other end user impact

None.

Deployer impact

Deployers who deploy Zaqar will need to ensure that they have email systems configured if the email notification is enabled in ‘subscriber_types’.

Developer impact

None.

Implementation

Assignee(s)

Primary assignee:: flwang (Feilong Wang)

Milestones

Target Milestone for completion: L-2

Work Items

Add a task driver for email

Dependencies

Mail transfer agent needs to be configured on the host.

Testing

Unit tests
Functional test, like sending to $(whoami)@$(hostname) and then check with ‘mail’.
Manual testing

Documentation Impact

Feature need to be documented

References

https://docs.python.org/2/library/email-examples.html

Design wire protocol for non RESTFul transports

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/non-rest-wire-protocol

This specs represents the work to be done to design a wire protocol that will respect the current API v1.1 and that will also be useful for non-RESTFul transmission protocols.

Problem description

We currently have a well defined protocol that works well for HTTP. As a project, we’re looking forward to welcome more transports that will work for different use-cases but we don’t have a way to support them. This blueprint aims to define such protocol and the work needed to make it happen.

Proposed change

Based on the existing protocol defined in this wiki page[0] and the rough spec proposed here[1], I’m proposing we use similar to the one below and complete the work started by the api-layer blueprint[2].

This blueprint, however, does not propose an API layer that should be used by all transports. Instead, it proposes an API layer that will be used by transports relying on lower-level transmission protocols like: websocket, raw tcp, etc.

Ideally, one would expect Zaqar to support existing protocols like STOMP, AMQP, etc. While this may/may not be possible depending on the protocol, we should have a protocol that sticks to the service goals of being simple, straightforward and lightweight. Other protocols could be implemented as separate transports in the future.

{
    "action": "post_message",
    "header": {
        "User-Agent": "python/2.7 killer-rabbit/1.2",
        "Date": "Wed, 2    8 Nov 2012 21:14:19 GMT",
        "Accept": "application/x-msgpack",
        "Client-ID": 30387f00-39a0-11e2-be4d-a8d15f34bae2,
        "X-Project-ID": 518b51ea133c4facadae42c328d6b77b,
        "X-Auth-Token": "7d2f63fd-4dcc-4752-8e9b-1d08f989cc00"
    },
    "body": {
        ...
    }
}

[0] https://wiki.openstack.org/wiki/Zaqar/specs/api/v1.1 [1] https://wiki.openstack.org/wiki/Zaqar/specs/zmq/api/v1 [2] https://blueprints.launchpad.net/zaqar/+spec/cross-transport-api-spec

Alternatives

Don’t do anything and let each transport implement it’s protocol.
Implement a transport on top of a different protocol

Implementation

Assignee(s)

Primary assignee:: flaper87

Milestones

Target Milestone for completion:: Kilo-1

Work Items

Define the wire protocol
Create an API manager that process messages

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Zaqar’s notification semantics

Wed, 17 Jan 2018 00:00:00

One of Zaqar’s goals, from an API semantics perspective, is to provide support for push notifications - or subscriptions, if you will. After having added support for all the queuing related semantcis to Zaqar’s API, we can start adding support for other things that sit on top of the existing semantics like the ones mentioned in this spec.

https://blueprints.launchpad.net/zaqar/+spec/notifications

Other references: - https://etherpad.openstack.org/p/marconi-notifications-brainstorm - https://etherpad.openstack.org/p/juno-marconi-notifications-on-marconi - https://etherpad.openstack.org/p/IcehouseMarconiNotificationService - https://www.dropbox.com/s/d2q1viz4ejebg24/marconi-notifications.png

Problem description

Zaqar’s support for queuing semantics that allow users to publish and consume messages to and from the service. These semantics cover several use-cases but they leave out others like ‘listening’ for messages. There are, as well as for prod/cons scenarios, many use-cases for pub/sub that need to be supported. Some examples of such use-cases are: mobile push notifications, support for events triggering, meetering, etc.

In order to cover the above scenarios, Zaqar needs to provide an API that will allow users for subscribing to specific queues and get messages from there without requiring to poll. This will allow for a better architecture on the client side, a more reliable interaction between Zaqar and the client in terms of connection management and it also opens the doors for supporting other scenarios.

Proposed change

The proposal is to extend Zaqar’s API with support for subscriptions without adding a separate service - please see the section below with regards to both services being merged. This proposal introduces the high-level changes required for this feature but the detailed API specification has yet to be written.

Here’s a, non-exahustive, list of resources required to support notifications:

Subscriptions: Subscriptions define what the subscriber wants to listen on. It contains the data of the queues/topics, routing parameters, maximum retries and other configirations required to correctly filter messages and keep the high-level guarantees.

A subscription is used by subscribers to listen on things. A non persistent subscriber - webhooks, sms, mobile push protocols - are configured in the subscription itself, whereas other subscribers using persistent connection can load a specific subscription they want to listen on.

A subscription consists in a object containing the information of the source, destination, expiration and a custom field that contains information useful for the notifier.

POST /v2/queues/{queue_name}/subscriptions

{
    'subscriber': 'http://trigger.me',
    'ttl': 3600,
    'options': {}
}

source: The source queue for notifications
subscriber: The subscriber URI. This can be any of the supported subscriber URI and the implementation must be based on stevedore to allow external contributions.
ttl: time to live for this subscription. It’s a positive number that expresses, in seconds, how long a subscription should exist. If omitted the subscription won’t expire.
options: publisher specific options.

Publishers: Publishers are users and/or third-party resources publishing messages to the notification endpoints. Users publishing messages to Zaqar don’t need any specialized endpoint for this. Messages must go through the normal and already implemented message publishing API. However, third-party publishers require a specific configuration. Third-party publishers consume messages from other services and publish them in zaqar’s queues.

Workers: Publishing tasks need to be executed in a distributed - or local to the node - fashion, they need to be reliable, fault-tolerant and atomic. To do so, I’ve evaluated taskflow as a valid library for this job. Taskflow has support for local/distributed, blocking/concurrent task execution. It provides support for several execution models, persistence layers - including sqlite, mysql and zookeeper - and it has support for retries. The alternative to taskflow is writing our on implementation for this work, which doesn’t seem to be worth it at this stage.

Push Protocols

There are several types of push technologies that could be supported, therefore the implementation must be generic enough to allow for new implementations to be done easily and also as external plugins.

Nonetheless, this spec proposes starting with just the first of the plugins proposed below:

Webhooks
Email
Mobile push
SMS

Why not 2 services

Zaqar has stated since its inception that it provides a single common API for things that other cloud services like AWS have in 2 separate services. Nonetheless, I think the real motivations for these 2 API’s to be under the same service are:

Maintenance: It’s easier to maintain and scale just 1 service type than a group of different services.
Consistency: It’ll help reducing the code needed to implement the notification API since they both will be running under the same structure and users will know where to find the services easily.
Performance: Implementing the notification API in a separte service will require a communication between that service and the queuing service. At least, it’ll require a constant polling from the backend (if it doesn’t support push itself). By having everything under the same service, we can trigger notification for messages as they come in.

Future Improvements

Support for subscription’s confirmation

Alternatives

Split the above into 2 different services. As mentioned in the previous section, 2 services don’t seem to be the ideal solution for this.

Implementation

Assignee(s)

Primary assignee:: flwang
Secondary assignees:: flaper87

Milestones

Target Milestone for completion:: Kilo-2

Work Items

Work on the detailed API spec
Write storage code for notifications
Implement the API on top of the storage code.
Work on the publishers

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Expose storage capabilities

Wed, 17 Jan 2018 00:00:00

Flavors allow operators to expose some of the internal storage capabilities without giving the exact details of how the system is configured. As of now, the operators has total control over what capabilities are exposed to the user regardeless on whether these capabilities are indeed guaranteed or valid. A capability is a feature that is either specific to the storage or to Zaqar - durable, fifo, in-memory, for example - and they can be enabled/exposed in a per-flavor basis allowing end-users to choose the best flavor for a specific queue.

https://blueprints.launchpad.net/zaqar/+spec/expose-storage-capabilities

Problem description

Flavors are very powerful when it comes to give choices to end-users without taking control out from operators. However, there’s no way for operators to know what capabilities each storage driver has, which makes this feature completely custom to whatever the operator thinks makes more sense.

It’s important to support operators on the choice of what features are exposed to the end-users through the API by making it clear which are supported by the drivers that have been deployed. Moreover, this is also important for doing a proper capacity planning based on the use-cases the service is trying to support.

Proposed change

Capabilities

This change request proposes defining a set of internal capabilities and a way for storage drivers to expose which capabilities are supported so that operators may know in advance what a flavor would support and what storage drivers they may need.

The set of internal capabilities includes:

FIFO
AOD (At least once delivery)
high-throughput
claims

Exposing Capabilities

This capabilities should be exposed by the storage driver iff supported. This spec proposes adding a new class method to the base class called capabilities that should return a set with a list of supported capabilities. The capabilities returned in this set cannot be custom, which means they must be supported internally.:

@six.add_metaclass(abc.ABCMeta)
class DataDriverBase(DriverBase):
    ...

@property
def capabilities(self):
    return self._CAPABILITIES

Drivers Load

In addition to the above-mentioned changes, we also need a better way to load drivers based on the capabilities. That is, when drivers are loaded, it’s necessary to pass down to the driver the capabilities that have been enabled per-flavor so that the driver itself can be specialized for some capabilities. In most of the cases, loading a driver will end up in always loading the same implementation. However, there are cases - FIFO, for example - where more specialized implementations may be needed depending on the storage. Therefore, instead of always loading the DataDriver, this spec proposes adding a new get_driver function that will let the storage itself load a driver according to the capabilities passed there.:

def get_driver(plane='data', capabilities=None):
    ...

This means we won’t need to register neither DataDriver`s nor `ControlDriver`s as `entry_points but just the new get_driver function. This will allow storage driver’s to expose fewer things as public API’s. A variant for the above get_driver proposal would be.:

def get_driver(base=base.BaseDataDriver, capabilities=None):
    ...

This way we can avoid giving ‘names’ to this planes and just ask what we need in terms of ‘signature’. However, it makes loading the actual driver a bit more complex and it’ll also duplicate some logic across different storage drivers.

Pools and Flavors

Flavors have support for capabilities. As of now, these capabilities are 100% custom. With the implementation of this spec, it’ll be possible for flavors to know in advance what capabilities are supported based on the stores registered in the pool.

Pools, however, shouldn’t allow storage drivers with different capabilities to co-exist under the same pool. That is to say that pools will have to verify the storage capabilities when new nodes are added to the pool and ensure that the capabilities supported by the new node are consistent with the rest of the nodes in the pool.

Alternatives

Keep it custom and do nothing.

Implementation

Assignee(s)

Primary assignee:: flaper87
Secondary assignee:: vkmc

Milestones

Target Milestone for completion:: K-1

Work Items

Define list of internal capabilities and document it
Add required abstractions to storage drivers to expose the supported capabilities
Let flavor’s pass the capabilities down to the storage driver when it’s being loaded.

Dependencies

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Authorization Policy Support

Wed, 17 Jan 2018 00:00:00

OpenStack components are supposed to check user privileges to perform any action. Generally these checks are role-based. See https://docs.openstack.org/keystone/latest/#approach-to-authorization-policy. Zaqar needs to support policies as well.

Problem description

Presently Zaqar is missing fine-grained permissions for actions. For example, it’s hard to allow one user only can get message from a queue but not be able to post message to the queue, or something like that.

Proposed change

Add policy check for all Zaqar API endpoints. This could be done by following the same way as in other OpenStack components, by leveraging the oslo.policy module which will do all the underlying work.

The implementation should be fairly simple, with oslo.policy’s Enforcer class being instantiated with the policy file, then the enforce method used to check each API call.

Proposed content of the policy file:

{
    "context_is_admin": "role:admin",
    "admin_or_owner":  "is_admin:True or project_id:%(project_id)s",
    "default": "rule:admin_or_owner",

    "queues:get_all": "",
    "queues:put": "",
    "queues:get": "",
    "queues:delete": "",

    "messages:post": "",
    "messages:get": "",
    "messages:bulk_get": "",
    "messages:bulk_delete": "",
    "messages:claim": "",

    "subscriptions:get_all": "",
    "subscriptions:create": "",
    "subscriptions:get": "",
    "subscriptions:delete": "",
    "subscriptions:update": "",
}

Alternatives

None.

Data model impact

None.

REST API impact

None.

Other end user impact

None.

Deployer impact

An additional file, policy.json must be deployed. The deployer should verify the settings in that file are correct for their deployment, such that the correct users are allowed access.

Developer impact

If there is any new API endpoint added for Zaqar, then policy rules in the json files should be updated accordingly.

Implementation

Assignee(s)

Primary assignee:: kragniz (Louis Taylor)

Milestones

Target Milestone for completion: L-1

Work Items

Add config options to point to control policy file and settings
Add policy check to all API calls
Add unit tests
Add documentation

Dependencies

Pre-Signed URLs

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/pre-signed-url

There’s a need to have pre-signed URLs - ala Swift’s tempURL - that would grant temporary access, to non-authenticated users, to specific queues.

Problem description

In cases where there’s a need to allow “outsiders” of the system - i.e guest-agents - to interact with Zaqar, it’s useful to have a way to grant them access so that they can do whatever is needed without giving these “outsiders” a username and password or any other kind of permission in the system.

This access, however, needs to be temporary, revocable and granular. Outsiders shouldn’t get access to more than 1 resource at a time and the permissions granted should identify what kind of operations they can execute.

Proposed change

The proposed solution to the aforementioned problem is to use pre-signed URLs. Services like Swift use a similar approach - called temp URL there - to provide access to internal resources. The pre-signed URL consists of a URL that contains a hash with the encoded permissions.

In order to make it easier to read/write this spec, let’s split it in several parts. The first part will describe the parts composing the URL. The second part will describe how the URL will be generated and the third part how it’ll be consumed.

Pre-Signed URL

A pre-signed URL ought to contain enough information for it to provide enough control over the resource being shared, without compromising security. Authorization is a must have and a huge part of this URL. Therefore, the information present in this URL has to be exhaustive in that perspective.

As mentioned in a previous paragraph, the URL contains a hashed piece of information that serializes the required fields. Those fields are:

Project: The keystone tenant of the entity generating the URL
TTL: Expiration time (in seconds) for the URL
Queue: Zaqar’s queue name that this URL gives access to
HTTP Method: 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.

The above fields will be part of the generated hash but they’ll also be available as public information in the URL. The reason they’re encoded is to have a way to verify that the URL has not been changed by the user whenever a request is made to Zaqar.

The generated hash will be an HMAC-SHA1. To generate such signature, it is required to have a secret key. In swift, it’s possible to have a key per-account. Unfortunately, that’s not possible in Zaqar + Keystone, therefore this spec proposes adding a new configuration option that will contain the key to use.:

[signed_url]
secret_key = some-very-strong-key

URL Generation

This spec proposes adding a new endpoint in the queue namespace that returns the generated signature and expiration time that’ll grant access to this resource. The request and response for this operation:

Request::

POST /v2/queues/shared_queue/share HTTP/1.1
...

{
    'methods': ['GET', 'POST']
}

Response::

HTTP/1.0 201 OK
...

{
    'signature': '518b51ea133c4facadae42c328d6b77b',
    'expires': 2015-05-31T19:00:17Z,
    'project': '7d2f63fd4dcc47528e9b1d08f989cc00',
    'url': '/v2/queues/shared_queue/messages',
    'methods': ['GET', 'POST']
}

This request sets a different expiration date for the URL. Note that the default method is GET.

Request::

POST /v2/queues/shared_queue/share HTTP/1.1
...

{
    'expires': 2015-06-19T19:00:00Z
}

Response::

HTTP/1.0 201 OK
...

{
    'signature': '518b51ea133c4facadae42c328d6b77b',
    'expires': 2015-06-19T19:00:00Z,
    'project': '7d2f63fd4dcc47528e9b1d08f989cc00',
    'url': '/v2/queues/shared_queue/messages'
    'methods': ['GET']
}

This request combines both parameters (methods and expires):

Request::

POST /v2/queues/shared_queue/share HTTP/1.1
...

{
    'methods': ['GET', 'POST'],
    'expires': 2015-06-19T19:00:00Z
}

Response::

HTTP/1.0 201 OK
...

{
    'signature': '518b51ea133c4facadae42c328d6b77b',
    'expires': 2015-06-19T19:00:00Z,
    'project': '7d2f63fd4dcc47528e9b1d08f989cc00',
    'url': '/v2/queues/shared_queue/messages'
    'methods': ['GET', 'POST']
}

Consuming the URL

First and foremost, it’s important to mention that NONE of the URL headers can/should be modified and/or omitted. As soon as one of them is, the signature verification will fail and therefore the request will respond 404.

Requests for pre-signed URLs will be processed by a middleware that should be placed before keystone’s middleware. This will allow us to authenticate the request in advance and skip keystone’s authentication. A request using the signature generated in the previous section would look like:

Request::

GET /v2/queues/shared_queue/messages HTTP/1.1
Host: zaqar.example.com
User-Agent: python/2.7 killer-rabbit/1.2
Date: Wed, 28 Nov 2012 21:14:19 GMT
Accept: application/json
Accept-Encoding: gzip
URL-Signature: 518b51ea133c4facadae42c328d6b77b
URL-Expires: 2015-05-31T19:00:17Z
X-Project-Id: 7d2f63fd4dcc47528e9b1d08f989cc00
Client-ID: 30387f00-39a0-11e2-be4d-a8d15f34bae2

Note that, in the above example, headers were chosen over query parameters. The main 2 reasons behind this choice are:

1. Consistency with other security related parameters - i.e X-Project-Id - that are sent in HTTP headers.

2. These new parameters don’t belong in the messages request and won’t affect messages navigation.

Similarly, other requests like the one below can be done.

Request::

GET /v2/queues/shared_queue/messages?marker=1355-237242-783&limit=10 HTTP/1.1
Host: zaqar.example.com
User-Agent: python/2.7 killer-rabbit/1.2
Date: Wed, 28 Nov 2012 21:14:19 GMT
Accept: application/json
Accept-Encoding: gzip
URL-Signature: 518b51ea133c4facadae42c328d6b77b
URL-Expires: 2015-05-31T19:00:17Z
X-Project-Id: 7d2f63fd4dcc47528e9b1d08f989cc00
Client-ID: 30387f00-39a0-11e2-be4d-a8d15f34bae2

Filtering and pagination are not part of the signature and fall into the read permissions that were granted on this.

Posting messages will work the same way:

Request::

POST /v2/queues/shared_queue/messages HTTP/1.1
Host: zaqar.example.com
User-Agent: python/2.7 killer-rabbit/1.2
Date: Wed, 28 Nov 2012 21:14:19 GMT
Accept: application/json
Accept-Encoding: gzip
URL-Signature: 518b51ea133c4facadae42c328d6b77b
URL-Expires: 2015-05-31T19:00:17Z
X-Project-Id: 7d2f63fd4dcc47528e9b1d08f989cc00
Client-ID: 30387f00-39a0-11e2-be4d-a8d15f34bae2

...

Other Notes

In the case of pre-signed URLs, the queue cannot be created lazily. This is to prevent cases where queues are deleted and users still have a valid URL. This is not a big issues in cases where there’s just 1 pool. However, if there’s a deployment using more than 1 type of pool, the lazily created queue may end up in an undesired pool and it’d be possible for an attacker to try a DoS on that pool. Therefore, whenever a pre-signed URL is created, if a pool doesn’t exist, one will be created.
I’m not a fan of passing the project-id around but I can’t think of another way to do this and still have the ability to preserve multi-tenancy without passing the project.
I don’t like having the key set in the config file. In future versions, we could think of making this information part of the queue itself. The reason we can’t do that right now is because we don’t have private fields in the metadata. It should be easy enough to do it as an enhancement for this feature.
As a future enhancement, we could also use Barbican for key management.

Drawbacks

Security issues may be added by this work. We ought to be extra careful on reviews and create a vulnerability team that is ready to address any issues that might come up.

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: flaper87

Work Items

Write utilities to generate the signature with proper tests
Add the endpoint that generates the pre-signed URL
Create a middleware capable of processing these URL

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Tests refactoring

Wed, 17 Jan 2018 00:00:00

Include the URL of your launchpad blueprint:

https://blueprints.launchpad.net/zaqar/+spec/tests-refactoring

Zaqar tests are currently split into 2 different places, we want to reunite them.

Problem description

Tests currently exists in the tests top directory in the tree, but most of them import abstract base classes from the zaqar.tests python package and set attributes to be able to run them. There are also some tests definition in the tests directory. It’s not obvious that tests in the zaqar.tests package are not run when using tox and in the gate, and it creates confusion on where the tests should properly live.

Proposed change

Move all the tests in the zaqar.tests package, and delete the tests directory.

To be able to have a reviewable stream, we will slowly add directories in zaqar/tests to the testrepository configuration, and move them in small chunks.

Alternatives

None.

Implementation

Assignee(s)

Primary assignee:: therve

Milestones

Target Milestone for completion:: Liberty-1

Work Items

Add one tests directory to .testr.conf and move the tests over
Iterate over all the tests directories in zaqar/tests
Move remaining tests out of tests/

Dependencies

None.

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

More reserved queue attributes

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/more-reserved-queue-attributes

Currently Zaqar supports setting metadata/attributes when user creating queue. However, the metadata/attributes are not used very much by Zaqar itself. Now we only support ‘_flavor’ but it would be nice if we can support more attributes to make the queue more flexible.

Problem description

Now Zaqar supports max_messages_post_size, default_message_ttl, default_claim_ttl and default_claim_grace. All of them defined in Zaqar’s configuration file. That means it’s global setting, all queues have to share the same configurations. It’s not really flexible from the end user perspective. So it would be nice if we can let end user set them and use the default value in configuration file if they are not defined.

Proposed change

The changes are not complicated, which may change two actions: Post messages and create claim for a queue.

Post Message: At line stable/liberty/zaqar/transport/wsgi/v2_0/messages.py#L182, we need to get the queue’s metadata so as to get the queue’s max_messages_post_size and ttl defined by user when creating the queue. If those aren’t exist, then just use the global configuration defined in configuration file.
Create Claim: Similar thing like above, we need to get the queue’s metadata at line stable/liberty/zaqar/transport/wsgi/v2_0/claims.py#L81 and then use that to do the check.

Drawbacks

It may introduce a tiny performance impact for message posting and claim creating. For example, instead of just checking if the queue is existing or not, Zaqar need to get the queue’s metadata so that to get those attributes. But actually, we can use ‘get_metadata’ replace ‘exists’ to check if the queue exist or not, and they’re calling the same collection.find_one() method, so technically, there is no performance impact.

Alternatives

Just keep current way, let all the queues share the same configurations.

Implementation

Assignee(s)

Primary assignee:: flwang (flwang@catalyst.net.nz)

Work Items

Support max_messages_size and ttl as queue attributes
Support claim_ttl and claim_grace as queue attributes

Dependencies

N/A

Support for binary data in the websocket transport

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/websocket-binary-support

Implement support for binary communications over websocket transport which will allow to reduce network traffic between Zaqar and it’s clients and also to increase performance.

Problem description

Currently websocket transport uses only text messages packed in JSON format to exchange data with clients.

An attempt to send binary data to Zaqar’s websocket transport will lead to receiving ‘bad request’ (HTTP error 400) response from Zaqar.

But websocket protocol actually allows communication via binary messages. Data packed(serialized) in binary format can be smaller and also may take less CPU time to pack/unpack it.

By using binary messages for communications it’s possible to reduce network traffic between Zaqar and it’s clients and also to increase Zaqar’s performance. It can also increase client performance if the client is not written in JavaScript.

Proposed change

We can serialize/deserialize data via MsgPack technology which was already proposed and approved in persistent-transport specification.

Deserialization of incoming messages to Zaqar

As you can see in protocol.py#L55, Zaqar already can distinguish binary and text messages.

So we will make Zaqar try to deserialize each received binary message via ‘msgpack’ library into a python object, just like Zaqar currently deserializes JSON messages via ‘json’ library. After successful deserialization the message can be processed as usual.

Serialization of response and subscription messages from Zaqar

The response from Zaqar will be serialized in the same format as the incoming request.

The subscription messages from Zaqar will be serialized in binary or text format based on the format of subscription create request.

Let’s take a look at the case where the client suddenly changes it’s messaging format while connection is open and subscription is still alive. There might be a problem when the client will not be able to deserialize the messages coming from the old subscription, because it has switched the format by changing some boolean variable (switch). But this situation is nearly impossible and, if not, the problem is solvable:

It’s hard to imagine a situation when it might be useful for the client to change it’s serialization format. Such client will probably never exist.
Even if such client will exist in the future, the client developer will take care of it by adding the code checking the format of each incoming message and deserializing the message accordingly inside “on message” method. Zaqar does exactly this, for example. All websocket implementations provide a convenient way to determine the format of each particular message.
Even if the client developer will not take care of this potential problem (he is inexperienced, for example) and will make the client just expect all incoming messages in the new format after switching while the old subscription is still alive, the client will crash on the first incoming message from this subscription and the problem will not go unnoticed.

Websocket html client example upgrade

The websocket html client example will be changed to make it also being able to communicate with Zaqar via binary messages.

Drawbacks

The performance of web clients on JavaScript

Seems like MsgPack serialization/deserialization works slower than JSON in JavaScript. Well, no surprise since JSON abbreviation expands to “JavaScript Object Notation”. It’s a drawback for Zaqar web clients as it decreases their performance.

How the change addresses this drawback:

The server is one and clients are many. The server processes much more messages than each particular client. So there are many cases when it’s reasonable to use binary serialization to increase server performance by sacrificing performance of JavaScript clients.
The additional delays on JavaScript clients are slightly compensated by faster responses from the server.
JavaScript clients can always use good old text format for communications with the server, while other clients can use binary format with the same server simultaneously.

Alternatives

These alternatives completely exclude the nearly impossible case where the client may suddenly switch it’s messaging format, while the connection is open and the old subscription is still alive, and while proper deserialization of incoming messages to the client is managed by some client’s boolean variable (switch).

Alternatives of serialization of response and subscription messages from Zaqar

Optional parameter approach

The response from Zaqar will be serialized in the same format as the incoming request.

The subscription messages from Zaqar will be serialized in binary or text format based on the new optional parameter passed in the message body of subscription create request. We can add this parameter to websocket API, name it accept, allow it to have only two possible values: json and msgpack and make json value as default if accept parameter was not passed. By making accept parameter optional, we are achieving backward compatibility.

Subscription request message example before implementation:

{
    'action': 'subscription_create',
    'headers': {'Client-ID': 31209ff3-ba03-4cec-b4ca-655f4899f8aa,
                'X-Project-ID': superproject},
    'body': {'queue_name': 'superqueue', 'ttl': 3600}
}

Subscription request message after implementation can be the same as before or it can also pass accept parameter explicitly:

{
    'action': 'subscription_create',
    'headers': {'Client-ID': 31209ff3-ba03-4cec-b4ca-655f4899f8aa,
                'X-Project-ID': superproject},
    'body': {'queue_name': 'superqueue', 'ttl': 3600, 'accept': 'json'}
}

First message approach

The response and subscription messages from Zaqar will be serialized in binary or text format based on in which format the particular client has sent it’s first successfully parsed message to Zaqar since connecting.

Once the format of communications between Zaqar and the client was established by that way, the client will not be able to change it, unless the client will reconnect to Zaqar and send the first message in other format.

Zaqar configuration approach

The response and subscription messages from Zaqar will be serialized in binary or text format based on the boolean variable in Zaqar server configuration.

Implementation

Assignee(s)

Primary assignee:: ubershy

Milestones

Target Milestone for completion:: Mitaka-2

Work Items

None

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

The title of your blueprint

Wed, 17 Jan 2018 00:00:00

Include the URL of your launchpad blueprint:

https://blueprints.launchpad.net/zaqar/+spec/example

Introduction paragraph – why are we doing anything?

Driver description

A detailed description of the driver.

Proposed change

Here is where you cover the change you propose to make in detail. How do you propose to solve this problem?

If this is one part of a larger effort make it clear where this piece ends. In other words, what’s the scope of this effort?

What are the driver’s guarantees in terms of reliability?

“Zaqar aims to be a fully-reliable service, therefore messages should never be lost under any circumstances except for when the message’s expiration time (ttl) is reached…”

What are the driver’s guarantees in terms of scalability?

Zaqar aims to be an easily scalable service. Zaqar provides an easy way to scale web-heads and to balance queue’s load across several different storage clusters. However, the real scalability is provided by the storage itself. If the storage can’t be unlimitedly scaled or it’s hard to scale, it’ll break this guarantee. Supported storage must be good for general use-cases and easy to scale unlimitedly. It’s fine to have storage drivers for very specific use-cases but it’s likely not going to be possible to maintain those drivers.

What are the driver’s guarantees in terms of interoperability?

In order for applications to easily talk to different clouds supporting Zaqar, it is necessary for the service to guarantee interoperability as much as possible. Lots of the interoperability guarantees depend on how the service itself is deployed. However, the team strives to provide an interoperable service and guide operators on what the best way to deploy the service is.

What are the driver’s guarantees in terms of openness?

Zaqar is an open-source software licensed under the Apache 2 license. It aims to be able to be installed in any deployments and circumstances. In order to do that, it tries to support technologies that will alow deployers to do so without any constraint. In order for the team to be able to maintain and support a storage driver, the driver has to be licensed under an open license and so has to be the technology the driver supports. The team won’t be able to maintain drivers relying on closed technologies that cannot be tested/deployed.

Implementation

Assignee(s)

Who is leading the writing of the code? Or is this a blueprint where you’re throwing it out there to see who picks it up?

If more than one person is working on the implementation, please designate the primary author and contact.

Primary assignee:: <launchpad-id or None>

Can list additional ids if they intend on doing substantial implementation work on this blueprint.

Milestones

Target Milestone for completion:: Juno-2

Work Items

Dependencies

Include specific references to specs and/or blueprints in zaqar, or in other projects, that this one either depends on or is related to.

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Lazy queues in subscriptions

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/lazy-queues-in-subscriptions

Make queues lazy on operations with subscriptions, so the user will be able to subscribe to yet unexisting queue.

Problem description

Queues are designed to be lazy resources in Zaqar’s API v1.1 and API v2 in messaging. That means, for example, that the user can post messages to unexisting queue, and the queue will be automatically created. But now queues do not behave like lazy resources on operations with subscriptions. Before creating a subscription, the user must ensure the queue exists, or Zaqar will send error response with HTTP code 400.

Proposed change

Make queues lazy on operations with subscriptions, so the user will be able to subscribe to yet unexisting queue. Make Zaqar do not send error response on queue creation operation in the case queue does not exists.

Advantages:

The behavior of API will be more consistent, because after the change queues will be lazy in all situations.
It will be easier for the user to work with subscriptions. No need to do pre-check for queue existence, or handle 400 error response from Zaqar, or always pre-create queue.
There will be no need to solve currently existing problem when the queue was deleted, but subscriptions to it are still existing. Problem solving will probably require storage driver code to delete also all subscriptions to a queue, when deleting the queue. It may be very undesirable for the user, because subscriptions will not guarantee to be existing till TTL expiration, and will need to be renewed also after queue delete and queue create operations. Proper solution to this problem will complicate behavior in many ways in both Zaqar and client’s code. It will be probably backward incompatible change.

The change is backward compatible. Client’s code should work after the change.

Drawbacks

None

Alternatives

Two alternatives:

Keep the current behavior.
There is opinion to make queues non-lazy resources in all situations like it was in API v1. But it will be backward incompatible change to our API v1.1 and API v2, so maybe make it in the distant future.

Both of them will require solving the problem about still active subscriptions to a queue that was deleted.

Implementation

Assignee(s)

Primary assignee:: ubershy

Milestones

Target Milestone for completion:: Newton-1

Work Items

Remove checks for queue existence on operations with subscriptions from storage drivers.
Remove the code that is catching QueueDoesNotExist exception on operations with subscriptions from transport drivers.
Change functional and unit tests accordingly.

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Subscription confirmation support

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/subscription-confirmation-support

Support subscribers confirm that whether they want the notifications or not before Zaqar sends them.

Problem description

Currently Zaqar can post notifications to the subscriber once the subscription is created. It doesn’t need the subscriber to confirm the subscription. This will lead a problem that users could send junk information that whether subscriber wants or not.

Proposed change

With Amazon SNS as reference, we will support to send HTTP POST request that contains subscription confirmation information(e.g. message type, pre-signed confirmation URL, signature information) to subscription endpoint. The endpoint needs to use the URL in notification to confirm subscription. When the subscription is deleted, Zaqar server will send a notification that the subscription with ID has been deleted. This mechanism tells endpoint no need to wait notifications any more.

The message types will be SubscriptionConfirmation, Notification and UnsubscribeConfirmation.
For backward compatibility, we also should add new option in Zaqar configuration file like this:
```
[notification]
require_confirmation=true/false
```

If the user omits this option in config, it will be ‘false’ by default. In further, we may change the default value to ‘true’ to let subscription more secure.

So the workflow will be this in webhook:

User creates subscription in Zaqar.

Zaqar sends a HTTP POST request with subscription confirmation information. This request is like this:

POST URL:

http://endpointUrl

Request Body:

 {
     'MessageType': 'SubscriptionConfirmation',
     'Message': 'You have chosen to subscribe to the queue: xxx.',
     'URL-Signature': 'xxxx',
     'URL-METHODS': 'PUT',
     'URL-PATHS': '/v2/queues/{queue_name}/subscriptions/{subscriptions_id}/confirm',
     'X-PROJECT-ID': 'xxxx',
     'URL-EXPIRES': '3600-01-01T00:00:00',
     'SubscribeURL': 'https://zaqar_server/v2/queues/{queue_name}/subscriptions/{subscriptions_id}/confirm',
     'SubscribeBody': {'confirmed': True},
     'UnsubscribeBody': {'confirmed': False},
}

Subscriber confirms this subscription by using those information in request body, and sends the pre-signed confirmation request to Zaqar. It’s a new endpoint in Zaqar. This request is like this:

PUT URL:
```
https://zaqar_server/v2/queues/{queue_name}/subscriptions/{subscriptions_id}/confirm
```
Request Body:
```
{
    'confirmed': True
}
```
Meanwhile, HTTP headers are also required by using pre-signed feature in Zaqar. If subscriber wants to unsubscribe this subscription, just needs to set ‘confirmed’ to False. If Zaqar processes this request successfully, Zaqar will response with:

Response code:
```
204
```
If Zaqar has failed processsing this request because of some error, it will return error message in response body.
Zaqar begins to send notifications to this endpoint after confirmation workflow is finished.

Note

If Zaqar server didn’t receive the response or subscriber didn’t sent it since something wrong, subscription will keep ‘confirmed’ as false, and Zaqar will support to resend confirmation request by calling subscription creation API again.

So the workflow will be this in email:

User creates subscription in Zaqar.
Zaqar sends an email with subscription confirmation page link. Email context is like this:: “You have chosen to subscribe to the queue: {queue name}.” “This queue belongs to project: {project id}.” “To confirm this subscription, click or visit this linke below:” “{confirmation link}”
When subscriber visits this link, he gets a page which calls Zaqar by ajax request to confirm the subscription as same as webhook way.
The page shows information about was the subscription successfully confirmed or not.
Zaqar begins to send notifications to this endpoint.

Note

About the confirmation page, Zaqar will host a sample page in Zaqar tree, but it’s not a part of Zaqar service. Cloud administrator should provide hosting for this page manually. After this page is hosted successfully, cloud administrator should specify this page location in Zaqar config “external_confirmation_url”.

Drawbacks

None

Alternatives

Another option is when subscriber creates a subscription, he also need to call Zaqar’s confirmation API to confirm it before confirmation is expired. In this option, Zaqar will not send any confirmation notification by itself.

Data model impact

Add new status “confirmed” into subscription model.

Implementation

Assignee(s)

Primary assignee:: wangxiyuan<wangxiyuan@huawei.com>
Secondary assignee:: wanghao<wanghao749@huawei.com>

Milestones

Target Milestone for completion:: Newton-3

Work Items

Implement subscriber confirmation API in wsgi.
Update subscription resource to add new property “confirmed” on MongoDB driver.
Add new config options.
Update notification to send confirmation message in way email.
Implement subscriber confirmation API in websocket.
Update subscription resource on other drivers.
Update notification to send confirmation message in way webhook.
Add message type.

Dependencies

Amazon SNS: http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html

Purge queue

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/purge-queue

Though user can delete messages, claims or subscriptions from a queue, but there is no way to delete many of them at once.

Problem description

Now Zaqar is missing a fast way to delete many resources at once for a given queue. This could be handy for user to clean the queue and keep all the metadata of the queue.

Proposed change

New endpoint for action ‘purge’ for queue:

/v2/queues/myqueue/purge

POST body:

{"resource_types": ["messages", "subscriptions"]}

So the idea is if there is no POST body, by default, all the resources under the queue will be delete. Otherwise, if the key ‘resource_types’ in the POST body, then Zaqar will delete resources based on the given resource types. It’s a list and it could be one of the combinations of the two types: ‘messages’, and ‘subscriptions’.

Currently, it’s hard to list “claims” under a queue, so this feature won’t support clean “claims”.

Drawbacks

N/A

Alternatives

User has to delete messages and subscriptions of the queue manually.

Implementation

Assignee(s)

Primary assignee:: flwang (flwang@catalyst.net.nz)

Work Items

Add a new method ‘purge’ for storage queue controller which will delete all messages and subscriptions under the queue.

Dependencies

N/A

Dead Letter Queue

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/dead-letter-queue

Problem description

Currently, Zaqar can’t do anything if the message has been claimed many times and still can’t be processed successfully. That could be nice if Zaqar can provide the dead letter queue support so that user can provide an existing queue A for queue B’s dead letter queue. Dead letter queue storing these messages allows developers to look for common patterns and potential software problems.

Proposed change

1. Add three new reserved attributes for queue’s metadata: _max_claim_count and _dead_letter_queue.

_max_claim_count is 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.

_dead_letter_queue is 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. It’s not the case we want to address in this spec. Technically, even though user can set a dead letter queue C for queue B(when queue B is a dead letter queue of queue A), because the moving is triggered by claim, so that means if user won’t explicitly claim messages in queue B, then nothing happened.

_dead_letter_queue_messages_ttl is the new TTL setting for messages when moved to DLQ. If it’s not set, current TTL will be kept.

2. Make sure the DLQ and current queue are in the same pool when doing validation to get better performance.

3. Add a new filed for message in database which can be used to save the claim count.

Changes for claim create method

4.1. get current claim count from the message, update the claim count by plus one.

4.2. check if the claim count has exceeded the max claim count defined in queue’s metadata. If it doesn’t exceed the _max_claim_count, just do normal claim.

4.3. If the claim count does exceed the _max_claim_count, move the message to the dead letter queue directly. Given the goal of DLQ, we’d like to keep the claim information of the message. So depends on the storage backend, the “move” could introduce a limitation. For example, for MongoDB backend, we may have to move the message from the source queue to DLQ by changing the queue name directly. Which means the two have to be created on same storage pool.

After moved the message, Zaqar will do nothing against those messages in dead letter queue. User could/will use these message to debug why those messages can’t be processed successfully. In other words, allows developers to look for common patterns and potential software problems from those messages.

4.4. messages moved to DLQ will be updated their TTL based on the setting _dead_letter_queue_messages_ttl. If it’s not set, currentl TTL of messages will be kept.

Drawbacks

Based on current design, we may have a limitation because of the technical trade off. When move the message from source queue to dead letter queue, it’d be nice to keep the claim info, but if we want to do that, we have to make sure the two queues are on same storage pool. The implementation could be different on different back ends.

Alternatives

None

Implementation

Assignee(s)

Primary assignee:: flwang <flwang@catalyst.net.nz>

Milestones

Target Milestone for completion:: Pike-3

Work Items

Add _max_claim_count and _dead_letter_queue as reserved attributes in queue metadata
Add validation for the new reserved attributes
Add a new filed for message to count the claim, this needs to be done against maongoDB, swift and redis.
Add change in claim create which will add the claim count for messages and check if the count has exceed the max claim count defined in queue’s metadata. If it has exceeded, move the message to the dead letter queue.
Add release note for this feature
Update API reference
Add user/developer document for this feature
Change unit, functional and tempest tests accordingly.

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Notification Delivery Policy

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/notification-delivery-policy

Sometimes, because of network/internet connection issue or the load of the target services/applications, the notification sent from Zaqar to the subscriber may fail, so it would be nice if we can support a retry and user can define the retry policy in the options of subscription.

This feature is only for HTTP/HTTPS subscription way, not including the Email notification.

Problem description

Now Zaqar didn’t have notification delivery policy, that means there is no retries if endpoint has some problem that can’t receive the notification. For users or applications, it’s missing important message without notification.

AWS SNS service has supported the policy, that would be a good reference for Zaqar[1].

Proposed change

For clarification what we want to do, there is some questions to be answered:

When do the notification delivery policy work?

Zaqar only attempts a retry after a failed delivery attempt. Those situations as a failed delivery attempt:

HTTP status in the range 500-599.
HTTP status outside the range 200-599.
A request timeout.
Any connection error such as connection timeout, endpoint unreachable, etc.

How do the notification delivery policy work?

You can use delivery policies to control not only the total number of retries, but also the time delay between each retry.

There are total four discrete phases that user can use to set policy of retry:

Immediate Retry Phase: Also called the no delay phase, this phase occurs immediately after the initial delivery attempt. The value user set for ‘Retries with no delay’ determines the number of retries immediately after the initial delivery attempt. There is no delay between retries in this phase.
Pre-Backoff Phase: The pre-backoff phase follows the immediate retry phase. Use this phase to create a set of retries that occur before a backoff function applies to the retries. Use the ‘Minimum delay retries’ setting to specify the number of retries in the Pre-Backoff Phase. User can control the time delay between retries in this phase by using the ‘Minimum delay’ setting.
Backoff Phase: This phase is called the backoff phase because user can control the delay between retries in this phase using the retry backoff function. Set the ‘Minimum delay’ and the ‘Maximum delay’, and then select a Retry backoff function to define how quickly the delay increases from the minimum delay to the maximum delay.
Post-Backoff Phase: The post-backoff phase follows the backoff phase. Use the ‘Maximum delay retries’ setting to specify the number of retries in the post-backoff phase. You can control the time delay between retries in this phase by using the ‘Maximum delay’ setting.

User can create and apply the retry policies to queues and subscriptions when creating them. So when Zaqar send the notification to those subscribers, it will use those policies to make retried after initial delivery attempt failed.

..note:

By default, if there are retry policies on both queue and subscription,
Zaqar will use the subscription's policy. If user don't want the override
he can set the ignore_subscription_override=True in _retry_policy metadata
of the queue.

What changes will bring into Zaqar?

First, user can create retry policies in metadata which’s in request body of queue creation.
Second, user also can create retry policies in options which’s in request body of subscription creation. If retry policy are set to both queue and subscription, Zaqar will use subscription policy instead of queue policy by default, but if ignore_subscription_override is True in queue’s metadata then Zaqar will still use the retry policy in queue.
Third, change the logic of notification, when fail is existing when sending notification to endpoint, then use the policy which has binded to this subscription to make retries, if subscription doesn’t have retry policy, then Zaqar will use the policy in queue’s metadata.

Since ‘metadata’ in queue and ‘options’ in subscription are dict, the data model of retry policy should be like this:

{
   '_retry_policy': {
                       'retries_with_no_delay': <Integer value, optional>,
                       'minimum_delay_retries': <Integer value, optional>,
                       'minimum_delay': <Interger value, optional>,
                       'maximum_delay': <Interger value, optional>,
                       'maximum_delay_retries': <Integer value, optional>,
                       'retry_backoff_function': <String value, optional>,
                       'ignore_subscription_override': <Bool value, optional>
                    }
}

'minimum_delay' and 'maximum_delay' mean delay time in seconds.
'retry_backoff_function' mean name of retry backoff function.
There will be a enum in Zaqar that contain all valid values. At first step,
Zaqar only supports one function: 'linear'.
If value of retry_policy is empty dict, that Zaqar will use default
value to those keys:
* retries_with_no_delay=3
* minimum_delay_retries=3
* minimum_delay=5
* maximum_delay=30
* maximum_delay_retries=3
* retry_backoff_function=linear
* ignore_subscription_override=False
Those default values will be configurable in Queens.

..note:

Retry policy is only applied for webhook(http/https) subscriber.
Zaqar will support linear retry backoff function only in Pike release,
it will increase the delay time linearly within 10 times from minimum delay
to maximum delay. We will support more retry backoff functions in future.
For avoiding the users receive notification message repeatedly
if connection is reconnected during retry process, once Zaqar sends the
notification successfully when doing retry, it will stop the whole retry
process.

Example

For better to know how does this work, there is an example case. Assume user use the default value of retry policy in a queue A, and create a subscription with HTTP subscriber: http://192.168.1.100:8080. When Zaqar send the notifications to this subscriber, it get a response with HTTP code 500, then the retry policy will go to work:

Phase 1: Immediate Retry. Zaqar will call the subscriber with no delay by 3: times. If there is no one successful, then go to Phase 2. If one of retries is successful, the retry process will be end.
Phase 2: Pre-Backoff. According to the minimum_delay_retries and minimum_delay.: Zaqar will make a total of 3 retries with a 5 second delay between each retry. If there is no one successful, then go to Phase 3. If one of retries is successful, the retry process will be end.
Phase 3: Backoff. By using the linear function, Zaqar will make the delay: between retries to increase at a constant rate over the course of the backoff phase. So as the constant rate is 5, Zaqar will call subscriber 12 times with delay time: [5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60]. If there is on one successful, then go to Phase 4. If one of retries is successful, the retry process will be end.
Phase 4: Post-Backoff. According to the maximum_delay and: maximum_delay_retries, Zaqar will make a total of 3 retries with a 60 second delay between each retry. After this phase, no matter the call is successful or not, the retry process will be end.

Drawbacks

N/A

Alternatives

N/A

Implementation

Assignee(s)

Primary assignee:: wanghao (sxmatch1986@gmail.com)

Milestones

P-3

Work Items

Add verification for retry policy when creating queue and subscription.
Change the notification process for applying the policy.
UTs for this feature.

Dependencies

[1]: http://docs.aws.amazon.com/sns/latest/dg/DeliveryPolicies.html

Support More Backoff Functions

Wed, 17 Jan 2018 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/support-more-backoff-functions

Sometimes, because of network/internet connection issue or the load of the target services/applications, the notification sent from Zaqar to the subscriber may fail. That means there is no retries if endpoint has some problem that can’t receive the notification. For users or applications, it’s missing important message without notification. To solve this problem, Zaqar has supported notification delivery policy in pike release [1].

Problem description

Now that Zaqar has supported only linear retry backoff function in Pike release,it increases the delay time linearly from minimum delay to maximum delay. We will support more retry backoff functions in Zaqar now.

Fortunately, AWS SNS service has supported the policy, that would be a good reference for Zaqar[2].

Proposed change

For clarification what we want to do, there are some questions to be answered:

How many retry backoff functions Will Zaqar support?

You can choose from four retry backoff functions as follows:

Linear.
Arithmetic.
Geometric.
Exponential.

What difference between these four retry backoff functions?

As we can see the picture in chapter Backoff Phase in [2], The screen shot shows how each retry backoff function affects the delay associated with messages during the backoff period. The vertical axis represents the delay in seconds associated with each of the 10 retries. The horizontal axis represents the retry number. The minimum delay is 5 seconds, and the maximum delay is 260 seconds.

The formula of these four retry backoff functions

Generally, we assume that the minimum delay is MIN, the maximum delay is MAX, and the total retry number is NUM. From three element above, we can conclude the formula of these four retry backoff functions.

Linear.

LINEAR_INTERVAL = ( MAX - MIN ) / NUM time1 = MIN time2 = MIN + LINEAR_INTERVAL*1 time3 = MIN + LINEAR_INTERVAL*2 timen = MIN + LINEAR_INTERVAL*(n-1) timeN = MAX

The Linear retry backoff functions has already been implemented in Pike release, we only list here for reference and comparing.
Geometric

we assume the common ratio of a geometric series is K: time1 = MIN time2 = K * MIN time3 = K^2 * MIN timen = K^(n-1) * MIN timeN = K^(NUM-1) * MIN = MAX

so :

K^(NUM-1) = MAX/MIN lg[ K^(NUM-1) ] = lg( MAX/MIN ) (NUM-1) * lg(K) = lg( MAX/MIN ) lg(K) = lg( MAX/MIN ) / (NUM-1) K = 10^[ lg( MAX/MIN ) / (NUM-1) ]

Finally:

timen = {10^[ lg( MAX/MIN ) / (NUM-1) ]}^(n-1) * MIN
Exponential.

we assume the power exponent of a exponential series is k, coefficient is p:

the general function of power exponent of a exponential series is: y = p * k^x

time1 = MIN = p*k^1 timeN = MAX = p*k^NUM MAX/MIN = k^(NUM-1) lg(MAX/MIN) = (NUM-1)*lg(k) lg(k) = lg(MAX/MIN)/ (NUM-1) k = 10^[lg(MAX/MIN)/ (NUM-1)] p = MIN/{10^[lg(MAX/MIN)/ (NUM-1)]}

Finally:

timen = p*k^n timen = MIN/{10^[lg(MAX/MIN)/ (NUM-1)]} * {10^[lg(MAX/MIN)/ (NUM-1)]} ^n
Arithmetic.

we assume the common difference of a arithmetic series is d:

time1 = MIN time2 = time1 + d*1 time3 = time2 + d*2 time4 = time3 + d*3

timen = timen-1 + d*(n-1)

timeN = timeN-1 + d*(NUM-1) = MAX

So: timeN - time1 = NUM*(NUM-1)/2*d

d = 2*(MAX-MIN)/[NUM*(NUM-1)]

timen - time1 = n*(n-1)/2 * { 2*(MAX-MIN)/[NUM*(NUM-1)] }

Finally:

timen = n*(n-1)/2 * { 2*(MAX-MIN)/[NUM*(NUM-1)] } + MIN

What changes will bring into Zaqar?

First, we will define three functions according to formula of these retry backoff functions.
Second, change the logic of notification, when fail is existing when sending notification to endpoint, then use the policy which has binded to this subscription to make retries. In Backoff Phase, we will select the retry backoff functions according to user choice to resend notification.

Drawbacks

N/A

Alternatives

N/A

Implementation

Assignee(s)

Primary assignee:: gecong (ge.cong@zte.com.cn)

Milestones

Q-2

Work Items

Add three functions according to formula of these retry backoff functions.
Change the Backoff Phase of notification process for applying the retry backoff functions.
UTs for this feature.

Dependencies

[1]:https://specs.openstack.org/openstack/zaqar-specs/specs/pike/notification-delivery-policy.html [2]:http://docs.aws.amazon.com/sns/latest/dg/DeliveryPolicies.html

Contributing to: zaqar-specs

Wed, 13 Sep 2017 00:00:00

If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

https://docs.openstack.org/infra/manual/developers.html

Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at:

https://docs.openstack.org/infra/manual/developers.html#development-workflow

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/zaqar

Persistent transport

Fri, 20 Jan 2017 00:00:00

Currently Zaqar has support for a non-persistent transport, leaving aside some use cases that would be covered in a more efficient and reliable way with a persistent transport solution.

Some use cases that will be positively impacted by this change are:

Communication with browsers: Websocket will enhance the communication between browsers and Zaqar, a key factor in the integration of Zaqar with the OpenStack Dashboard (Horizon).
Notifications: this type of transport will constitute a better protocol for notifications, a feature planned for Kilo as well.

https://blueprints.launchpad.net/zaqar/+spec/persistent-transport

Problem description

Currently there is no way to establish persistent connections in Zaqar. This spec proposes adding this feature through a websocket implementation.

During Kilo release we refactored the code to make the addition of this driver feasible, and we worked on adding the queues endpoint.

To provide full support for the data plane, we should add the messages endpoint and the claims endpoint.

The control plane operations do not require the performance that a websocket driver can provide, hence we are not going to add websocket support for the control plane.

Proposed change

The proposed change, as stated in previous sections, is to add a persistent transport alternative to Zaqar. This can be done by using websocket.

Websocket provide a full-duplex communication channel operating over a single socket that will remove overhead and significantly reduce complexity.

Fallback

In case WebSocket is not available, the client will fallback to short-polling the REST API.

Some of the reasons of WebSockets not being available are:

Firewalls could be configured to kill HTTP connections after a certain amount of time.
Concerns from a security standpoint will lead to killing any traffic over port 80 or 443 that doesn’t look like HTTP.

Messages serialization

A serialization technology is needed in order to transport data. There are several alternatives, including JSON, MsgPack, Protobuf, Apache Avro and Cap’n Proto.

In the previous cycle we noted that the whereas MsgPack was the best candidate -considering overall performance, easiness to use, languages support, data structures support-, it doesn’t have good support for Javascript. Using MsgPack would impose a significative constraint to the Zaqar use cases, considering that many web applications nowaways are written with Javascript. For that reason, we decided to stick with JSON and maybe talk about a more performant serialization technology in a future change.

Alternatives

Establish persistent connections enabling WSGI keep-alive
Long polling

Implementation

Assignee(s)

Primary assignee: vkmc

Milestones

Target Milestone for completion: Liberty-1

Work Items

Implement messages controller
Implement claims controller
Write messages unit tests
Write claims unit tests
Would like to have: write functional tests
Perform benchmarks with the new driver

WebSocket Libraries

After discussing several alternatives, including SockJS, SocketIO, Autobahn, ws4py and Tornado, it has been decided that Autobahn is going to be used to implement this feature. More details on this decision will be available in the WebSockets wiki.

Dependencies

https://blueprints.launchpad.net/zaqar/+spec/cross-transport-api-spec

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Finish client support for v1.1 features

Wed, 23 Nov 2016 00:00:00

https://blueprints.launchpad.net/zaqar/+spec/finish-client-support- for-v1.1-features

Several endpoints have been added without being reflected on the client side. This endpoints include:

Pools
Flavors
Notifications

Adding support for these features would make developing applications with Zaqar easier.

Problem description

Python-zaqarclient currently has some missing features that need to be added. This spec describes which endpoints are missing and how those are going to be added to the client side.

Proposed change

Based on the endpoints that are currently missing to the python-zaqarclient v1.1,the proposed change is to add support for the following features:

Pools:

pool_update
pool_list

flavors:

flavor_update
flavor_list

Notifications

Alternatives

Implementation

Assignee(s)

Primary assignee:: dynarro

Milestones

Target Milestone for completion:: Liberty-2

Work Items

Add support to:

pools
flavors
notifications

Add unit testing for:

pools
flavors
notifications

Add developers documentation for:

pools
flavors
notifications

Dependencies

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

zaqar-specs

Sun, 17 Aug 2014 00:00:00

Queuing Service (Zaqar) Specifications

Free software: Apache license
Documentation: http://specs.openstack.org/openstack/zaqar-specs

Features

TODO