zaqar-specs/specs/stein/introduce-topic-resource-for-notification.rst

Introduce Topic Resource For Notification

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.

1. Could set the users or projects who can send topic message to this Topic
2. Could set the users or projects who can subscribe this Topic.
3. 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

1. 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.

2. 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)

3. 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)

4. 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)

5. 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