@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/cache-reserve/configuration.md

@@ -0,0 +1,169 @@
+# Cache Reserve Configuration
+
+## Dashboard Setup
+
+**Minimum steps to enable:**
+
+```bash
+# Navigate to dashboard
+https://dash.cloudflare.com/caching/cache-reserve
+
+# Click "Enable Storage Sync" or "Purchase" button
+```
+
+**Prerequisites:**
+- Paid Cache Reserve plan or Smart Shield Advanced required
+- Tiered Cache **required** for Cache Reserve to function optimally
+
+## API Configuration
+
+### REST API
+
+```bash
+# Enable
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+
+# Check status
+curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### TypeScript SDK
+
+```bash
+npm install cloudflare
+```
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+});
+
+// Enable Cache Reserve
+await client.cache.cacheReserve.edit({
+  zone_id: 'abc123',
+  value: 'on',
+});
+
+// Get Cache Reserve status
+const status = await client.cache.cacheReserve.get({
+  zone_id: 'abc123',
+});
+console.log(status.value); // 'on' or 'off'
+```
+
+### Python SDK
+
+```bash
+pip install cloudflare
+```
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token=os.environ.get("CLOUDFLARE_API_TOKEN"))
+
+# Enable Cache Reserve
+client.cache.cache_reserve.edit(
+    zone_id="abc123",
+    value="on"
+)
+
+# Get Cache Reserve status
+status = client.cache.cache_reserve.get(zone_id="abc123")
+print(status.value)  # 'on' or 'off'
+```
+
+### Terraform
+
+```hcl
+terraform {
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+  }
+}
+
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token
+}
+
+resource "cloudflare_zone_cache_reserve" "example" {
+  zone_id = var.zone_id
+  enabled = true
+}
+
+# Tiered Cache is required for Cache Reserve
+resource "cloudflare_tiered_cache" "example" {
+  zone_id    = var.zone_id
+  cache_type = "smart"
+}
+```
+
+### Pulumi
+
+```typescript
+import * as cloudflare from "@pulumi/cloudflare";
+
+// Enable Cache Reserve
+const cacheReserve = new cloudflare.ZoneCacheReserve("example", {
+  zoneId: zoneId,
+  enabled: true,
+});
+
+// Enable Tiered Cache (required)
+const tieredCache = new cloudflare.TieredCache("example", {
+  zoneId: zoneId,
+  cacheType: "smart",
+});
+```
+
+### Required API Token Permissions
+
+- `Zone Settings Read`
+- `Zone Settings Write`
+- `Zone Read`
+- `Zone Write`
+
+## Cache Rules Integration
+
+Control Cache Reserve eligibility via Cache Rules:
+
+```typescript
+// Enable for static assets
+{
+  action: 'set_cache_settings',
+  action_parameters: {
+    cache_reserve: { eligible: true, minimum_file_ttl: 86400 },
+    edge_ttl: { mode: 'override_origin', default: 86400 },
+    cache: true
+  },
+  expression: '(http.request.uri.path matches "\\.(jpg|png|webp|pdf|zip)$")'
+}
+
+// Disable for APIs
+{
+  action: 'set_cache_settings',
+  action_parameters: { cache_reserve: { eligible: false } },
+  expression: '(http.request.uri.path matches "^/api/")'
+}
+
+// Create via API: PUT to zones/{zone_id}/rulesets/phases/http_request_cache_settings/entrypoint
+```
+
+## Wrangler Integration
+
+Cache Reserve works automatically with Workers deployed via Wrangler. No special wrangler.jsonc configuration needed - enable Cache Reserve via Dashboard or API for the zone.
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [API Reference](./api.md) - Purging and monitoring APIs
+- [Patterns](./patterns.md) - Best practices and optimization
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting

package/skills/cloudflare-deploy/references/cache-reserve/gotchas.md

@@ -0,0 +1,132 @@
+# Cache Reserve Gotchas
+
+## Common Errors
+
+### "Assets Not Being Cached in Cache Reserve"
+
+**Cause:** Asset is not cacheable, TTL < 10 hours, Content-Length header missing, or blocking headers present (Set-Cookie, Vary: *)  
+**Solution:** Ensure minimum TTL of 10+ hours (`Cache-Control: public, max-age=36000`), add Content-Length header, remove Set-Cookie header, and set `Vary: Accept-Encoding` (not *)
+
+### "Range Requests Not Working" (Video Seeking Fails)
+
+**Cause:** Cache Reserve does **NOT** support range requests (HTTP 206 Partial Content)  
+**Solution:** Range requests bypass Cache Reserve entirely. For video streaming with seeking:
+- Use edge cache only (shorter TTLs)
+- Consider R2 with direct access for range-heavy workloads
+- Accept that seekable content won't benefit from Cache Reserve persistence
+
+### "Origin Bandwidth Higher Than Expected"
+
+**Cause:** Cache Reserve fetches **uncompressed** content from origin, even though it serves compressed to visitors  
+**Solution:** 
+- If origin charges by bandwidth, factor in uncompressed transfer costs
+- Cache Reserve compresses for visitors automatically (saves visitor bandwidth)
+- Compare: origin egress savings vs higher uncompressed fetch costs
+
+### "Cloudflare Images Not Caching with Cache Reserve"
+
+**Cause:** Cloudflare Images with `Vary: Accept` header (format negotiation) is incompatible with Cache Reserve  
+**Solution:** 
+- Cache Reserve silently skips images with Vary for format negotiation
+- Original images (non-transformed) may still be eligible
+- Use Cloudflare Images variants or edge cache for transformed images
+
+### "High Class A Operations Costs"
+
+**Cause:** Frequent cache misses, short TTLs, or frequent revalidation  
+**Solution:** Increase TTL for stable content (24+ hours), enable Tiered Cache to reduce direct Cache Reserve misses, or use stale-while-revalidate
+
+### "Purge Not Working as Expected"
+
+**Cause:** Purge by tag only triggers revalidation but doesn't remove from Cache Reserve storage  
+**Solution:** Use purge by URL for immediate removal, or disable Cache Reserve then clear all data for complete removal
+
+### "O2O (Orange-to-Orange) Assets Not Caching"
+
+**Cause:** Orange-to-Orange (proxied zone requesting another proxied zone on Cloudflare) bypasses Cache Reserve  
+**Solution:** 
+- **What is O2O**: Zone A (proxied) → Zone B (proxied), both on Cloudflare
+- **Detection**: Check `cf-cache-status` for `BYPASS` and review request path
+- **Workaround**: Use R2 or direct origin access instead of O2O proxy chains
+
+### "Cache Reserve must be OFF before clearing data"
+
+**Cause:** Attempting to clear Cache Reserve data while it's still enabled  
+**Solution:** Disable Cache Reserve first, wait briefly for propagation (5s), then clear data (can take up to 24 hours)
+
+## Limits
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Minimum TTL | 10 hours (36000 seconds) | Assets with shorter TTL not eligible |
+| Default retention | 30 days (2592000 seconds) | Configurable |
+| Maximum file size | Same as R2 limits | No practical limit |
+| Purge/clear time | Up to 24 hours | Complete propagation time |
+| Plan requirement | Paid Cache Reserve or Smart Shield | Not available on free plans |
+| Content-Length header | Required | Must be present for eligibility |
+| Set-Cookie header | Blocks caching | Must not be present (or use private directive) |
+| Vary header | Cannot be * | Can use Vary: Accept-Encoding |
+| Image transformations | Variants not eligible | Original images only |
+| Range requests | NOT supported | HTTP 206 bypasses Cache Reserve |
+| Compression | Fetches uncompressed | Serves compressed to visitors |
+| Worker control | Zone-level only | Cannot control per-request |
+| O2O requests | Bypassed | Orange-to-Orange not eligible |
+
+## Additional Resources
+
+- **Official Docs**: https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/
+- **API Reference**: https://developers.cloudflare.com/api/resources/cache/subresources/cache_reserve/
+- **Cache Rules**: https://developers.cloudflare.com/cache/how-to/cache-rules/
+- **Workers Cache API**: https://developers.cloudflare.com/workers/runtime-apis/cache/
+- **R2 Documentation**: https://developers.cloudflare.com/r2/
+- **Smart Shield**: https://developers.cloudflare.com/smart-shield/
+- **Tiered Cache**: https://developers.cloudflare.com/cache/how-to/tiered-cache/
+
+## Troubleshooting Flowchart
+
+Asset not caching in Cache Reserve?
+
+```
+1. Is Cache Reserve enabled for zone?
+   → No: Enable via Dashboard or API
+   → Yes: Continue to step 2
+
+2. Is Tiered Cache enabled?
+   → No: Enable Tiered Cache (required!)
+   → Yes: Continue to step 3
+
+3. Does asset have TTL ≥ 10 hours?
+   → No: Increase via Cache Rules (edge_ttl override)
+   → Yes: Continue to step 4
+
+4. Is Content-Length header present?
+   → No: Fix origin to include Content-Length
+   → Yes: Continue to step 5
+
+5. Is Set-Cookie header present?
+   → Yes: Remove Set-Cookie or scope appropriately
+   → No: Continue to step 6
+
+6. Is Vary header set to *?
+   → Yes: Change to specific value (e.g., Accept-Encoding)
+   → No: Continue to step 7
+
+7. Is this a range request?
+   → Yes: Range requests bypass Cache Reserve (not supported)
+   → No: Continue to step 8
+
+8. Is this an O2O (Orange-to-Orange) request?
+   → Yes: O2O bypasses Cache Reserve
+   → No: Continue to step 9
+
+9. Check Logpush CacheReserveUsed field
+   → Filter logs to see if assets ever hit Cache Reserve
+   → Verify cf-cache-status header (should be HIT after first request)
+```
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [API Reference](./api.md) - Purging and monitoring
+- [Patterns](./patterns.md) - Best practices and optimization

package/skills/cloudflare-deploy/references/cache-reserve/patterns.md

@@ -0,0 +1,197 @@
+# Cache Reserve Patterns
+
+## Best Practices
+
+### 1. Always Enable Tiered Cache
+
+```typescript
+// Cache Reserve is designed for use WITH Tiered Cache
+const configuration = {
+  tieredCache: 'enabled',    // Required for optimal performance
+  cacheReserve: 'enabled',   // Works best with Tiered Cache
+  
+  hierarchy: [
+    'Lower-Tier Cache (visitor)',
+    'Upper-Tier Cache (origin region)',
+    'Cache Reserve (persistent)',
+    'Origin'
+  ]
+};
+```
+
+### 2. Set Appropriate Cache-Control Headers
+
+```typescript
+// Origin response headers for Cache Reserve eligibility
+const originHeaders = {
+  'Cache-Control': 'public, max-age=86400', // 24hr (minimum 10hr)
+  'Content-Length': '1024000', // Required
+  'Cache-Tag': 'images,product-123', // Optional: purging
+  'ETag': '"abc123"', // Optional: revalidation
+  // Avoid: 'Set-Cookie' and 'Vary: *' prevent caching
+};
+```
+
+### 3. Use Cache Rules for Fine-Grained Control
+
+```typescript
+// Different TTLs for different content types
+const cacheRules = [
+  {
+    description: 'Long-term cache for immutable assets',
+    expression: '(http.request.uri.path matches "^/static/.*\\.[a-f0-9]{8}\\.")',
+    action_parameters: {
+      cache_reserve: { eligible: true },
+      edge_ttl: { mode: 'override_origin', default: 2592000 }, // 30 days
+      cache: true
+    }
+  },
+  {
+    description: 'Moderate cache for regular images',
+    expression: '(http.request.uri.path matches "\\.(jpg|png|webp)$")',
+    action_parameters: {
+      cache_reserve: { eligible: true },
+      edge_ttl: { mode: 'override_origin', default: 86400 }, // 24 hours
+      cache: true
+    }
+  },
+  {
+    description: 'Exclude API from Cache Reserve',
+    expression: '(http.request.uri.path matches "^/api/")',
+    action_parameters: { cache_reserve: { eligible: false }, cache: false }
+  }
+];
+```
+
+### 4. Making Assets Cache Reserve Eligible from Workers
+
+**Note**: This modifies response headers to meet eligibility criteria but does NOT directly control Cache Reserve storage (which is zone-level automatic).
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await fetch(request);
+    if (!response.ok) return response;
+    
+    const headers = new Headers(response.headers);
+    headers.set('Cache-Control', 'public, max-age=36000'); // 10hr minimum
+    headers.delete('Set-Cookie'); // Blocks caching
+    
+    // Ensure Content-Length present
+    if (!headers.has('Content-Length')) {
+      const blob = await response.blob();
+      headers.set('Content-Length', blob.size.toString());
+      return new Response(blob, { status: response.status, headers });
+    }
+    
+    return new Response(response.body, { status: response.status, headers });
+  }
+};
+```
+
+### 5. Hostname Best Practices
+
+Use Worker's hostname for efficient caching - avoid overriding hostname unnecessarily.
+
+## Architecture Patterns
+
+### Multi-Tier Caching + Immutable Assets
+
+```typescript
+// Optimal: L1 (visitor) → L2 (region) → L3 (Cache Reserve) → Origin
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const isImmutable = /\.[a-f0-9]{8,}\.(js|css|jpg|png|woff2)$/.test(url.pathname);
+    const response = await fetch(request);
+    
+    if (isImmutable) {
+      const headers = new Headers(response.headers);
+      headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+      return new Response(response.body, { status: response.status, headers });
+    }
+    return response;
+  }
+};
+```
+
+## Cost Optimization
+
+### Cost Calculator
+
+```typescript
+interface CacheReserveEstimate {
+  avgAssetSizeGB: number;
+  uniqueAssets: number;
+  monthlyReads: number;
+  monthlyWrites: number;
+  originEgressCostPerGB: number; // e.g., AWS: $0.09/GB
+}
+
+function estimateMonthlyCost(input: CacheReserveEstimate) {
+  // Cache Reserve pricing
+  const storageCostPerGBMonth = 0.015;
+  const classAPerMillion = 4.50; // writes
+  const classBPerMillion = 0.36; // reads
+  
+  // Calculate Cache Reserve costs
+  const totalStorageGB = input.avgAssetSizeGB * input.uniqueAssets;
+  const storageCost = totalStorageGB * storageCostPerGBMonth;
+  const writeCost = (input.monthlyWrites / 1_000_000) * classAPerMillion;
+  const readCost = (input.monthlyReads / 1_000_000) * classBPerMillion;
+  
+  const cacheReserveCost = storageCost + writeCost + readCost;
+  
+  // Calculate origin egress cost (what you'd pay without Cache Reserve)
+  const totalTrafficGB = (input.monthlyReads * input.avgAssetSizeGB);
+  const originEgressCost = totalTrafficGB * input.originEgressCostPerGB;
+  
+  // Savings calculation
+  const savings = originEgressCost - cacheReserveCost;
+  const savingsPercent = ((savings / originEgressCost) * 100).toFixed(1);
+  
+  return {
+    cacheReserveCost: `$${cacheReserveCost.toFixed(2)}`,
+    originEgressCost: `$${originEgressCost.toFixed(2)}`,
+    monthlySavings: `$${savings.toFixed(2)}`,
+    savingsPercent: `${savingsPercent}%`,
+    breakdown: {
+      storage: `$${storageCost.toFixed(2)}`,
+      writes: `$${writeCost.toFixed(2)}`,
+      reads: `$${readCost.toFixed(2)}`,
+    }
+  };
+}
+
+// Example: Media library
+const mediaLibrary = estimateMonthlyCost({
+  avgAssetSizeGB: 0.005, // 5MB images
+  uniqueAssets: 10_000,
+  monthlyReads: 5_000_000,
+  monthlyWrites: 50_000,
+  originEgressCostPerGB: 0.09, // AWS S3
+});
+
+console.log(mediaLibrary);
+// {
+//   cacheReserveCost: "$9.98",
+//   originEgressCost: "$25.00",
+//   monthlySavings: "$15.02",
+//   savingsPercent: "60.1%",
+//   breakdown: { storage: "$0.75", writes: "$0.23", reads: "$9.00" }
+// }
+```
+
+### Optimization Guidelines
+
+- **Set appropriate TTLs**: 10hr minimum, 24hr+ optimal for stable content, 30d max cautiously
+- **Cache high-value stable assets**: Images, media, fonts, archives, documentation
+- **Exclude frequently changing**: APIs, user-specific content, real-time data
+- **Compression note**: Cache Reserve fetches uncompressed from origin, serves compressed to visitors - factor in origin egress costs
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [API Reference](./api.md) - Purging and monitoring
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting

package/skills/cloudflare-deploy/references/containers/README.md

@@ -0,0 +1,85 @@
+# Cloudflare Containers Skill Reference
+
+**APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers**
+
+Use when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patterns.
+
+## Beta Status
+
+⚠️ Containers is currently in **beta**. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.
+
+## Core Concepts
+
+**Container as Durable Object:** Each container is a Durable Object with persistent identity. Accessed via `getByName(id)` or `getRandom()`.
+
+**Image deployment:** Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).
+
+**Lifecycle:** cold start (2-3s) → running → `sleepAfter` timeout → stopped. No autoscaling - manual load balancing via `getRandom()`.
+
+**Persistent identity, ephemeral disk:** Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.
+
+## Quick Start
+
+```typescript
+import { Container } from "@cloudflare/containers";
+
+export class MyContainer extends Container {
+  defaultPort = 8080;
+  sleepAfter = "30m";
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.MY_CONTAINER.getByName("instance-1");
+    await container.startAndWaitForPorts();
+    return container.fetch(request);
+  }
+};
+```
+
+## Reading Order
+
+| Task | Files |
+|------|-------|
+| Setup new container project | README → configuration.md |
+| Implement container logic | README → api.md → patterns.md |
+| Choose routing pattern | patterns.md (routing section) |
+| Debug issues | gotchas.md |
+| Production hardening | gotchas.md → patterns.md (lifecycle) |
+
+## Routing Decision Tree
+
+**How should requests reach containers?**
+
+- **Same user/session → same container:** Use `getByName(sessionId)` for session affinity
+- **Stateless, spread load:** Use `getRandom()` for load balancing
+- **Job per container:** Use `getByName(jobId)` + explicit lifecycle management
+- **Single global instance:** Use `getByName("singleton")`
+
+## When to Use Containers vs Workers
+
+**Use Containers when:**
+- Need stateful, long-lived processes (sessions, WebSockets, games)
+- Running existing containerized apps (Node.js, Python, custom binaries)
+- Need filesystem access or specific system dependencies
+- Per-user/session isolation with dedicated compute
+
+**Use Workers when:**
+- Stateless HTTP handlers
+- Sub-millisecond cold starts required
+- Auto-scaling to zero critical
+- Simple request/response patterns
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Wrangler config, instance types, Container class properties, environment variables, account limits
+- **[api.md](api.md)** - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection
+- **[patterns.md](patterns.md)** - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration
+- **[gotchas.md](gotchas.md)** - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats
+
+## See Also
+
+- [Durable Objects](../durable-objects/) - Containers extend Durable Objects
+- [Workflows](../workflows/) - Orchestrate container operations
+- [Queues](../queues/) - Trigger containers from queue messages
+- [Cloudflare Docs](https://developers.cloudflare.com/containers/)