pacnpal/simpleguardhome
1
0
Fork 0
mirror of https://github.com/pacnpal/simpleguardhome.git synced 2025-12-19 20:11:14 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs(README.md): remove outdated userscript documentation and browser integration setup

Browse Source
This commit is contained in:
pacnpal
2025-01-30 07:49:20 -05:00
parent 719845b1c8
commit 0bb99d3c6d
3 changed files with 0 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@@ -40,14 +40,6 @@ Then visit `http://localhost:8000` to start managing your AdGuard Home filtering
- ✅ Implements official AdGuard Home API spec - ✅ Implements official AdGuard Home API spec
- 🐳 Docker support - 🐳 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 ## Requirements
### System Requirements ### System Requirements
@@ -158,18 +150,6 @@ python -m uvicorn src.simpleguardhome.main:app --reload
The application will be available at `http://localhost:8000` 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 ## API Documentation
The API documentation is automatically generated by FastAPI using: The API documentation is automatically generated by FastAPI using:
@@ -226,9 +206,6 @@ simpleguardhome/
│ └── index.html # Web interface │ └── index.html # Web interface
├── static/ ├── static/
│ └── simpleguardhome.png # Project logo │ └── simpleguardhome.png # Project logo
├── userscript/
│ ├── README.md # Userscript documentation
│ └── simpleguardhome-404-checker.user.js
├── rules_backup/ # Backup storage location ├── rules_backup/ # Backup storage location
├── requirements.txt ├── requirements.txt
├── setup.py ├── setup.py

97
userscript/README.md
View File

