Merge pull request #131 from python-ellar/exception_doc_update

Exception Docs Update

Author: eadwinCode

docs/overview/exception_handling.md

@@ -1,52 +1,56 @@
 # **Exceptions & Exception Handling**
-The `ExceptionMiddleware` and `ExceptionMiddlewareService` handle all unhandled exceptions throughout an application and provide user-friendly responses.
+Ellar comes with a built-in exceptions middleware, `ExceptionMiddleware`, which is responsible for processing all exceptions across 
+an application. When an exception is not handled by your application code, it is caught by this middleware, which 
+then automatically sends an appropriate user-friendly response .
 
 ```json
 {
   "status_code": 403,
   "detail": "Forbidden"
 }
 ```
+And based on application config `DEBUG` value, the exception is raised during is `config.DEBUG`
+is True but when `config.DEBUG` a 500 error is returned as shown below:
+```json
+{
+  "statusCode": 500,
+  "message": "Internal server error"
+}
+```
 
-Types of exceptions managed by default:
+Types of exceptions types managed by default:
 
-- **`HTTPException`**: Provided by `Starlette` to handle HTTP errors
-- **`WebSocketException`**: Provided by `Starlette` to manage websocket errors
+- **`HTTPException`**: Provided by `Starlette` to handle HTTP errors.eg. `HTTPException(status_code, detail=None, headers=None)`
+- **`WebSocketException`**: Provided by `Starlette` to manage websocket errors. eg `WebSocketException(code=1008, reason=None)`
 - **`RequestValidationException`**: Provided by `Pydantic` for validation of request data
-- **`APIException`**: Handles HTTP errors and provides more context about the error.
-
-## **HTTPException**
-
-The `HTTPException` class provides a base class that you can use for any
-handled exceptions.
-
-* `HTTPException(status_code, detail=None, headers=None)`
-
-## **WebSocketException**
-
-You can use the `WebSocketException` class to raise errors inside WebSocket endpoints.
-
-* `WebSocketException(code=1008, reason=None)`
+- **`APIException`**: It is a type of exception for REST API based applications. It gives more concept to error and provides a simple interface for creating other custom exception needs in your application without having to create an extra exception handler.
 
