Skip to content

try-works/role-model / .agents/skills/cloudflare

cloudflare

Unverified

Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

FileKindSize
SKILL.mdskill md8.8 KB
references/agents-sdk/README.mdmarkdown2.7 KB
references/agents-sdk/api.mdmarkdown5.7 KB
references/agents-sdk/configuration.mdmarkdown3.5 KB
references/agents-sdk/gotchas.mdmarkdown5.0 KB
references/agents-sdk/patterns.mdmarkdown5.5 KB
references/ai-gateway/README.mdmarkdown6.2 KB
references/ai-gateway/configuration.mdmarkdown2.9 KB
references/ai-gateway/dynamic-routing.mdmarkdown1.8 KB
references/ai-gateway/features.mdmarkdown2.7 KB
references/ai-gateway/sdk-integration.mdmarkdown2.6 KB
references/ai-gateway/troubleshooting.mdmarkdown2.4 KB
references/ai-search/README.mdmarkdown4.4 KB
references/ai-search/api.mdmarkdown2.5 KB
references/ai-search/configuration.mdmarkdown1.7 KB
references/ai-search/gotchas.mdmarkdown2.1 KB
references/ai-search/patterns.mdmarkdown2.0 KB
references/analytics-engine/README.mdmarkdown3.3 KB
references/analytics-engine/api.mdmarkdown3.1 KB
references/analytics-engine/configuration.mdmarkdown2.3 KB
references/analytics-engine/gotchas.mdmarkdown2.0 KB
references/analytics-engine/patterns.mdmarkdown2.3 KB
references/api-shield/README.mdmarkdown1.8 KB
references/api-shield/api.mdmarkdown3.8 KB
references/api-shield/configuration.mdmarkdown4.9 KB
references/api-shield/gotchas.mdmarkdown4.8 KB
references/api-shield/patterns.mdmarkdown5.7 KB
references/api/README.mdmarkdown2.4 KB
references/api/api.mdmarkdown4.2 KB
references/api/configuration.mdmarkdown3.7 KB
references/api/gotchas.mdmarkdown5.3 KB
references/api/patterns.mdmarkdown4.5 KB
references/argo-smart-routing/README.mdmarkdown4.0 KB
references/argo-smart-routing/api.mdmarkdown6.4 KB
references/argo-smart-routing/configuration.mdmarkdown4.4 KB
references/argo-smart-routing/gotchas.mdmarkdown4.2 KB
references/argo-smart-routing/patterns.mdmarkdown3.0 KB
references/artifacts/README.mdmarkdown3.7 KB
references/artifacts/api.mdmarkdown5.0 KB
references/artifacts/configuration.mdmarkdown3.1 KB
references/bindings/README.mdmarkdown3.9 KB
references/bindings/api.mdmarkdown5.1 KB
references/bindings/configuration.mdmarkdown4.4 KB
references/bindings/gotchas.mdmarkdown6.0 KB
references/bindings/patterns.mdmarkdown4.9 KB
references/bot-management/README.mdmarkdown3.7 KB
references/bot-management/api.mdmarkdown5.7 KB
references/bot-management/configuration.mdmarkdown5.6 KB
references/bot-management/gotchas.mdmarkdown5.5 KB
references/bot-management/patterns.mdmarkdown4.9 KB
references/browser-rendering/README.mdmarkdown3.0 KB
references/browser-rendering/api.mdmarkdown2.9 KB
references/browser-rendering/configuration.mdmarkdown1.8 KB
references/browser-rendering/gotchas.mdmarkdown2.5 KB
references/browser-rendering/patterns.mdmarkdown2.6 KB
references/c3/README.mdmarkdown3.3 KB
references/c3/api.mdmarkdown2.2 KB
references/c3/configuration.mdmarkdown1.6 KB
references/c3/gotchas.mdmarkdown2.3 KB
references/c3/patterns.mdmarkdown2.2 KB
references/cache-reserve/README.mdmarkdown5.5 KB
references/cache-reserve/api.mdmarkdown5.9 KB
references/cache-reserve/configuration.mdmarkdown3.6 KB
references/cache-reserve/gotchas.mdmarkdown5.7 KB
references/cache-reserve/patterns.mdmarkdown6.1 KB
references/containers/README.mdmarkdown3.4 KB
references/containers/api.mdmarkdown4.2 KB
references/containers/configuration.mdmarkdown5.3 KB
references/containers/gotchas.mdmarkdown4.4 KB
references/containers/patterns.mdmarkdown4.8 KB
references/cron-triggers/README.mdmarkdown2.9 KB
references/cron-triggers/api.mdmarkdown5.7 KB
references/cron-triggers/configuration.mdmarkdown4.2 KB
references/cron-triggers/gotchas.mdmarkdown6.2 KB
references/cron-triggers/patterns.mdmarkdown6.8 KB
references/d1/README.mdmarkdown4.6 KB
references/d1/api.mdmarkdown6.6 KB
references/d1/configuration.mdmarkdown5.5 KB
references/d1/gotchas.mdmarkdown4.2 KB
references/d1/patterns.mdmarkdown7.1 KB
references/ddos/README.mdmarkdown2.0 KB
references/ddos/api.mdmarkdown4.1 KB
references/ddos/configuration.mdmarkdown2.9 KB
references/ddos/gotchas.mdmarkdown3.8 KB
references/ddos/patterns.mdmarkdown5.5 KB
references/do-storage/README.mdmarkdown2.7 KB
references/do-storage/api.mdmarkdown3.5 KB
references/do-storage/configuration.mdmarkdown2.2 KB
references/do-storage/gotchas.mdmarkdown5.1 KB
references/do-storage/patterns.mdmarkdown6.0 KB
references/do-storage/testing.mdmarkdown4.8 KB
references/durable-objects/README.mdmarkdown6.5 KB
references/durable-objects/api.mdmarkdown6.0 KB
references/durable-objects/configuration.mdmarkdown4.2 KB
references/durable-objects/gotchas.mdmarkdown7.1 KB
references/durable-objects/patterns.mdmarkdown6.5 KB
references/email-routing/README.mdmarkdown3.4 KB
references/email-routing/api.mdmarkdown5.2 KB
references/email-routing/configuration.mdmarkdown3.5 KB
references/email-routing/gotchas.mdmarkdown4.0 KB
references/email-routing/patterns.mdmarkdown5.4 KB
references/email-workers/README.mdmarkdown5.3 KB
references/email-workers/api.mdmarkdown5.9 KB
references/email-workers/configuration.mdmarkdown2.7 KB
references/email-workers/gotchas.mdmarkdown3.0 KB
references/email-workers/patterns.mdmarkdown2.7 KB
references/flagship/README.mdmarkdown3.6 KB
references/flagship/api.mdmarkdown11.5 KB
references/flagship/configuration.mdmarkdown4.7 KB
references/flagship/gotchas.mdmarkdown6.2 KB
references/flagship/patterns.mdmarkdown13.7 KB
references/graphql-api/README.mdmarkdown7.6 KB
references/graphql-api/api.mdmarkdown5.6 KB
references/graphql-api/configuration.mdmarkdown4.6 KB
references/graphql-api/gotchas.mdmarkdown4.7 KB
references/graphql-api/patterns.mdmarkdown6.4 KB
references/hyperdrive/README.mdmarkdown2.8 KB
references/hyperdrive/api.mdmarkdown3.8 KB
references/hyperdrive/configuration.mdmarkdown3.8 KB
references/hyperdrive/gotchas.mdmarkdown3.8 KB
references/hyperdrive/patterns.mdmarkdown5.8 KB
references/images/README.mdmarkdown2.8 KB
references/images/api.mdmarkdown2.5 KB
references/images/configuration.mdmarkdown4.0 KB
references/images/gotchas.mdmarkdown2.4 KB
references/images/patterns.mdmarkdown3.5 KB
references/kv/README.mdmarkdown2.8 KB
references/kv/api.mdmarkdown4.2 KB
references/kv/configuration.mdmarkdown3.0 KB
references/kv/gotchas.mdmarkdown4.3 KB
references/kv/patterns.mdmarkdown4.6 KB
references/miniflare/README.mdmarkdown2.9 KB
references/miniflare/api.mdmarkdown4.5 KB
references/miniflare/configuration.mdmarkdown3.4 KB
references/miniflare/gotchas.mdmarkdown3.6 KB
references/miniflare/patterns.mdmarkdown4.2 KB
references/network-interconnect/README.mdmarkdown3.2 KB
references/network-interconnect/api.mdmarkdown5.5 KB
references/network-interconnect/configuration.mdmarkdown4.2 KB
references/network-interconnect/gotchas.mdmarkdown5.4 KB
references/network-interconnect/patterns.mdmarkdown3.9 KB
references/observability/README.mdmarkdown3.9 KB
references/observability/api.mdmarkdown3.4 KB
references/observability/configuration.mdmarkdown3.5 KB
references/observability/gotchas.mdmarkdown3.7 KB
references/observability/patterns.mdmarkdown2.4 KB
references/pages-functions/README.mdmarkdown3.2 KB
references/pages-functions/api.mdmarkdown4.6 KB
references/pages-functions/configuration.mdmarkdown2.9 KB
references/pages-functions/gotchas.mdmarkdown3.8 KB
references/pages-functions/patterns.mdmarkdown4.1 KB
references/pages/README.mdmarkdown2.8 KB
references/pages/api.mdmarkdown5.8 KB
references/pages/configuration.mdmarkdown5.7 KB
references/pages/gotchas.mdmarkdown7.9 KB
references/pages/patterns.mdmarkdown5.9 KB
references/pipelines/README.mdmarkdown4.2 KB
references/pipelines/api.mdmarkdown4.9 KB
references/pipelines/configuration.mdmarkdown6.0 KB
references/pipelines/gotchas.mdmarkdown3.0 KB
references/pipelines/patterns.mdmarkdown4.6 KB
references/pulumi/README.mdmarkdown3.2 KB
references/pulumi/api.mdmarkdown5.6 KB
references/pulumi/configuration.mdmarkdown5.5 KB
references/pulumi/gotchas.mdmarkdown6.4 KB
references/pulumi/patterns.mdmarkdown6.8 KB
references/queues/README.mdmarkdown3.0 KB
references/queues/api.mdmarkdown5.4 KB
references/queues/configuration.mdmarkdown3.7 KB
references/queues/gotchas.mdmarkdown7.1 KB
references/queues/patterns.mdmarkdown5.4 KB
references/r2-data-catalog/README.mdmarkdown3.9 KB
references/r2-data-catalog/api.mdmarkdown5.5 KB
references/r2-data-catalog/configuration.mdmarkdown3.9 KB
references/r2-data-catalog/gotchas.mdmarkdown3.2 KB
references/r2-data-catalog/patterns.mdmarkdown5.2 KB
references/r2-sql/README.mdmarkdown3.2 KB
references/r2-sql/api.mdmarkdown4.8 KB
references/r2-sql/configuration.mdmarkdown1.6 KB
references/r2-sql/gotchas.mdmarkdown1.9 KB
references/r2-sql/patterns.mdmarkdown4.3 KB
references/r2/README.mdmarkdown2.8 KB
references/r2/api.mdmarkdown5.5 KB
references/r2/configuration.mdmarkdown3.6 KB
references/r2/gotchas.mdmarkdown4.9 KB
references/r2/patterns.mdmarkdown5.7 KB
references/realtime-sfu/README.mdmarkdown3.0 KB
references/realtime-sfu/api.mdmarkdown3.7 KB
references/realtime-sfu/configuration.mdmarkdown3.4 KB
references/realtime-sfu/gotchas.mdmarkdown4.8 KB
references/realtime-sfu/patterns.mdmarkdown5.3 KB
references/realtimekit/README.mdmarkdown4.0 KB
references/realtimekit/api.mdmarkdown8.2 KB
references/realtimekit/configuration.mdmarkdown5.1 KB
references/realtimekit/gotchas.mdmarkdown6.7 KB
references/realtimekit/patterns.mdmarkdown7.5 KB
references/sandbox/README.mdmarkdown3.0 KB
references/sandbox/api.mdmarkdown4.9 KB
references/sandbox/configuration.mdmarkdown3.3 KB
references/sandbox/gotchas.mdmarkdown5.3 KB

