473 lines
10 KiB
Markdown
473 lines
10 KiB
Markdown
# Cloudflare Workers Platform Guide
|
|
|
|
Comprehensive guide for deploying, monitoring, and troubleshooting Cloudflare Workers in Grey Haven's stack.
|
|
|
|
## Workers Architecture
|
|
|
|
**Execution Model**:
|
|
- V8 isolates (not containers)
|
|
- Deployed globally to 300+ datacenters
|
|
- Request routed to nearest location
|
|
- Cold start: ~1-5ms (vs 100-1000ms for containers)
|
|
- CPU time limit: 50ms (Free), 50ms-30s (Paid)
|
|
|
|
**Resource Limits**:
|
|
```
|
|
Free Plan:
|
|
- Bundle size: 1MB compressed
|
|
- CPU time: 50ms per request
|
|
- Requests: 100,000/day
|
|
- KV reads: 100,000/day
|
|
|
|
Paid Plan ($5/month):
|
|
- Bundle size: 10MB compressed
|
|
- CPU time: 50ms (standard), up to 30s (unbound)
|
|
- Requests: 10M included, $0.50/million after
|
|
- KV reads: 10M included
|
|
```
|
|
|
|
---
|
|
|
|
## Deployment Best Practices
|
|
|
|
### Bundle Optimization
|
|
|
|
**Size Reduction Strategies**:
|
|
```typescript
|
|
// 1. Tree shaking with named imports
|
|
import { uniq } from 'lodash-es'; // ✅ Only imports uniq
|
|
import _ from 'lodash'; // ❌ Imports entire library
|
|
|
|
// 2. Use native APIs instead of libraries
|
|
const date = new Date().toISOString(); // ✅ Native
|
|
import moment from 'moment'; // ❌ 300KB library
|
|
|
|
// 3. External API calls instead of SDKs
|
|
await fetch('https://api.anthropic.com/v1/messages', {
|
|
method: 'POST',
|
|
headers: { 'x-api-key': env.API_KEY },
|
|
body: JSON.stringify({ ... })
|
|
}); // ✅ 0KB vs @anthropic-ai/sdk (2.1MB)
|
|
|
|
// 4. Code splitting with dynamic imports
|
|
if (request.url.includes('/special')) {
|
|
const { handler } = await import('./expensive-module');
|
|
return handler(request);
|
|
} // ✅ Lazy load
|
|
```
|
|
|
|
**webpack Configuration**:
|
|
```javascript
|
|
module.exports = {
|
|
mode: 'production',
|
|
target: 'webworker',
|
|
optimization: {
|
|
minimize: true,
|
|
usedExports: true, // Tree shaking
|
|
sideEffects: false
|
|
},
|
|
resolve: {
|
|
alias: {
|
|
'lodash': 'lodash-es' // Use ES modules version
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### Environment Variables
|
|
|
|
**Using Secrets**:
|
|
```bash
|
|
# Add secret (never in code)
|
|
wrangler secret put DATABASE_URL
|
|
|
|
# List secrets
|
|
wrangler secret list
|
|
|
|
# Delete secret
|
|
wrangler secret delete OLD_KEY
|
|
```
|
|
|
|
**Using Variables** (wrangler.toml):
|
|
```toml
|
|
[vars]
|
|
API_ENDPOINT = "https://api.partner.com"
|
|
MAX_RETRIES = "3"
|
|
CACHE_TTL = "300"
|
|
|
|
[env.staging.vars]
|
|
API_ENDPOINT = "https://staging-api.partner.com"
|
|
|
|
[env.production.vars]
|
|
API_ENDPOINT = "https://api.partner.com"
|
|
```
|
|
|
|
**Accessing in Code**:
|
|
```typescript
|
|
export default {
|
|
async fetch(request: Request, env: Env) {
|
|
const dbUrl = env.DATABASE_URL; // Secret
|
|
const endpoint = env.API_ENDPOINT; // Var
|
|
const maxRetries = parseInt(env.MAX_RETRIES);
|
|
|
|
return new Response('OK');
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Performance Optimization
|
|
|
|
### CPU Time Management
|
|
|
|
**Avoid CPU-Intensive Operations**:
|
|
```typescript
|
|
// ❌ BAD: CPU-intensive operation
|
|
function processLargeDataset(data) {
|
|
const sorted = data.sort((a, b) => a.value - b.value);
|
|
const filtered = sorted.filter(item => item.value > 1000);
|
|
const mapped = filtered.map(item => ({ ...item, processed: true }));
|
|
return mapped; // Can exceed 50ms CPU limit
|
|
}
|
|
|
|
// ✅ GOOD: Offload to external service
|
|
async function processLargeDataset(data, env) {
|
|
const response = await fetch(`${env.PROCESSING_API}/process`, {
|
|
method: 'POST',
|
|
body: JSON.stringify(data)
|
|
});
|
|
return response.json(); // External service handles heavy lifting
|
|
}
|
|
|
|
// ✅ BETTER: Use Durable Objects for stateful computation
|
|
const id = env.PROCESSOR.idFromName('processor');
|
|
const stub = env.PROCESSOR.get(id);
|
|
return stub.fetch(request); // Durable Object has more CPU time
|
|
```
|
|
|
|
**Monitor CPU Usage**:
|
|
```typescript
|
|
export default {
|
|
async fetch(request: Request, env: Env) {
|
|
const start = Date.now();
|
|
|
|
try {
|
|
const response = await handleRequest(request, env);
|
|
const duration = Date.now() - start;
|
|
|
|
if (duration > 40) {
|
|
console.warn(`CPU time approaching limit: ${duration}ms`);
|
|
}
|
|
|
|
return response;
|
|
} catch (error) {
|
|
const duration = Date.now() - start;
|
|
console.error(`Request failed after ${duration}ms:`, error);
|
|
throw error;
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### Caching Strategies
|
|
|
|
**Cache API**:
|
|
```typescript
|
|
export default {
|
|
async fetch(request: Request) {
|
|
const cache = caches.default;
|
|
|
|
// Check cache
|
|
let response = await cache.match(request);
|
|
if (response) return response;
|
|
|
|
// Cache miss - fetch and cache
|
|
response = await fetch(request);
|
|
|
|
// Cache for 5 minutes
|
|
const cacheResponse = new Response(response.body, response);
|
|
cacheResponse.headers.set('Cache-Control', 'max-age=300');
|
|
await cache.put(request, cacheResponse.clone());
|
|
|
|
return response;
|
|
}
|
|
};
|
|
```
|
|
|
|
**KV for Data Caching**:
|
|
```typescript
|
|
export default {
|
|
async fetch(request: Request, env: Env) {
|
|
const url = new URL(request.url);
|
|
const cacheKey = `data:${url.pathname}`;
|
|
|
|
// Check KV
|
|
const cached = await env.CACHE.get(cacheKey, 'json');
|
|
if (cached) return Response.json(cached);
|
|
|
|
// Fetch data
|
|
const data = await fetchExpensiveData();
|
|
|
|
// Store in KV with 5min TTL
|
|
await env.CACHE.put(cacheKey, JSON.stringify(data), {
|
|
expirationTtl: 300
|
|
});
|
|
|
|
return Response.json(data);
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Common Errors and Solutions
|
|
|
|
### Error 1101: Worker Threw Exception
|
|
|
|
**Cause**: Unhandled JavaScript exception
|
|
|
|
**Example**:
|
|
```typescript
|
|
// ❌ BAD: Unhandled error
|
|
export default {
|
|
async fetch(request: Request) {
|
|
const data = JSON.parse(request.body); // Throws if invalid JSON
|
|
return Response.json(data);
|
|
}
|
|
};
|
|
```
|
|
|
|
**Solution**:
|
|
```typescript
|
|
// ✅ GOOD: Proper error handling
|
|
export default {
|
|
async fetch(request: Request) {
|
|
try {
|
|
const body = await request.text();
|
|
const data = JSON.parse(body);
|
|
return Response.json(data);
|
|
} catch (error) {
|
|
console.error('JSON parse error:', error);
|
|
return new Response('Invalid JSON', { status: 400 });
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### Error 1015: Rate Limited
|
|
|
|
**Cause**: Too many requests to origin
|
|
|
|
**Solution**: Implement caching and rate limiting
|
|
```typescript
|
|
const RATE_LIMIT = 100; // requests per minute
|
|
const rateLimits = new Map();
|
|
|
|
export default {
|
|
async fetch(request: Request) {
|
|
const ip = request.headers.get('CF-Connecting-IP');
|
|
const key = `ratelimit:${ip}`;
|
|
|
|
const count = rateLimits.get(key) || 0;
|
|
if (count >= RATE_LIMIT) {
|
|
return new Response('Rate limit exceeded', { status: 429 });
|
|
}
|
|
|
|
rateLimits.set(key, count + 1);
|
|
setTimeout(() => rateLimits.delete(key), 60000);
|
|
|
|
return new Response('OK');
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### Error: Script Exceeds Size Limit
|
|
|
|
**Diagnosis**:
|
|
```bash
|
|
# Check bundle size
|
|
npm run build
|
|
ls -lh dist/worker.js
|
|
|
|
# Analyze bundle
|
|
npm install --save-dev webpack-bundle-analyzer
|
|
npm run build -- --analyze
|
|
```
|
|
|
|
**Solutions**: See [bundle optimization](#bundle-optimization) above
|
|
|
|
---
|
|
|
|
## Monitoring and Logging
|
|
|
|
### Structured Logging
|
|
|
|
```typescript
|
|
interface LogEntry {
|
|
level: 'info' | 'warn' | 'error';
|
|
message: string;
|
|
timestamp: string;
|
|
requestId?: string;
|
|
duration?: number;
|
|
metadata?: Record<string, any>;
|
|
}
|
|
|
|
function log(entry: LogEntry) {
|
|
console.log(JSON.stringify({
|
|
...entry,
|
|
timestamp: new Date().toISOString()
|
|
}));
|
|
}
|
|
|
|
export default {
|
|
async fetch(request: Request, env: Env) {
|
|
const requestId = crypto.randomUUID();
|
|
const start = Date.now();
|
|
|
|
try {
|
|
log({
|
|
level: 'info',
|
|
message: 'Request started',
|
|
requestId,
|
|
metadata: {
|
|
method: request.method,
|
|
url: request.url
|
|
}
|
|
});
|
|
|
|
const response = await handleRequest(request, env);
|
|
|
|
log({
|
|
level: 'info',
|
|
message: 'Request completed',
|
|
requestId,
|
|
duration: Date.now() - start,
|
|
metadata: {
|
|
status: response.status
|
|
}
|
|
});
|
|
|
|
return response;
|
|
} catch (error) {
|
|
log({
|
|
level: 'error',
|
|
message: 'Request failed',
|
|
requestId,
|
|
duration: Date.now() - start,
|
|
metadata: {
|
|
error: error.message,
|
|
stack: error.stack
|
|
}
|
|
});
|
|
|
|
return new Response('Internal Server Error', { status: 500 });
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### Health Check Endpoint
|
|
|
|
```typescript
|
|
export default {
|
|
async fetch(request: Request, env: Env) {
|
|
const url = new URL(request.url);
|
|
|
|
if (url.pathname === '/health') {
|
|
return Response.json({
|
|
status: 'healthy',
|
|
timestamp: new Date().toISOString(),
|
|
version: env.VERSION || 'unknown'
|
|
});
|
|
}
|
|
|
|
// Regular request handling
|
|
return handleRequest(request, env);
|
|
}
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Workers
|
|
|
|
```bash
|
|
# Local testing
|
|
wrangler dev
|
|
curl http://localhost:8787/api/users
|
|
curl -X POST http://localhost:8787/api/users -H "Content-Type: application/json" -d '{"name": "Test User"}'
|
|
|
|
# Unit testing (Vitest)
|
|
import { describe, it, expect } from 'vitest';
|
|
import worker from './worker';
|
|
|
|
describe('Worker', () => {
|
|
it('returns 200 for health check', async () => {
|
|
const request = new Request('https://example.com/health');
|
|
const response = await worker.fetch(request, getMockEnv());
|
|
expect(response.status).toBe(200);
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
```typescript
|
|
// 1. Validate inputs
|
|
function validateEmail(email: string): boolean {
|
|
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
|
|
}
|
|
|
|
// 2. Set security headers
|
|
function addSecurityHeaders(response: Response): Response {
|
|
response.headers.set('X-Content-Type-Options', 'nosniff');
|
|
response.headers.set('X-Frame-Options', 'DENY');
|
|
response.headers.set('Strict-Transport-Security', 'max-age=31536000');
|
|
return response;
|
|
}
|
|
|
|
// 3. CORS configuration
|
|
const ALLOWED_ORIGINS = ['https://app.greyhaven.io', 'https://staging.greyhaven.io'];
|
|
function handleCors(request: Request): Response | null {
|
|
const origin = request.headers.get('Origin');
|
|
if (request.method === 'OPTIONS') {
|
|
return new Response(null, {
|
|
headers: {
|
|
'Access-Control-Allow-Origin': origin,
|
|
'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE',
|
|
'Access-Control-Max-Age': '86400'
|
|
}
|
|
});
|
|
}
|
|
if (origin && !ALLOWED_ORIGINS.includes(origin)) {
|
|
return new Response('Forbidden', { status: 403 });
|
|
}
|
|
return null;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **Runbooks**: [troubleshooting-runbooks.md](troubleshooting-runbooks.md) - Step-by-step procedures
|
|
- **Commands**: [diagnostic-commands.md](diagnostic-commands.md) - Command reference
|
|
- **Examples**: [Examples Index](../examples/INDEX.md) - Full examples
|
|
|
|
---
|
|
|
|
Return to [reference index](INDEX.md)
|