memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,204 @@
+## Routing Patterns
+
+### Session Affinity (Stateful)
+
+```typescript
+export class SessionBackend extends Container {
+  defaultPort = 3000
+  sleepAfter = '30m'
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const sessionId = request.headers.get('X-Session-ID') || crypto.randomUUID()
+    const container = env.SESSION_BACKEND.getByName(sessionId)
+    await container.startAndWaitForPorts()
+    return container.fetch(request)
+  },
+}
+```
+
+**Use:** User sessions, WebSocket, stateful games, per-user caching.
+
+### Load Balancing (Stateless)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.STATELESS_API.getRandom()
+    await container.startAndWaitForPorts()
+    return container.fetch(request)
+  },
+}
+```
+
+**Use:** Stateless HTTP APIs, CPU-intensive work, read-only queries.
+
+### Singleton Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const container = env.GLOBAL_SERVICE.getByName('singleton')
+    await container.startAndWaitForPorts()
+    return container.fetch(request)
+  },
+}
+```
+
+**Use:** Global cache, centralized coordinator, single source of truth.
+
+## WebSocket Forwarding
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    if (request.headers.get('Upgrade') === 'websocket') {
+      const sessionId = request.headers.get('X-Session-ID') || crypto.randomUUID()
+      const container = env.WS_BACKEND.getByName(sessionId)
+      await container.startAndWaitForPorts()
+
+      // ⚠️ MUST use fetch(), not containerFetch()
+      return container.fetch(request)
+    }
+    return new Response('Not a WebSocket request', { status: 400 })
+  },
+}
+```
+
+**⚠️ Critical:** Always use `fetch()` for WebSocket.
+
+## Graceful Shutdown
+
+```typescript
+export class GracefulContainer extends Container {
+  private connections = new Set<WebSocket>()
+
+  onStop() {
+    // SIGTERM received, 15 minutes until SIGKILL
+    for (const ws of this.connections) {
+      ws.close(1001, 'Server shutting down')
+    }
+    this.ctx.storage.put('shutdown-time', Date.now())
+  }
+
+  onActivityExpired(): boolean {
+    return this.connections.size > 0 // Keep alive if connections
+  }
+}
+```
+
+## Concurrent Request Handling
+
+```typescript
+export class SafeContainer extends Container {
+  private initialized = false
+
+  async fetch(request: Request) {
+    await this.ctx.blockConcurrencyWhile(async () => {
+      if (!this.initialized) {
+        await this.startAndWaitForPorts()
+        this.initialized = true
+      }
+    })
+    return super.fetch(request)
+  }
+}
+```
+
+**Use:** One-time initialization, preventing concurrent startup.
+
+## Activity Timeout Renewal
+
+```typescript
+export class LongRunningContainer extends Container {
+  sleepAfter = '5m'
+
+  async processLongJob(data: unknown) {
+    const interval = setInterval(() => {
+      this.ctx.storage.put('keepalive', Date.now())
+    }, 60000)
+
+    try {
+      await this.doLongWork(data)
+    } finally {
+      clearInterval(interval)
+    }
+  }
+}
+```
+
+**Use:** Long operations exceeding `sleepAfter`.
+
+## Multiple Port Routing
+
+```typescript
+export class MultiPortContainer extends Container {
+  requiredPorts = [8080, 8081, 9090]
+
+  async fetch(request: Request) {
+    const path = new URL(request.url).pathname
+    if (path.startsWith('/grpc')) this.switchPort(8081)
+    else if (path.startsWith('/metrics')) this.switchPort(9090)
+    return super.fetch(request)
+  }
+}
+```
+
+**Use:** Multi-protocol services (HTTP + gRPC), separate metrics endpoints.
+
+## Workflow Integration
+
+```typescript
+import { WorkflowEntrypoint } from 'cloudflare:workers'
+
+export class ProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    const container = this.env.PROCESSOR.getByName(event.payload.jobId)
+
+    await step.do('start', async () => {
+      await container.startAndWaitForPorts()
+    })
+
+    const result = await step.do('process', async () => {
+      return container
+        .fetch('/process', {
+          method: 'POST',
+          body: JSON.stringify(event.payload.data),
+        })
+        .then((r) => r.json())
+    })
+
+    return result
+  }
+}
+```
+
+**Use:** Orchestrating multi-step container operations, durable execution.
+
+## Queue Consumer Integration
+
+```typescript
+export default {
+  async queue(batch, env) {
+    for (const msg of batch.messages) {
+      try {
+        const container = env.PROCESSOR.getByName(msg.body.jobId)
+        await container.startAndWaitForPorts()
+
+        const response = await container.fetch('/process', {
+          method: 'POST',
+          body: JSON.stringify(msg.body),
+        })
+
+        response.ok ? msg.ack() : msg.retry()
+      } catch (err) {
+        console.error('Queue processing error:', err)
+        msg.retry()
+      }
+    }
+  },
+}
+```
+
+**Use:** Asynchronous job processing, batch operations, event-driven execution.

package/skills/cloudflare/references/cron-triggers/README.md

@@ -0,0 +1,101 @@
+# Cloudflare Cron Triggers
+
+Schedule Workers execution using cron expressions. Runs on Cloudflare's global network during underutilized periods.
+
+## Key Features
+
+- **UTC-only execution** - All schedules run on UTC time
+- **5-field cron syntax** - Quartz scheduler extensions (L, W, #)
+- **Global propagation** - 15min deployment delay
+- **At-least-once delivery** - Rare duplicate executions possible
+- **Workflow integration** - Trigger long-running multi-step tasks
+- **Green Compute** - Optional carbon-aware scheduling during low-carbon periods
+
+## Cron Syntax
+
+```
+ ┌─────────── minute (0-59)
+ │ ┌───────── hour (0-23)
+ │ │ ┌─────── day of month (1-31)
+ │ │ │ ┌───── month (1-12, JAN-DEC)
+ │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday)
+ * * * * *
+```
+
+**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)
+
+## Common Schedules
+
+```bash
+*/5 * * * *        # Every 5 minutes
+0 * * * *          # Hourly
+0 2 * * *          # Daily 2am UTC (off-peak)
+0 9 * * MON-FRI    # Weekdays 9am UTC
+0 0 1 * *          # Monthly 1st midnight UTC
+0 9 L * *          # Last day of month 9am UTC
+0 10 * * MON#2     # 2nd Monday 10am UTC
+*/10 9-17 * * MON-FRI  # Every 10min, 9am-5pm weekdays
+```
+
+## Quick Start
+
+**wrangler.jsonc:**
+
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["*/5 * * * *", "0 2 * * *"],
+  },
+}
+```
+
+**Handler:**
+
+```typescript
+export default {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+    console.log('Cron:', controller.cron)
+    console.log('Time:', new Date(controller.scheduledTime))
+
+    ctx.waitUntil(asyncTask(env)) // Non-blocking
+  },
+}
+```
+
+**Test locally:**
+
+```bash
+npx wrangler dev
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+```
+
+## Limits
+
+- **Free:** 3 triggers/worker, 10ms CPU
+- **Paid:** Unlimited triggers, 50ms CPU
+- **Propagation:** 15min global deployment
+- **Timezone:** UTC only
+
+## Reading Order
+
+**New to cron triggers?** Start here:
+
+1. This README - Overview and quick start
+2. [configuration.md](./configuration.md) - Set up your first cron trigger
+3. [api.md](./api.md) - Understand the handler API
+4. [patterns.md](./patterns.md) - Common use cases and examples
+
+**Troubleshooting?** Jump to [gotchas.md](./gotchas.md)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler config, env-specific schedules, Green Compute
+- [api.md](./api.md) - ScheduledController, noRetry(), waitUntil, testing patterns
+- [patterns.md](./patterns.md) - Use cases, monitoring, queue integration, Durable Objects
+- [gotchas.md](./gotchas.md) - Timezone issues, idempotency, security, testing
+
+## See Also
+
+- [workflows](../workflows/) - Alternative for long-running scheduled tasks
+- [workers](../workers/) - Worker runtime documentation

