refactor!: moved allowed hosts to a plugin

Author: lsfratel

README.md

@@ -18,7 +18,7 @@ WebSpark provides a simple yet powerful architecture for handling HTTP requests
 -   **Optimized JSON Handling**: Automatically uses the fastest available JSON library (`orjson`, `ujson`, or `json`).
 -   **Built-in File Uploads**: Seamlessly handle multipart form data and file uploads.
 -   **Comprehensive Error Handling**: A simple `HTTPException` system for clear and consistent error responses.
--   **Security Features**: Built-in protection against HTTP Host header attacks and proxy support.
+-   **Proxy Support**: Built-in support for running behind a reverse proxy.
 -   **Environment Configuration**: Helper utilities for managing configuration via environment variables.
 -   **Extensive Testing**: 90% test coverage ensuring reliability and stability.
 
@@ -271,7 +271,7 @@ app.add_paths([
 WebSpark includes a CORS (Cross-Origin Resource Sharing) plugin that implements the full CORS specification. It supports both simple and preflighted requests with configurable origins, methods, headers, and credentials.
 
 ```python
-from webspark.contrib import CORSPlugin
+from webspark.contrib.plugins import CORSPlugin
 
 # Create a CORS plugin with a specific configuration
 cors_plugin = CORSPlugin(
@@ -302,6 +302,29 @@ The CORS plugin supports the following configuration options:
 - `expose_headers` - List of headers that browsers are allowed to access.
 - `vary_header` - Whether to add Vary header for preflight requests.
 
+#### AllowedHosts Plugin
+
+To prevent HTTP Host header attacks, WebSpark provides an `AllowedHostsPlugin`. This plugin checks the request's `Host` header against a list of allowed hostnames.
+
+```python
+from webspark.contrib.plugins import AllowedHostsPlugin
+
+# Allow requests only to "mydomain.com" and any subdomain of "api.mydomain.com"
+allowed_hosts_plugin = AllowedHostsPlugin(
+    allowed_hosts=["mydomain.com", ".api.mydomain.com"]
+)
+
+# Register the plugin globally
+app = WebSpark(plugins=[allowed_hosts_plugin])
+```
+
+-   **Behavior**:
+    -   If `allowed_hosts` is not set, all requests will be rejected with a `400 Bad Request` error, ensuring that only requests from specified hosts are processed.
+-   **Matching**:
+    -   `"mydomain.com"`: Matches the exact domain.
+    -   `".mydomain.com"`: Matches `mydomain.com` and any subdomain (e.g., `api.mydomain.com`).
+    -   `"*"`: Matches any host.
+
 ### 7. Error Handling
 
 Gracefully handle errors using `HTTPException`. When raised, the framework will catch it and generate a standardized JSON error response.
@@ -372,27 +395,7 @@ The framework checks for the following headers when `TRUST_PROXY` is enabled:
 -   `X-Forwarded-Proto` for the request scheme (`http` or `https`).
 -   `X-Forwarded-Host` for the original host.
 
-### 10. Allowed Hosts
-
-To prevent HTTP Host header attacks, WebSpark checks the request's `Host` header against a list of allowed hostnames. This is configured via the `ALLOWED_HOSTS` setting on the configuration object.
-
-```python
-class AppConfig:
-    # Allow requests only to "mydomain.com" and any subdomain of "api.mydomain.com"
-    ALLOWED_HOSTS = ["mydomain.com", ".api.mydomain.com"]
-
-app = WebSpark(config=AppConfig())
-```
-
--   **Behavior**:
-    -   If `debug=True`, `ALLOWED_HOSTS` defaults to `["*"]` (allowing all hosts).
-    -   If `debug=False` and `ALLOWED_HOSTS` is not set, all requests will be rejected with a `400 Bad Request` error.
--   **Matching**:
-    -   `"mydomain.com"`: Matches the exact domain.
-    -   `".mydomain.com"`: Matches `mydomain.com` and any subdomain (e.g., `api.mydomain.com`).
-    -   `"*"`: Matches any host.
-
-### 11. Environment Variable Helper
+### 10. Environment Variable Helper
 
 WebSpark includes a convenient `env` helper function in `webspark.utils` to simplify reading and parsing environment variables.
 
@@ -411,7 +414,7 @@ DEBUG = env("DEBUG", default=False, parser=bool)
 
 This helper streamlines configuration management, making it easy to handle different data types and required settings.
 
-### 12. File Uploads
+### 11. File Uploads
 
 WebSpark makes handling file uploads simple with built-in multipart form data parsing. Uploaded files are accessible through the `ctx.files` attribute.
 
@@ -473,6 +476,7 @@ pdm run ruff format .
 ```
 webspark/
 ├── core/          # Core components (WSGI app, router, views, schemas)
+├── contrib/       # Optional plugins (CORS, AllowedHosts)
 ├── http/          # HTTP abstractions (request, response, cookies)
 ├── schema/        # Data validation schemas and fields
 ├── utils/         # Utilities (exceptions, JSON handling, env vars)
@@ -490,6 +494,10 @@ webspark/
   - `path` - Routing helper function
   - `Plugin` - Base class for middleware
 
+- **contrib/** - Optional plugins:
+  - `CORSPlugin` - Handles Cross-Origin Resource Sharing.
+  - `AllowedHostsPlugin` - Validates incoming Host headers.
+
 - **http/** - HTTP abstractions:
   - `Context` - Request/response context object
   - `Cookie` - Cookie handling utilities

examples/config_example.py

@@ -7,6 +7,7 @@
 - Environment variable usage
 """
 
+from webspark.contrib.plugins import AllowedHostsPlugin
 from webspark.core import View, WebSpark, path
 from webspark.http import Context
 from webspark.utils import env
@@ -30,12 +31,18 @@ class AppConfig:
 
     # Allowed hosts for security (in production, specify your domain)
     ALLOWED_HOSTS = env(
-        "ALLOWED_HOSTS", default=["*"] if DEBUG else ["localhost", "127.0.0.1"]
+        "ALLOWED_HOSTS",
+        default=["*"] if DEBUG else ["localhost", "127.0.0.1"],
+        parser=lambda x: x.split(",") if x else [],
     )
 
 
 # Create the app with configuration
-app = WebSpark(config=AppConfig(), debug=AppConfig.DEBUG)
+app = WebSpark(
+    config=AppConfig(),
+    debug=AppConfig.DEBUG,
+    plugins=[AllowedHostsPlugin(allowed_hosts=AppConfig.ALLOWED_HOSTS)],
+)
 
 
 # Sample view to show configuration

examples/cors_example.py

@@ -2,7 +2,7 @@
 Example demonstrating how to use the CORS plugin with WebSpark.
 """
 
-from webspark.contrib.cors import CORSPlugin
+from webspark.contrib.plugins import CORSPlugin
 from webspark.core import View, WebSpark, path
 from webspark.http import Context
 

tests/contrib/plugins/__init__.py

@@ -0,0 +1,107 @@
+from unittest.mock import Mock
+
+import pytest
+
+from webspark.contrib.plugins.allowed_hosts import AllowedHostsPlugin
+from webspark.utils import HTTPException
+
+
+@pytest.fixture
+def mock_handler():
+    """Fixture for a mock handler."""
+    return Mock()
+
+
+@pytest.fixture
+def mock_context():
+    """Fixture for a mock context."""
+    return Mock()
+
+
+def test_allowed_hosts_valid_host(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=["test.com"])
+    mock_context.host = "test.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    wrapped_handler(mock_context)
+
+    mock_handler.assert_called_once_with(mock_context)
+
+
+def test_allowed_hosts_invalid_host(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=["test.com"])
+    mock_context.host = "invalid.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    with pytest.raises(HTTPException) as exc_info:
+        wrapped_handler(mock_context)
+
+    assert exc_info.value.status_code == 400
+    assert "Host not allowed" in exc_info.value.details
+    mock_handler.assert_not_called()
+
+
+def test_allowed_hosts_wildcard_subdomain(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=[".test.com"])
+    mock_context.host = "sub.test.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    wrapped_handler(mock_context)
+
+    mock_handler.assert_called_once_with(mock_context)
+
+
+def test_allowed_hosts_wildcard_root_domain(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=[".test.com"])
+    mock_context.host = "test.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    wrapped_handler(mock_context)
+
+    mock_handler.assert_called_once_with(mock_context)
+
+
+def test_allowed_hosts_wildcard_invalid_domain(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=[".test.com"])
+    mock_context.host = "invalid.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    with pytest.raises(HTTPException) as exc_info:
+        wrapped_handler(mock_context)
+
+    assert exc_info.value.status_code == 400
+    assert "Host not allowed" in exc_info.value.details
+    mock_handler.assert_not_called()
+
+
+def test_allowed_hosts_star_allows_all(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=["*"])
+    mock_context.host = "any.host.com"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    wrapped_handler(mock_context)
+
+    mock_handler.assert_called_once_with(mock_context)
+
+
+def test_allowed_hosts_missing_host_header(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=["example.com"])
+    mock_context.host = ""
+    wrapped_handler = plugin.apply(mock_handler)
+
+    with pytest.raises(HTTPException) as exc_info:
+        wrapped_handler(mock_context)
+
+    assert exc_info.value.status_code == 400
+    assert "Invalid or missing host header" in exc_info.value.details
+    mock_handler.assert_not_called()
+
+
+def test_allowed_hosts_strips_port(mock_handler, mock_context):
+    plugin = AllowedHostsPlugin(allowed_hosts=["test.com"])
+    mock_context.host = "test.com:8000"
+    wrapped_handler = plugin.apply(mock_handler)
+
+    wrapped_handler(mock_context)
+
+    mock_handler.assert_called_once_with(mock_context)

tests/contrib/plugins/test_allowed_hosts.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from webspark.contrib.cors import CORSPlugin
+from webspark.contrib.plugins.cors import CORSPlugin
 from webspark.http import Context
 from webspark.utils import HTTPException