Skip to content

secondsky/claude-skills / plugins/cloudflare-durable-objects/skills/cloudflare-durable-objects

cloudflare-durable-objects

Verified

Cloudflare Durable Objects for stateful coordination and real-time apps. Use for chat, multiplayer games, WebSocket hibernation, or encountering class export, migration, alarm errors.

FileKindSize
SKILL.mdskill md21.6 KB
references/advanced-sql-patterns.mdmarkdown15.8 KB
references/alarms-api.mdmarkdown6.5 KB
references/best-practices.mdmarkdown8.5 KB
references/common-patterns.mdmarkdown16.7 KB
references/data-modeling.mdmarkdown16.9 KB
references/error-codes.mdmarkdown7.7 KB
references/gradual-deployments.mdmarkdown13.9 KB
references/migration-cheatsheet.mdmarkdown3.2 KB
references/migrations-guide.mdmarkdown7.3 KB
references/monitoring-debugging.mdmarkdown18.2 KB
references/performance-optimization.mdmarkdown16.2 KB
references/rpc-metadata.mdmarkdown16.9 KB
references/rpc-patterns.mdmarkdown6.5 KB
references/security-best-practices.mdmarkdown15.9 KB
references/state-api-reference.mdmarkdown6.0 KB
references/stubs-routing.mdmarkdown10.6 KB
references/top-errors.mdmarkdown10.2 KB
references/typescript-config.mdmarkdown8.3 KB
references/vitest-testing.mdmarkdown18.1 KB
references/websocket-hibernation.mdmarkdown6.3 KB
references/wrangler-commands.mdmarkdown3.4 KB
scripts/check-versions.shexecutablescript593 B
scripts/migration-generator.shexecutablescript13.4 KB
scripts/setup-vitest-do.shexecutablescript10.2 KB
scripts/validate-do-config.shexecutablescript10.0 KB
templates/alarms-api-do.tsscript6.1 KB
templates/basic-do.tsscript2.9 KB
templates/gradual-deployment-config.jsoncother10.4 KB
templates/location-hints.tsscript6.8 KB
templates/multi-do-coordination.tsscript7.8 KB
templates/package.jsonmanifest384 B
templates/rpc-metadata-do.tsscript10.8 KB
templates/rpc-vs-fetch.tsscript6.0 KB
templates/state-api-patterns.tsscript5.8 KB
templates/ttl-cleanup-do.tsscript17.6 KB
templates/vitest-do-test.tsscript12.3 KB
templates/websocket-hibernation-do.tsscript6.0 KB
templates/wrangler-do-config.jsoncother2.0 KB

templates/gradual-deployment-config.jsonc

View on GitHub
/**
 * Gradual Deployment Configuration for Cloudflare Workers
 *
 * Enables:
 * - Traffic splitting between versions (canary deployments)
 * - Version-specific Durable Object routing
 * - Safe rollout strategies
 * - Quick rollback capability
 *
 * Critical Notes:
 * ⚠️ Durable Objects: Only ONE version runs per DO instance
 * ⚠️ Migrations: CANNOT be uploaded as versions
 * ⚠️ Version Affinity: Use ctx.id.name patterns to prevent version skew
 *
 * See: references/gradual-deployments.md for complete guide
 */

