memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,206 @@
+## 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/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/references/static-assets/api.md

@@ -0,0 +1,201 @@
+# 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.

package/skills/cloudflare/references/static-assets/configuration.md

@@ -0,0 +1,186 @@
+## Configuration
+
+### Basic Setup
+
+Minimal configuration requires only `assets.directory`:
+
+```jsonc
+{
+  "name": "my-worker",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  "assets": {
+    "directory": "./dist",
+  },
+}
+```
+
+### Full Configuration Options
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "not_found_handling": "single-page-application",
+    "html_handling": "auto-trailing-slash",
+    "run_worker_first": ["/api/*", "!/api/docs/*"],
+  },
+}
+```
+
+**Configuration keys:**
+
+- `directory` (string, required): Path to assets folder (e.g. `./dist`, `./public`, `./build`)
+- `binding` (string, optional): Name to access assets in Worker code (e.g. `env.ASSETS`). Default: `"ASSETS"`
+- `not_found_handling` (string, optional): Behavior when asset not found
+  - `"single-page-application"`: Serve `/index.html` for non-asset paths (default for SPAs)
+  - `"404-page"`: Serve `/404.html` if present, otherwise 404
+  - `"none"`: Return 404 for missing assets
+- `html_handling` (string, optional): URL trailing slash behavior
+- `run_worker_first` (boolean | string[], optional): Routes that invoke Worker before checking assets
+
+### not_found_handling Modes
+
+| Mode                        | Behavior                                   | Use Case                            |
+| --------------------------- | ------------------------------------------ | ----------------------------------- |
+| `"single-page-application"` | Serve `/index.html` for non-asset requests | React, Vue, Angular SPAs            |
+| `"404-page"`                | Serve `/404.html` if exists, else 404      | Static sites with custom error page |
+| `"none"`                    | Return 404 for missing assets              | API-first or custom routing         |
+
+### html_handling Modes
+
+Controls trailing slash behavior for HTML files:
+
+| Mode                     | `/page`                                           | `/page/`                 | Use Case                    |
+| ------------------------ | ------------------------------------------------- | ------------------------ | --------------------------- |
+| `"auto-trailing-slash"`  | Redirect to `/page/` if `/page/index.html` exists | Serve `/page/index.html` | Default, SEO-friendly       |
+| `"force-trailing-slash"` | Always redirect to `/page/`                       | Serve if exists          | Consistent trailing slashes |
+| `"drop-trailing-slash"`  | Serve if exists                                   | Redirect to `/page`      | Cleaner URLs                |
+| `"none"`                 | No modification                                   | No modification          | Custom routing logic        |
+
+**Default:** `"auto-trailing-slash"`
+
+### run_worker_first Configuration
+
+Controls which requests invoke Worker before checking assets.
+
+**Boolean syntax:**
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": true, // ALL requests invoke Worker
+  },
+}
+```
+
+**Array syntax (recommended):**
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": [
+      "/api/*", // Positive pattern: match API routes
+      "/admin/*", // Match admin routes
+      "!/admin/assets/*", // Negative pattern: exclude admin assets
+    ],
+  },
+}
+```
+
+**Pattern rules:**
+
+- Glob patterns: `*` (any chars), `**` (any path segments)
+- Negative patterns: Prefix with `!` to exclude
+- Precedence: Negative patterns override positive patterns
+- Default: `false` (assets served directly)
+
+**Decision guidance:**
+
+- Use `true` for API-first apps (few static assets)
+- Use array patterns for hybrid apps (APIs + static assets)
+- Use `false` for static-first sites (minimal dynamic routes)
+
+### .assetsignore File
+
+Exclude files from upload using `.assetsignore` (same syntax as `.gitignore`):
+
+```
+# .assetsignore
+_worker.js
+*.map
+*.md
+node_modules/
+.git/
+```
+
+**Common patterns:**
+
+- `_worker.js` - Exclude Worker code from assets
+- `*.map` - Exclude source maps
+- `*.md` - Exclude markdown files
+- Development artifacts
+
+### Vite Plugin Integration
+
+For Vite-based projects, use `@cloudflare/vite-plugin`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    cloudflare({
+      assets: {
+        directory: './dist',
+        binding: 'ASSETS',
+      },
+    }),
+  ],
+})
+```
+
+**Features:**
+
+- Automatic asset detection during dev
+- Hot module replacement for assets
+- Production build integration
+- Requires: Wrangler 4.0.0+, `@cloudflare/vite-plugin` 1.0.0+
+
+### Key Compatibility Dates
+
+| Date         | Feature                         | Impact                                          |
+| ------------ | ------------------------------- | ----------------------------------------------- |
+| `2025-04-01` | Navigation request optimization | SPAs skip Worker for navigation, reducing costs |
+
+Use current date for new projects. See [Compatibility Dates](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) for full list.
+
+### Environment-Specific Configuration
+
+Use `wrangler.jsonc` environments for different configs:
+
+```jsonc
+{
+  "name": "my-worker",
+  "assets": { "directory": "./dist" },
+  "env": {
+    "staging": {
+      "assets": {
+        "not_found_handling": "404-page",
+      },
+    },
+    "production": {
+      "assets": {
+        "not_found_handling": "single-page-application",
+      },
+    },
+  },
+}
+```
+
+Deploy with: `wrangler deploy --env staging`