Basic Compilation
Simple URL-based compilation with standard transformations
Hosts File Conversion
Convert /etc/hosts format to AdGuard syntax
Raw Rules
Compile directly from pasted filter rules
Multiple Sources
Combine multiple filter lists with different transformations
With Exclusions
Filter out unwanted rules using exclusions
Rule Optimizer NEW
Optimize patterns and remove redundant rules
Pi-hole Format NEW
Output in Pi-hole domain list format
Conflict Detection NEW
Detect blocking/allowing rule conflicts
đ Event Pipeline
Our compiler uses Server-Sent Events (SSE) to provide real-time progress updates throughout the compilation process.
Event Types
source:start - Fires when fetching a source begins
source:complete - Source successfully fetched and parsed
source:error - Source fetching or parsing failed
transformation:start - Transformation begins (e.g., Deduplicate)
transformation:complete - Transformation finished
progress - General progress updates with current phase
result - Final compilation results with rules and metrics
done - Compilation process complete
error - Fatal error occurred
API Endpoints
Base URL: https://adblock-compiler.jayson-knight.workers.dev
POST /compile
Compile filter lists and return complete results as JSON
curl -X POST https://adblock-compiler.jayson-knight.workers.dev/compile \\
-H "Content-Type: application/json" \\
-d '{
"configuration": {
"name": "My Filter List",
"sources": [{"source": "https://example.com/filters.txt"}],
"transformations": ["Deduplicate", "RemoveEmptyLines"]
},
"benchmark": true
}'
POST /compile/stream
Compile with real-time Server-Sent Events for progress tracking
const eventSource = new EventSource('/compile/stream');
eventSource.addEventListener('source:start', (e) => {
const data = JSON.parse(e.data);
console.log('Fetching:', data.source.name);
});
eventSource.addEventListener('result', (e) => {
const data = JSON.parse(e.data);
console.log('Compiled', data.ruleCount, 'rules');
});
POST /compile/batch
Compile multiple filter lists in parallel (max 10 per batch)
curl -X POST https://adblock-compiler.jayson-knight.workers.dev/compile/batch \\
-H "Content-Type: application/json" \\
-d '{
"requests": [
{
"id": "list-1",
"configuration": {
"name": "First List",
"sources": [{"source": "https://example.com/list1.txt"}]
}
},
{
"id": "list-2",
"configuration": {
"name": "Second List",
"sources": [{"source": "https://example.com/list2.txt"}]
}
}
]
}'
Performance Features
⨠Gzip Compression: Cache storage uses gzip compression (70-80% size reduction)
⥠Request Deduplication: Identical concurrent requests share results
đ Circuit Breaker: Automatic retry with exponential backoff for failed sources
đ Diff Visualization: See changes between cached and new compilations
Cache TTL: Results cached for 1 hour with automatic invalidation
Try It Now
Switch to Simple Mode or Advanced Mode and compile a list. Watch the "Compilation Progress" section below to see the event pipeline in action!
Available Transformations
Transformations are applied in the following fixed order:
- ConvertToAscii - Convert internationalized domains
- TrimLines - Remove whitespace
- RemoveComments - Strip comments
- Compress - Convert hosts to adblock syntax
- RemoveModifiers - Remove unsupported modifiers
- InvertAllow - Convert to allowlist
- Validate - Remove invalid rules
- ValidateAllowIp - Validate but keep IPs
- Deduplicate - Remove duplicates
- RemoveEmptyLines - Clean empty lines
- InsertFinalNewLine - Add final newline
- RuleOptimizer NEW - Optimize patterns, remove redundant rules
- ConflictDetection NEW - Detect blocking/allowing conflicts
Output Formats
The compiler supports multiple output formats:
- Adblock - Standard adblock filter syntax (default)
- Hosts - /etc/hosts format (0.0.0.0 domain.com)
- Pi-hole - Simple domain list for Pi-hole
- Dnsmasq - Dnsmasq address= format
- Unbound - Unbound DNS resolver format
- DoH - DNS-over-HTTPS blocklist format
- JSON - Structured JSON with metadata
Streaming API (SSE)
The streaming API provides real-time progress updates using Server-Sent Events (SSE). This is now the default compilation method in the web UI.
Benefits:
- Real-time progress tracking for each source
- Live transformation status updates
- Immediate error notifications
- Non-blocking UI during compilation
CORS & Rate Limits
CORS: All endpoints support CORS with Access-Control-Allow-Origin: *
Rate Limits: No hard limits currently. Execution timeout: 50 seconds