feat(main.py): add endpoint to unblock a domain and improve error handling

fix(userscript): update default port and restore 404 response interception
2025-12-20 04:21:13 -05:00 · 2025-01-29 15:46:11 -05:00
parent 0d482fa33e
commit 99d8265235
4 changed files with 227 additions and 185 deletions
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 <p align="center">
  <a href="https://github.com/pacnpal/simpleguardhome/releases"><img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="Version 0.1.0"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
-  <a href="#requirements"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
+  <a href="#requirements"><img src="https://img.shields.io/badge/python-3.7+-blue.svg" alt="Python 3.7+"></a>
 </p>

 A modern web application for checking and managing domain filtering in AdGuard Home. Built with FastAPI and modern JavaScript, following the official AdGuard Home OpenAPI specification.
@@ -27,9 +27,11 @@ Then visit `http://localhost:8000` to start managing your AdGuard Home filtering

 ## Features

+### Core Features
 - 🔍 Real-time domain filtering status checks
 - 🚫 One-click domain unblocking
 - 💻 Modern, responsive web interface with Tailwind CSS
+- 🌓 Support for light and dark modes
 - 🔄 Live feedback and error handling
 - 📝 Comprehensive logging
 - 🏥 Health monitoring endpoint
@@ -38,10 +40,18 @@ Then visit `http://localhost:8000` to start managing your AdGuard Home filtering
 - ✅ Implements official AdGuard Home API spec
 - 🐳 Docker support

+### Browser Integration
+- 🔎 404 Page Checker Userscript
+  - Automatically detects 404 responses while browsing
+  - Checks if failed domains are blocked by AdGuard Home
+  - Shows unblock notifications with one-click actions
+  - Configurable settings and caching system
+  - Tampermonkey integration for all major browsers
+
 ## Requirements

 ### System Requirements
- Python 3.9 or higher (for local installation)
+- Python 3.7 or higher (for local installation)
 - Running AdGuard Home instance
 - AdGuard Home API credentials
 - Docker (optional, for containerized deployment)
@@ -148,13 +158,32 @@ python -m uvicorn src.simpleguardhome.main:app --reload

 The application will be available at `http://localhost:8000`

