# 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.