@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/spectrum/gotchas.md

@@ -0,0 +1,145 @@
+## Common Issues
+
+### Connection Timeouts
+
+**Problem:** Connections fail or timeout  
+**Cause:** Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS  
+**Solution:**
+1. Verify origin firewall allows Cloudflare IP ranges
+2. Check origin service running on correct port
+3. Ensure DNS record is CNAME (not A/AAAA)
+4. Verify origin IP/hostname is correct
+
+```bash
+# Test connectivity
+nc -zv app.example.com 22
+dig app.example.com
+```
+
+### Client IP Showing Cloudflare IP
+
+**Problem:** Origin logs show Cloudflare IPs not real client IPs  
+**Cause:** Proxy Protocol not enabled or origin not configured  
+**Solution:**
+```typescript
+// Enable in Spectrum app
+const app = await client.spectrum.apps.create({
+  // ...
+  proxy_protocol: 'v1',  // TCP: v1/v2; UDP: simple
+});
+```
+
+**Origin config:**
+- **nginx**: `listen 22 proxy_protocol;`
+- **HAProxy**: `bind :22 accept-proxy`
+
+### TLS Errors
+
+**Problem:** TLS handshake failures, 525 errors  
+**Cause:** TLS mode mismatch
+
+| Error | TLS Mode | Problem | Solution |
+|-------|----------|---------|----------|
+| Connection refused | `full`/`strict` | Origin not TLS | Use `tls: "off"` or enable TLS |
+| 525 cert invalid | `strict` | Self-signed cert | Use `tls: "full"` or valid cert |
+| Handshake timeout | `flexible` | Origin expects TLS | Use `tls: "full"` |
+
+**Debug:**
+```bash
+openssl s_client -connect app.example.com:443 -showcerts
+```
+
+### SMTP Reverse DNS
+
+**Problem:** Email servers reject SMTP via Spectrum  
+**Cause:** Spectrum IPs lack PTR (reverse DNS) records  
+**Impact:** Many mail servers require valid rDNS for anti-spam
+
+**Solution:**
+- Outbound SMTP: NOT recommended through Spectrum
+- Inbound SMTP: Use Cloudflare Email Routing
+- Internal relay: Whitelist Spectrum IPs on destination
+
+### Proxy Protocol Compatibility
+
+**Problem:** Connection works but app behaves incorrectly  
+**Cause:** Origin doesn't support Proxy Protocol
+
+**Solution:**
+1. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+)
+2. Test with `proxy_protocol: 'off'` first
+3. Configure origin to parse headers
+
+**nginx TCP:**
+```nginx
+stream {
+    server {
+        listen 22 proxy_protocol;
+        proxy_pass backend:22;
+    }
+}
+```
+
+**HAProxy:**
+```
+frontend ft_ssh
+    bind :22 accept-proxy
+```
+
+### Analytics Data Retention
+
+**Problem:** Historical data not available  
+**Cause:** Retention varies by plan
+
+| Plan | Real-time | Historical |
+|------|-----------|------------|
+| Pro | Last hour | ❌ |
+| Business | Last hour | Limited |
+| Enterprise | Last hour | 90+ days |
+
+**Solution:** Query within retention window or export to external system
+
+### Enterprise-Only Features
+
+**Problem:** Feature unavailable/errors  
+**Cause:** Requires Enterprise plan
+
+**Enterprise-only:**
+- Port ranges (`tcp/25565-25575`)
+- All TCP/UDP ports (Pro/Business: selected only)
+- Extended analytics retention
+- Advanced load balancing
+
+### IPv6 Considerations
+
+**Problem:** IPv6 clients can't connect or origin doesn't support IPv6  
+**Solution:** Configure `edge_ips.connectivity`
+
+```typescript
+const app = await client.spectrum.apps.create({
+  // ...
+  edge_ips: {
+    type: 'dynamic',
+    connectivity: 'ipv4',  // Options: 'all', 'ipv4', 'ipv6'
+  },
+});
+```
+
+**Options:**
+- `all`: Dual-stack (default, requires origin support both)
+- `ipv4`: IPv4 only (use if origin lacks IPv6)
+- `ipv6`: IPv6 only (rare)
+
+## Limits
+
+| Resource | Pro/Business | Enterprise |
+|----------|--------------|------------|
+| Max apps | ~10-15 | 100+ |
+| Protocols | Selected | All TCP/UDP |
+| Port ranges | ❌ | ✅ |
+| Analytics | ~1 hour | 90+ days |
+
+## See Also
+
+- [patterns.md](patterns.md) - Protocol examples
+- [configuration.md](configuration.md) - TLS/Proxy setup

