memory-journal-mcp 8.0.1 → 9.1.0

package/skills/cloudflare/references/durable-objects/README.md

@@ -1,194 +0,0 @@
-# Cloudflare Durable Objects
-
-Expert guidance for building stateful applications with Cloudflare Durable Objects.
-
-## Reading Order
-
-1. **First time?** Read this overview + Quick Start
-2. **Setting up?** See [Configuration](./configuration.md)
-3. **Building features?** Use decision trees below → [Patterns](./patterns.md)
-4. **Debugging issues?** Check [Gotchas](./gotchas.md)
-5. **Deep dive?** [API](./api.md) and [DO Storage](../do-storage/README.md)
-
-## Overview
-
-Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:
-
-- **Globally unique instances**: Each DO has unique ID for multi-client coordination
-- **Co-located storage**: Fast, strongly-consistent storage with compute
-- **Automatic placement**: Objects spawn near first request location
-- **Stateful serverless**: In-memory state + persistent storage
-- **Single-threaded**: Serial request processing (no race conditions)
-
-## Rules of Durable Objects
-
-Critical rules preventing most production issues:
-
-1. **One alarm per DO** - Schedule multiple events via queue pattern
-2. **~1K req/s per DO max** - Shard for higher throughput
-3. **Constructor runs every wake** - Keep initialization light; use lazy loading
-4. **Hibernation clears memory** - In-memory state lost; persist critical data
-5. **Use `ctx.waitUntil()` for cleanup** - Ensures completion after response sent
-6. **No setTimeout for persistence** - Use `setAlarm()` for reliable scheduling
-
-## Core Concepts
-
-### Class Structure
-
-All DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).
-
-### Lifecycle States
-
-```
-[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]
-                   ↓
-              [Destroyed]
-```
-
-- **Not Created**: DO ID exists but instance never spawned
-- **Active**: Processing requests, in-memory state valid, billed per GB-hour
-- **Hibernated**: WebSocket connections open but zero compute, zero cost
-- **Evicted**: Removed from memory; next request triggers cold start
-- **Destroyed**: Data deleted via migration or manual deletion
-
-### Accessing from Workers
-
-Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).
-
-**RPC vs fetch() decision:**
-
-```
-├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)
-├─ Need HTTP semantics (headers, status) → fetch()
-├─ Proxying requests to DO → fetch()
-└─ Legacy compatibility → fetch()
-```
-
-See [Patterns: RPC vs fetch()](./patterns.md) for examples.
-
-### ID Generation
-
-- `idFromName()`: Deterministic, named coordination (rate limiting, locks)
-- `newUniqueId()`: Random IDs for sharding high-throughput workloads
-- `idFromString()`: Derive from existing IDs
-- Jurisdiction option: Data locality compliance
-
-### Storage Options
-
-**Which storage API?**
-
-```
-├─ Structured data, relations, transactions → SQLite (recommended)
-├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)
-└─ Legacy KV-only DO → ctx.storage (async KV)
-```
-
-- **SQLite** (recommended): Structured data, transactions, 10GB/DO
-- **Synchronous KV API**: Simple key-value on SQLite objects
-- **Asynchronous KV API**: Legacy/advanced use cases
-
-See [DO Storage](../do-storage/README.md) for deep dive.
-
-### Special Features
-
-- **Alarms**: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)
-- **WebSocket Hibernation**: Zero-cost idle connections (memory cleared on hibernation)
-- **Point-in-Time Recovery**: Restore to any point in 30 days (SQLite only)
-
-## Quick Start
-
-```typescript
-import { DurableObject } from 'cloudflare:workers'
-
-export class Counter extends DurableObject<Env> {
-  async increment(): Promise<number> {
-    const result = this.ctx.storage.sql
-      .exec(
-        `INSERT INTO counters (id, value) VALUES (1, 1)
-       ON CONFLICT(id) DO UPDATE SET value = value + 1
-       RETURNING value`
-      )
-      .one()
-    return result.value
-  }
-}
-
-// Worker access
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const id = env.COUNTER.idFromName('global')
-    const stub = env.COUNTER.get(id)
-    const count = await stub.increment()
-    return new Response(`Count: ${count}`)
-  },
-}
-```
-
-## Decision Trees
-
-### What do you need?
-
-```
-├─ Coordinate requests (rate limit, lock, session)
-│   → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)
-│
-├─ High throughput (>1K req/s)
-│   → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)
-│
-├─ Real-time updates (WebSocket, chat, collab)
-│   → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)
-│
-├─ Background work (cleanup, notifications, scheduled tasks)
-│   → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)
-│
-└─ User sessions with expiration
-    → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)
-```
-
-### Which access pattern?
-
-```
-├─ New project + typed methods → RPC (compat ≥2024-04-03)
-├─ Need HTTP semantics → fetch()
-├─ Proxying to DO → fetch()
-└─ Legacy compat → fetch()
-```
-
-See [Patterns: RPC vs fetch()](./patterns.md) for examples.
-
-### Which storage?
-
-```
-├─ Structured data, SQL queries, transactions → SQLite (recommended)
-├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)
-└─ Legacy KV-only DO → ctx.storage (async API)
-```
-
-See [DO Storage](../do-storage/README.md) for complete guide.
-
-## Essential Commands
-
-```bash
-npx wrangler dev              # Local dev with DOs
-npx wrangler dev --remote     # Test against prod DOs
-npx wrangler deploy           # Deploy + auto-apply migrations
-```
-
-## Resources
-
-**Docs**: https://developers.cloudflare.com/durable-objects/  
-**API Reference**: https://developers.cloudflare.com/durable-objects/api/  
-**Examples**: https://developers.cloudflare.com/durable-objects/examples/
-
-## In This Reference
-
-- **[Configuration](./configuration.md)** - wrangler.jsonc setup, migrations, bindings, environments
-- **[API](./api.md)** - Class structure, ctx methods, alarms, WebSocket hibernation
-- **[Patterns](./patterns.md)** - Sharding, rate limiting, locks, real-time, sessions
-- **[Gotchas](./gotchas.md)** - Limits, hibernation caveats, common errors
-
-## See Also
-
-- **[DO Storage](../do-storage/README.md)** - SQLite, KV, transactions (detailed storage guide)
-- **[Workers](../workers/README.md)** - Core Workers runtime features
-- **[WebSockets](../websockets/README.md)** - WebSocket APIs and patterns

