memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,187 @@
+# Testing Patterns
+
+## Choosing a Testing Approach
+
+| Approach                | Use Case                        | Speed  | Setup  | Runtime   |
+| ----------------------- | ------------------------------- | ------ | ------ | --------- |
+| **getPlatformProxy**    | Unit tests, logic testing       | Fast   | Low    | Miniflare |
+| **Miniflare API**       | Integration tests, full control | Medium | Medium | Miniflare |
+| **vitest-pool-workers** | Vitest runner integration       | Medium | Medium | workerd   |
+
+**Quick guide:**
+
+- Unit tests → getPlatformProxy
+- Integration tests → Miniflare API
+- Vitest workflows → vitest-pool-workers
+
+## getPlatformProxy
+
+Lightweight unit testing - provides bindings without full Worker runtime.
+
+```js
+// vitest.config.js
+export default { test: { environment: 'node' } }
+```
+
+```js
+import { env } from 'cloudflare:test'
+import { describe, it, expect } from 'vitest'
+
+describe('Business logic', () => {
+  it('processes data with KV', async () => {
+    await env.KV.put('test', 'value')
+    expect(await env.KV.get('test')).toBe('value')
+  })
+})
+```
+
+**Pros:** Fast, simple  
+**Cons:** No full runtime, can't test fetch handler
+
+## vitest-pool-workers
+
+Full Workers runtime in Vitest. Reads `wrangler.toml`.
+
+```bash
+npm i -D @cloudflare/vitest-pool-workers
+```
+
+```js
+// vitest.config.js
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: { workers: { wrangler: { configPath: './wrangler.toml' } } },
+  },
+})
+```
+
+```js
+import { env, SELF } from 'cloudflare:test'
+import { it, expect } from 'vitest'
+
+it('handles fetch', async () => {
+  const res = await SELF.fetch('http://example.com/')
+  expect(res.status).toBe(200)
+})
+```
+
+**Pros:** Full runtime, uses wrangler.toml  
+**Cons:** Requires Wrangler config
+
+## Miniflare API (node:test)
+
+```js
+import assert from 'node:assert'
+import test, { after, before } from 'node:test'
+import { Miniflare } from 'miniflare'
+
+let mf
+before(() => {
+  mf = new Miniflare({ scriptPath: 'src/index.js', kvNamespaces: ['TEST_KV'] })
+})
+
+test('fetch', async () => {
+  const res = await mf.dispatchFetch('http://localhost/')
+  assert.strictEqual(await res.text(), 'Hello')
+})
+
+after(() => mf.dispose())
+```
+
+## Testing Durable Objects & Events
+
+```js
+// Durable Objects
+const ns = await mf.getDurableObjectNamespace('COUNTER')
+const stub = ns.get(ns.idFromName('test-counter'))
+await stub.fetch('http://localhost/increment')
+
+// Direct storage
+const storage = await mf.getDurableObjectStorage(ns.idFromName('test-counter'))
+const count = await storage.get('count')
+
+// Queue
+const worker = await mf.getWorker()
+await worker.queue('my-queue', [
+  { id: 'msg1', timestamp: new Date(), body: { userId: 123 }, attempts: 1 },
+])
+
+// Scheduled
+await worker.scheduled({ cron: '0 0 * * *' })
+```
+
+## Test Isolation & Mocking
+
+```js
+// Per-test isolation
+beforeEach(() => {
+  mf = new Miniflare({ kvNamespaces: ['TEST'] })
+})
+afterEach(() => mf.dispose())
+
+// Mock external APIs
+new Miniflare({
+  workers: [
+    { name: 'main', serviceBindings: { API: 'mock-api' }, script: `...` },
+    {
+      name: 'mock-api',
+      script: `export default { async fetch() { return Response.json({mock: true}); } }`,
+    },
+  ],
+})
+```
+
+## Type Safety
+
+```ts
+import type { KVNamespace } from '@cloudflare/workers-types'
+
+interface Env {
+  KV: KVNamespace
+  API_KEY: string
+}
+
+const env = await mf.getBindings<Env>()
+await env.KV.put('key', 'value') // Typed!
+
+export default {
+  async fetch(req: Request, env: Env) {
+    return new Response(await env.KV.get('key'))
+  },
+} satisfies ExportedHandler<Env>
+```
+
+## WebSocket Testing
+
+```js
+const res = await mf.dispatchFetch('http://localhost/ws', {
+  headers: { Upgrade: 'websocket' },
+})
+assert.strictEqual(res.status, 101)
+```
+
+## Migration from unstable_dev
+
+```js
+// Old (deprecated)
+import { unstable_dev } from 'wrangler'
+const worker = await unstable_dev('src/index.ts')
+
+// New
+import { Miniflare } from 'miniflare'
+const mf = new Miniflare({ scriptPath: 'src/index.ts' })
+```
+
+## CI/CD Tips
+
+```js
+// In-memory storage (faster)
+new Miniflare({ kvNamespaces: ['TEST'] }) // No persist = in-memory
+
+// Use dispatchFetch (no port conflicts)
+await mf.dispatchFetch('http://localhost/')
+```
+
+See [gotchas.md](./gotchas.md) for troubleshooting.

