memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/tail-workers/patterns.md

@@ -0,0 +1,190 @@
+# Tail Workers Common Patterns
+
+## Community Libraries
+
+While most tail Worker implementations are custom, these libraries may help:
+
+**Logging/Observability:**
+
+- **Axiom** - `axiom-cloudflare-workers` (npm) - Direct Axiom integration
+- **Baselime** - SDK for Baselime observability platform
+- **LogFlare** - Structured log aggregation
+
+**Type Definitions:**
+
+- **@cloudflare/workers-types** - Official TypeScript types (use `TraceItem`)
+
+**Note:** Most integrations require custom tail handler implementation. See integration examples below.
+
+## Basic Patterns
+
+### HTTP Endpoint Logging
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const payload = events.map((event) => ({
+      script: event.scriptName,
+      timestamp: event.eventTimestamp,
+      outcome: event.outcome,
+      url: event.event?.request?.url,
+      status: event.event?.response?.status,
+      logs: event.logs,
+      exceptions: event.exceptions,
+    }))
+
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+      })
+    )
+  },
+}
+```
+
+### Error Tracking Only
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const errors = events.filter((e) => e.outcome === 'exception' || e.exceptions.length > 0)
+
+    if (errors.length === 0) return
+
+    ctx.waitUntil(
+      fetch(env.ERROR_ENDPOINT, {
+        method: 'POST',
+        body: JSON.stringify(errors),
+      })
+    )
+  },
+}
+```
+
+## Storage Integration
+
+### KV Storage with TTL
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    ctx.waitUntil(
+      Promise.all(
+        events.map((event) =>
+          env.LOGS_KV.put(
+            `log:${event.scriptName}:${event.eventTimestamp}`,
+            JSON.stringify(event),
+            { expirationTtl: 86400 } // 24 hours
+          )
+        )
+      )
+    )
+  },
+}
+```
+
+### Analytics Engine Metrics
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    ctx.waitUntil(
+      Promise.all(
+        events.map((event) =>
+          env.ANALYTICS.writeDataPoint({
+            blobs: [event.scriptName, event.outcome],
+            doubles: [1, event.event?.response?.status ?? 0],
+            indexes: [event.event?.request?.cf?.colo ?? 'unknown'],
+          })
+        )
+      )
+    )
+  },
+}
+```
+
+## Filtering & Routing
+
+Filter by route, outcome, or other criteria:
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    // Route filtering
+    const apiEvents = events.filter((e) => e.event?.request?.url?.includes('/api/'))
+
+    // Multi-destination routing
+    const errors = events.filter((e) => e.outcome === 'exception')
+    const success = events.filter((e) => e.outcome === 'ok')
+
+    const tasks = []
+    if (errors.length > 0) {
+      tasks.push(
+        fetch(env.ERROR_ENDPOINT, {
+          method: 'POST',
+          body: JSON.stringify(errors),
+        })
+      )
+    }
+    if (success.length > 0) {
+      tasks.push(
+        fetch(env.SUCCESS_ENDPOINT, {
+          method: 'POST',
+          body: JSON.stringify(success),
+        })
+      )
+    }
+
+    ctx.waitUntil(Promise.all(tasks))
+  },
+}
+```
+
+## Sampling
+
+Reduce costs by processing only a percentage of events:
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    if (Math.random() > 0.1) return // 10% sample rate
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: 'POST',
+        body: JSON.stringify(events),
+      })
+    )
+  },
+}
+```
+
+## Advanced Patterns
+
+### Batching with Durable Objects
+
+Accumulate events before sending:
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const batch = env.BATCH_DO.get(env.BATCH_DO.idFromName('batch'))
+    ctx.waitUntil(
+      batch.fetch('https://batch/add', {
+        method: 'POST',
+        body: JSON.stringify(events),
+      })
+    )
+  },
+}
+```
+
+See durable-objects skill for full implementation.
+
+### Workers for Platforms
+
+Dynamic dispatch sends TWO events per request. Filter by `scriptName` to distinguish dispatch vs user Worker events.
+
+### Error Handling
+
+Always wrap external calls. See gotchas.md for fallback storage pattern.

package/skills/cloudflare/references/terraform/README.md

@@ -0,0 +1,100 @@
+# Cloudflare Terraform Provider
+
+**Expert guidance for Cloudflare Terraform Provider - infrastructure as code for Cloudflare resources.**
+
+## Core Principles
+
+- **Provider-first**: Use Terraform provider for ALL infrastructure - never mix with wrangler.jsonc for the same resources
+- **State management**: Always use remote state (S3, Terraform Cloud, etc.) for team environments
+- **Modular architecture**: Create reusable modules for common patterns (zones, workers, pages)
+- **Version pinning**: Always pin provider version with `~>` for predictable upgrades
+- **Secret management**: Use variables + environment vars for sensitive data - never hardcode API tokens
+
+## Provider Version
+
+| Version | Status  | Notes                                                 |
+| ------- | ------- | ----------------------------------------------------- |
+| 5.x     | Current | Auto-generated from OpenAPI, breaking changes from v4 |
+| 4.x     | Legacy  | Manual maintenance, deprecated                        |
+
+**Critical:** v5 renamed many resources (`cloudflare_record` → `cloudflare_dns_record`, `cloudflare_worker_*` → `cloudflare_workers_*`). See [gotchas.md](./gotchas.md#v5-breaking-changes) for migration details.
+
+## Provider Setup
+
+### Basic Configuration
+
+```hcl
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 5.15.0"
+    }
+  }
+}
+
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token  # or CLOUDFLARE_API_TOKEN env var
+}
+```
+
+### Authentication Methods (priority order)
+
+1. **API Token** (RECOMMENDED): `api_token` or `CLOUDFLARE_API_TOKEN`
+   - Create: Dashboard → My Profile → API Tokens
+   - Scope to specific accounts/zones for security
+2. **Global API Key** (LEGACY): `api_key` + `api_email` or `CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`
+   - Less secure, use tokens instead
+3. **User Service Key**: `user_service_key` for Origin CA certificates
+
+## Quick Reference: Common Commands
+
+```bash
+terraform init          # Initialize provider
+terraform plan          # Plan changes
+terraform apply         # Apply changes
+terraform destroy       # Destroy resources
+terraform import cloudflare_zone.example <zone-id>  # Import existing
+terraform state list    # List resources in state
+terraform output        # Show outputs
+terraform fmt -recursive  # Format code
+terraform validate      # Validate configuration
+```
+
+## Import Existing Resources
+
+Use cf-terraforming to generate configs from existing Cloudflare resources:
+
+```bash
+# Install
+brew install cloudflare/cloudflare/cf-terraforming
+
+# Generate HCL from existing resources
+cf-terraforming generate --resource-type cloudflare_dns_record --zone <zone-id>
+
+# Import into Terraform state
+cf-terraforming import --resource-type cloudflare_dns_record --zone <zone-id>
+```
+
+## Reading Order
+
+1. Start with [README.md](./README.md) for provider setup and authentication
+2. Review [configuration.md](./configuration.md) for resource configurations
+3. Check [api.md](./api.md) for data sources and existing resource queries
+4. See [patterns.md](./patterns.md) for multi-environment and CI/CD patterns
+5. Read [gotchas.md](./gotchas.md) for state drift, v5 breaking changes, and troubleshooting
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Resources for zones, DNS, workers, KV, R2, D1, Pages, rulesets
+- [api.md](./api.md) - Data sources for existing resources
+- [patterns.md](./patterns.md) - Architecture patterns, multi-env setup, CI/CD integration
+- [gotchas.md](./gotchas.md) - Common issues, security, best practices
+
+## See Also
+
+- [pulumi](../pulumi/) - Alternative IaC tool for Cloudflare
+- [wrangler](../wrangler/) - CLI deployment alternative
+- [workers](../workers/) - Worker runtime documentation

package/skills/cloudflare/references/terraform/api.md

@@ -0,0 +1,178 @@
+# Terraform Data Sources Reference
+
+Query existing Cloudflare resources to reference in your configurations.
+
+## v5 Data Source Names
+
+| v4 Name                    | v5 Name                     | Notes               |
+| -------------------------- | --------------------------- | ------------------- |
+| `cloudflare_record`        | `cloudflare_dns_record`     |                     |
+| `cloudflare_worker_script` | `cloudflare_workers_script` | Note: plural        |
+| `cloudflare_access_*`      | `cloudflare_zero_trust_*`   | Access → Zero Trust |
+
+## Zone Data Sources
+
+```hcl
+# Get zone by name
+data "cloudflare_zone" "example" {
+  name = "example.com"
+}
+
+# Use in resources
+resource "cloudflare_dns_record" "www" {
+  zone_id = data.cloudflare_zone.example.id
+  name = "www"
+  # ...
+}
+```
+
+## Account Data Sources
+
+```hcl
+# List all accounts
+data "cloudflare_accounts" "main" {
+  name = "My Account"
+}
+
+# Use account ID
+resource "cloudflare_worker_script" "api" {
+  account_id = data.cloudflare_accounts.main.accounts[0].id
+  # ...
+}
+```
+
+## Worker Data Sources
+
+```hcl
+# Get existing worker script (v5: cloudflare_workers_script)
+data "cloudflare_workers_script" "existing" {
+  account_id = var.account_id
+  name = "existing-worker"
+}
+
+# Reference in service bindings
+resource "cloudflare_workers_script" "consumer" {
+  service_binding {
+    name = "UPSTREAM"
+    service = data.cloudflare_workers_script.existing.name
+  }
+}
+```
+
+## KV Data Sources
+
+```hcl
+# Get KV namespace
+data "cloudflare_workers_kv_namespace" "existing" {
+  account_id = var.account_id
+  namespace_id = "abc123"
+}
+
+# Use in worker binding
+resource "cloudflare_workers_script" "api" {
+  kv_namespace_binding {
+    name = "KV"
+    namespace_id = data.cloudflare_workers_kv_namespace.existing.id
+  }
+}
+```
+
+## Lists Data Source
+
+```hcl
+# Get IP lists for WAF rules
+data "cloudflare_list" "blocked_ips" {
+  account_id = var.account_id
+  name = "blocked_ips"
+}
+```
+
+## IP Ranges Data Source
+
+```hcl
+# Get Cloudflare IP ranges (for firewall rules)
+data "cloudflare_ip_ranges" "cloudflare" {}
+
+output "ipv4_cidrs" {
+  value = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks
+}
+
+output "ipv6_cidrs" {
+  value = data.cloudflare_ip_ranges.cloudflare.ipv6_cidr_blocks
+}
+
+# Use in security group rules (AWS example)
+resource "aws_security_group_rule" "allow_cloudflare" {
+  type = "ingress"
+  from_port = 443
+  to_port = 443
+  protocol = "tcp"
+  cidr_blocks = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks
+  security_group_id = aws_security_group.web.id
+}
+```
+
+## Common Patterns
+
+### Import ID Formats
+
+| Resource                          | Import ID Format              |
+| --------------------------------- | ----------------------------- |
+| `cloudflare_zone`                 | `<zone-id>`                   |
+| `cloudflare_dns_record`           | `<zone-id>/<record-id>`       |
+| `cloudflare_workers_script`       | `<account-id>/<script-name>`  |
+| `cloudflare_workers_kv_namespace` | `<account-id>/<namespace-id>` |
+| `cloudflare_r2_bucket`            | `<account-id>/<bucket-name>`  |
+| `cloudflare_d1_database`          | `<account-id>/<database-id>`  |
+| `cloudflare_pages_project`        | `<account-id>/<project-name>` |
+
+```bash
+# Example: Import DNS record
+terraform import cloudflare_dns_record.example <zone-id>/<record-id>
+```
+
+### Reference Across Modules
+
+```hcl
+# modules/worker/main.tf
+data "cloudflare_zone" "main" {
+  name = var.domain
+}
+
+resource "cloudflare_worker_route" "api" {
+  zone_id = data.cloudflare_zone.main.id
+  pattern = "api.${var.domain}/*"
+  script_name = cloudflare_worker_script.api.name
+}
+```
+
+### Output Important Values
+
+```hcl
+output "zone_id" {
+  value = cloudflare_zone.main.id
+  description = "Zone ID for DNS management"
+}
+
+output "worker_url" {
+  value = "https://${cloudflare_worker_domain.api.hostname}"
+  description = "Worker API endpoint"
+}
+
+output "kv_namespace_id" {
+  value = cloudflare_workers_kv_namespace.app.id
+  sensitive = false
+}
+
+output "name_servers" {
+  value = cloudflare_zone.main.name_servers
+  description = "Name servers for domain registration"
+}
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration Reference](./configuration.md) - All resource types
+- [Patterns](./patterns.md) - Architecture patterns
+- [Troubleshooting](./gotchas.md) - Common issues