package/skills/cloudflare/references/durable-objects/api.md

@@ -1,205 +0,0 @@
-# Durable Objects API
-
-## Class Structure
-
-```typescript
-import { DurableObject } from 'cloudflare:workers'
-
-export class MyDO extends DurableObject<Env> {
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env)
-    // Runs on EVERY wake - keep light!
-  }
-
-  // RPC methods (called directly from worker)
-  async myMethod(arg: string): Promise<string> {
-    return arg
-  }
-
-  // fetch handler (legacy/HTTP semantics)
-  async fetch(req: Request): Promise<Response> {
-    /* ... */
-  }
-
-  // Lifecycle handlers
-  async alarm() {
-    /* alarm fired */
-  }
-  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
-    /* ... */
-  }
-  async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-    /* ... */
-  }
-  async webSocketError(ws: WebSocket, error: unknown) {
-    /* ... */
-  }
-}
-```
-
-## DurableObjectState Context Methods
-
-### Concurrency Control
-
-```typescript
-// Complete work after response sent (e.g., cleanup, logging)
-this.ctx.waitUntil(promise: Promise<any>): void
-
-// Critical section - blocks all other requests until complete
-await this.ctx.blockConcurrencyWhile(async () => {
-  // No other requests processed during this block
-  // Use for initialization or critical operations
-})
-```
-
-**When to use:**
-
-- `waitUntil()`: Background cleanup, logging, non-critical work after response
-- `blockConcurrencyWhile()`: First-time init, schema migration, critical state setup
-
-### Lifecycle
-
-```typescript
-this.ctx.id // DurableObjectId of this instance
-this.ctx.abort() // Force eviction (use after PITR restore to reload state)
-```
-
-### Storage Access
-
-```typescript
-this.ctx.storage.sql // SQLite API (recommended)
-this.ctx.storage.kv // Sync KV API (SQLite DOs only)
-this.ctx.storage // Async KV API (legacy/KV-only DOs)
-```
-
-See **[DO Storage](../do-storage/README.md)** for complete storage API reference.
-
-### WebSocket Management
-
-```typescript
-this.ctx.acceptWebSocket(ws: WebSocket, tags?: string[])  // Enable hibernation
-this.ctx.getWebSockets(tag?: string): WebSocket[]         // Get by tag or all
-this.ctx.getTags(ws: WebSocket): string[]                 // Get tags for connection
-```
-
-### Alarms
-
-```typescript
-await this.ctx.storage.setAlarm(timestamp: number | Date)  // Schedule (overwrites existing)
-await this.ctx.storage.getAlarm(): number | null           // Get next alarm time
-await this.ctx.storage.deleteAlarm(): void                 // Cancel alarm
-```
-
-**Limit:** 1 alarm per DO. Use queue pattern for multiple events (see [Patterns](./patterns.md)).
-
-## Storage APIs
-
-For detailed storage documentation including SQLite queries, KV operations, transactions, and Point-in-Time Recovery, see **[DO Storage](../do-storage/README.md)**.
-
-Quick reference:
-
-```typescript
-// SQLite (recommended)
-this.ctx.storage.sql.exec('SELECT * FROM users WHERE id = ?', userId).one()
-
-// Sync KV (SQLite DOs only)
-this.ctx.storage.kv.get('key')
-
-// Async KV (legacy)
-await this.ctx.storage.get('key')
-```
-
-## Alarms
-
-Schedule future work that survives eviction:
-
-```typescript
-// Set alarm (overwrites any existing alarm)
-await this.ctx.storage.setAlarm(Date.now() + 3600000)  // 1 hour from now
-await this.ctx.storage.setAlarm(new Date("2026-02-01"))  // Absolute time
-
-// Check next alarm
-const nextRun = await this.ctx.storage.getAlarm()  // null if none
-
-// Cancel alarm
-await this.ctx.storage.deleteAlarm()
-
-// Handler called when alarm fires
-async alarm() {
-  // Runs once alarm triggers
-  // DO wakes from hibernation if needed
-  // Use for cleanup, notifications, scheduled tasks
-}
-```
-
-**Limitations:**
-
-- 1 alarm per DO maximum
-- Overwrites previous alarm when set
-- Use queue pattern for multiple scheduled events (see [Patterns](./patterns.md))
-
-**Reliability:**
-
-- Alarms survive DO eviction/restart
-- Cloudflare retries failed alarms automatically
-- Not guaranteed exactly-once (handle idempotently)
-
-## WebSocket Hibernation
-
-Hibernation allows DOs with open WebSocket connections to consume zero compute/memory until message arrives.
-
-```typescript
-async fetch(req: Request): Promise<Response> {
-  const [client, server] = Object.values(new WebSocketPair());
-  this.ctx.acceptWebSocket(server, ["room:123"]);  // Tags for filtering
-  server.serializeAttachment({ userId: "abc" });    // Persisted metadata
-  return new Response(null, { status: 101, webSocket: client });
-}
-
-// Called when message arrives (DO wakes from hibernation)
-async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
-  const data = ws.deserializeAttachment();          // Retrieve metadata
-  for (const c of this.ctx.getWebSockets("room:123")) c.send(msg);
-}
-
-// Called on close (optional handler)
-async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
-  // Cleanup logic, remove from lists, etc.
-}
-
-// Called on error (optional handler)
-async webSocketError(ws: WebSocket, error: unknown) {
-  console.error("WebSocket error:", error);
-  // Handle error, close connection, etc.
-}
-```
-
-**Key concepts:**
-
-- **Auto-hibernation:** DO hibernates when no active requests/alarms
-- **Zero cost:** Hibernated DOs incur no charges while preserving connections
-- **Memory cleared:** All in-memory state lost on hibernation
-- **Attachment persistence:** Use `serializeAttachment()` for per-connection metadata that survives hibernation
-- **Tags for filtering:** Group connections by room/channel/user for targeted broadcasts
-
-**Handler lifecycle:**
-
-- `webSocketMessage`: DO wakes, processes message, may hibernate after
-- `webSocketClose`: Called when client closes (optional - implement for cleanup)
-- `webSocketError`: Called on connection error (optional - implement for error handling)
-
-**Metadata persistence:**
-
-```typescript
-// Store connection metadata (survives hibernation)
-ws.serializeAttachment({ userId: 'abc', room: 'lobby' })
-
-// Retrieve after hibernation
-const { userId, room } = ws.deserializeAttachment()
-```
-
-## See Also
-
-- **[DO Storage](../do-storage/README.md)** - Complete storage API reference
-- **[Patterns](./patterns.md)** - Real-world usage patterns
-- **[Gotchas](./gotchas.md)** - Hibernation caveats and limits

