Merge pull request #111 from eadwinCode/auth_doc

Linting, MyPy Upgrade and Example fixes

Author: eadwinCode

.github/workflows/test_full.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install Dependencies
         run: flit install --symlink
       - name: Test
-        run: pytest tests
+        run: pytest
 
   codestyle:
     runs-on: ubuntu-latest
@@ -38,10 +38,8 @@ jobs:
       - name: Install Dependencies
         run: flit install --symlink
       - name: Black
-        run: black --check ellar tests
-      - name: isort
-        run: isort --check ellar tests
-      - name: Flake8
-        run: flake8 ellar tests
+        run: black --check ellar tests examples
+      - name: Ruff Linting Check
+        run: ruff check ellar tests examples
       - name: mypy
         run: mypy ellar

.gitignore

@@ -126,4 +126,4 @@ dist
 test.py
 
 docs/site
-site/
+site/

Makefile

@@ -18,21 +18,19 @@ install-full: ## Install dependencies
 	pre-commit install -f
 
 lint: ## Run code linters
-	black --check ellar tests
-	isort --check ellar tests
-	autoflake --remove-unused-variables --remove-unused-variables -r ellar tests
-	flake8 ellar tests
+	black --check ellar tests examples
+	ruff check ellar tests examples
 	mypy ellar
 
 fmt format: ## Run code formatters
-	black ellar tests
-	isort ellar tests
+	black ellar tests examples
+	ruff check --fix ellar tests examples
 
 test: ## Run tests
-	pytest tests
+	pytest
 
 test-cov: ## Run tests with coverage
-	pytest --cov=ellar --cov-report term-missing tests
+	pytest --cov=ellar --cov-report term-missing
 
 doc-deploy: ## Run Deploy Documentation
 	make clean

docs/overview/middleware.md

@@ -39,27 +39,7 @@ Actions that can be performed by middleware functions:
 - End the request-response cycle if need be
 - Each middleware class or function must call `app` or `call_next` respectively else the request will be left without response
 
-## **Dependency Injection**
-This is still feature is still in progress
-
-```python
-import typing as t
-from starlette.types import ASGIApp
-from ellar.di import injectable
-
-
-@injectable
-class MyCustomService:
-    pass
-
 
-class EllarASGIMiddlewareStructure:
-    def __init__(self, app: ASGIApp, service: MyCustomService, **other_options: t.Any):
-        self.app = app
-        self.options = other_options
-        self.custom_service = service
-
-```
 ## **Application Middleware**
 Ellar applies some ASGI middleware necessary for resource protection, error handling, and context management.
 They include:
@@ -69,9 +49,11 @@ They include:
 - **`RequestServiceProviderMiddleware`**: - This inherits from `ServerErrorMiddleware`. It provides DI context during request and 
 also ensures that application exceptions may return a custom 500 page, or display an application traceback in DEBUG mode.
 - **`RequestVersioningMiddleware`**: This computes resource versioning info from request object based on configured resource versioning scheme at the application level.
-- **`ExceptionMiddleware`**: - Adds exception handlers, so that particular types of expected exception cases can be associated with handler functions. For example raising `HTTPException(status_code=404)` within an endpoint will end up rendering a custom 404 page.
+- **`ExceptionMiddleware`**: - Adds exception handlers, so that some common exception raised with the application can be associated with handler functions. For example raising `HTTPException(status_code=404)` within an endpoint will end up rendering a custom 404 page.
+- **`SessionMiddleware`**: controls session state using the session strategy configured in the application.   
+- **`IdentityMiddleware`**: controls all registered authentication schemes and provides user identity to all request
 
-## Applying Middleware
+## **Applying Middleware**
 Middleware can be applied through the application `config` - `MIDDLEWARES` variable. 
 
 Let's apply some middleware in our previous project. At the project root level, open `config.py`.
@@ -95,6 +77,36 @@ class DevelopmentConfig(BaseConfig):
 !!! Hint
     This is how to apply any `ASGI` middlewares such as `GZipMiddleware`, `EllarASGIMiddlewareStructure`, and others available in the `Starlette` library.
 
+## **Dependency Injection**
+In section above, we saw how middleware are registered to the application. But what if the middleware class depends on other services, how then should we configure it? 
+The `Middleware` does all the work.
+
+For example, lets modify the `GZipMiddleware` class and make it depend on `Config` service.
+```python
+from ellar.core import Config
+from ellar.core.middleware import GZipMiddleware, Middleware
+from ellar.common.types import ASGIApp
+
+
+class CustomGZipMiddleware(GZipMiddleware):
+    def __init__(self, app: ASGIApp, config: Config, minimum_size: int = 500, compresslevel: int = 9):
+        super().__init__(app, minimum_size, compresslevel)
+        self._config = config
+
+## And in Config.py
+...
+
+class DevelopmentConfig(BaseConfig):
+    DEBUG: bool = True
+    # Application middlewares
+    MIDDLEWARE: list[Middleware] = [
+        Middleware(CustomGZipMiddleware, minimum_size=1000)
+    ]
+```
+
+In the example above, `Middleware` that wraps `CustomGZipMiddleware` with ensure dependent classes in `CustomGZipMiddleware` are resolved when
+instantiating `CustomGZipMiddleware` object. As you see, the `config` value was not provided but will be injected during runtime.
+
 ## **Starlette Middlewares**
 Let's explore other Starlette middlewares and other third party `ASGI` Middlewares
 

