diff --git a/specs/newton/subscription-confirmation-support.rst b/specs/newton/subscription-confirmation-support.rst new file mode 100644 index 0000000..39245ac --- /dev/null +++ b/specs/newton/subscription-confirmation-support.rst @@ -0,0 +1,223 @@ +.. + This template should be in ReSTructured text. The filename in the git + repository should match the launchpad URL, for example a URL of + https://blueprints.launchpad.net/zaqar/+spec/awesome-thing should be named + awesome-thing.rst. + + Please do not delete any of the sections in this + template. If you have nothing to say for a whole section, just write: None + + For help with syntax, see http://sphinx-doc.org/rest.html + To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html + +=================================== + Subscription confirmation support +=================================== + +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. + +Comparison AWS SNS API and Zaqar API +------------------------------------ +For developer to better understand this feature, this spec compares SNS API +and Zaqar API what difference between them. + +Subscription Confirmation Request +SNS is using GET request like this:: + + GET https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn={Topic}&Token={Token} + +Zaqar is using PUT request like this:: + + PUT https://zaqar_server/v2/queues/{queue_name}/subscriptions/{subscriptions_id}/confirm + +Request Body:: + + { + 'confirmed': True + } + + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + wangxiyuan + +Secondary assignee: + wanghao + +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 +============ + +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 +========== + +_`Amazon SNS`: http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html