@@ -1,97 +0,0 @@
# SimpleGuardHome 404 Checker Userscript
A Tampermonkey userscript that detects 404 responses while browsing and automatically checks if the domains are blocked by your AdGuard Home instance. This helps identify when DNS blocking might be causing page load failures.
## Features
- Automatically detects 404 responses from both fetch and XMLHttpRequest calls
- Checks failed domains against your AdGuard Home instance
- Shows notifications for blocked domains with one-click unblock button
- Directly unblocks domains using SimpleGuardHome API
- Configurable AdGuard Home instance settings
- Caches results to minimize API calls
- Error handling with configuration shortcuts
## Installation
1. Install the [Tampermonkey](https://www.tampermonkey.net/) browser extension
2. Click on the Tampermonkey icon and select "Create a new script"
3. Copy the contents of `simpleguardhome-404-checker.user.js` into the editor
4. Save the script (Ctrl+S or File -> Save)
## Configuration
### Initial Setup
1. Click on the Tampermonkey icon in your browser
2. Select "⚙️ Configure SimpleGuardHome" under the script's menu
3. Review your current settings (if any)
4. Enter new host and port settings
5. Connection test will be performed automatically
- Success: Settings are saved immediately
- Failure: Option to save anyway or retry
### Menu Options
- "⚙️ Configure SimpleGuardHome" - Open configuration dialog
- "🔄 Test Connection" - Test current settings
### Default Settings
- Host: `http://localhost`
- Port: `8000` (SimpleGuardHome default port)
### Connection Testing
- Automatic testing when saving new settings
- Manual testing available through menu
- Clear notifications of test results
- Option to save settings even if test fails
## How It Works
1. The script monitors all web requests on any website
2. When a 404 response is detected:
- Extracts the domain from the failed URL
- Checks if the domain is blocked by AdGuard Home
- Shows a notification with status if domain is blocked
- Provides a one-click "Unblock Domain" button
- Directly unblocks domain when button is clicked
- Shows success/error notification after unblock attempt
3. Error handling:
- Connection issues show a notification with configuration options
- Results are cached for 1 hour to reduce API load
- Failed requests provide clear error messages
## Technical Details
### Required Permissions
- `GM_xmlhttpRequest`: For making cross-origin requests to AdGuard Home
- `GM_getValue`/`GM_setValue`: For storing configuration
- `GM_registerMenuCommand`: For adding configuration menu
- `@connect *`: For connecting to custom AdGuard Home instances
### Cache System
- Domain check results are cached for 1 hour
- Cache includes:
- Block status (true/false)
- Timestamp
- Cache is updated when:
- Domain is checked (status: "not blocked", "blocked")
- Domain is unblocked (status: "already unblocked", "has been unblocked")
### Error Handling
- Connection failures
- Request timeouts
- API errors
- JSON parsing errors
## Development
The userscript is part of the SimpleGuardHome project and is designed to complement the main application by providing real-time feedback during web browsing.
To modify or extend the script:
1. Make changes to `simpleguardhome-404-checker.user.js`
2. Update version number in the metadata block
3. Reinstall in Tampermonkey to test changes
## License
Same as the main SimpleGuardHome project

252
userscript/simpleguardhome-404-checker.user.js
View File

@@ -1,252 +0,0 @@
// ==UserScript==
// @name SimpleGuardHome 404 Checker
// @namespace http://tampermonkey.net/
// @version 0.1
// @description Detects 404 responses and checks if they are blocked by AdGuard Home
// @author SimpleGuardHome
// @match *://*/*
// @grant GM_xmlhttpRequest
// @grant GM_getValue
// @grant GM_setValue
// @grant GM_registerMenuCommand
// @connect *
// @run-at document-start
// ==/UserScript==
(function() {
'use strict';
// Default configuration
const DEFAULT_CONFIG = {
host: 'http://localhost',
port: 8000 // SimpleGuardHome runs on port 8000 by default
};
// Get current configuration
function getConfig() {
return {
host: GM_getValue('host', DEFAULT_CONFIG.host),
port: GM_getValue('port', DEFAULT_CONFIG.port)
};
}
// Test SimpleGuardHome connection
async function testConnection(host, port) {
try {
const response = await new Promise((resolve, reject) => {
GM_xmlhttpRequest({
method: 'GET',
url: `${host}:${port}/health`,
headers: {'Accept': 'application/json'},
onload: resolve,
onerror: reject
});
});
return response.status === 200;
} catch (error) {
return false;
}
}
// Show configuration dialog
async function showConfigDialog() {
const config = getConfig();
const currentSettings = `Current Settings:
- Host: ${config.host}
- Port: ${config.port}
Enter new settings or cancel to keep current.`;
const host = prompt(currentSettings + '\n\nEnter SimpleGuardHome host (e.g. http://localhost):', config.host);
if (host === null) return;
const port = prompt('Enter SimpleGuardHome port (default: 8000):', config.port);
if (port === null) return;
const newPort = parseInt(port, 10) || DEFAULT_CONFIG.port;
// Test connection with new settings
const success = await testConnection(host, newPort);
if (success) {
GM_setValue('host', host);
GM_setValue('port', newPort);
createNotification('SimpleGuardHome configuration saved and connection tested successfully!');
} else {
const save = confirm('Could not connect to SimpleGuardHome with these settings. Save anyway?');
if (save) {
GM_setValue('host', host);
GM_setValue('port', newPort);
createNotification('Configuration saved, but connection test failed. Please verify your settings.');
}
}
}
// Register configuration menu commands
GM_registerMenuCommand('⚙️ Configure SimpleGuardHome', showConfigDialog);
GM_registerMenuCommand('🔄 Test Connection', async () => {
const config = getConfig();
const success = await testConnection(config.host, config.port);
createNotification(success ?
'Successfully connected to SimpleGuardHome!' :
'Could not connect to SimpleGuardHome. Please check your settings.');
});
// Store check results to avoid repeated API calls
const checkedDomains = new Map();
// Create notification container
function createNotification(message, showUnblockButton = false, domain = '') {
const notif = document.createElement('div');
notif.style.cssText = `
position: fixed;
bottom: 20px;
right: 20px;
background: #333;
color: white;
padding: 15px;
border-radius: 5px;
box-shadow: 0 2px 5px rgba(0,0,0,0.2);
z-index: 9999;
font-family: sans-serif;
max-width: 300px;
`;
const messageDiv = document.createElement('div');
messageDiv.textContent = message;
notif.appendChild(messageDiv);
if (showUnblockButton) {
const button = document.createElement('button');
button.textContent = 'Unblock Domain';
button.style.cssText = `
margin-top: 10px;
padding: 5px 10px;
background: #007bff;
color: white;
border: none;
border-radius: 3px;
cursor: pointer;
`;
button.onclick = () => unblockDomain(domain);
notif.appendChild(button);
}
document.body.appendChild(notif);
setTimeout(() => notif.remove(), 10000); // Remove after 10 seconds
}
// Unblock a domain
async function unblockDomain(domain) {
const config = getConfig();
const apiUrl = `${config.host}:${config.port}/control/filtering/unblock_host?name=${encodeURIComponent(domain)}`;
GM_xmlhttpRequest({
method: 'GET',
url: apiUrl,
headers: {'Accept': 'application/json'},
onload: function(response) {
try {
const data = JSON.parse(response.responseText);
createNotification(data.message);
// Update cache if successful
if (data.message.includes('unblocked')) {
checkedDomains.set(domain, {
isBlocked: false,
timestamp: Date.now()
});
}
} catch (error) {
console.error('SimpleGuardHome unblock error:', error);
createNotification('Failed to unblock domain. Please try again.');
}
},
onerror: function(error) {
console.error('SimpleGuardHome API error:', error);
createNotification('Error connecting to SimpleGuardHome. Please check your settings.');
}
});
}
// Check if domain is blocked by AdGuard Home
async function checkDomain(domain) {
// Skip if already checked recently
if (checkedDomains.has(domain)) {
const cachedResult = checkedDomains.get(domain);
if (Date.now() - cachedResult.timestamp < 3600000) { // Cache for 1 hour
return;
}
}
try {
const config = getConfig();
const apiUrl = `${config.host}:${config.port}/control/filtering/check_host?name=${encodeURIComponent(domain)}`;
GM_xmlhttpRequest({
method: 'GET',
url: apiUrl,
headers: {'Accept': 'application/json'},
onload: function(response) {
try {
const data = JSON.parse(response.responseText);
const isBlocked = data.reason.startsWith('Filtered');
// Cache the result
checkedDomains.set(domain, {
isBlocked,
timestamp: Date.now()
});
// If blocked, show notification with unblock option
if (isBlocked) {
createNotification(
`Domain ${domain} is blocked by AdGuard Home.`,
true,
domain
);
}
} catch (error) {
console.error('SimpleGuardHome parsing error:', error);
}
},
onerror: function(error) {
console.error('SimpleGuardHome API error:', error);
}
});
} catch (error) {
console.error('SimpleGuardHome check error:', error);
}
}
// Intercept 404 responses using a fetch handler
const originalFetch = window.fetch;
window.fetch = async function(...args) {
try {
const response = await originalFetch.apply(this, args);
if (response.status === 404) {
const url = new URL(args[0].toString());
checkDomain(url.hostname);
}
return response;
} catch (error) {
console.error('SimpleGuardHome 404 Checker Error:', error);
return originalFetch.apply(this, args);
}
};
// Also intercept XHR for broader compatibility
const originalXHROpen = XMLHttpRequest.prototype.open;
XMLHttpRequest.prototype.open = function(method, url, ...rest) {
const originalOnReadyStateChange = this.onreadystatechange;
this.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 404) {
const urlObj = new URL(url, window.location.href);
checkDomain(urlObj.hostname);
}
if (originalOnReadyStateChange) {
originalOnReadyStateChange.apply(this, arguments);
}
};
originalXHROpen.apply(this, [method, url, ...rest]);
};
})();