package/skills/cloudflare/references/cron-triggers/api.md

@@ -0,0 +1,224 @@
+# Cron Triggers API
+
+## Basic Handler
+
+```typescript
+export default {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+    console.log('Cron executed:', new Date(controller.scheduledTime))
+  },
+}
+```
+
+**JavaScript:** Same signature without types  
+**Python:** `class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx)`
+
+## ScheduledController
+
+```typescript
+interface ScheduledController {
+  scheduledTime: number // Unix ms when scheduled to run
+  cron: string // Expression that triggered (e.g., "*/5 * * * *")
+  type: string // Always "scheduled"
+  noRetry(): void // Prevent automatic retry on failure
+}
+```
+
+**Prevent retry on failure:**
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    try {
+      await riskyOperation(env)
+    } catch (error) {
+      // Don't retry - failure is expected/acceptable
+      controller.noRetry()
+      console.error('Operation failed, not retrying:', error)
+    }
+  },
+}
+```
+
+**When to use noRetry():**
+
+- External API failures outside your control (avoid hammering failed services)
+- Rate limit errors (retry would fail again immediately)
+- Duplicate execution detected (idempotency check failed)
+- Non-critical operations where skip is acceptable (analytics, caching)
+- Validation errors that won't resolve on retry
+
+## Handler Parameters
+
+**`controller: ScheduledController`**
+
+- Access cron expression and scheduled time
+
+**`env: Env`**
+
+- All bindings: KV, R2, D1, secrets, service bindings
+
+**`ctx: ExecutionContext`**
+
+- `ctx.waitUntil(promise)` - Extend execution for async tasks (logging, cleanup, external APIs)
+- First `waitUntil` failure recorded in Cron Events
+
+## Multiple Schedules
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    switch (controller.cron) {
+      case '*/3 * * * *':
+        ctx.waitUntil(updateRecentData(env))
+        break
+      case '0 * * * *':
+        ctx.waitUntil(processHourlyAggregation(env))
+        break
+      case '0 2 * * *':
+        ctx.waitUntil(performDailyMaintenance(env))
+        break
+      default:
+        console.warn(`Unhandled: ${controller.cron}`)
+    }
+  },
+}
+```
+
+## ctx.waitUntil Usage
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const data = await fetchCriticalData() // Critical path
+
+    // Non-blocking background tasks
+    ctx.waitUntil(
+      Promise.all([
+        logToAnalytics(data),
+        cleanupOldRecords(env.DB),
+        notifyWebhook(env.WEBHOOK_URL, data),
+      ])
+    )
+  },
+}
+```
+
+## Workflow Integration
+
+```typescript
+import { WorkflowEntrypoint } from 'cloudflare:workers'
+
+export class DataProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    const data = await step.do('fetch-data', () => fetchLargeDataset())
+    const processed = await step.do('process-data', () => processDataset(data))
+    await step.do('store-results', () => storeResults(processed))
+  }
+}
+
+export default {
+  async scheduled(controller, env, ctx) {
+    const instance = await env.MY_WORKFLOW.create({
+      params: { scheduledTime: controller.scheduledTime, cron: controller.cron },
+    })
+    console.log(`Started workflow: ${instance.id}`)
+  },
+}
+```
+
+## Testing Handler
+
+**Local development (/\_\_scheduled endpoint):**
+
+```bash
+# Start dev server
+npx wrangler dev
+
+# Trigger any cron
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Trigger specific cron with custom time
+curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
+```
+
+**Query parameters:**
+
+- `cron` - Required. URL-encoded cron expression (use `+` for spaces)
+- `scheduledTime` - Optional. Unix timestamp in milliseconds (defaults to current time)
+
+**Production security:** The `/__scheduled` endpoint is available in production and can be triggered by anyone. Block it or implement authentication - see [gotchas.md](./gotchas.md#security-concerns)
+
+**Unit testing (Vitest):**
+
+```typescript
+// test/scheduled.test.ts
+import { describe, it, expect } from 'vitest'
+import { env } from 'cloudflare:test'
+import worker from '../src/index'
+
+describe('Scheduled Handler', () => {
+  it('processes scheduled event', async () => {
+    const controller = {
+      scheduledTime: Date.now(),
+      cron: '*/5 * * * *',
+      type: 'scheduled' as const,
+      noRetry: () => {},
+    }
+    const ctx = { waitUntil: (p: Promise<any>) => p, passThroughOnException: () => {} }
+    await worker.scheduled(controller, env, ctx)
+    expect(await env.MY_KV.get('last_run')).toBeDefined()
+  })
+
+  it('handles multiple crons', async () => {
+    const ctx = { waitUntil: () => {}, passThroughOnException: () => {} }
+    await worker.scheduled(
+      { scheduledTime: Date.now(), cron: '*/5 * * * *', type: 'scheduled', noRetry: () => {} },
+      env,
+      ctx
+    )
+    expect(await env.MY_KV.get('last_type')).toBe('frequent')
+  })
+})
+```
+
+## Error Handling
+
+**Automatic retries:**
+
+- Failed cron executions are retried automatically unless `noRetry()` is called
+- Retry happens after a delay (typically minutes)
+- Only first `waitUntil()` failure is recorded in Cron Events
+
+**Best practices:**
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    try {
+      await criticalOperation(env)
+    } catch (error) {
+      // Log error details
+      console.error('Cron failed:', {
+        cron: controller.cron,
+        scheduledTime: controller.scheduledTime,
+        error: error.message,
+        stack: error.stack,
+      })
+
+      // Decide: retry or skip
+      if (error.message.includes('rate limit')) {
+        controller.noRetry() // Skip retry for rate limits
+      }
+      // Otherwise allow automatic retry
+      throw error
+    }
+  },
+}
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [patterns.md](./patterns.md) - Use cases, examples
+- [gotchas.md](./gotchas.md) - Common errors, testing issues

package/skills/cloudflare/references/cron-triggers/configuration.md

@@ -0,0 +1,190 @@
+# Cron Triggers Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-cron-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+
+  "triggers": {
+    "crons": [
+      "*/5 * * * *", // Every 5 minutes
+      "0 */2 * * *", // Every 2 hours
+      "0 9 * * MON-FRI", // Weekdays at 9am UTC
+      "0 2 1 * *", // Monthly on 1st at 2am UTC
+    ],
+  },
+}
+```
+
+## Green Compute (Beta)
+
+Schedule crons during low-carbon periods for carbon-aware execution:
+
+```jsonc
+{
+  "name": "eco-cron-worker",
+  "triggers": {
+    "crons": ["0 2 * * *"],
+  },
+  "placement": {
+    "mode": "smart", // Runs during low-carbon periods
+  },
+}
+```
+
+**Modes:**
+
+- `"smart"` - Carbon-aware scheduling (may delay up to 24h for optimal window)
+- Default (no placement config) - Standard scheduling (no delay)
+
+**How it works:**
+
+- Cloudflare delays execution until grid carbon intensity is lower
+- Maximum delay: 24 hours from scheduled time
+- Ideal for batch jobs with flexible timing requirements
+
+**Use cases:**
+
+- Nightly data processing and ETL pipelines
+- Weekly/monthly report generation
+- Database backups and maintenance
+- Analytics aggregation
+- ML model training
+
+**Not suitable for:**
+
+- Time-sensitive operations (SLA requirements)
+- User-facing features requiring immediate execution
+- Real-time monitoring and alerting
+- Compliance tasks with strict time windows
+
+## Environment-Specific Schedules
+
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["0 */6 * * *"], // Prod: every 6 hours
+  },
+  "env": {
+    "staging": {
+      "triggers": {
+        "crons": ["*/15 * * * *"], // Staging: every 15min
+      },
+    },
+    "dev": {
+      "triggers": {
+        "crons": ["*/5 * * * *"], // Dev: every 5min
+      },
+    },
+  },
+}
+```
+
+## Schedule Format
+
+**Structure:** `minute hour day-of-month month day-of-week`
+
+**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)
+
+## Managing Triggers
+
+**Remove all:** `"triggers": { "crons": [] }`  
+**Preserve existing:** Omit `"triggers"` field entirely
+
+## Deployment
+
+```bash
+# Deploy with config crons
+npx wrangler deploy
+
+# Deploy specific environment
+npx wrangler deploy --env production
+
+# View deployments
+npx wrangler deployments list
+```
+
+**⚠️ Changes take up to 15 minutes to propagate globally**
+
+## API Management
+
+**Get triggers:**
+
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}"
+```
+
+**Update triggers:**
+
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": ["*/5 * * * *", "0 2 * * *"]}'
+```
+
+**Delete all:**
+
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": []}'
+```
+
+## Combining Multiple Workers
+
+For complex schedules, use multiple workers:
+
+```jsonc
+// worker-frequent.jsonc
+{
+  "name": "data-sync-frequent",
+  "triggers": { "crons": ["*/5 * * * *"] }
+}
+
+// worker-daily.jsonc
+{
+  "name": "reports-daily",
+  "triggers": { "crons": ["0 2 * * *"] },
+  "placement": { "mode": "smart" }
+}
+
+// worker-weekly.jsonc
+{
+  "name": "cleanup-weekly",
+  "triggers": { "crons": ["0 3 * * SUN"] }
+}
+```
+
+**Benefits:**
+
+- Separate CPU limits per worker
+- Independent error isolation
+- Different Green Compute policies
+- Easier to maintain and debug
+
+## Validation
+
+**Test cron syntax:**
+
+- [crontab.guru](https://crontab.guru/) - Interactive validator
+- Wrangler validates on deploy but won't catch logic errors
+
+**Common mistakes:**
+
+- `0 0 * * *` runs daily at midnight UTC, not your local timezone
+- `*/60 * * * *` is invalid (use `0 * * * *` for hourly)
+- `0 2 31 * *` only runs on months with 31 days
+
+## See Also
+
+- [README.md](./README.md) - Overview, quick start
+- [api.md](./api.md) - Handler implementation
+- [patterns.md](./patterns.md) - Multi-cron routing examples