Allow to customize the web-framework

The customizer allows for web-framework specific customiztion.
For example, it can be used to add authentication to pyctuator running with FastAPI.

See #67

Author: michael.yak

README.md

@@ -331,6 +331,10 @@ Pyctuator(
 )
 ``` 
 
+### Protecting Pyctuator with authentication
+Since there are numerous standard approaches to protect an API, Pyctuator doesn't explicitly support any of them. Instead, Pyctuator allows to customize its integration with the web-framework.
+See the example in [fastapi_with_authentication_example_app.py](examples/FastAPI/fastapi_with_authentication_example_app.py).
+
 ## Full blown examples
 The `examples` folder contains full blown Python projects that are built using [Poetry](https://python-poetry.org/).
 

examples/FastAPI/README.md

@@ -13,4 +13,8 @@ This example demonstrates the integration with the [FastAPI](https://fastapi.tia
     poetry run python -m fastapi_example_app
     ``` 
 
-![FastAPI Example](../images/FastAPI.png)
+![FastAPI Example](../images/FastAPI.png)
+
+## Running an example where pyctuator requires authentication
+In order to protect the Pyctuator endpoint, a customizer is used to make the required configuration changes to the API router. 
+In addition, the credentials need to be included in the registration request sent to SBA in order for it it could authenticate when querying the pyctuator API.

examples/FastAPI/fastapi_with_authentication_example_app.py

@@ -0,0 +1,87 @@
+import datetime
+import logging
+import random
+import secrets
+
+from fastapi import FastAPI, Depends, APIRouter, HTTPException
+from fastapi.security import HTTPBasicCredentials, HTTPBasic
+from starlette import status
+from uvicorn import Server
+from uvicorn.config import Config
+
+from pyctuator.pyctuator import Pyctuator
+
+my_logger = logging.getLogger("example")
+
+
+class SimplisticBasicAuth:
+    def __init__(self, username: str, password: str):
+        """
+        Initializes a simplistic basic-auth FastAPI dependency with hardcoded username and password -
+        don't do this at home!
+        """
+        self.username = username
+        self.password = password
+
+    def __call__(self, credentials: HTTPBasicCredentials = Depends(HTTPBasic(realm="pyctuator"))):
+        correct_username = secrets.compare_digest(credentials.username, self.username)
+        correct_password = secrets.compare_digest(credentials.password, self.password) if self.password else True
+
+        if not (correct_username and correct_password):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Incorrect username or password",
+                headers={"WWW-Authenticate": "Basic"},
+            )
+
+
+username = "u1"
+password = "p2"
+security = SimplisticBasicAuth(username, password)
+
+
+app = FastAPI(
+    title="FastAPI Example Server",
+    description="Demonstrate Spring Boot Admin Integration with FastAPI",
+    docs_url="/api",
+)
+
+
+def add_authentication_to_pyctuator(router: APIRouter) -> None:
+    router.dependencies = [Depends(security)]
+
+
+@app.get("/")
+def read_root(credentials: HTTPBasicCredentials = Depends(security)):
+    my_logger.debug(f"{datetime.datetime.now()} - {str(random.randint(0, 100))}")
+    return {"username": credentials.username, "password": credentials.password}
+
+
+example_app_address = "172.18.0.1"
+example_sba_address = "localhost"
+
+pyctuator = Pyctuator(
+    app,
+    "Example FastAPI",
+    app_url=f"http://{example_app_address}:8000",
+    pyctuator_endpoint_url=f"http://{example_app_address}:8000/pyctuator",
+    registration_url=f"http://{example_sba_address}:8080/instances",
+    app_description=app.description,
+    customizer=add_authentication_to_pyctuator,  # Customize Pyctuator's API router to require authentication
+    metadata={
+        "user.name": username,  # Include the credentials in the registration request sent to SBA
+        "user.password": password,
+    }
+)
+
+# Keep the console clear - configure uvicorn (FastAPI's WSGI web app) not to log the detail of every incoming request
+uvicorn_logger = logging.getLogger("uvicorn")
+uvicorn_logger.setLevel(logging.WARNING)
+
+server = Server(config=(Config(
+    app=app,
+    loop="asyncio",
+    host="0.0.0.0",
+    logger=uvicorn_logger,
+)))
+server.run()

examples/FastAPI/pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 [tool.poetry.dependencies]
 python = "^3.7"
 psutil = { version = "^5.6" }
-fastapi = { version = "^0.41.0" }
+fastapi = { version = "^0.68.0" }
 uvicorn = { version = "^0.9.0" }
 pyctuator = { version = "^0.16.0" }
 

pyctuator/impl/fastapi_pyctuator.py