package/skills/cloudflare/references/network-interconnect/README.md

@@ -0,0 +1,104 @@
+# Cloudflare Network Interconnect (CNI)
+
+Private, high-performance connectivity to Cloudflare's network. **Enterprise-only**.
+
+## Connection Types
+
+**Direct**: Physical fiber in shared datacenter. 10/100 Gbps. You order cross-connect.
+
+**Partner**: Virtual via Console Connect, Equinix, Megaport, etc. Managed via partner SDN.
+
+**Cloud**: AWS Direct Connect or GCP Cloud Interconnect. Magic WAN only.
+
+## Dataplane Versions
+
+**v1 (Classic)**: GRE tunnel support, VLAN/BFD/LACP, asymmetric MTU (1500↓/1476↑), peering support.
+
+**v2 (Beta)**: No GRE, 1500 MTU both ways, no VLAN/BFD/LACP yet, ECMP instead.
+
+## Use Cases
+
+- **Magic Transit DSR**: DDoS protection, egress via ISP (v1/v2)
+- **Magic Transit + Egress**: DDoS + egress via CF (v1/v2)
+- **Magic WAN + Zero Trust**: Private backbone (v1 needs GRE, v2 native)
+- **Peering**: Public routes at PoP (v1 only)
+- **App Security**: WAF/Cache/LB (v1/v2 over Magic Transit)
+
+## Prerequisites
+
+- Enterprise plan
+- IPv4 /24+ or IPv6 /48+ prefixes
+- BGP ASN for v1
+- See [locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-2026-01.pdf)
+
+## Specs
+
+- /31 point-to-point subnets
+- 10km max optical distance
+- 10G: 10GBASE-LR single-mode
+- 100G: 100GBASE-LR4 single-mode
+- **No SLA** (free service)
+- Backup Internet required
+
+## Throughput
+
+| Direction               | 10G                  | 100G                 |
+| ----------------------- | -------------------- | -------------------- |
+| CF → Customer           | 10 Gbps              | 100 Gbps             |
+| Customer → CF (peering) | 10 Gbps              | 100 Gbps             |
+| Customer → CF (Magic)   | 1 Gbps/tunnel or CNI | 1 Gbps/tunnel or CNI |
+
+## Timeline
+
+2-4 weeks typical. Steps: request → config review → order connection → configure → test → enable health checks → activate → monitor.
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - BGP, routing, setup
+- [api.md](./api.md) - API endpoints, SDKs
+- [patterns.md](./patterns.md) - HA, hybrid cloud, failover
+- [gotchas.md](./gotchas.md) - Troubleshooting, limits
+
+## Reading Order by Task
+
+| Task                        | Files to Load                      |
+| --------------------------- | ---------------------------------- |
+| Initial setup               | README → configuration.md → api.md |
+| Create interconnect via API | api.md → gotchas.md                |
+| Design HA architecture      | patterns.md → README               |
+| Troubleshoot connection     | gotchas.md → configuration.md      |
+| Cloud integration (AWS/GCP) | configuration.md → patterns.md     |
+| Monitor + alerts            | configuration.md                   |
+
+## Automation Boundary
+
+**API-Automatable:**
+
+- List/create/delete interconnects (Direct, Partner)
+- List available slots
+- Get interconnect status
+- Download LOA PDF
+- Create/update CNI objects (BGP config)
+- Query settings
+
+**Requires Account Team:**
+
+- Initial request approval
+- AWS Direct Connect setup (send LOA+VLAN to CF)
+- GCP Cloud Interconnect final activation
+- Partner interconnect acceptance (Equinix, Megaport)
+- VLAN assignment (v1)
+- Configuration document generation (v1)
+- Escalations + troubleshooting support
+
+**Cannot Be Automated:**
+
+- Physical cross-connect installation (Direct)
+- Partner portal operations (virtual circuit ordering)
+- AWS/GCP portal operations
+- Maintenance window coordination
+
+## See Also
+
+- [tunnel](../tunnel/) - Alternative for private network connectivity
+- [spectrum](../spectrum/) - Layer 4 proxy for TCP/UDP traffic