-You can set any code valid as defined [in the specification](https://tools.ietf.org/html/rfc6455#section-7.4.1){target="_blank"}.
-
-## **APIException**
-It is a type of exception for REST API based applications. It gives more concept to error and provides a simple interface for creating other custom exception needs in your application without having to create an extra exception handler.
-
-For example,
-
-```python
-from ellar.common.exceptions import APIException
-from starlette import status
-
-class ServiceUnavailableException(APIException):
-    status_code = status.HTTP_503_SERVICE_UNAVAILABLE
-    code = 'service_unavailable'
-
-```
-!!!hint
-    You should only raise `HTTPException` and `APIException` inside routing or endpoints. Middleware classes should instead just return appropriate responses directly.
+    For example,
 
+    ```python
+    from ellar.common import APIException
+    from starlette import status
+    
+    class ServiceUnavailableException(APIException):
+        status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        code = 'service_unavailable'
+    
+    ```
+
+### **Built-in APIExceptions**
+Ellar provides a set of standard exceptions that inherit from the base `APIException`. 
+These are exposed from the `ellar.common` package, and represent many of the most common HTTP exceptions:
+
+- `AuthenticationFailed`
+- `ImproperConfiguration`
+- `MethodNotAllowed`
+- `NotAcceptable`
+- `NotAuthenticated`
+- `NotFound`
+- `PermissionDenied`
+- `UnsupportedMediaType`
+
+## **Throwing standard exceptions**
 Let's use this `ServiceUnavailableException` in our previous project.
 
 For example, in the `CarController`, we have a `get_all()` method (a `GET` route handler). 
@@ -81,6 +85,51 @@ Service Unavailable
 {'detail':'Service Unavailable','code':'service_unavailable', 'description': 'The server cannot process the request due to a high load'}
 ```
 
+!!!hint
+    You should only raise `HTTPException` and `APIException` during route function handling. Since exception manager is a 
+    middleware and `HTTPException` raised before the `ExceptionMiddleware` will not be managed. Its advice exceptions happening
+    inside middleware classes should return appropriate responses directly.
+
+
+## **Exception Handlers**
+Exception Handlers are classes or functions that handles specific exception type response generation.
+
+Below is an example of ExceptionHandler that handles `HTTPException` in the application:
+```python
+import typing as t
+
+from ellar.common.interfaces import IExceptionHandler, IHostContext
+from starlette.exceptions import (
+    HTTPException as StarletteHTTPException,
+)
+from starlette.responses import Response
+
+
+class HTTPExceptionHandler(IExceptionHandler):
+    exception_type_or_code = StarletteHTTPException
+
+    async def catch(
+        self, ctx: IHostContext, exc: StarletteHTTPException
+    ) -> t.Union[Response, t.Any]:
+        assert isinstance(exc, StarletteHTTPException)
+        config = ctx.get_app().config
+
+        if exc.status_code in {204, 304}:
+            return Response(status_code=exc.status_code, headers=exc.headers)
+
+        if isinstance(exc.detail, (list, dict)):
+            data = exc.detail
+        else:
+            data = {"detail": exc.detail, "status_code": exc.status_code}  # type: ignore[assignment]
+
+        return config.DEFAULT_JSON_CLASS(
+            data, status_code=exc.status_code, headers=exc.headers
+        )
+```
+In the example above, `HTTPExceptionHandler.catch` method will be called when `ExeceptionMiddleware` detect exception of type `HTTPException`.
+And its return response to the client.
+
+
 ## **Creating Custom Exception Handler**
 
 To create an exception handler for your custom exception, you have to make a class that follows the `IExceptionHandler` contract.
@@ -227,3 +276,67 @@ class OverrideAPIExceptionHandler(IExceptionHandler):
 ```
 
 Once we register the `OverrideAPIExceptionHandler` exception handler, it will become the default handler for the `APIException` exception type.
+
+## **Declaring Exception Handler as a function**
+In the previous section, we have seen how to create a custom ExceptionHandler from `IExceptionHandler`. In this section we will do the same using a plane function. 
+
+For example, lets say we have a function `exception_handler_fun` as shown below
+
+```python
+from starlette.responses import PlainTextResponse
+from ellar.common import IExecutionContext
+
+
+def exception_handler_fun(ctx: IExecutionContext, exc: Exception):
+    return PlainTextResponse('Bad Request', status_code=400)
+```
+
+To get the `exception_handler_fun` to work as an ExceptionHandler, you will need `CallableExceptionHandler` from `ellar.common.exceptions` package.
+
+```python
+from starlette.responses import PlainTextResponse
+from ellar.common import IExecutionContext
+from ellar.common.exceptions import CallableExceptionHandler
+
+
+def exception_handler_fun(ctx: IExecutionContext, exc: Exception):
+    return PlainTextResponse('Bad Request', status_code=400)
+
+
+exception_400_handler = CallableExceptionHandler(
+    exc_class_or_status_code=400, callable_exception_handler=exception_handler_fun
+)
+```
+In the above example, you have created `exception_400_handler` Exception Handler to handler http exceptions with status code 400.
+And then it can be registed as an exception handler as we did in previous section
+
+```python
+from .custom_exception_handlers import exception_400_handler
+
+
+class BaseConfig(ConfigDefaultTypesMixin):
+    EXCEPTION_HANDLERS: List[IExceptionHandler] = [
+        exception_400_handler
+    ]
+```
+
+Also, `exception_handler_fun` can be made to handle an custom exception type as shown below.
+```python
+from starlette.responses import PlainTextResponse
+from ellar.common import IExecutionContext
+from ellar.common.exceptions import CallableExceptionHandler
+
+
+class CustomException(Exception):
+    pass
+
+
+def exception_handler_fun(ctx: IExecutionContext, exc: Exception):
+    return PlainTextResponse('Bad Request', status_code=400)
+
+
+exception_custom_handler = CallableExceptionHandler(
+    exc_class_or_status_code=CustomException, callable_exception_handler=exception_handler_fun
+)
+```
+In the above example, `exception_custom_handler` 

docs/security/csrf.md

@@ -29,3 +29,8 @@ class Development(BaseConfig):
     ]
 
 ```
+
+## **CORS**
+Cross-origin resource sharing (CORS) is a mechanism that allows resources to be requested from another domain. 
+Under the hood, Ellar registers CORS Middleware and provides CORS options in application for CORS customization.
+See how to configure **CORS** [here](../overview/middleware.md#corsmiddleware)

docs/security/encryption_and_hashing.md

@@ -0,0 +1,115 @@
+# **Encryption and Hashing**
+
+**Encryption** is the method of transforming data. This process changes the original information, referred to as plaintext, 
+into an alternative form called ciphertext. 
+The goal is to ensure that only authorized parties possess the capability to decrypt ciphertext back into plaintext and access the original information. 
+Encryption doesn't inherently prevent interference but rather restricts the intelligible content from potential interceptors. 
+Encryption is a bidirectional operation; what's encrypted can be decrypted using the correct key.
+
+**Hashing** is the process of converting a given key into another value. 
+A hash function is employed to create this new value following a mathematical algorithm. 
+After hashing is applied, it should be practically impossible to reverse the process and derive the original 
+input from the output.
+
+## **Encryption**
+In Python, the [`cryptography`](https://pypi.org/project/cryptography/) library provides a user-friendly way to implement encryption. 
+One common encryption scheme is Fernet, which offers symmetric key encryption.
+
+For example,
+```python
+from cryptography.fernet import Fernet
+
+# Generate a random encryption key
+key = Fernet.generate_key()
+
+# Create a Fernet cipher object with the key
+cipher_suite = Fernet(key)
+
+# Text to be encrypted
+plaintext = b"Hello, this is a secret message!"
+
+# Encrypt the plaintext
+cipher_text = cipher_suite.encrypt(plaintext)
+
+# Decrypt the ciphertext
+decrypted_text = cipher_suite.decrypt(cipher_text)
+
+# Convert bytes to string for printing
+original_message = decrypted_text.decode("utf-8")
+
+print("Original Message: ", plaintext)
+print("Encrypted Message: ", cipher_text)
+print("Decrypted Message: ", original_message)
+
+```
+The provided Python example demonstrates this process, securing a message with encryption and then decrypting it using the same key. 
+It's crucial to manage encryption keys securely in real applications to maintain the confidentiality and integrity of your data.
+
+## **Hashing**
+For hashing, Ellar works with [passlib](https://pypi.org/project/passlib/) and [hashlib](https://docs.python.org/3/library/hashlib.html)
+to create a wrapper around some hashing algorithms listed below,
+
+- **PBKDF2Hasher**: `pbkdf2_sha256` hashing algorithm wrapper
+- **PBKDF2SHA1Hasher**: `pbkdf2_sha1` hashing algorithm wrapper
+- **Argon2Hasher**: `argon2` hashing algorithm wrapper
+- **BCryptSHA256Hasher**: `bcrypt_sha256` hashing algorithm wrapper
+- **BCryptHasher**: `bcrypt` hashing algorithm wrapper
+- **ScryptHasher**: `scrypt` hashing algorithm wrapper
+- **MD5Hasher**: `md5` hashing algorithm wrapper
+
+## **Password Hashing**
+Ellar provides two important utility functions: `make_password` for password hashing 
+and `check_password` for password validation. Both of these functions are available in the 
+`ellar.core.security.hashers` package.
+
+```python
+def make_password(
+    password: str|bytes,
+    algorithm: str = "pbkdf2_sha256",
+    salt: str|None = None,
+) -> str:
+    pass
+
+
+def check_password(
+    password: str|bytes,
+    encoded: str,
+    setter: Callable[..., Any]|None = None,
+    preferred_algorithm: str = "pbkdf2_sha256",
+) -> bool:
+    pass
+```
+
+The `make_password` function takes plain text and generates a hashed result based on the provided hash algorithm. 
+In the code snippet above, the default algorithm for `make_password` is `pbkdf2_sha256`.
+
+The [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) algorithm with a SHA256 hash is a password stretching mechanism recommended by [NIST](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf).
+This should be sufficient for most users as it is quite secure and requires massive amounts of computing time to break.
+
+!!! note
+    All hashing wrappers are registered as `key-value` pairs and can be accessed by the algorithm names
+    using the get_hasher utility function in the `ellar.core.security.hashers` package.
+
+For an example,
+```python
+from ellar.core.security.hashers import make_password
+
+## Using pbkdf2_sha256 - PBKDF2Hasher
+password_hash = make_password('mypassword1234', algorithm="pbkdf2_sha256", salt='seasalt')
+print(password_hash)
+# pbkdf2_sha256$870000$seasalt$XE8bb8u57rxvyv2SThRFtMg9mzJLff2wjm3J8kGgFVI=
+
+## Using bcrypt_sha256 - BCryptSHA256Hasher
+password_hash = make_password('mypassword1234', algorithm="bcrypt_sha256", salt='20AmWL1wKJZAHPiI1HEk4k')
+print(password_hash)
+# bcrypt_sha256$$2b$12$20AmWL1wKJZAHPiI1HEk4eZuAlMGHkK1rw4oou26bnwGmAE8F0JGK
+```
+
+On the other hand, you can check or validate a password using the `check_password` function.
+
+```python
+from ellar.core.security.hashers import check_password
+
+hash_secret = "bcrypt_sha256$$2b$12$20AmWL1wKJZAHPiI1HEk4eZuAlMGHkK1rw4oou26bnwGmAE8F0JGK"
+assert check_password('mypassword1234', hash_secret) # True
+```

ellar/cache/backends/serializer.py

@@ -28,7 +28,7 @@ def load(self, data: t.Any) -> t.Any:
     def dumps(self, data: t.Any) -> t.Any:
         # Only skip pickling for integers, an int subclasses as bool should be
         # pickled.
-        if type(data) is int:
+        if isinstance(data, int):
             return data
         return pickle.dumps(data, self._protocol)
 

ellar/common/__init__.py

@@ -1,7 +1,5 @@
 import typing as t
 
-from starlette.exceptions import WebSocketException
-
 from .commands import EllarTyper, command
 from .datastructures import UploadFile
 from .decorators import (
@@ -30,6 +28,7 @@
     NotFound,
     PermissionDenied,
     UnsupportedMediaType,
+    WebSocketException,
 )
 from .interfaces import (
     IApplicationShutdown,

ellar/common/exceptions/__init__.py

@@ -11,6 +11,7 @@
     PermissionDenied,
     UnsupportedMediaType,
 )
+from .callable_exceptions import CallableExceptionHandler
 from .context import ExecutionContextException, HostContextException
 from .validation import RequestValidationError, WebSocketRequestValidationError
 
@@ -30,4 +31,5 @@
     "MethodNotAllowed",
     "NotAcceptable",
     "UnsupportedMediaType",
+    "CallableExceptionHandler",
 ]