{
  // ============================================================================
  // Example 1: Basic Canary Deployment (10% Traffic to New Version)
  // ============================================================================

  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-10-01",

  /**
   * Upload new version without traffic:
   * wrangler versions upload --tag v2 --message "New feature"
   *
   * Deploy with 10% traffic:
   * wrangler versions deploy v2@10% --message "Canary deployment"
   *
   * Result:
   * - 90% of requests go to previous version
   * - 10% of requests go to v2 (canary)
   * - Monitor metrics for errors/performance
   */
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",
        "class_name": "Counter",
        "script_name": "my-worker"
        // No version specified: All versions share DO instances
      }
    ]
  },

  // ============================================================================
  // Example 2: Progressive Rollout Strategy
  // ============================================================================

  /**
   * Phase 1: Upload new version
   * wrangler versions upload --tag v3.0.0 --message "Major feature release"
   *
   * Phase 2: Canary (5% traffic)
   * wrangler versions deploy v3.0.0@5% --message "Canary testing"
   * - Monitor for 1 hour
   * - Check error rates, latency, DO behavior
   *
   * Phase 3: Expand (25% traffic)
   * wrangler versions deploy v3.0.0@25% --message "Expand rollout"
   * - Monitor for 4 hours
   * - Verify DO coordination patterns work
   *
   * Phase 4: Majority (75% traffic)
   * wrangler versions deploy v3.0.0@75% --message "Majority rollout"
   * - Monitor for 12 hours
   * - Final checks before full rollout
   *
   * Phase 5: Full Deployment (100% traffic)
   * wrangler versions deploy v3.0.0@100% --message "Full rollout"
   * - All traffic on new version
   * - Old version still available for quick rollback
   *
   * Rollback (if issues detected):
   * wrangler versions deploy v2.5.0@100% --message "Rollback to stable"
   */

  // ============================================================================
  // Example 3: Version Affinity Pattern for Durable Objects
  // ============================================================================

  /**
   * Problem: DO instance sees requests from multiple versions
   * Solution: Use version affinity to route specific DOs to specific versions
   *
   * Implementation: Hash DO name to determine version
   */

  // In your Worker code:
  /*
  export default {
    async fetch(request: Request, env: Env): Promise<Response> {
      const url = new URL(request.url);
      const doName = url.searchParams.get("doName");

      // Version affinity: Route based on DO name hash
      const hash = await hashString(doName);
      const useNewVersion = hash % 100 < 10; // 10% of DOs on new version

      if (useNewVersion) {
        // Route to new version explicitly
        // This requires version-specific bindings
        const id = env.COUNTER_V2.idFromName(doName);
        const stub = env.COUNTER_V2.get(id);
        return stub.fetch(request);
      } else {
        // Route to stable version
        const id = env.COUNTER.idFromName(doName);
        const stub = env.COUNTER.get(id);
        return stub.fetch(request);
      }
    }
  };

  async function hashString(str: string): Promise<number> {
    const encoder = new TextEncoder();
    const data = encoder.encode(str);
    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
    const hashArray = Array.from(new Uint8Array(hashBuffer));
    return hashArray[0]; // Use first byte
  }
  */

  // Configuration for version-specific bindings:
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",
        "class_name": "Counter",
        "script_name": "my-worker"
        // Stable version binding
      },
      {
        "name": "COUNTER_V2",
        "class_name": "CounterV2",
        "script_name": "my-worker"
        // New version binding (separate class name required)
      }
    ]
  },

  // ============================================================================
  // Example 4: Dashboard-Based Gradual Deployment
  // ============================================================================

  /**
   * Alternative: Use Cloudflare Dashboard for visual traffic splitting
   *
   * Steps:
   * 1. Navigate to Workers & Pages > your-worker > Deployments
   * 2. Click "Create Deployment"
   * 3. Upload new version
   * 4. Use traffic slider to split traffic:
   *    - Drag to 10% for canary
   *    - Drag to 50% for A/B testing
   *    - Drag to 100% for full rollout
   * 5. Click "Save" to apply changes
   *
   * Benefits:
   * - Visual interface (easier than CLI)
   * - Real-time metrics in dashboard
   * - Quick rollback with one click
   *
   * Drawbacks:
   * - Less reproducible than wrangler CLI
   * - No version control for traffic splits
   * - Manual process (not CI/CD friendly)
   */

  // ============================================================================
  // Example 5: Feature Flags with Gradual Deployment
  // ============================================================================

  /**
   * Combine gradual deployment with feature flags for fine-grained control
   */

  // In your Worker code:
  /*
  export default {
    async fetch(request: Request, env: Env): Promise<Response> {
      const url = new URL(request.url);
      const userId = url.searchParams.get("userId");

      // Feature flag: Enable new chat feature for 10% of users
      const enableNewChat = await shouldEnableFeature(userId, "new-chat", 10);

      if (enableNewChat) {
        // Use new chat implementation
        const id = env.CHAT_ROOM_V2.idFromName(`room-${userId}`);
        const stub = env.CHAT_ROOM_V2.get(id);
        return stub.fetch(request);
      } else {
        // Use stable chat implementation
        const id = env.CHAT_ROOM.idFromName(`room-${userId}`);
        const stub = env.CHAT_ROOM.get(id);
        return stub.fetch(request);
      }
    }
  };

  async function shouldEnableFeature(
    userId: string,
    featureName: string,
    percentage: number
  ): Promise<boolean> {
    const key = `${userId}:${featureName}`;
    const hash = await hashString(key);
    return (hash % 100) < percentage;
  }
  */

  // ============================================================================
  // Example 6: Monitoring Configuration for Gradual Deployments
  // ============================================================================

  /**
   * Use wrangler tail to monitor version-specific traffic
   */

  /**
   * Terminal 1: Monitor stable version
   * wrangler tail --version-id <stable-version-id>
   *
   * Terminal 2: Monitor canary version
   * wrangler tail --version-id <canary-version-id>
   *
   * Compare:
   * - Error rates between versions
   * - Latency (p50, p95, p99)
   * - DO creation rate
   * - WebSocket connection count
   */

  // Add structured logging for version tracking:
  /*
  console.log(JSON.stringify({
    version: env.VERSION, // Set via environment variable
    event: "do-created",
    doName: id.toString(),
    timestamp: Date.now()
  }));
  */

  // ============================================================================
  // Example 7: Rollback Strategy
  // ============================================================================

  /**
   * Automated Rollback Criteria:
   *
   * 1. Error Rate Spike:
   *    - Canary error rate > 2x stable error rate
   *    - Action: Immediate rollback
   *    - Command: wrangler versions deploy <stable-version>@100%
   *
   * 2. Latency Degradation:
   *    - p95 latency > 2x stable version
   *    - Action: Reduce canary traffic or rollback
   *    - Command: wrangler versions deploy <canary-version>@5%
   *
   * 3. DO Creation Failures:
   *    - New version fails to create DOs
   *    - Action: Immediate rollback
   *    - Reason: Likely migration or binding issue
   *
   * 4. WebSocket Errors:
   *    - WebSocket hibernation failures
   *    - Action: Rollback and investigate
   *    - Check: alarm handlers, setTimeout/setInterval usage
   *
   * Manual Rollback (Emergency):
   * wrangler versions deploy <previous-stable>@100% --message "Emergency rollback"
   */

  // ============================================================================
  // Best Practices Summary
  // ============================================================================

  /**
   * ✅ DO:
   * - Upload versions before deploying traffic
   * - Start with 5-10% canary traffic
   * - Monitor for 1+ hour before expanding
   * - Use version affinity for DO routing
   * - Keep stable version available for quick rollback
   * - Log version info in all requests
   * - Test DO coordination patterns in canary
   *
   * ❌ DON'T:
   * - Deploy migrations as versions (use separate wrangler deploy)
   * - Split traffic to versions with incompatible schemas
   * - Roll out to 100% without testing at lower percentages
   * - Mix versions for same DO instance without affinity
   * - Forget to monitor error rates during rollout
   * - Deploy breaking changes without version affinity
   * - Use gradual deployments for urgent hotfixes (use wrangler deploy)
   */

  // ============================================================================
  // Wrangler Commands Reference
  // ============================================================================

  /**
   * Upload version (no traffic):
   * wrangler versions upload --tag <version-tag> --message "<description>"
   *
   * Deploy with traffic split:
   * wrangler versions deploy <version-tag>@<percentage> --message "<reason>"
   *
   * List versions:
   * wrangler versions list
   *
   * View version details:
   * wrangler versions view <version-id>
   *
   * Rollback to previous version:
   * wrangler versions deploy <previous-version>@100% --message "Rollback"
   *
   * Monitor version traffic:
   * wrangler tail --version-id <version-id>
   */
}
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall