Release/v1.1 (#11)

* Feature/user sessions (#10)

* Fixed file opening with context handler to ensure that files are not already closed when actually posting.

* Added SimpleTenantApp sample.

* Added User Sessions sample.

* Split CumulocityApp to SimpleCumulocityApp and MultiTenantCumulocityApp; Adding proper caching with TTL; Adding support for Token-based authentication; Adding support for user sessions; Adding samples.

* Fixed typo.

* Prepare release 1.1

Author: chsou

CHANGELOG.md

@@ -3,6 +3,47 @@
 
 ## Work in progress
 
+## Version 1.1
+
+### Notes
+
+* _Warning_, this release is a breaking change as it introduces an `auth` parameter to the API base classes,
+  `CumulocityRestAPI` and `CumulocityAPI`. This parameter should be the new standard to use (instead of just
+  username and password).
+
+* _Warning_, this release replaces the 'all-purpose' class `CumulocityApp` with specialized versions for multi-tenant
+  (`MultiTenantCumulocityApp`) and single tenant (`SimpleCumulocityApp`) environments.
+
+### Added
+
+* Added `_util.py` file to hold all cross-class auxiliary functionality.
+
+* Added `_auth.py` file to hold all cross-class authentication functionality. Moved corresponding code from file
+  `app.__init__.py` to the `AuthUtil` class.
+ 
+* Added `_jwt.py` with `JWT` class which encapsulates JWT handling for the libraries purpose. This is _not_ a full
+  JWT implementation. 
+
+* Added `HTMLBearerAuth` class which encapsulates Cumulocity's JWT token-based authentication mechanism. 
+ 
+* Added token-based authentication support. All API classes now can be initialized with an AuthBase parameter which
+  would allow all kinds of authentication mechanisms. As of now, `HTTPbasicAuth` and `HTTPBearerAuth` is supported.
+
+* Added caching with TTL/Max Size strategies to `MultiTenantCumulocityApp` and `SimpleCumulocityApp`.
+
+* Added samples: `user_sessions.py` illustrating how user sessions can be obtained and `simple_tenant_app.py` 
+  illustrating how the `SimpleCumulocityApp` class is used.
+
+* Added requirements: `cachetools` (for caching), `inputtimeout` and `flask` (for samples).
+
+### Changed
+
+* Fixed file opening in `post_file` function in `_base_api.py` to avoid files already being closed when posting.
+
+* Removed class `CumulocityApp` as it was too generic and hard to use. Replaces with classes `SimpleCumulocityApp`
+  which behaves pretty much identical and `MultiTenantCumulocityApp` which behances more like a factory.
+
+
 ## Version 1.0.2
 
 ### Changed

c8y_api/_auth.py

@@ -0,0 +1,171 @@
+# Copyright (c) 2020 Software AG,
+# Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA,
+# and/or its subsidiaries and/or its affiliates and/or their licensors.
+# Use, reproduction, transfer, publication or disclosure is prohibited except
+# as specifically provided for in your License Agreement with Software AG.
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from requests.auth import HTTPBasicAuth, AuthBase
+
+from c8y_api._jwt import JWT
+
+
+class HTTPBearerAuth(AuthBase):
+    """Token based authentication."""
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def __call__(self, r):
+        r.headers['Authorization'] = 'Bearer ' + self.token
+
+
+class AuthUtil:
+    """Authorization utility functions."""
+
+    @staticmethod
+    def parse_auth_string(auth_string: str) -> AuthBase:
+        """Parse a given auth string into a corresponding auth object.
+
+        Args:
+            auth_string (str):  Complete Auth string (including the type prefix
+                like BASIC etc.) as it comes with an Authorization HTTP header
+
+        Returns:
+            An AuthBase instance for this auth string.
+        """
+        return AuthUtil._parse_with(auth_string,
+                                    basic_fun=AuthUtil.parse_basic_auth_value,
+                                    bearer_fun=AuthUtil.parse_bearer_auth_value)
+
+    @staticmethod
+    def get_tenant_id(auth: AuthBase) -> str:
+        """Read the tenant ID from authorization information.
+
+        Args:
+            auth (AuthBase):  Auth instance, only HTTPBasicAuth and
+                HTTPBearerAuth are supported
+
+        Returns:
+            The tenant ID encoded in the auth information.
+
+        Raises:
+            ValueError if the tenant ID cannot be resolved or an unsupported
+            AuthBase instance was provided.
+        """
+        def resolve_basic(a):
+            username = a.username
+            if '/' not in username:
+                raise ValueError(f"Unable to isolate tenant ID from username: {username}")
+            return username[:username.index('/')]
+
+        def resolve_bearer(a):
+            try:
+                tenant_id = JWT(a.token).tenant_id
+            except KeyError:
+                tenant_id = None
+            if not tenant_id:
+                raise ValueError("Unable to resolve tenant ID. JWT does not appear to include it.")
+            return tenant_id
+
+        return AuthUtil._parse_auth_with(auth, resolve_basic, resolve_bearer)
+
+    @staticmethod
+    def get_username(auth: AuthBase) -> str:
+        """Read the username from authorization information.
+
+        Args:
+            auth (AuthBase):  Auth instance, only HTTPBasicAuth and
+                HTTPBearerAuth are supported
+
+        Returns:
+            The username encoded in the auth information.
+
+        Raises:
+            ValueError if the username cannot be resolved or an unsupported
+            AuthBase instance was provided.
+        """
+        def resolve_basic(a):
+            return a.username
+
+        def resolve_bearer(a):
+            return JWT(a.token).username
+
+        return AuthUtil._parse_auth_with(auth, resolve_basic, resolve_bearer)
+
+    @staticmethod
+    def parse_basic_auth_value(auth_value: str) -> HTTPBasicAuth:
+        """Parse a BASIC HTTP auth string.
+
+        Args:
+             auth_value:  The Authorization header value (Base64 encoded,
+                without the 'BASIC' type prefix)
+
+        Returns:
+            An HTTPBasicAuth object.
+        """
+        decoded = base64.b64decode(bytes(auth_value, 'utf-8'))
+        parts = [x.decode('utf-8') for x in decoded.split(b':', 1)]
+        return HTTPBasicAuth(username=parts[0], password=parts[1])
+
+    @staticmethod
+    def parse_bearer_auth_value(auth_value: str) -> HTTPBearerAuth:
+        """Parse a BEARER HTTP auth string.
+
+        Args:
+             auth_value:  The Authorization header value (Base64 encoded,
+                without the 'BEARER' type prefix)
+
+        Returns:
+            An HTTPBearerAuth object.
+        """
+        return HTTPBearerAuth(token=auth_value)
+
+    @staticmethod
+    def _parse_auth_with(auth: AuthBase, basic_fun, bearer_fun) -> Any:
+        """Parse an auth instance.
+
+        Args:
+            auth (AuthBase): Authentication information
+            basic_fun: Parsing function to be applied for BASIC auth
+            bearer_fun: Parsing function to be applied for BEARER auth
+
+        Returns:
+            Whatever is returned by the parsing functions.
+
+        Raises:
+            ValueError if the auth string is of an unsupported type.
+        """
+        if isinstance(auth, HTTPBasicAuth):
+            return basic_fun(auth)
+        if isinstance(auth, HTTPBearerAuth):
+            return bearer_fun(auth)
+        raise ValueError(f"Unable to parse authentication information! Unexpected AuthBase instance: {auth.__class__}")
+
+    @staticmethod
+    def _parse_with(auth_string: str, basic_fun, bearer_fun) -> Any:
+        """Parse an auth header string.
+
+        Args:
+            auth_string (str): Complete auth string (including type prefix).
+            basic_fun: Parsing function to be applied for BASIC auth
+            bearer_fun: Parsing function to be applied for BEARER auth
+
+        Returns:
+            Whatever is returned by the parsing functions.
+
+        Raises:
+            ValueError if the auth string is of an unsupported type.
+        """
+        auth_type, auth_value = auth_string.split(' ')
+
+        if auth_type.upper() == 'BASIC':
+            return basic_fun(auth_value)
+        if auth_type.upper() == 'BEARER':
+            return bearer_fun(auth_value)
+
+        raise ValueError(f"Unexpected authorization header type: {auth_type}")

c8y_api/_base_api.py

@@ -7,19 +7,14 @@
 from __future__ import annotations
 
 import json as json_lib
-import os
-from typing import Union, Dict, BinaryIO, Set
+from typing import Union, Dict, BinaryIO
 
-import requests
 import collections
+import requests
+from requests.auth import AuthBase, HTTPBasicAuth
 
-
-def c8y_keys() -> Set[str]:
-    """Provide the names of defined Cumulocity environment variables.
-
-    Returns: A set of environment variable names, starting with 'C8Y_'
-    """
-    return set(filter(lambda x: 'C8Y_' in x, os.environ.keys()))
+from c8y_api._auth import HTTPBearerAuth
+from c8y_api._jwt import JWT
 
 
 class CumulocityRestApi:
@@ -36,36 +31,46 @@ class CumulocityRestApi:
     ACCEPT_GLOBAL_ROLE = 'application/vnd.com.nsn.cumulocity.group+json'
     CONTENT_MEASUREMENT_COLLECTION = 'application/vnd.com.nsn.cumulocity.measurementcollection+json'
 
-    def __init__(self, base_url: str, tenant_id: str, username: str, password: str,
-                 tfa_token: str = None, application_key: str = None):
+    def __init__(self, base_url: str, tenant_id: str, username: str = None, password: str = None, tfa_token: str = None,
+                 auth: AuthBase = None, application_key: str = None):
         """Build a CumulocityRestApi instance.
 
+        One of `auth` or `username/password` must be provided. The TFA token
+        parameter is only sensible for basic authentication.
+
         Args:
             base_url (str):  Cumulocity base URL, e.g. https://cumulocity.com
             tenant_id (str):  The ID of the tenant to connect to
             username (str):  Username
             password (str):  User password
             tfa_token (str):  Currently valid two factor authorization token
+            auth (AuthBase):  Authentication details
             application_key (str):  Application ID to include in requests
                 (for billing/metering purposes).
         """
         self.base_url = base_url
         self.tenant_id = tenant_id
-        self.username = username
-        self.password = password
-        self.tfa_token = tfa_token
         self.application_key = application_key
-        self.__auth = f'{tenant_id}/{username}', password
+
+        if auth:
+            self.auth = auth
+            self.username = self._resolve_username_from_auth(auth)
+        elif username and password:
+            self.auth = HTTPBasicAuth(f'{tenant_id}/{username}', password)
+            self.username = username
+        else:
+            raise ValueError("One of 'auth' or 'username/password' must be defined.")
+
         self.__default_headers = {}
-        if self.tfa_token:
-            self.__default_headers['tfatoken'] = self.tfa_token
+        if tfa_token:
+            self.__default_headers['tfatoken'] = tfa_token
         if self.application_key:
             self.__default_headers[self.HEADER_APPLICATION_KEY] = self.application_key
         self.session = self._create_session()
 
     def _create_session(self) -> requests.Session:
         s = requests.Session()
-        s.auth = self.__auth
+        s.auth = self.auth
         s.headers = {'Accept': 'application/json'}
         if self.application_key:
             s.headers.update({self.HEADER_APPLICATION_KEY: self.application_key})
@@ -88,7 +93,7 @@ def prepare_request(self, method: str, resource: str,
         hs = self.__default_headers
         if additional_headers:
             hs.update(additional_headers)
-        rq = requests.Request(method=method, url=self.base_url + resource, headers=hs, auth=self.__auth)
+        rq = requests.Request(method=method, url=self.base_url + resource, headers=hs, auth=self.auth)
         if json:
             rq.json = json
         return rq.prepare()
@@ -211,18 +216,20 @@ def post_file(self, resource: str, file: str | BinaryIO, object: dict,
                 (only 201 is accepted).
         """
 
-        def ensure_open_file(f):
-            if isinstance(f, str):
-                with open(f, 'rb') as fp:
-                    return fp
-            return f
+        def perform_post(open_file):
+            files = {
+                'object': (None, json_lib.dumps(object)),
+                'file': (None, open_file, content_type or 'application/octet-stream')
+            }
+            additional_headers = self._prepare_headers(accept=accept)
+            return self.session.post(self.base_url + resource, files=files, headers=additional_headers)
+
+        if isinstance(file, str):
+            with open(file, 'rb') as f:
+                r = perform_post(f)
+        else:
+            r = perform_post(file)
 
-        files = {
-            'object': (None, json_lib.dumps(object)),
-            'file': (None, ensure_open_file(file), content_type or 'application/octet-stream')
-        }
-        additional_headers = self._prepare_headers(accept=accept)
-        r = self.session.post(self.base_url + resource, files=files, headers=additional_headers)
         if 500 <= r.status_code <= 599:
             raise SyntaxError(f"Invalid POST request. Status: {r.status_code} Response:\n" + r.text)
         if r.status_code != 201:
@@ -342,6 +349,20 @@ def delete(self, resource: str, json: dict = None, params: dict = None):
         if r.status_code not in (200, 204):
             raise ValueError(f"Unable to perform DELETE request. Status: {r.status_code} Response:\n" + r.text)
 
+    @classmethod
+    def _resolve_username_from_auth(cls, auth: AuthBase):
+        """Resolve the username from the authentication information.
+
+        For Basic authentication the username will be simply read from the
+        provided data, for Bearer authentication the token will be parsed
+        and the username resolved from the payload.
+        """
+        if isinstance(auth, HTTPBasicAuth):
+            return auth.username
+        if isinstance(auth, HTTPBearerAuth):
+            return JWT(auth.token).username
+        raise ValueError(f"Unexpected AuthBase instance: {auth.__class__}. Unable to resolve username.")
+
     @classmethod
     def _prepare_headers(cls, **kwargs) -> Union[dict, None]:
         """Format a set of named arguments into a header dictionary.