DECKHAND-2: Design core Deckhand API framework

This commit implements the core Deckhand API framework.
It does not implement any real API routes. The core
framework is modeled after Drydock's [0].

This commit specifically:

  - implements the core API framework which uses falcon
  - implements errors.py for preliminary errors
  - implements base resource class from which other API
    resources will inherit to build out the API itself
  - implements base API router
  - implements entry-point for kicking off deckhand
  - updates base README.rst with instructions on
  - running and installing -- similar to Drydock's
  - implements dummy API resource for secrets, to
    be fleshed out further in a follow-up commit

[0] https://github.com/att-comdev/drydock

AUTHORS

@@ -1,2 +1,3 @@
 Alan Meadows <alan.meadows@gmail.com>
 Felipe Monteiro <felipe.monteiro@att.com>
+Felipe Monteiro <fmontei@users.noreply.github.com>

ChangeLog

@@ -1,6 +1,8 @@
 CHANGES
 =======
 
-* DECKHAND-11: Add oslo.config integration to Deckhand
+* pep8
+* Cookie-butter falcon logic
+* Oslo config integration (#1)
 * Add ChangeLog
 * Initial commit

README.rst

@@ -2,3 +2,12 @@ Deckhand
 ========
 A foundational python REST YAML processing engine providing data and secrets
 management to other platform services.
+
+To run::
+
+	$ sudo pip install uwsgi
+	$ virtualenv -p python3 /var/tmp/deckhand
+	$ . /var/tmp/deckhand/bin/activate
+	$ sudo pip install .
+	$ python setup.py install
+	$ uwsgi --http :9000 -w deckhand.deckhand --callable deckhand --enable-threads -L

deckhand/control/api.py

@@ -0,0 +1,37 @@
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+import falcon
+
+from deckhand.control import base as api_base
+from deckhand.control import secrets
+
+
+def start_api(state_manager=None):
+    """Start the Deckhand API service.
+
+    Create routes for the v1.0 API.
+    """
+    control_api = falcon.API(request_type=api_base.DeckhandRequest)
+
+    v1_0_routes = [
+        ('/secrets', secrets.SecretsResource())
+    ]
+
+    for path, res in v1_0_routes:
+        control_api.add_route(os.path.join('/api/v1.0', path), res)
+
+    return control_api

deckhand/control/base.py

@@ -0,0 +1,102 @@
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import uuid
+
+import falcon
+from falcon import request
+
+from deckhand import errors
+
+
+class BaseResource(object):
+    """Base resource class for implementing API resources."""
+
+    def __init__(self):
+        self.authorized_roles = []
+
+    def on_options(self, req, resp):
+        self_attrs = dir(self)
+        methods = ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'PATCH']
+        allowed_methods = []
+
+        for m in methods:
+            if 'on_' + m.lower() in self_attrs:
+                allowed_methods.append(m)
+
+        resp.headers['Allow'] = ','.join(allowed_methods)
+        resp.status = falcon.HTTP_200
+
+    # For authorizing access at the Resource level. A Resource requiring
+    # finer-grained authorization at the method or instance level must
+    # implement that in the request handlers
+    def authorize_roles(self, role_list):
+        authorized = set(self.authorized_roles)
+        applied = set(role_list)
+
+        if authorized.isdisjoint(applied):
+            return False
+        else:
+            return True
+
+    def req_json(self, req):
+        if req.content_length is None or req.content_length == 0:
+            return None
+
+        if req.content_type is not None and req.content_type.lower() \
+            == 'application/json':
+            raw_body = req.stream.read(req.content_length or 0)
+
+            if raw_body is None:
+                return None
+
+            try:
+                json_body = json.loads(raw_body.decode('utf-8'))
+                return json_body
+            except json.JSONDecodeError as jex:
+                raise errors.InvalidFormat("%s: Invalid JSON in body: %s" % (
+                    req.path, jex))
+        else:
+            raise errors.InvalidFormat("Requires application/json payload")
+
+    def return_error(self, resp, status_code, message="", retry=False):
+        resp.body = json.dumps(
+            {'type': 'error', 'message': message, 'retry': retry})
+        resp.status = status_code
+
+
+class DeckhandRequestContext(object):
+
+    def __init__(self):
+        self.user = None
+        self.roles = ['anyone']
+        self.request_id = str(uuid.uuid4())
+
+    def set_user(self, user):
+        self.user = user
+
+    def add_role(self, role):
+        self.roles.append(role)
+
+    def add_roles(self, roles):
+        self.roles.extend(roles)
+
+    def remove_role(self, role):
+        if role in self.roles:
+            self.roles.remove(role)
+
+
+class DeckhandRequest(request.Request):
+    context_type = DeckhandRequestContext

deckhand/control/secrets.py

@@ -0,0 +1,36 @@
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import falcon
+
+from oslo_serialization import jsonutils as json
+
+from deckhand.control import base as api_base
+
+
+class SecretsResource(api_base.BaseResource):
+    """API resource for interacting with Barbican.
+
+    TODO(felipemonteiro): Once Barbican integration is fully implemented,
+    implement API endpoints below.
+    """
+
+    def __init__(self, **kwargs):
+        super(SecretsResource, self).__init__(**kwargs)
+        self.authorized_roles = ['user']
+
+    def on_get(self, req, resp):
+        # TODO(felipemonteiro): Implement this API endpoint.
+        resp.body = json.dumps({'secrets': 'test_secrets'})
+        resp.status = falcon.HTTP_200

deckhand/deckhand.py

@@ -0,0 +1,23 @@
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from deckhand.control import api
+
+
+def start_deckhand():
+    return api.start_api()
+
+
+# Callable to be used by uwsgi.
+deckhand = start_deckhand()

deckhand/errors.py

@@ -0,0 +1,21 @@
+# Copyright 2017 AT&T Intellectual Property.  All other rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# 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
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+class ApiError(Exception):
+    pass
+
+
+class InvalidFormat(ApiError):
+    pass

requirements.txt

@@ -1,5 +1,6 @@
-# API
 falcon==1.1.0
-
-# Oslo
 oslo.config>=3.22.0 # Apache-2.0
+oslo.config>=3.22.0  # Apache-2.0
+oslo.serialization>=1.10.0  # Apache-2.0
+python-barbicanclient>=4.0.0  # Apache-2.0
+keystoneauth1>=2.21.0  # Apache-2.0

test-requirements.txt

@@ -0,0 +1 @@
+falcon==1.1.0

tox.ini

@@ -18,7 +18,7 @@ commands = oslo-config-generator --config-file=etc/deckhand/config-generator.con
 commands = flake8 {posargs}
 
 [flake8]
-# D100, D103, D104 deal with docstrings in public functions
+# D100-104 deal with docstrings in public functions
 # D205, D400, D401 deal with docstring formatting
-ignore=E121,E122,E123,E124,E125,E126,E127,E128,E129,E131,E251,H405,D100,D103,D104,D205,D400,D401
+ignore=E121,E122,E123,E124,E125,E126,E127,E128,E129,E131,E251,H405,D100,D101,D102,D103,D104,D205,D400,D401,I100
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,tools/xenserver*,releasenotes