+## Browser Integration Setup
+
+1. Install the [Tampermonkey](https://www.tampermonkey.net/) browser extension
+2. Navigate to the `userscript` directory in this repository
+3. Install the `simpleguardhome-404-checker.user.js` script
+4. Configure the script with your AdGuard Home instance details
+
+The userscript will automatically:
+- Monitor web requests for 404 responses
+- Check if failed domains are blocked
+- Show notifications for blocked domains
+- Provide quick unblock options
 ## API Documentation

-The API documentation is available at:
- Swagger UI: `http://localhost:8000/api/docs`
- ReDoc: `http://localhost:8000/api/redoc`
- OpenAPI Schema: `http://localhost:8000/api/openapi.json`
+The API documentation is automatically generated by FastAPI using:
+- Type hints in endpoint definitions
+- Pydantic models for request/response validation
+- Function docstrings for descriptions
+- Response models and status codes

+Documentation is available at:
+- Swagger UI: `http://localhost:8000/api/docs` - Interactive API documentation
+- ReDoc: `http://localhost:8000/api/redoc` - Alternative documentation UI
+- OpenAPI Schema: `http://localhost:8000/api/openapi.json` - Raw OpenAPI specification
+
+### API Endpoints
 ### API Endpoints

 All endpoints follow the official AdGuard Home API specification:
@@ -163,13 +192,19 @@ All endpoints follow the official AdGuard Home API specification:
 - `GET /` - Main web interface for domain checking and unblocking

 #### Filtering Endpoints
- `POST /control/filtering/check_host` - Check if a domain is blocked
+- `GET /control/filtering/check_host` - Check if a domain is blocked
  - Parameters: `name` (query parameter)
  - Returns: Detailed filtering status and rules

- `POST /control/filtering/whitelist/add` - Add a domain to the allowed list
-  - Parameters: `name` (JSON body)
-  - Returns: Success status
+- `GET /control/filtering/unblock_host` - Unblock a domain by adding it to whitelist
+  - Parameters: `name` (query parameter)
+  - Returns: Success message with domain status
+  - Status: Returns whether domain was unblocked, already unblocked, or not blocked
+
+- `POST /control/filtering/set_rules` - Add domains to the filtering rules
+  - Parameters: Array of rules in request body
+  - Returns: Success message on successful update
+  - Note: Used internally by unblock_host endpoint

 - `GET /control/filtering/status` - Get current filtering configuration
  - Returns: Complete filtering status including rules and filters
@@ -178,6 +213,63 @@ All endpoints follow the official AdGuard Home API specification:
 - `GET /control/status` - Check application and AdGuard Home connection status
  - Returns: Health status with filtering state

+## Project Structure
+
+```
+simpleguardhome/
+├── src/
+│   └── simpleguardhome/
+│       ├── __init__.py
+│       ├── main.py          # FastAPI application
+│       ├── config.py        # Configuration management
+│       ├── adguard.py       # AdGuard Home API client
+│       └── templates/
+│           └── index.html   # Web interface
+├── static/
+│   └── simpleguardhome.png  # Project logo
+├── userscript/
+│   ├── README.md           # Userscript documentation
+│   └── simpleguardhome-404-checker.user.js
+├── rules_backup/          # Backup storage location
+├── requirements.txt
+├── setup.py
+├── pyproject.toml        # Project metadata and dependencies
+├── .env.example
+├── Dockerfile
+└── README.md
+```
+
+## Security Notes
+
+- API credentials are handled via environment variables
+- Connections use proper error handling and timeouts
+- Input validation is performed on all endpoints
+- CORS protection with proper headers
+- Rate limiting on sensitive endpoints
+- Session-based authentication with AdGuard Home
+- Sensitive information is not exposed in responses
+
+## Error Handling
+
+The application implements comprehensive error handling for all endpoints:
+
+- 400 Bad Request
+  - Invalid domain format
+  - Missing required parameters
+  - Invalid whitelist rule format
+- 500 Internal Server Error
+  - Failed to add domain to whitelist
+  - Other internal processing errors
+- 502 Bad Gateway
+  - AdGuard Home API errors
+  - Invalid API responses
+- 503 Service Unavailable
+  - AdGuard Home service unreachable
+  - Connection timeouts
+  - Network errors
+
+All errors return an ErrorResponse object with a descriptive message.
+
 ## Response Models

 The application uses Pydantic models that match the AdGuard Home API specification:
@@ -200,74 +292,37 @@ The application uses Pydantic models that match the AdGuard Home API specificati
 }
 ```

-### DomainCheckResult
+### FilterCheckHostResponse
 ```python
 {
-    "reason": str,  # Filtering status (e.g., "FilteredBlackList")
-    "rule": str,    # Applied filtering rule
-    "filter_id": int,  # ID of the filter containing the rule
-    "service_name": str,  # For blocked services
-    "cname": str,   # For CNAME rewrites
-    "ip_addrs": List[str]  # For A/AAAA rewrites
+    "reason": str,      # Filtering status (e.g., "FilteredBlackList", "NotFilteredNotFound")
+    "filter_id": int,   # Optional: ID of the filter containing the rule (deprecated)
+    "rule": str,        # Optional: Applied filtering rule (deprecated)
+    "rules": [          # List of applied rules with details
+        {
+            "filter_list_id": int,  # Filter list ID
+            "text": str            # Rule text
+        }
+    ],
+    "service_name": str,  # Optional: For blocked services
+    "cname": str,        # Optional: For CNAME rewrites
+    "ip_addrs": List[str] # Optional: For A/AAAA rewrites
 }
 ```

-## Error Handling
-
-The application implements proper error handling according to the AdGuard Home API spec:
-
- 400 Bad Request - Invalid input
- 401 Unauthorized - Authentication required
- 403 Forbidden - Authentication failed
- 502 Bad Gateway - AdGuard Home API error
- 503 Service Unavailable - AdGuard Home unreachable
-
-## Development
-
-### Project Structure
-
-```
-simpleguardhome/
-├── src/
-│   └── simpleguardhome/
-│       ├── __init__.py
-│       ├── main.py          # FastAPI application
-│       ├── config.py        # Configuration management
-│       ├── adguard.py       # AdGuard Home API client
-│       └── templates/
-│           └── index.html   # Web interface
-├── static/
-│   └── simpleguardhome.png  # Project logo
-├── requirements.txt
-├── setup.py
-├── .env.example
-├── Dockerfile
-├── docker-compose.yml
-└── README.md
+### SetRulesRequest
+```python
+{
+    "rules": List[str]  # List of filtering rules to set
+}
 ```

-### Adding New Features
-
-1. Backend Changes:
-   - Add routes in `main.py`
-   - Extend AdGuard client in `adguard.py`
-   - Update configuration in `config.py`
-   - Follow AdGuard Home OpenAPI spec
-
-2. Frontend Changes:
-   - Modify `templates/index.html`
-   - Use Tailwind CSS for styling
-   - Follow existing error handling patterns
-
-## Security Notes
-
- API credentials are handled via environment variables
- Connections use proper error handling and timeouts
- Input validation is performed on all endpoints
- CORS protection with proper headers
- Rate limiting on sensitive endpoints
- Session-based authentication with AdGuard Home
- Sensitive information is not exposed in responses
+### ErrorResponse
+```python
+{
+    "message": str  # Error description
+}
+```

 ## License