docs/security/csrf.md

@@ -1 +1,31 @@
-# Coming Soon
+# **CSRF or XSRF**
+CSRF or XSRF is a security vulnerability and attack method in web applications. It involves tricking a user's browser 
+into sending unauthorized requests to a website where the user is authenticated, allowing attackers to perform actions on behalf of the user.
+
+## **Available ASGI CSRF Middlewares**
+
+- [Piccolo CSRF Middleware](https://piccolo-api.readthedocs.io/en/latest/csrf/usage.html)
+- [Starlette CSRF](https://pypi.org/project/starlette-csrf/)
+
+These middlewares can be configured as every other asgi middleware as shown in middleware [docs](../../overview/middleware/#applying-middleware) to work in Ellar
+
+For example, using [Starlette CSRF](https://pypi.org/project/starlette-csrf/) Middleware
+```python
+# config.py
+import typing as t
+from ellar.core.middleware import Middleware
+from starlette_csrf import CSRFMiddleware
+
+class Development(BaseConfig):
+    DEBUG: bool = True
+    # Application middlewares
+    MIDDLEWARE: t.Sequence[Middleware] = [
+        Middleware(
+            CSRFMiddleware, 
+            secret="__CHANGE_ME__", 
+            cookie_name='csrftoken', 
+            safe_methods={"GET", "HEAD", "OPTIONS", "TRACE"}
+        )
+    ]
+
+```

ellar/auth/guard.py

@@ -1,10 +1,9 @@
 import typing as t
 from functools import partial
 
-from starlette import status
-
 from ellar.common import APIException, GuardCanActivate, IExecutionContext
 from ellar.di import injectable
+from starlette import status
 
 from .constants import POLICY_KEYS
 from .policy import BasePolicyHandler, PolicyType

ellar/auth/handlers/schemes/base.py

@@ -1,15 +1,14 @@
 import typing as t
 from abc import ABC, abstractmethod
 
-from starlette.exceptions import HTTPException
-from starlette.status import HTTP_401_UNAUTHORIZED
-
 from ellar.common.exceptions import APIException
 from ellar.common.interfaces import IHostContext
 from ellar.common.serializer.guard import (
     HTTPAuthorizationCredentials,
     HTTPBasicCredentials,
 )
+from starlette.exceptions import HTTPException
+from starlette.status import HTTP_401_UNAUTHORIZED
 
 if t.TYPE_CHECKING:  # pragma: no cover
     from ellar.core.connection import HTTPConnection

ellar/auth/handlers/schemes/http.py

@@ -91,7 +91,7 @@ def _get_credentials(self, connection: "HTTPConnection") -> HTTPBasicCredentials
 
         if not separator:
             self._not_unauthorized_exception("Invalid authentication credentials")
-        return HTTPBasicCredentials(username=username, password=password)
+        return HTTPBasicCredentials(username=username, password=password)  # type: ignore[arg-type]
 
 
 class HttpDigestAuth(HttpBearerAuth, ABC):

ellar/auth/services/auth_schemes.py

@@ -20,10 +20,10 @@ def add_authentication(
     def find_authentication_scheme(self, scheme: str) -> AuthenticationHandlerType:
         try:
             return self._authentication_schemes[scheme]
-        except KeyError:
+        except KeyError as ex:
             raise RuntimeError(
                 f'No Authentication Scheme found with the name:"{scheme}"'
-            )
+            ) from ex
 
     def get_authentication_schemes(
         self,

ellar/auth/session/strategy.py

@@ -1,19 +1,17 @@
 try:
     import itsdangerous
-except Exception:  # pragma: no cover
+except Exception as ex:  # pragma: no cover
     raise RuntimeError(
         "SessionClientStrategy requires itsdangerous package installed. Run `pip install itsdangerous`"
-    )
+    ) from ex
 
 import json
 import typing as t
 from base64 import b64decode, b64encode
 
-import itsdangerous
-from itsdangerous import BadSignature
-
 from ellar.core import Config
 from ellar.di import injectable
+from itsdangerous import BadSignature
 
 from .cookie_dict import SessionCookieObject
 from .interface import ISessionStrategy
@@ -26,12 +24,12 @@ def __init__(self, config: Config) -> None:
         self._signer = itsdangerous.TimestampSigner(str(config.SECRET_KEY))
         self.config = config
         self._session_config = SessionCookieOption(
-            NAME=config.SESSION_COOKIE_NAME,
+            NAME=config.SESSION_COOKIE_NAME or "",
             DOMAIN=config.SESSION_COOKIE_DOMAIN,
             PATH=config.SESSION_COOKIE_PATH or "/",
-            HTTPONLY=config.SESSION_COOKIE_HTTPONLY,
-            SECURE=config.SESSION_COOKIE_SECURE,
-            SAME_SITE=config.SESSION_COOKIE_SAME_SITE,
+            HTTPONLY=config.SESSION_COOKIE_HTTPONLY or False,
+            SECURE=config.SESSION_COOKIE_SECURE or False,
+            SAME_SITE=config.SESSION_COOKIE_SAME_SITE or "none",
             MAX_AGE=config.SESSION_COOKIE_MAX_AGE,
         )