nodejs-cloudflare-cdnsurfer/README.md

CDN Surfer

A high-performance Cloudflare Worker-based proxy that leverages Cloudflare's global edge network to accelerate web browsing and optimize content delivery.

CDN Surfer - Surf the web at CDN speeds! 🌐

Project Layout

• wrangler.toml
  • Worker entrypoint is src/index.js
  • KV namespace bindings for API keys and session cookies
• src/index.js
  • Single-file Worker implementation
  • Edge routing + content optimization + URL rewriting + browser consistency
  • Serves the dashboard HTML when no fetch query param is present
• package.json
  • Project dependencies and deployment scripts

Features

• Edge Acceleration: Leverages Cloudflare's global CDN
• Complete URL Rewriting: All links route through the edge
• Browser Consistency: Standardizes browser fingerprints
• Session Management: Cookie handling with KV storage
• Performance Optimized: Efficient content delivery

Installation

1. Clone or download this project
2. Install dependencies:

   npm install
   

Configuration

Create wrangler.toml (gitignored for security):

name = "sanitizing-proxy"
main = "src/index.js"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "PROXY_KEYS"
id = "your-keys-namespace-id"

[[kv_namespaces]]
binding = "PROXY_COOKIES"
id = "your-cookies-namespace-id"

All other configuration is in src/index.js inside the CONFIG object.

Usage

Web Interface

The proxy includes a built-in browser interface for easy navigation!

1. Access the browser: Open https://your-worker.workers.dev/ in your browser
2. Enter URLs: Type any website URL in the address bar
3. Browse normally: All navigation routes through the edge
4. Persistent navigation: Back/Forward buttons for history

Endpoints

• Dashboard

  • GET / - Serves the browser UI

• Proxy

  • GET /?fetch=https://example.com&api_key=YOUR_KEY

Features of the Web Interface

• Clean, modern design with responsive layout
• URL bar for direct navigation
• Loading indicators and status display
• Error handling with user-friendly messages
• Back/Forward navigation with history tracking
• Mobile-friendly responsive design

Direct API Usage

You can use the proxy directly via API:

Query Parameter Method

GET https://your-worker.workers.dev/?fetch=https://example.com&api_key=YOUR_KEY

With API Key Header

curl https://your-worker.workers.dev/?fetch=https://example.com \
  -H "x-api-key: YOUR_KEY"

How It Works

All traffic routes through Cloudflare's edge network:

• Client requests → Edge Worker → Destination
• Responses are rewritten to route all URLs through the edge
• Headers optimized for consistency and performance

Testing

Automated Testing

npm test          # Run comprehensive test suite
npm run test:sites # Test specific sites

Code Quality

npm run lint      # Check code style
npm run lint:fix  # Fix linting issues
npm run format    # Format code with Prettier

Manual Testing

npm run dev       # Start local development server

Tests verify:

• Dashboard UI loads correctly
• URL input and navigation functionality
• Content proxying through the edge
• Resource loading (JS/CSS/images)
• Link clicking and form handling

Note: Some complex sites may have anti-bot measures that interfere with automated testing.

Deployment

Development

npm run dev

Production

npx wrangler deploy

License

GPL v2.0