From f87b228a8e7b2de03cd4b05b4c5ed99896657b43 Mon Sep 17 00:00:00 2001 From: Yuvaraju Meenuga Date: Tue, 4 Dec 2018 20:54:07 +0530 Subject: [PATCH] Docstring for Pecan SSL certificate controller Adding docstring for poppy/poppy/transport/pecan/controllers/v1/ssl_certificates.py --- .../pecan/controllers/v1/ssl_certificates.py | 106 +++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) diff --git a/poppy/transport/pecan/controllers/v1/ssl_certificates.py b/poppy/transport/pecan/controllers/v1/ssl_certificates.py index d45d05d0..d77deace 100644 --- a/poppy/transport/pecan/controllers/v1/ssl_certificates.py +++ b/poppy/transport/pecan/controllers/v1/ssl_certificates.py @@ -4,7 +4,7 @@ # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # -# http://www.apache.org/licenses/LICENSE-2.0 +# http:..www.apache.org.licenses.LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, @@ -13,6 +13,52 @@ # See the License for the specific language governing permissions and # limitations under the License. +"""Pecan router to map SSL certificate related URLs. + +The :class:`SSLCertificateController` does below +operations. + + - Create certificate dictionary in Cassandra + - Create a new CPS certificate + - Delete an existing certificate + - Fetch details for a given domain + + +Pecan Mappings:- + + Each HTTP method is mapped to Pecan's method as shown below. + + Pecan Method HttpMethod and URL + ------------- ------------------------- + get_one -> GET {{host}}/v1.0/ssl_certificate// + post -> POST /ssl_certificate/ + delete -> DELETE /ssl_certificate// + + Example:- + + - The URL ``{{host}}/v1.0/ssl_certificate/ with HTTP POST`` will be received by + :py:func:`SSLCertificateController.post()`` + - The URL ``{{host}}/v1.0/ssl_certificate/abc.domain.com with HTTP POST`` will be received by + :py:func:`SSLCertificateController.get_one()`` + +The :class:`SSLCertificateController` have Enabled Context Hook and Errors Hook. +`Context Hook` checks that `X-Project-ID` and `X-Auth-Token` +are present in the request payload and constructs `base_url`. +`Errors Hook` handles any errors during the request. + +``validate`` decorators are injected into each method of the class +to validate the payload and other dependencies. If any of the +validation fails, operation will be aborted and ``Errors Hook`` +will be responsible for sending error response to the user. + +After doing the base level validations on the request +payload, calls will be delegated to Manager layer to +process the request. The Default Manager layer has +various controllers to handle these requests. + +For more details on how the top level URL mapping is done, refer to +:py:mod:`poppy.poppy.transport.pecan.driver.py` +""" import json import pecan @@ -32,6 +78,7 @@ class SSLCertificateController(base.Controller, hooks.HookController): + """Create,Delete,GET SSL certificates for domains""" __hooks__ = [poppy_hooks.Context(), poppy_hooks.Error()] @@ -45,6 +92,40 @@ class SSLCertificateController(base.Controller, hooks.HookController): helpers.abort_with_message, stoplight_helpers.pecan_getter)) def post(self): + """Create an SSL certificate for HTTPS domains. + + After the base level validations, this request will + reach to Default manager. + + Default Manager will .. + + - Call Storage layer(Cassandra) to store the certificate details + - Invokes ``create_ssl_certificate`` `Taskflow` to create provider + certificates + + The ``create_ssl_certificate`` will .. + - ``Enqueue`` flag(which is by default `True`) determines + whether or not to create the certificate right now + - If ``Enqueue`` is `True`, it simply adds this request + to `mod_san_queue` and returns + - Else, + + - It will look for an available provider certificate + - If there is any available certificate, makes CPS call + to the provider requesting to add this domain to + that certificate + - Else, again this request will be added to + `mod_san_queue`. + + All the requests enqueued in `mod_san_queue` will be processed + by admin job `rerun_retry_list`. + + :return: Pecan's 200 response If the request to add + this domain to a certificate is successful or enqueued + into `mod_san_queue`. 400 response will be returned + if there was any error while doing so. + :rtype: pecan.Response + """ ssl_certificate_controller = ( self._driver.manager.ssl_certificate_controller) @@ -72,6 +153,22 @@ def post(self): helpers.abort_with_message) ) def delete(self, domain_name): + """Delete domain from a service. + + Deleting domain involves ... + - Deleting the certificate dictionary from cassandra + - Deleting associated provider certificates + - Deleting the respective DNS mappings + + All the three tasks are executed by the + ``delete_ssl_certificate`` taskflow which is + invoked from Default manager layer. + + :param unicode domain_name: The name of the domain + :return: Pecan's 200 response if successfully invoked + the delete_ssl_certificate taskflow. Else, 400 response + will be returned. + """ # For now we only support 'san' cert type cert_type = pecan.request.GET.get('cert_type', 'san') @@ -94,6 +191,13 @@ def delete(self, domain_name): helpers.abort_with_message) ) def get_one(self, domain_name): + """Get domain details for a given domain name. + + :param unicode domain_name: The Name of the domain + :return: Serialized SSLCertificate object in the + form of collections.OrderedDict + :rtype: collections.OrderedDict + """ certificate_controller = \ self._driver.manager.ssl_certificate_controller