package/skills/cloudflare/references/network-interconnect/api.md

@@ -0,0 +1,220 @@
+# CNI API Reference
+
+See [README.md](README.md) for overview.
+
+## Base
+
+```
+https://api.cloudflare.com/client/v4
+Auth: Authorization: Bearer <token>
+```
+
+## SDK Namespaces
+
+**Primary (recommended):**
+
+```typescript
+client.networkInterconnects.interconnects.*
+client.networkInterconnects.cnis.*
+client.networkInterconnects.slots.*
+```
+
+**Alternate (deprecated):**
+
+```typescript
+client.magicTransit.cfInterconnects.*
+```
+
+Use `networkInterconnects` namespace for all new code.
+
+## Interconnects
+
+```http
+GET    /accounts/{account_id}/cni/interconnects              # Query: page, per_page
+POST   /accounts/{account_id}/cni/interconnects              # Query: validate_only=true (optional)
+GET    /accounts/{account_id}/cni/interconnects/{icon}
+GET    /accounts/{account_id}/cni/interconnects/{icon}/status
+GET    /accounts/{account_id}/cni/interconnects/{icon}/loa   # Returns PDF
+DELETE /accounts/{account_id}/cni/interconnects/{icon}
+```
+
+**Create Body:** `account`, `slot_id`, `type`, `facility`, `speed`, `name`, `description`  
+**Status Values:** `active` | `healthy` | `unhealthy` | `pending` | `down`
+
+**Response Example:**
+
+```json
+{
+  "result": [
+    {
+      "id": "icon_abc",
+      "name": "prod",
+      "type": "direct",
+      "facility": "EWR1",
+      "speed": "10G",
+      "status": "active"
+    }
+  ]
+}
+```
+
+## CNI Objects (BGP config)
+
+```http
+GET    /accounts/{account_id}/cni/cnis
+POST   /accounts/{account_id}/cni/cnis
+GET    /accounts/{account_id}/cni/cnis/{cni}
+PUT    /accounts/{account_id}/cni/cnis/{cni}
+DELETE /accounts/{account_id}/cni/cnis/{cni}
+```
+
+Body: `account`, `cust_ip`, `cf_ip`, `bgp_asn`, `bgp_password`, `vlan`
+
+## Slots
+
+```http
+GET /accounts/{account_id}/cni/slots
+GET /accounts/{account_id}/cni/slots/{slot}
+```
+
+Query: `facility`, `occupied`, `speed`
+
+## Health Checks
+
+Configure via Magic Transit/WAN tunnel endpoints (CNI v2).
+
+```typescript
+await client.magicTransit.tunnels.update(accountId, tunnelId, {
+  health_check: { enabled: true, target: '192.0.2.1', rate: 'high', type: 'request' },
+})
+```
+
+Rates: `high` | `medium` | `low`. Types: `request` | `reply`. See [Magic Transit docs](https://developers.cloudflare.com/magic-transit/how-to/configure-tunnel-endpoints/#add-tunnels).
+
+## Settings
+
+```http
+GET /accounts/{account_id}/cni/settings
+PUT /accounts/{account_id}/cni/settings
+```
+
+Body: `default_asn`
+
+## TypeScript SDK
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.CF_TOKEN })
+
+// List
+await client.networkInterconnects.interconnects.list({ account_id: id })
+
+// Create with validation
+await client.networkInterconnects.interconnects.create(
+  {
+    account_id: id,
+    account: id,
+    slot_id: 'slot_abc',
+    type: 'direct',
+    facility: 'EWR1',
+    speed: '10G',
+    name: 'prod-interconnect',
+  },
+  {
+    query: { validate_only: true }, // Dry-run validation
+  }
+)
+
+// Create without validation
+await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  account: id,
+  slot_id: 'slot_abc',
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'prod-interconnect',
+})
+
+// Status
+await client.networkInterconnects.interconnects.get(accountId, iconId)
+
+// LOA (use fetch)
+const res = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${id}/cni/interconnects/${iconId}/loa`,
+  {
+    headers: { Authorization: `Bearer ${token}` },
+  }
+)
+await fs.writeFile('loa.pdf', Buffer.from(await res.arrayBuffer()))
+
+// CNI object
+await client.networkInterconnects.cnis.create({
+  account_id: id,
+  account: id,
+  cust_ip: '192.0.2.1/31',
+  cf_ip: '192.0.2.0/31',
+  bgp_asn: 65000,
+  vlan: 100,
+})
+
+// Slots (filter by facility and speed)
+await client.networkInterconnects.slots.list({
+  account_id: id,
+  occupied: false,
+  facility: 'EWR1',
+  speed: '10G',
+})
+```
+
+## Python SDK
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token=os.environ["CF_TOKEN"])
+
+# List, create, status (same pattern as TypeScript)
+client.network_interconnects.interconnects.list(account_id=id)
+client.network_interconnects.interconnects.create(account_id=id, account=id, slot_id="slot_abc", type="direct", facility="EWR1", speed="10G")
+client.network_interconnects.interconnects.get(account_id=id, icon=icon_id)
+
+# CNI objects and slots
+client.network_interconnects.cnis.create(account_id=id, cust_ip="192.0.2.1/31", cf_ip="192.0.2.0/31", bgp_asn=65000)
+client.network_interconnects.slots.list(account_id=id, occupied=False)
+```
+
+## cURL
+
+```bash
+# List interconnects
+curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects" \
+  -H "Authorization: Bearer ${CF_TOKEN}"
+
+# Create interconnect
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects?validate_only=true" \
+  -H "Authorization: Bearer ${CF_TOKEN}" -H "Content-Type: application/json" \
+  -d '{"account": "id", "slot_id": "slot_abc", "type": "direct", "facility": "EWR1", "speed": "10G"}'
+
+# LOA PDF
+curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects/${ICON_ID}/loa" \
+  -H "Authorization: Bearer ${CF_TOKEN}" --output loa.pdf
+```
+
+## Not Available via API
+
+**Missing Capabilities:**
+
+- BGP session state query (use Dashboard or BGP logs)
+- Bandwidth utilization metrics (use external monitoring)
+- Traffic statistics per interconnect
+- Historical uptime/downtime data
+- Light level readings (contact account team)
+- Maintenance window scheduling (notifications only)
+
+## Resources
+
+- [API Docs](https://developers.cloudflare.com/api/resources/network_interconnects/)
+- [TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)
+- [Python SDK](https://github.com/cloudflare/cloudflare-python)

package/skills/cloudflare/references/network-interconnect/configuration.md

@@ -0,0 +1,123 @@
+# CNI Configuration
+
+See [README.md](README.md) for overview.
+
+## Workflow (2-4 weeks)
+
+1. **Submit request** (Week 1): Contact account team, provide type/location/use case
+2. **Review config** (Week 1-2, v1 only): Approve IP/VLAN/spec doc
+3. **Order connection** (Week 2-3):
+   - **Direct**: Get LOA, order cross-connect from facility
+   - **Partner**: Order virtual circuit in partner portal
+   - **Cloud**: Order Direct Connect/Cloud Interconnect, send LOA+VLAN to CF
+4. **Configure** (Week 3): Both sides configure per doc
+5. **Test** (Week 3-4): Ping, verify BGP, check routes
+6. **Health checks** (Week 4): Configure [Magic Transit](https://developers.cloudflare.com/magic-transit/how-to/configure-tunnel-endpoints/#add-tunnels) or [Magic WAN](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-tunnel-endpoints/#add-tunnels) health checks
+7. **Activate** (Week 4): Route traffic, verify flow
+8. **Monitor**: Enable [maintenance notifications](https://developers.cloudflare.com/network-interconnect/monitoring-and-alerts/#enable-cloudflare-status-maintenance-notification)
+
+## BGP Configuration
+
+**v1 Requirements:**
+
+- BGP ASN (provide during setup)
+- /31 subnet for peering
+- Optional: BGP password
+
+**v2:** Simplified, less BGP config needed.
+
+**BGP over CNI (Dec 2024):** Magic WAN/Transit can now peer BGP directly over CNI v2 (no GRE tunnel required).
+
+**Example v1 BGP:**
+
+```
+Router ID: 192.0.2.1
+Peer IP: 192.0.2.0
+Remote ASN: 13335
+Local ASN: 65000
+Password: [optional]
+VLAN: 100
+```
+
+## Cloud Interconnect Setup
+
+### AWS Direct Connect (Beta)
+
+**Requirements:** Magic WAN, AWS Dedicated Direct Connect 1/10 Gbps.
+
+**Process:**
+
+1. Contact CF account team
+2. Choose location
+3. Order in AWS portal
+4. AWS provides LOA + VLAN ID
+5. Send to CF account team
+6. Wait ~4 weeks
+
+**Post-setup:** Add [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes) to Magic WAN. Enable [bidirectional health checks](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-tunnel-endpoints/#legacy-bidirectional-health-checks).
+
+### GCP Cloud Interconnect (Beta)
+
+**Setup via Dashboard:**
+
+1. Interconnects → Create → Cloud Interconnect → Google
+2. Provide name, MTU (match GCP VLAN attachment), speed (50M-50G granular options available for partner interconnects)
+3. Enter VLAN attachment pairing key
+4. Confirm order
+
+**Routing to GCP:** Add [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes). BGP routes from GCP Cloud Router **ignored**.
+
+**Routing to CF:** Configure [custom learned routes](https://cloud.google.com/network-connectivity/docs/router/how-to/configure-custom-learned-routes) in Cloud Router. Request prefixes from CF account team.
+
+## Monitoring
+
+**Dashboard Status:**
+
+| Status        | Meaning                                                      |
+| ------------- | ------------------------------------------------------------ |
+| **Healthy**   | Link operational, traffic flowing, health checks passing     |
+| **Active**    | Link up, sufficient light, Ethernet negotiated               |
+| **Unhealthy** | Link down, no/low light (<-20 dBm), can't negotiate          |
+| **Pending**   | Cross-connect incomplete, device unresponsive, RX/TX swapped |
+| **Down**      | Physical link down, no connectivity                          |
+
+**Alerts:**
+
+**CNI Connection Maintenance** (Magic Networking only):
+
+```
+Dashboard → Notifications → Add
+Product: Cloudflare Network Interconnect
+Type: Connection Maintenance Alert
+```
+
+Warnings up to 2 weeks advance. 6hr delay for new additions.
+
+**Cloudflare Status Maintenance** (entire PoP):
+
+```
+Dashboard → Notifications → Add
+Product: Cloudflare Status
+Filter PoPs: gru,fra,lhr
+```
+
+**Find PoP code:**
+
+```
+Dashboard → Magic Transit/WAN → Configuration → Interconnects
+Select CNI → Note Data Center (e.g., "gru-b")
+Use first 3 letters: "gru"
+```
+
+## Best Practices
+
+**Critical config-specific practices:**
+
+- /31 subnets required for BGP
+- BGP passwords recommended
+- BFD for fast failover (v1 only)
+- Test ping connectivity before BGP
+- Enable maintenance notifications immediately after activation
+- Monitor status programmatically via API
+
+For design patterns, HA architecture, and security best practices, see [patterns.md](./patterns.md).