@@ -35,9 +35,12 @@ def __init__(
             app: FastAPI,
             pyctuator_impl: PyctuatorImpl,
             include_in_openapi_schema: bool = False,
+            customizer: Callable[[APIRouter], None] = None
     ) -> None:
         super().__init__(app, pyctuator_impl)
         router = APIRouter()
+        if customizer:
+            customizer(router)
 
         @router.get("/", include_in_schema=include_in_openapi_schema, tags=["pyctuator"])
         def get_endpoints() -> EndpointsData:

pyctuator/pyctuator.py

@@ -42,6 +42,7 @@ def __init__(
             metadata: Optional[dict] = None,
             additional_app_info: Optional[dict] = None,
             ssl_context: Optional[ssl.SSLContext] = None,
+            customizer: Optional[Callable] = None
     ) -> None:
         """The entry point for integrating pyctuator with a web-frameworks such as FastAPI and Flask.
 
@@ -79,6 +80,9 @@ def __init__(
         :param metadata: optional metadata key-value pairs that are displayed in SBA main page of an instance
         :param additional_app_info: additional arbitrary information to add to the application's "Info" section
         :param ssl_context: optional SSL context to be used when registering with SBA
+        :param customizer: a function that can customize the integration with the web-framework which is therefore web-
+         framework specific. For FastAPI, the function receives pyctuator's APIRouter allowing to add "dependencies" and
+         anything else that's provided by the router. See fastapi_with_authentication_example_app.py
         """
 
         self.auto_deregister = auto_deregister
@@ -113,7 +117,7 @@ def __init__(
         root_logger.addHandler(self.pyctuator_impl.logfile.log_messages)
 
         # Find and initialize an integration layer between the web-framework adn pyctuator
-        framework_integrations = {
+        framework_integrations: Dict[str, Callable[[Any, PyctuatorImpl, Optional[Callable]], bool]] = {
             "flask": self._integrate_flask,
             "fastapi": self._integrate_fastapi,
             "aiohttp": self._integrate_aiohttp,
@@ -122,7 +126,7 @@ def __init__(
         for framework_name, framework_integration_function in framework_integrations.items():
             if self._is_framework_installed(framework_name):
                 logging.debug("Framework %s is installed, trying to integrate with it", framework_name)
-                success = framework_integration_function(app, self.pyctuator_impl)
+                success = framework_integration_function(app, self.pyctuator_impl, customizer)
                 if success:
                     logging.debug("Integrated with framework %s", framework_name)
                     if registration_url is not None:
@@ -176,7 +180,7 @@ def set_build_info(
     def _is_framework_installed(self, framework_name: str) -> bool:
         return importlib.util.find_spec(framework_name) is not None
 
-    def _integrate_fastapi(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
+    def _integrate_fastapi(self, app: Any, pyctuator_impl: PyctuatorImpl, customizer: Optional[Callable]) -> bool:
         """
         This method should only be called if we detected that FastAPI is installed.
         It will then check whether the given app is a FastAPI app, and if so - it will add the Pyctuator
@@ -185,11 +189,12 @@ def _integrate_fastapi(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
         from fastapi import FastAPI
         if isinstance(app, FastAPI):
             from pyctuator.impl.fastapi_pyctuator import FastApiPyctuator
-            FastApiPyctuator(app, pyctuator_impl, False)
+            FastApiPyctuator(app, pyctuator_impl, False, customizer)
             return True
         return False
 
-    def _integrate_flask(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
+    # pylint: disable=unused-argument
+    def _integrate_flask(self, app: Any, pyctuator_impl: PyctuatorImpl, customizer: Optional[Callable]) -> bool:
         """
         This method should only be called if we detected that Flask is installed.
         It will then check whether the given app is a Flask app, and if so - it will add the Pyctuator
@@ -202,7 +207,8 @@ def _integrate_flask(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
             return True
         return False
 
-    def _integrate_aiohttp(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
+    # pylint: disable=unused-argument
+    def _integrate_aiohttp(self, app: Any, pyctuator_impl: PyctuatorImpl, customizer: Optional[Callable]) -> bool:
         """
         This method should only be called if we detected that aiohttp is installed.
         It will then check whether the given app is a aiohttp app, and if so - it will add the Pyctuator
@@ -215,7 +221,8 @@ def _integrate_aiohttp(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
             return True
         return False
 
-    def _integrate_tornado(self, app: Any, pyctuator_impl: PyctuatorImpl) -> bool:
+    # pylint: disable=unused-argument
+    def _integrate_tornado(self, app: Any, pyctuator_impl: PyctuatorImpl, customizer: Optional[Callable]) -> bool:
         """
         This method should only be called if we detected that tornado is installed.
         It will then check whether the given app is a tornado app, and if so - it will add the Pyctuator