references/cron-triggers/gotchas.md

View on GitHub
# Cron Triggers Gotchas

## Common Errors

### "Timezone Issues"

**Problem:** Cron runs at wrong time relative to local timezone  
**Cause:** All crons execute in UTC, no local timezone support  
**Solution:** Convert local time to UTC manually

**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`

**Examples:**
- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`
- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`
- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`

**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)

### "Cron Not Executing"

**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits  
**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits

### "Duplicate Executions"

**Cause:** At-least-once delivery  
**Solution:** Track execution IDs in KV - see idempotency pattern below

### "Execution Failures"

**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors  
**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks

### "Local Testing Not Working"

**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler  
**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format  
**Solution:**

1. Verify `scheduled()` is exported:
```typescript
export default {
  async scheduled(controller, env, ctx) {
    console.log("Cron triggered");
  },
};
```

2. Start dev server:
```bash
npx wrangler dev
```

3. Use correct endpoint format (URL-encode spaces as `+`):
```bash
# Correct
curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"

# Wrong (will fail)
curl "http://localhost:8787/__scheduled?cron=*/5 * * * *"
```

4. Update Wrangler if outdated:
```bash
npm install -g wrangler@latest
```

### "waitUntil() Tasks Not Completing"

**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute  
**Cause:** Promises rejected without error handling, or handler returns before promise settles  
**Solution:** Always await or handle errors in waitUntil promises:

