memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,207 @@
+# Cron Triggers Gotchas
+
+## Common Errors
+
+### "Timezone Issues"
+
+**Problem:** Cron runs at wrong time relative to local timezone  
+**Cause:** All crons execute in UTC, no local timezone support  
+**Solution:** Convert local time to UTC manually
+
+**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`
+
+**Examples:**
+
+- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`
+- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`
+- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`
+
+**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)
+
+### "Cron Not Executing"
+
+**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits  
+**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits
+
+### "Duplicate Executions"
+
+**Cause:** At-least-once delivery  
+**Solution:** Track execution IDs in KV - see idempotency pattern below
+
+### "Execution Failures"
+
+**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors  
+**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks
+
+### "Local Testing Not Working"
+
+**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler  
+**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format  
+**Solution:**
+
+1. Verify `scheduled()` is exported:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    console.log('Cron triggered')
+  },
+}
+```
+
+2. Start dev server:
+
+```bash
+npx wrangler dev
+```
+
+3. Use correct endpoint format (URL-encode spaces as `+`):
+
+```bash
+# Correct
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Wrong (will fail)
+curl "http://localhost:8787/__scheduled?cron=*/5 * * * *"
+```
+
+4. Update Wrangler if outdated:
+
+```bash
+npm install -g wrangler@latest
+```
+
+### "waitUntil() Tasks Not Completing"
+
+**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute  
+**Cause:** Promises rejected without error handling, or handler returns before promise settles  
+**Solution:** Always await or handle errors in waitUntil promises:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    // BAD: Silent failures
+    ctx.waitUntil(riskyOperation())
+
+    // GOOD: Explicit error handling
+    ctx.waitUntil(
+      riskyOperation().catch((err) => {
+        console.error('Background task failed:', err)
+        return logError(err, env)
+      })
+    )
+  },
+}
+```
+
+### "Idempotency Issues"
+
+**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails)  
+**Cause:** No deduplication mechanism  
+**Solution:** Use KV to track execution IDs:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const executionId = `${controller.cron}-${controller.scheduledTime}`
+    const existing = await env.EXECUTIONS.get(executionId)
+
+    if (existing) {
+      console.log('Already executed, skipping')
+      controller.noRetry()
+      return
+    }
+
+    await env.EXECUTIONS.put(executionId, '1', { expirationTtl: 86400 }) // 24h TTL
+    await performIdempotentOperation(env)
+  },
+}
+```
+
+### "Security Concerns"
+
+**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering  
+**Cause:** Testing endpoint available in deployed Workers  
+**Solution:** Block `__scheduled` in production:
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url)
+
+    // Block __scheduled in production
+    if (url.pathname === '/__scheduled' && env.ENVIRONMENT === 'production') {
+      return new Response('Not Found', { status: 404 })
+    }
+
+    return handleRequest(request, env, ctx)
+  },
+
+  async scheduled(controller, env, ctx) {
+    // Your cron logic
+  },
+}
+```
+
+**Also:** Use `env.API_KEY` for secrets (never hardcode)
+
+**Alternative:** Add middleware to verify request origin:
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url)
+
+    if (url.pathname === '/__scheduled') {
+      // Check Cloudflare headers to verify internal request
+      const cfRay = request.headers.get('cf-ray')
+      if (!cfRay && env.ENVIRONMENT === 'production') {
+        return new Response('Not Found', { status: 404 })
+      }
+    }
+
+    return handleRequest(request, env, ctx)
+  },
+
+  async scheduled(controller, env, ctx) {
+    // Your cron logic
+  },
+}
+```
+
+## Limits & Quotas
+
+| Limit               | Free             | Paid             | Notes                                    |
+| ------------------- | ---------------- | ---------------- | ---------------------------------------- |
+| Triggers per Worker | 3                | Unlimited        | Maximum cron schedules per Worker        |
+| CPU time            | 10ms             | 50ms             | May need `ctx.waitUntil()` or Workflows  |
+| Execution guarantee | At-least-once    | At-least-once    | Duplicates possible - use idempotency    |
+| Propagation delay   | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |
+| Min interval        | 1 minute         | 1 minute         | Cannot schedule more frequently          |
+| Cron accuracy       | ±1 minute        | ±1 minute        | Execution may drift slightly             |
+
+## Testing Best Practices
+
+**Unit tests:**
+
+- Mock `ScheduledController`, `ExecutionContext`, and bindings
+- Test each cron expression separately
+- Verify `noRetry()` is called when expected
+- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env
+
+**Integration tests:**
+
+- Test via `/__scheduled` endpoint in dev environment
+- Verify idempotency logic with duplicate `scheduledTime` values
+- Test error handling and retry behavior
+
+**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval
+
+## Resources
+
+- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
+- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
+- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
+- [Crontab Guru](https://crontab.guru/) - Validator
+- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)

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

@@ -0,0 +1,274 @@
+# Cron Triggers Patterns
+
+## API Data Sync
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const response = await fetch('https://api.example.com/data', {
+      headers: { Authorization: `Bearer ${env.API_KEY}` },
+    })
+    if (!response.ok) throw new Error(`API error: ${response.status}`)
+    ctx.waitUntil(
+      env.MY_KV.put('cached_data', JSON.stringify(await response.json()), { expirationTtl: 3600 })
+    )
+  },
+}
+```
+
+## Database Cleanup
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const result = await env.DB.prepare(
+      `DELETE FROM sessions WHERE expires_at < datetime('now')`
+    ).run()
+    console.log(`Deleted ${result.meta.changes} expired sessions`)
+    ctx.waitUntil(env.DB.prepare('VACUUM').run())
+  },
+}
+```
+
+## Report Generation
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const startOfWeek = new Date()
+    startOfWeek.setDate(startOfWeek.getDate() - 7)
+    const { results } = await env.DB.prepare(
+      `SELECT date, revenue, orders FROM daily_stats WHERE date >= ? ORDER BY date`
+    )
+      .bind(startOfWeek.toISOString())
+      .all()
+    const report = {
+      period: 'weekly',
+      totalRevenue: results.reduce((sum, d) => sum + d.revenue, 0),
+      totalOrders: results.reduce((sum, d) => sum + d.orders, 0),
+      dailyBreakdown: results,
+    }
+    const reportKey = `reports/weekly-${Date.now()}.json`
+    await env.REPORTS_BUCKET.put(reportKey, JSON.stringify(report))
+    ctx.waitUntil(
+      env.SEND_EMAIL.fetch('https://example.com/send', {
+        method: 'POST',
+        body: JSON.stringify({
+          to: 'team@example.com',
+          subject: 'Weekly Report',
+          reportUrl: `https://reports.example.com/${reportKey}`,
+        }),
+      })
+    )
+  },
+}
+```
+
+## Health Checks
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const services = [
+      { name: 'API', url: 'https://api.example.com/health' },
+      { name: 'CDN', url: 'https://cdn.example.com/health' },
+    ]
+    const checks = await Promise.all(
+      services.map(async (service) => {
+        const start = Date.now()
+        try {
+          const response = await fetch(service.url, { signal: AbortSignal.timeout(5000) })
+          return {
+            name: service.name,
+            status: response.ok ? 'up' : 'down',
+            responseTime: Date.now() - start,
+          }
+        } catch (error) {
+          return {
+            name: service.name,
+            status: 'down',
+            responseTime: Date.now() - start,
+            error: error.message,
+          }
+        }
+      })
+    )
+    ctx.waitUntil(env.STATUS_KV.put('health_status', JSON.stringify(checks)))
+    const failures = checks.filter((c) => c.status === 'down')
+    if (failures.length > 0)
+      ctx.waitUntil(
+        fetch(env.ALERT_WEBHOOK, {
+          method: 'POST',
+          body: JSON.stringify({
+            text: `${failures.length} service(s) down: ${failures.map((f) => f.name).join(', ')}`,
+          }),
+        })
+      )
+  },
+}
+```
+
+## Batch Processing (Rate-Limited)
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const queueData = await env.QUEUE_KV.get('pending_items', 'json')
+    if (!queueData || queueData.length === 0) return
+    const batch = queueData.slice(0, 100)
+    const results = await Promise.allSettled(
+      batch.map((item) =>
+        fetch('https://api.example.com/process', {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${env.API_KEY}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify(item),
+        })
+      )
+    )
+    console.log(
+      `Processed ${results.filter((r) => r.status === 'fulfilled').length}/${batch.length} items`
+    )
+    ctx.waitUntil(env.QUEUE_KV.put('pending_items', JSON.stringify(queueData.slice(100))))
+  },
+}
+```
+
+## Queue Integration
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const batch = await env.MY_QUEUE.receive({ batchSize: 100 })
+    const results = await Promise.allSettled(
+      batch.messages.map(async (msg) => {
+        await processMessage(msg.body, env)
+        await msg.ack()
+      })
+    )
+    console.log(
+      `Processed ${results.filter((r) => r.status === 'fulfilled').length}/${batch.messages.length}`
+    )
+  },
+}
+```
+
+## Monitoring & Observability
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const startTime = Date.now()
+    const meta = { cron: controller.cron, scheduledTime: controller.scheduledTime }
+    console.log('[START]', meta)
+    try {
+      const result = await performTask(env)
+      console.log('[SUCCESS]', { ...meta, duration: Date.now() - startTime, count: result.count })
+      ctx.waitUntil(
+        env.METRICS.put(
+          `cron:${controller.scheduledTime}`,
+          JSON.stringify({ ...meta, status: 'success' }),
+          { expirationTtl: 2592000 }
+        )
+      )
+    } catch (error) {
+      console.error('[ERROR]', { ...meta, duration: Date.now() - startTime, error: error.message })
+      ctx.waitUntil(
+        fetch(env.ALERT_WEBHOOK, {
+          method: 'POST',
+          body: JSON.stringify({ text: `Cron failed: ${controller.cron}`, error: error.message }),
+        })
+      )
+      throw error
+    }
+  },
+}
+```
+
+**View logs:** `npx wrangler tail` or Dashboard → Workers & Pages → Worker → Logs
+
+## Durable Objects Coordination
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const stub = env.COORDINATOR.get(env.COORDINATOR.idFromName('cron-lock'))
+    const acquired = await stub.tryAcquireLock(controller.scheduledTime)
+    if (!acquired) {
+      controller.noRetry()
+      return
+    }
+    try {
+      await performTask(env)
+    } finally {
+      await stub.releaseLock()
+    }
+  },
+}
+```
+
+## Python Handler
+
+```python
+from workers import WorkerEntrypoint
+
+class Default(WorkerEntrypoint):
+    async def scheduled(self, controller, env, ctx):
+        data = await env.MY_KV.get("key")
+        ctx.waitUntil(env.DB.execute("DELETE FROM logs WHERE created_at < datetime('now', '-7 days')"))
+```
+
+## Testing Patterns
+
+**Local testing with /\_\_scheduled:**
+
+```bash
+# Start dev server
+npx wrangler dev
+
+# Test specific cron
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Test with specific time
+curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
+```
+
+**Unit tests:**
+
+```typescript
+// test/scheduled.test.ts
+import { describe, it, expect, vi } from 'vitest'
+import { env } from 'cloudflare:test'
+import worker from '../src/index'
+
+describe('Scheduled Handler', () => {
+  it('executes cron', async () => {
+    const controller = {
+      scheduledTime: Date.now(),
+      cron: '*/5 * * * *',
+      type: 'scheduled' as const,
+      noRetry: vi.fn(),
+    }
+    const ctx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() }
+    await worker.scheduled(controller, env, ctx)
+    expect(await env.MY_KV.get('last_run')).toBeDefined()
+  })
+
+  it('calls noRetry on duplicate', async () => {
+    const controller = {
+      scheduledTime: 1704067200000,
+      cron: '0 2 * * *',
+      type: 'scheduled' as const,
+      noRetry: vi.fn(),
+    }
+    await env.EXECUTIONS.put('0 2 * * *-1704067200000', '1')
+    await worker.scheduled(controller, env, { waitUntil: vi.fn(), passThroughOnException: vi.fn() })
+    expect(controller.noRetry).toHaveBeenCalled()
+  })
+})
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [api.md](./api.md) - Handler implementation
+- [gotchas.md](./gotchas.md) - Troubleshooting

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

@@ -0,0 +1,137 @@
+# Cloudflare D1 Database
+
+Expert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.
+
+## Overview
+
+D1 is Cloudflare's managed, serverless database with:
+
+- SQLite SQL semantics and compatibility
+- Built-in disaster recovery via Time Travel (30-day point-in-time recovery)
+- Horizontal scale-out architecture (10 GB per database)
+- Worker and HTTP API access
+- Pricing based on query and storage costs only
+
+**Architecture Philosophy**: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.
+
+## Quick Start
+
+```bash
+# Create database
+wrangler d1 create <database-name>
+
+# Execute migration
+wrangler d1 migrations apply <db-name> --remote
+
+# Local development
+wrangler dev
+```
+
+## Core Query Methods
+
+```typescript
+// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value
+// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)
+const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?')
+  .bind(true)
+  .all()
+const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+```
+
+## Batch Operations
+
+```typescript
+// Multiple queries in single round trip (atomic transaction)
+const results = await env.DB.batch([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
+  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
+  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1),
+])
+```
+
+## Sessions API (Paid Plans)
+
+```typescript
+// Create long-running session for analytics/migrations (up to 15 minutes)
+const session = env.DB.withSession()
+try {
+  await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run()
+  await session.prepare('ANALYZE').run()
+} finally {
+  session.close() // Always close to release resources
+}
+```
+
+## Read Replication (Paid Plans)
+
+```typescript
+// Read from nearest replica for lower latency (automatic failover)
+const user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+
+// Writes always go to primary
+await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run()
+```
+
+## Platform Limits
+
+| Limit                 | Free Tier        | Paid Plans         |
+| --------------------- | ---------------- | ------------------ |
+| Database size         | 500 MB           | 10 GB per database |
+| Row size              | 1 MB max         | 1 MB max           |
+| Query timeout         | 30 seconds       | 30 seconds         |
+| Batch size            | 1,000 statements | 10,000 statements  |
+| Time Travel retention | 7 days           | 30 days            |
+| Read replicas         | Not available    | Yes (paid add-on)  |
+
+**Pricing**: $5/month per database beyond free tier + $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month
+
+## CLI Commands
+
+```bash
+# Database management
+wrangler d1 create <db-name>
+wrangler d1 list
+wrangler d1 delete <db-name>
+
+# Migrations
+wrangler d1 migrations create <db-name> <migration-name>    # Create new migration file
+wrangler d1 migrations apply <db-name> --remote             # Apply pending migrations
+wrangler d1 migrations apply <db-name> --local              # Apply locally
+wrangler d1 migrations list <db-name> --remote              # Show applied migrations
+
+# Direct SQL execution
+wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
+wrangler d1 execute <db-name> --local --file=./schema.sql
+
+# Backups & Import/Export
+wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export with schema
+wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
+wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time recovery
+
+# Development
+wrangler dev --persist-to=./.wrangler/state
+```
+
+## Reading Order
+
+**Start here**: Quick Start above → configuration.md (setup) → api.md (queries)
+
+**Common tasks**:
+
+- First time setup: configuration.md → Run migrations
+- Adding queries: api.md → Prepared statements
+- Pagination/caching: patterns.md
+- Production optimization: Read Replication + Sessions API (this file)
+- Debugging: gotchas.md
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev
+- [api.md](./api.md) - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling
+- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant, sessions, analytics
+- [gotchas.md](./gotchas.md) - SQL injection, limits by plan tier, performance, common errors
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handler patterns
+- [hyperdrive](../hyperdrive/) - Connection pooling for external databases