From 8bf1693cc0699750a967a1c4343256108b40db75 Mon Sep 17 00:00:00 2001 From: lsemenenko Date: Sat, 1 Mar 2025 01:38:23 +0000 Subject: [PATCH] Add README.md --- README.md | 231 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e8c3305 --- /dev/null +++ b/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. \ No newline at end of file