```typescript
export default {
  async scheduled(controller, env, ctx) {
    // BAD: Silent failures
    ctx.waitUntil(riskyOperation());
    
    // GOOD: Explicit error handling
    ctx.waitUntil(
      riskyOperation().catch(err => {
        console.error("Background task failed:", err);
        return logError(err, env);
      })
    );
  },
};
```

### "Idempotency Issues"

**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails)  
**Cause:** No deduplication mechanism  
**Solution:** Use KV to track execution IDs:

```typescript
export default {
  async scheduled(controller, env, ctx) {
    const executionId = `${controller.cron}-${controller.scheduledTime}`;
    const existing = await env.EXECUTIONS.get(executionId);
    
    if (existing) {
      console.log("Already executed, skipping");
      controller.noRetry();
      return;
    }
    
    await env.EXECUTIONS.put(executionId, "1", { expirationTtl: 86400 }); // 24h TTL
    await performIdempotentOperation(env);
  },
};
```

### "Security Concerns"

**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering  
**Cause:** Testing endpoint available in deployed Workers  
**Solution:** Block `__scheduled` in production:

```typescript
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    
    // Block __scheduled in production
    if (url.pathname === "/__scheduled" && env.ENVIRONMENT === "production") {
      return new Response("Not Found", { status: 404 });
    }
    
    return handleRequest(request, env, ctx);
  },
  
  async scheduled(controller, env, ctx) {
    // Your cron logic
  },
};
```