package/skills/cloudflare/references/terraform/configuration.md

@@ -0,0 +1,197 @@
+# Terraform Configuration Reference
+
+Complete resource configurations for Cloudflare infrastructure.
+
+## Zone & DNS
+
+```hcl
+# Zone + settings
+resource "cloudflare_zone" "example" { account = { id = var.account_id }; name = "example.com"; type = "full" }
+resource "cloudflare_zone_settings_override" "example" {
+  zone_id = cloudflare_zone.example.id
+  settings { ssl = "strict"; always_use_https = "on"; min_tls_version = "1.2"; tls_1_3 = "on"; http3 = "on" }
+}
+
+# DNS records (A, CNAME, MX, TXT)
+resource "cloudflare_dns_record" "www" {
+  zone_id = cloudflare_zone.example.id; name = "www"; content = "192.0.2.1"; type = "A"; proxied = true
+}
+resource "cloudflare_dns_record" "mx" {
+  for_each = { "10" = "mail1.example.com", "20" = "mail2.example.com" }
+  zone_id = cloudflare_zone.example.id; name = "@"; content = each.value; type = "MX"; priority = each.key
+}
+```
+
+## Workers
+
+### Simple Pattern (Legacy - Still Works)
+
+```hcl
+resource "cloudflare_workers_script" "api" {
+  account_id = var.account_id; name = "api-worker"; content = file("worker.js")
+  module = true; compatibility_date = "2025-01-01"
+  kv_namespace_binding { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.cache.id }
+  r2_bucket_binding { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.assets.name }
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.app.id }
+  secret_text_binding { name = "SECRET"; text = var.secret }
+}
+```
+
+### Gradual Rollouts (Recommended for Production)
+
+```hcl
+resource "cloudflare_worker" "api" { account_id = var.account_id; name = "api-worker" }
+resource "cloudflare_worker_version" "api_v1" {
+  account_id = var.account_id; worker_name = cloudflare_worker.api.name
+  content = file("worker.js"); content_sha256 = filesha256("worker.js")
+  compatibility_date = "2025-01-01"
+  bindings {
+    kv_namespace { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.cache.id }
+    r2_bucket { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.assets.name }
+  }
+}
+resource "cloudflare_workers_deployment" "api" {
+  account_id = var.account_id; worker_name = cloudflare_worker.api.name
+  versions { version_id = cloudflare_worker_version.api_v1.id; percentage = 100 }
+}
+```
+
+### Worker Binding Types (v5)
+
+| Binding    | Attribute                  | Example                                      |
+| ---------- | -------------------------- | -------------------------------------------- |
+| KV         | `kv_namespace_binding`     | `{ name = "KV", namespace_id = "..." }`      |
+| R2         | `r2_bucket_binding`        | `{ name = "BUCKET", bucket_name = "..." }`   |
+| D1         | `d1_database_binding`      | `{ name = "DB", database_id = "..." }`       |
+| Service    | `service_binding`          | `{ name = "AUTH", service = "auth-worker" }` |
+| Secret     | `secret_text_binding`      | `{ name = "API_KEY", text = "..." }`         |
+| Queue      | `queue_binding`            | `{ name = "QUEUE", queue_name = "..." }`     |
+| Vectorize  | `vectorize_binding`        | `{ name = "INDEX", index_name = "..." }`     |
+| Hyperdrive | `hyperdrive_binding`       | `{ name = "DB", id = "..." }`                |
+| AI         | `ai_binding`               | `{ name = "AI" }`                            |
+| Browser    | `browser_binding`          | `{ name = "BROWSER" }`                       |
+| Analytics  | `analytics_engine_binding` | `{ name = "ANALYTICS", dataset = "..." }`    |
+| mTLS       | `mtls_certificate_binding` | `{ name = "CERT", certificate_id = "..." }`  |
+
+### Routes & Triggers
+
+```hcl
+resource "cloudflare_worker_route" "api" {
+  zone_id = cloudflare_zone.example.id; pattern = "api.example.com/*"
+  script_name = cloudflare_workers_script.api.name
+}
+resource "cloudflare_worker_cron_trigger" "task" {
+  account_id = var.account_id; script_name = cloudflare_workers_script.api.name
+  schedules = ["*/5 * * * *"]
+}
+```
+
+## Storage (KV, R2, D1)
+
+```hcl
+# KV
+resource "cloudflare_workers_kv_namespace" "cache" { account_id = var.account_id; title = "cache" }
+resource "cloudflare_workers_kv" "config" {
+  account_id = var.account_id; namespace_id = cloudflare_workers_kv_namespace.cache.id
+  key_name = "config"; value = jsonencode({ version = "1.0" })
+}
+
+# R2
+resource "cloudflare_r2_bucket" "assets" { account_id = var.account_id; name = "assets"; location = "WNAM" }
+
+# D1 (migrations via wrangler) & Queues
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "app-db" }
+resource "cloudflare_queue" "events" { account_id = var.account_id; name = "events-queue" }
+```
+
+## Pages
+
+```hcl
+resource "cloudflare_pages_project" "site" {
+  account_id = var.account_id; name = "site"; production_branch = "main"
+  deployment_configs {
+    production {
+      compatibility_date = "2025-01-01"
+      environment_variables = { NODE_ENV = "production" }
+      kv_namespaces = { KV = cloudflare_workers_kv_namespace.cache.id }
+      d1_databases = { DB = cloudflare_d1_database.app.id }
+    }
+  }
+  build_config { build_command = "npm run build"; destination_dir = "dist" }
+  source { type = "github"; config { owner = "org"; repo_name = "site"; production_branch = "main" }}
+}
+
+resource "cloudflare_pages_domain" "custom" {
+  account_id = var.account_id; project_name = cloudflare_pages_project.site.name; domain = "site.example.com"
+}
+```
+
+## Rulesets (WAF, Redirects, Cache)
+
+```hcl
+# WAF
+resource "cloudflare_ruleset" "waf" {
+  zone_id = cloudflare_zone.example.id; name = "WAF"; kind = "zone"; phase = "http_request_firewall_custom"
+  rules { action = "block"; enabled = true; expression = "(cf.client.bot) and not (cf.verified_bot)" }
+}
+
+# Redirects
+resource "cloudflare_ruleset" "redirects" {
+  zone_id = cloudflare_zone.example.id; name = "Redirects"; kind = "zone"; phase = "http_request_dynamic_redirect"
+  rules {
+    action = "redirect"; enabled = true; expression = "(http.request.uri.path eq \"/old\")"
+    action_parameters { from_value { status_code = 301; target_url { value = "https://example.com/new" }}}
+  }
+}
+
+# Cache rules
+resource "cloudflare_ruleset" "cache" {
+  zone_id = cloudflare_zone.example.id; name = "Cache"; kind = "zone"; phase = "http_request_cache_settings"
+  rules {
+    action = "set_cache_settings"; enabled = true; expression = "(http.request.uri.path matches \"\\.(jpg|png|css|js)$\")"
+    action_parameters { cache = true; edge_ttl { mode = "override_origin"; default = 86400 }}
+  }
+}
+```
+
+## Load Balancers
+
+```hcl
+resource "cloudflare_load_balancer_monitor" "http" {
+  account_id = var.account_id; type = "http"; path = "/health"; interval = 60; timeout = 5
+}
+resource "cloudflare_load_balancer_pool" "api" {
+  account_id = var.account_id; name = "api-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "api-1"; address = "192.0.2.1" }
+  origins { name = "api-2"; address = "192.0.2.2" }
+}
+resource "cloudflare_load_balancer" "api" {
+  zone_id = cloudflare_zone.example.id; name = "api.example.com"
+  default_pool_ids = [cloudflare_load_balancer_pool.api.id]; steering_policy = "geo"
+}
+```
+
+## Access (Zero Trust)
+
+```hcl
+resource "cloudflare_access_application" "admin" {
+  account_id = var.account_id; name = "Admin"; domain = "admin.example.com"; type = "self_hosted"
+  session_duration = "24h"; allowed_idps = [cloudflare_access_identity_provider.github.id]
+}
+resource "cloudflare_access_policy" "allow" {
+  account_id = var.account_id; application_id = cloudflare_access_application.admin.id
+  name = "Allow"; decision = "allow"; precedence = 1
+  include { email = ["admin@example.com"] }
+}
+resource "cloudflare_access_identity_provider" "github" {
+  account_id = var.account_id; name = "GitHub"; type = "github"
+  config { client_id = var.github_id; client_secret = var.github_secret }
+}
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [API](./api.md) - Data sources
+- [Patterns](./patterns.md) - Use cases
+- [Troubleshooting](./gotchas.md) - Issues