package/skills/cloudflare/references/durable-objects/configuration.md

@@ -1,160 +0,0 @@
-# Durable Objects Configuration
-
-## Basic Setup
-
-```jsonc
-{
-  "name": "my-worker",
-  "main": "src/index.ts",
-  "compatibility_date": "2025-01-01", // Use latest; ≥2024-04-03 for RPC
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "MY_DO", // Env binding name
-        "class_name": "MyDO", // Class exported from this worker
-      },
-      {
-        "name": "EXTERNAL", // Access DO from another worker
-        "class_name": "ExternalDO",
-        "script_name": "other-worker",
-      },
-    ],
-  },
-  "migrations": [
-    { "tag": "v1", "new_sqlite_classes": ["MyDO"] }, // Prefer SQLite
-  ],
-}
-```
-
-## Binding Options
-
-```jsonc
-{
-  "name": "BINDING_NAME",
-  "class_name": "ClassName",
-  "script_name": "other-worker", // Optional: external DO
-  "environment": "production", // Optional: isolate by env
-}
-```
-
-## Jurisdiction (Data Locality)
-
-Specify jurisdiction at ID creation for data residency compliance:
-
-```typescript
-// EU data residency
-const id = env.MY_DO.idFromName('user:123', { jurisdiction: 'eu' })
-
-// Available jurisdictions
-const jurisdictions = ['eu', 'fedramp'] // More may be added
-
-// All operations on this DO stay within jurisdiction
-const stub = env.MY_DO.get(id)
-await stub.someMethod() // Data stays in EU
-```
-
-**Key points:**
-
-- Set at ID creation time, immutable afterward
-- DO instance physically located within jurisdiction
-- Storage and compute guaranteed within boundary
-- Use for GDPR, FedRAMP, other compliance requirements
-- No cross-jurisdiction access (requests fail if DO in different jurisdiction)
-
-## Migrations
-
-```jsonc
-{
-  "migrations": [
-    { "tag": "v1", "new_sqlite_classes": ["MyDO"] }, // Create SQLite (recommended)
-    // { "tag": "v1", "new_classes": ["MyDO"] },                // Create KV (paid only)
-    { "tag": "v2", "renamed_classes": [{ "from": "Old", "to": "New" }] },
-    { "tag": "v3", "transferred_classes": [{ "from": "Src", "from_script": "old", "to": "Dest" }] },
-    { "tag": "v4", "deleted_classes": ["Obsolete"] }, // Destroys ALL data!
-  ],
-}
-```
-
-**Migration rules:**
-
-- Tags must be unique and sequential (v1, v2, v3...)
-- No rollback supported (test with `--dry-run` first)
-- Auto-applied on deploy
-- `new_sqlite_classes` recommended over `new_classes` (SQLite vs KV)
-- `deleted_classes` immediately destroys ALL data (irreversible)
-
-## Environment Isolation
-
-Separate DO namespaces per environment (staging/production have distinct object instances):
-
-```jsonc
-{
-  "durable_objects": {
-    "bindings": [{ "name": "MY_DO", "class_name": "MyDO" }],
-  },
-  "env": {
-    "production": {
-      "durable_objects": {
-        "bindings": [{ "name": "MY_DO", "class_name": "MyDO", "environment": "production" }],
-      },
-    },
-  },
-}
-```
-
-Deploy: `npx wrangler deploy --env production`
-
-## Limits & Settings
-
-```jsonc
-{
-  "limits": {
-    "cpu_ms": 300000, // Max CPU time: 30s default, 300s max
-  },
-}
-```
-
-See [Gotchas](./gotchas.md) for complete limits table.
-
-## Types
-
-```typescript
-import { DurableObject } from 'cloudflare:workers'
-
-interface Env {
-  MY_DO: DurableObjectNamespace<MyDO>
-}
-
-export class MyDO extends DurableObject<Env> {}
-
-type DurableObjectNamespace<T> = {
-  newUniqueId(options?: { jurisdiction?: string }): DurableObjectId
-  idFromName(name: string): DurableObjectId
-  idFromString(id: string): DurableObjectId
-  get(id: DurableObjectId): DurableObjectStub<T>
-}
-```
-
-## Commands
-
-```bash
-# Development
-npx wrangler dev                    # Local dev
-npx wrangler dev --remote           # Test against production DOs
-
-# Deployment
-npx wrangler deploy                 # Deploy + auto-apply migrations
-npx wrangler deploy --dry-run       # Validate migrations without deploying
-npx wrangler deploy --env production
-
-# Management
-npx wrangler durable-objects list                      # List namespaces
-npx wrangler durable-objects info <namespace> <id>     # Inspect specific DO
-npx wrangler durable-objects delete <namespace> <id>   # Delete DO (destroys data)
-```
-
-## See Also
-
-- **[API](./api.md)** - DurableObjectState and lifecycle handlers
-- **[Patterns](./patterns.md)** - Multi-environment patterns
-- **[Gotchas](./gotchas.md)** - Migration caveats, limits