**Also:** Use `env.API_KEY` for secrets (never hardcode)

**Alternative:** Add middleware to verify request origin:
```typescript
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    
    if (url.pathname === "/__scheduled") {
      // Check Cloudflare headers to verify internal request
      const cfRay = request.headers.get("cf-ray");
      if (!cfRay && env.ENVIRONMENT === "production") {
        return new Response("Not Found", { status: 404 });
      }
    }
    
    return handleRequest(request, env, ctx);
  },
  
  async scheduled(controller, env, ctx) {
    // Your cron logic
  },
};
```

## Limits & Quotas

| Limit | Free | Paid | Notes |
|-------|------|------|-------|
| Triggers per Worker | 3 | Unlimited | Maximum cron schedules per Worker |
| CPU time | 10ms | 30s (<1hr interval), 15min (≥1hr interval) | May need `ctx.waitUntil()` or Workflows |
| Execution guarantee | At-least-once | At-least-once | Duplicates possible - use idempotency |
| Propagation delay | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |
| Min interval | 1 minute | 1 minute | Cannot schedule more frequently |
| Cron accuracy | ±1 minute | ±1 minute | Execution may drift slightly |

## Testing Best Practices

**Unit tests:**
- Mock `ScheduledController`, `ExecutionContext`, and bindings
- Test each cron expression separately
- Verify `noRetry()` is called when expected
- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env

**Integration tests:**
- Test via `/__scheduled` endpoint in dev environment
- Verify idempotency logic with duplicate `scheduledTime` values
- Test error handling and retry behavior

**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval

## Resources

- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)
- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
- [Crontab Guru](https://crontab.guru/) - Validator
- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall