Add README.md

README.md

@@ -0,0 +1,231 @@
+# US Edge Cache Warmer
+
+A Cloudflare Worker that pre-warms the cache for a URL across all major US edge locations. This tool helps ensure your content is cached and ready to serve in all US regions, improving load times for your users.
+
+## Features
+
+- Caches a target URL on all major US Cloudflare edge locations
+- Accepts target URLs via query parameters or POST request
+- Provides detailed per-region caching status reports
+- Can be scheduled to run automatically using Cloudflare's Cron Triggers
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (version 14 or later)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) (Cloudflare's command-line tool for Workers)
+- A Cloudflare account with Workers enabled
+
+## Installation & Deployment
+
+### 1. Install Wrangler
+
+If you haven't already installed Wrangler, do so with npm:
+
+```bash
+npm install -g wrangler
+```
+
+### 2. Log in to your Cloudflare account
+
+Authenticate Wrangler with your Cloudflare account:
+
+```bash
+wrangler login
+```
+
+Follow the prompts to log in through your browser.
+
+### 3. Create a new Worker project
+
+Create a new directory for your project and initialize it:
+
+```bash
+mkdir cache-warmer
+cd cache-warmer
+```
+
+### 4. Create your Worker script
+
+Create a file named `index.js` and paste the provided Worker code into it.
+
+### 5. Create a wrangler.toml configuration file
+
+Create a `wrangler.toml` file in your project directory with the following content:
+
+```toml
+name = "cache-warmer"
+main = "index.js"
+compatibility_date = "2023-10-16"
+
+[triggers]
+# Cron trigger example: run daily at 2:00 AM UTC
+# Uncomment the line below to enable
+# crons = ["0 2 * * *"]
+```
+
+### 6. Deploy the Worker
+
+Deploy your Worker to Cloudflare:
+
+```bash
+wrangler deploy
+```
+
+After deployment, Wrangler will output the URL where your Worker is available.
+
+## Setting Up a Cron Trigger
+
+To run the cache warmer automatically on a schedule, you can use Cloudflare's Cron Triggers.
+
+### Using wrangler.toml (Recommended)
+
+1. Edit your `wrangler.toml` file and uncomment the `crons` line:
+
+```toml
+[triggers]
+crons = ["0 2 * * *"]  # Run at 2:00 AM UTC every day
+```
+
+2. The cron format is `"minute hour day month day_of_week"`. Some examples:
+   - `"0 2 * * *"` - Run at 2:00 AM UTC every day
+   - `"0 */6 * * *"` - Run every 6 hours
+   - `"0 0 * * MON"` - Run at midnight every Monday
+
+3. Redeploy your Worker:
+
+```bash
+wrangler deploy
+```
+
+### Using Cloudflare Dashboard
+
+Alternatively, you can set up cron triggers via the Cloudflare Dashboard:
+
+1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/)
+2. Navigate to Workers & Pages
+3. Select your `cache-warmer` Worker
+4. Go to the "Triggers" tab
+5. Click "Add Cron Trigger"
+6. Enter your desired cron schedule
+7. Click "Add"
+
+## Example: Warming Cache for Your Homepage Daily
+
+A common usage is to set up a daily cron job to pre-warm the cache for your website's homepage.
+
+### Option 1: Using the Scheduled Event Handler
+
+To automate the process, you can modify your worker to handle scheduled events:
+
+1. Update your `index.js` to add a scheduled event handler:
+
+```javascript
+export default {
+  // Keep your existing fetch handler
+  async fetch(request, env, ctx) {
+    // Existing code...
+  },
+  
+  // Add a scheduled handler to warm cache for a specific URL
+  async scheduled(event, env, ctx) {
+    const targetUrl = "https://your-website.com";
+    
+    // Process all regions in parallel
+    const results = await Promise.allSettled(US_REGIONS.map(async (region) => {
+      return await cacheInRegion(targetUrl, region);
+    }));
+    
+    console.log(`Cache warming completed for ${targetUrl}`);
+  }
+};
+```
+
+2. Update your `wrangler.toml` to enable the cron trigger:
+
+```toml
+name = "cache-warmer"
+main = "index.js"
+compatibility_date = "2023-10-16"
+
+[triggers]
+crons = ["0 7 * * *"]  # Run daily at 7:00 AM UTC (before peak traffic)
+```
+
+3. Deploy with the updated configuration:
+
+```bash
+wrangler deploy
+```
+
+### Option 2: Using Another Worker or Service
+
+You can also trigger your cache warmer externally:
+
+1. Set up a curl command in any server cron job:
+
+```bash
+curl -X POST \
+  https://cache-warmer.[your-worker-subdomain].workers.dev/ \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://your-website.com"}'
+```
+
+2. Or use a third-party cron service like [cron-job.org](https://cron-job.org) to call your worker URL at scheduled times.
+
+## Manual Usage
+
+### Via GET Request
+
+You can trigger the cache warmer by sending a GET request with a `url` parameter:
+
+```
+https://cache-warmer.[your-worker-subdomain].workers.dev/?url=https://example.com/page-to-cache
+```
+
+### Via POST Request
+
+Alternatively, you can send a POST request with a JSON body:
+
+```bash
+curl -X POST \
+  https://cache-warmer.[your-worker-subdomain].workers.dev/ \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com/page-to-cache"}'
+```
+
+## Response Format
+
+The Worker will respond with a JSON object containing:
+
+- `url`: The URL that was cached
+- `cached`: Whether caching was attempted
+- `regionResults`: Array of results for each region
+  - `region`: The region code
+  - `success`: Whether the request to that region succeeded
+  - `status`: HTTP status code
+  - `error`: Error message if the request failed
+
+Example response:
+
+```json
+{
+  "url": "https://example.com",
+  "cached": true,
+  "regionResults": [
+    {
+      "region": "IAD",
+      "success": true,
+      "status": 200,
+      "error": null
+    },
+    // Additional regions...
+  ]
+}
+```
+
+## Troubleshooting
+
+- **HTTP 400 Errors**: Check that your URL is properly formatted and includes the protocol (http:// or https://).
+- **Authentication Issues**: If you need to cache authenticated content, you'll need to modify the Worker to include authentication headers.
+- **Deployment Failed**: Ensure you're logged in via `wrangler login` and have the proper permissions on your Cloudflare account.
+- **Cron Not Running**: Verify your cron expression is valid and check the "Logs" section in the Cloudflare Dashboard for your Worker.