package/skills/cloudflare-deploy/references/spectrum/patterns.md

@@ -0,0 +1,196 @@
+## Common Use Cases
+
+### 1. SSH Server Protection
+
+**Terraform:**
+```hcl
+resource "cloudflare_spectrum_application" "ssh" {
+  zone_id  = var.zone_id
+  protocol = "tcp/22"
+
+  dns {
+    type = "CNAME"
+    name = "ssh.example.com"
+  }
+
+  origin_direct      = ["tcp://10.0.1.5:22"]
+  ip_firewall        = true
+  argo_smart_routing = true
+}
+```
+
+**Benefits:** Hide origin IP, DDoS protection, IP firewall, Argo reduces latency
+
+### 2. Game Server
+
+**TypeScript (Minecraft):**
+```typescript
+const app = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/25565',
+  dns: { type: 'CNAME', name: 'mc.example.com' },
+  origin_direct: ['tcp://192.168.1.10:25565'],
+  proxy_protocol: 'v1',  // Preserves player IPs
+  argo_smart_routing: true,
+});
+```
+
+**Benefits:** DDoS protection, hide origin IP, Proxy Protocol for player IPs/bans, Argo reduces latency
+
+### 3. MQTT Broker
+
+IoT device communication.
+
+**TypeScript:**
+```typescript
+const mqttApp = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/8883',  // Use 1883 for plain MQTT
+  dns: { type: 'CNAME', name: 'mqtt.example.com' },
+  origin_direct: ['tcp://mqtt-broker.internal:8883'],
+  tls: 'full',  // Use 'off' for plain MQTT
+});
+```
+
+**Benefits:** DDoS protection, hide broker IP, TLS termination at edge
+
+### 4. SMTP Relay
+
+Email submission (port 587). **WARNING**: See [gotchas.md](gotchas.md#smtp-reverse-dns)
+
+**Terraform:**
+```hcl
+resource "cloudflare_spectrum_application" "smtp" {
+  zone_id  = var.zone_id
+  protocol = "tcp/587"
+
+  dns {
+    type = "CNAME"
+    name = "smtp.example.com"
+  }
+
+  origin_direct = ["tcp://mail-server.internal:587"]
+  tls           = "full"  # STARTTLS support
+}
+```
+
+**Limitations:**
+- Spectrum IPs lack reverse DNS (PTR records)
+- Many mail servers reject without valid rDNS
+- Best for internal/trusted relay only
+
+### 5. Database Proxy
+
+MySQL/PostgreSQL. **Use with caution** - security critical.
+
+**PostgreSQL:**
+```typescript
+const postgresApp = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/5432',
+  dns: { type: 'CNAME', name: 'postgres.example.com' },
+  origin_dns: { name: 'db-primary.internal.example.com' },
+  origin_port: 5432,
+  tls: 'strict',      // REQUIRED
+  ip_firewall: true,  // REQUIRED
+});
+```
+
+**MySQL:**
+```hcl
+resource "cloudflare_spectrum_application" "mysql" {
+  zone_id  = var.zone_id
+  protocol = "tcp/3306"
+
+  dns {
+    type = "CNAME"
+    name = "mysql.example.com"
+  }
+
+  origin_dns {
+    name = "mysql-primary.internal.example.com"
+  }
+
+  origin_port = 3306
+  tls         = "strict"
+  ip_firewall = true
+}
+```
+
+**Security:**
+- ALWAYS use `tls: "strict"`
+- ALWAYS use `ip_firewall: true`
+- Restrict to known IPs via zone firewall
+- Use strong DB authentication
+- Consider VPN or Cloudflare Access instead
+
+### 6. RDP (Remote Desktop)
+
+**Requires IP firewall.**
+
+**Terraform:**
+```hcl
+resource "cloudflare_spectrum_application" "rdp" {
+  zone_id  = var.zone_id
+  protocol = "tcp/3389"
+
+  dns {
+    type = "CNAME"
+    name = "rdp.example.com"
+  }
+
+  origin_direct = ["tcp://windows-server.internal:3389"]
+  tls           = "off"       # RDP has own encryption
+  ip_firewall   = true        # REQUIRED
+}
+```
+
+**Security:** ALWAYS `ip_firewall: true`, whitelist admin IPs, RDP is DDoS/brute-force target
+
+### 7. Multi-Origin Failover
+
+High availability with load balancer.
+
+**Terraform:**
+```hcl
+resource "cloudflare_load_balancer" "database_lb" {
+  zone_id          = var.zone_id
+  name             = "db-lb.example.com"
+  default_pool_ids = [cloudflare_load_balancer_pool.db_primary.id]
+  fallback_pool_id = cloudflare_load_balancer_pool.db_secondary.id
+}
+
+resource "cloudflare_load_balancer_pool" "db_primary" {
+  name    = "db-primary-pool"
+  origins { name = "db-1"; address = "192.0.2.1" }
+  monitor = cloudflare_load_balancer_monitor.postgres_monitor.id
+}
+
+resource "cloudflare_load_balancer_pool" "db_secondary" {
+  name    = "db-secondary-pool"
+  origins { name = "db-2"; address = "192.0.2.2" }
+  monitor = cloudflare_load_balancer_monitor.postgres_monitor.id
+}
+
+resource "cloudflare_load_balancer_monitor" "postgres_monitor" {
+  type = "tcp"; port = 5432; interval = 30; timeout = 5
+}
+
+resource "cloudflare_spectrum_application" "postgres_ha" {
+  zone_id     = var.zone_id
+  protocol    = "tcp/5432"
+  dns         { type = "CNAME"; name = "postgres.example.com" }
+  origin_dns  { name = cloudflare_load_balancer.database_lb.name }
+  origin_port = 5432
+  tls         = "strict"
+  ip_firewall = true
+}
+```
+
+**Benefits:** Automatic failover, health monitoring, traffic distribution, zero-downtime deployments
+
+## See Also
+
+- [configuration.md](configuration.md) - Origin type setup
+- [gotchas.md](gotchas.md) - Protocol limitations
+- [api.md](api.md) - SDK reference

package/skills/cloudflare-deploy/references/static-assets/README.md

@@ -0,0 +1,65 @@
+# Cloudflare Static Assets Skill Reference
+
+Expert guidance for deploying and configuring static assets with Cloudflare Workers. This skill covers configuration patterns, routing architectures, asset binding usage, and best practices for SPAs, SSG sites, and full-stack applications.
+
+## Quick Start
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "assets": {
+    "directory": "./dist"
+  }
+}
+```
+
+```typescript
+// src/index.ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+Deploy: `wrangler deploy`
+
+## When to Use Workers Static Assets vs Pages
+
+| Factor | Workers Static Assets | Cloudflare Pages |
+|--------|----------------------|------------------|
+| **Use case** | Hybrid apps (static + dynamic API) | Static sites, SSG |
+| **Worker control** | Full control over routing | Limited (Functions) |
+| **Configuration** | Code-first, flexible | Git-based, opinionated |
+| **Dynamic routing** | Worker-first patterns | Functions (_functions/) |
+| **Best for** | Full-stack apps, SPAs with APIs | Jamstack, static docs |
+
+**Decision tree:**
+
+- Need custom routing logic? → Workers Static Assets
+- Pure static site or SSG? → Pages
+- API routes + SPA? → Workers Static Assets
+- Framework (Next, Nuxt, Remix)? → Pages
+
+## Reading Order
+
+1. **configuration.md** - Setup, wrangler.jsonc options, routing patterns
+2. **api.md** - ASSETS binding API, request/response handling
+3. **patterns.md** - Common patterns (SPA, API routes, auth, A/B testing)
+4. **gotchas.md** - Limits, errors, performance tips
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, deployment, configuration
+- **[api.md](api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Static Assets Docs](https://developers.cloudflare.com/workers/static-assets/)
+- [Cloudflare Pages](https://developers.cloudflare.com/pages/)

package/skills/cloudflare-deploy/references/static-assets/api.md

@@ -0,0 +1,199 @@
+# API Reference
+
+## ASSETS Binding
+
+The `ASSETS` binding provides access to static assets via the `Fetcher` interface.
+
+### Type Definition
+
+```typescript
+interface Env {
+  ASSETS: Fetcher;
+}
+
+interface Fetcher {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+```
+
+### Method Signatures
+
+```typescript
+// 1. Forward entire request
+await env.ASSETS.fetch(request);
+
+// 2. String path (hostname ignored, only path matters)
+await env.ASSETS.fetch("https://any-host/path/to/asset.png");
+
+// 3. URL object
+await env.ASSETS.fetch(new URL("/index.html", request.url));
+
+// 4. Constructed Request object
+await env.ASSETS.fetch(new Request(new URL("/logo.png", request.url), {
+  method: "GET",
+  headers: request.headers
+}));
+```
+
+**Key behaviors:**
+
+- Host/origin is ignored for string/URL inputs (only path is used)
+- Method must be GET (others return 405)
+- Request headers pass through (affects response)
+- Returns standard `Response` object
+
+## Request Handling
+
+### Path Resolution
+
+```typescript
+// All resolve to same asset:
+env.ASSETS.fetch("https://example.com/logo.png")
+env.ASSETS.fetch("https://ignored.host/logo.png")
+env.ASSETS.fetch("/logo.png")
+```
+
+Assets are resolved relative to configured `assets.directory`.
+
+### Headers
+
+Request headers that affect response:
+
+| Header | Effect |
+|--------|--------|
+| `Accept-Encoding` | Controls compression (gzip, brotli) |
+| `Range` | Enables partial content (206 responses) |
+| `If-None-Match` | Conditional request via ETag |
+| `If-Modified-Since` | Conditional request via modification date |
+
+Custom headers pass through but don't affect asset serving.
+
+### Method Support
+
+| Method | Supported | Response |
+|--------|-----------|----------|
+| `GET` | ✅ Yes | Asset content |
+| `HEAD` | ✅ Yes | Headers only, no body |
+| `POST`, `PUT`, etc. | ❌ No | 405 Method Not Allowed |
+
+## Response Behavior
+
+### Content-Type Inference
+
+Automatically set based on file extension:
+
+| Extension | Content-Type |
+|-----------|--------------|
+| `.html` | `text/html; charset=utf-8` |
+| `.css` | `text/css` |
+| `.js` | `application/javascript` |
+| `.json` | `application/json` |
+| `.png` | `image/png` |
+| `.jpg`, `.jpeg` | `image/jpeg` |
+| `.svg` | `image/svg+xml` |
+| `.woff2` | `font/woff2` |
+
+### Default Headers
+
+Responses include:
+
+```
+Content-Type: <inferred>
+ETag: "<hash>"
+Cache-Control: public, max-age=3600
+Content-Encoding: br  (if supported and beneficial)
+```
+
+**Cache-Control defaults:**
+
+- 1 hour (`max-age=3600`) for most assets
+- Override via Worker response transformation (see patterns.md:27-35)
+
+### Compression
+
+Automatic compression based on `Accept-Encoding`:
+
+- **Brotli** (`br`): Preferred, best compression
+- **Gzip** (`gzip`): Fallback
+- **None**: If client doesn't support or asset too small
+
+### ETag Generation
+
+ETags are content-based hashes:
+
+```
+ETag: "a3b2c1d4e5f6..."
+```
+
+Used for conditional requests (`If-None-Match`). Returns `304 Not Modified` if match.
+
+## Error Responses
+
+| Status | Condition | Behavior |
+|--------|-----------|----------|
+| `404` | Asset not found | Body depends on `not_found_handling` config |
+| `405` | Non-GET/HEAD method | `{ "error": "Method not allowed" }` |
+| `416` | Invalid Range header | Range not satisfiable |
+
+### 404 Handling
+
+Depends on configuration (see configuration.md:45-52):
+
+```typescript
+// not_found_handling: "single-page-application"
+// Returns /index.html with 200 status
+
+// not_found_handling: "404-page"
+// Returns /404.html if exists, else 404 response
+
+// not_found_handling: "none"
+// Returns 404 response
+```
+
+## Advanced Usage
+
+### Modifying Responses
+
+```typescript
+const response = await env.ASSETS.fetch(request);
+
+// Clone and modify
+return new Response(response.body, {
+  status: response.status,
+  headers: {
+    ...Object.fromEntries(response.headers),
+    'Cache-Control': 'public, max-age=31536000',
+    'X-Custom': 'value'
+  }
+});
+```
+
+See patterns.md:27-35 for full example.
+
+### Error Handling
+
+```typescript
+const response = await env.ASSETS.fetch(request);
+
+if (!response.ok) {
+  // Asset not found or error
+  return new Response('Custom error page', { status: 404 });
+}
+
+return response;
+```
+
+### Conditional Serving
+
+```typescript
+const url = new URL(request.url);
+
+// Serve different assets based on conditions
+if (url.pathname === '/') {
+  return env.ASSETS.fetch('/index.html');
+}
+
+return env.ASSETS.fetch(request);
+```
+
+See patterns.md for complete patterns.