Durable Objects Pattern Checker

Durable Objects Pattern Checker SKILL

Activation Patterns

This SKILL automatically activates when:

• Durable Object imports or exports are detected
• DO stub creation and usage patterns
• State management in Durable Objects
• ID generation patterns (idFromName, newUniqueId)
• Hibernation and lifecycle patterns
• WebSocket or real-time features with DOs

Expertise Provided

Durable Objects Best Practices

• State Management: Ensures proper state persistence and consistency
• ID Generation: Validates correct ID patterns for different use cases
• Hibernation: Checks for proper hibernation implementation
• Lifecycle Management: Validates constructor, fetch, and alarm handling
• Strong Consistency: Ensures DOs are used when strong consistency is needed
• Performance: Identifies DO performance anti-patterns

Specific Checks Performed

❌ Durable Objects Anti-Patterns

// These patterns trigger immediate alerts:
// Using DOs for stateless operations
export default {
  async fetch(request: Request, env: Env) {
    const id = env.COUNTER.newUniqueId();  // New DO every request!
    const stub = env.COUNTER.get(id);
    return stub.fetch(request);  // Overkill for simple counter
  }
}

// Missing hibernation for long-lived DOs
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    // Missing this.state.storage.setAlarm() for hibernation
  }
}

✅ Durable Objects Best Practices

// These patterns are validated as correct:
// Reuse DO instances for stateful coordination
export default {
  async fetch(request: Request, env: Env) {
    const ip = request.headers.get('CF-Connecting-IP');
    const id = env.RATE_LIMITER.idFromName(ip);  // Reuse same DO
    const stub = env.RATE_LIMITER.get(id);
    return stub.fetch(request);
  }
}

// Proper hibernation implementation
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.env = env;
    
    // Set alarm for hibernation after inactivity
    this.state.storage.setAlarm(Date.now() + 30000); // 30 seconds
  }
  
  alarm() {
    // DO will hibernate after alarm
  }
}

Integration Points

Complementary to Existing Components

• cloudflare-architecture-strategist agent: Handles complex DO architecture, SKILL provides immediate pattern validation
• edge-performance-oracle agent: Handles DO performance analysis, SKILL ensures correct usage patterns
• workers-binding-validator SKILL: Ensures DO bindings are correct, SKILL validates usage patterns

Escalation Triggers

• Complex DO architecture questions → cloudflare-architecture-strategist agent
• DO performance troubleshooting → edge-performance-oracle agent
• DO migration strategies → cloudflare-architecture-strategist agent

Validation Rules

P1 - Critical (Will Cause Issues)

• New Unique ID Per Request: Creating new DO for every request
• Missing Hibernation: Long-lived DOs without hibernation
• State Leaks: State not properly persisted to storage
• Blocking Operations: Synchronous operations in DO fetch

P2 - High (Performance/Correctness Issues)

• Wrong ID Pattern: Using newUniqueId when idFromName is appropriate
• Stateless DOs: Using DOs for operations that don't need state
• Missing Error Handling: DO operations without proper error handling
• Alarm Misuse: Incorrect alarm patterns for hibernation

P3 - Medium (Best Practices)

• State Size: Large state objects that impact performance
• Concurrency: Missing concurrency control for shared state
• Cleanup: Missing cleanup in DO lifecycle

Remediation Examples

Fixing New Unique ID Per Request

// ❌ Critical: New DO for every request (expensive and wrong)
export default {
  async fetch(request: Request, env: Env) {
    const userId = getUserId(request);
    
    // Creates new DO instance for every request!
    const id = env.USER_SESSION.newUniqueId();
    const stub = env.USER_SESSION.get(id);
    
    return stub.fetch(request);
  }
}

// ✅ Correct: Reuse DO for same entity
export default {
  async fetch(request: Request, env: Env) {
    const userId = getUserId(request);
    
    // Reuse same DO for this user
    const id = env.USER_SESSION.idFromName(userId);
    const stub = env.USER_SESSION.get(id);
    
    return stub.fetch(request);
  }
}

Fixing Missing Hibernation

// ❌ High: DO never hibernates (wastes resources)
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.env = env;
    this.messages = [];
  }
  
  async fetch(request) {
    // Handle chat messages...
    // But never hibernates - stays in memory forever!
  }
}

// ✅ Correct: Implement hibernation
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.env = env;
    
    // Load persisted state
    this.loadState();
    
    // Set alarm for hibernation after inactivity
    this.resetHibernationTimer();
  }
  
  async loadState() {
    const messages = await this.state.storage.get('messages');
    this.messages = messages || [];
  }
  
  resetHibernationTimer() {
    // Reset alarm for 30 seconds from now
    this.state.storage.setAlarm(Date.now() + 30000);
  }
  
  async fetch(request) {
    // Reset timer on activity
    this.resetHibernationTimer();
    
    // Handle chat messages...
    return new Response('Message processed');
  }
  
  async alarm() {
    // Persist state before hibernation
    await this.state.storage.put('messages', this.messages);
    // DO will hibernate after this method returns
  }
}

Fixing Wrong ID Pattern

// ❌ High: Using newUniqueId for named resources
export default {
  async fetch(request: Request, env: Env) {
    const roomId = new URL(request.url).searchParams.get('room');
    
    // Wrong: Creates new DO for same room name
    const id = env.CHAT_ROOM.newUniqueId();
    const stub = env.CHAT_ROOM.get(id);
    
    return stub.fetch(request);
  }
}

// ✅ Correct: Use idFromName for named resources
export default {
  async fetch(request: Request, env: Env) {
    const roomId = new URL(request.url).searchParams.get('room');
    
    // Correct: Same DO for same room name
    const id = env.CHAT_ROOM.idFromName(roomId);
    const stub = env.CHAT_ROOM.get(id);
    
    return stub.fetch(request);
  }
}

Fixing State Persistence

// ❌ Critical: State not persisted (lost on hibernation)
export class Counter {
  constructor(state, env) {
    this.state = state;
    this.count = 0;  // Not persisted!
  }
  
  async fetch(request) {
    if (request.url.endsWith('/increment')) {
      this.count++;  // Lost when DO hibernates!
      return new Response(`Count: ${this.count}`);
    }
  }
}

// ✅ Correct: Persist state to storage
export class Counter {
  constructor(state, env) {
    this.state = state;
  }
  
  async fetch(request) {
    if (request.url.endsWith('/increment')) {
      // Persist to storage
      const currentCount = (await this.state.storage.get('count')) || 0;
      const newCount = currentCount + 1;
      await this.state.storage.put('count', newCount);
      
      return new Response(`Count: ${newCount}`);
    }
    
    if (request.url.endsWith('/get')) {
      const count = await this.state.storage.get('count') || 0;
      return new Response(`Count: ${count}`);
    }
  }
}

Fixing Stateless DO Usage

// ❌ High: Using DO for stateless operation (overkill)
export default {
  async fetch(request: Request, env: Env) {
    // Using DO for simple API call - unnecessary!
    const id = env.API_PROXY.newUniqueId();
    const stub = env.API_PROXY.get(id);
    return stub.fetch(request);
  }
}

// ✅ Correct: Handle stateless operations in Worker
export default {
  async fetch(request: Request, env: Env) {
    // Simple API call - handle directly in Worker
    const response = await fetch('https://api.example.com/data');
    return response;
  }
}

// ✅ Correct: Use DO for actual stateful coordination
export default {
  async fetch(request: Request, env: Env) {
    const ip = request.headers.get('CF-Connecting-IP');
    
    // Rate limiting needs state - perfect for DO
    const id = env.RATE_LIMITER.idFromName(ip);
    const stub = env.RATE_LIMITER.get(id);
    
    return stub.fetch(request);
  }
}

Durable Objects Use Cases

Use Durable Objects When:

• Strong Consistency required (rate limiting, counters)
• Stateful Coordination (chat rooms, game sessions)
• Real-time Features (WebSockets, collaboration)
• Distributed Locks (coordination between requests)
• Long-running Operations (background processing)

Don't Use Durable Objects When:

• Stateless Operations (simple API calls)
• Read-heavy Caching (use KV instead)
• Large File Storage (use R2 instead)
• Simple Key-Value (use KV instead)

MCP Server Integration

When Cloudflare MCP server is available:

• Query DO performance metrics and best practices
• Get latest hibernation patterns and techniques
• Check DO usage limits and quotas
• Analyze DO performance in production

Benefits

Immediate Impact

• Prevents Resource Waste: Catches DO anti-patterns that waste resources
• Ensures Correctness: Validates state persistence and consistency
• Improves Performance: Identifies performance issues in DO usage

Long-term Value

• Consistent DO Patterns: Ensures all DO usage follows best practices
• Better Resource Management: Proper hibernation and lifecycle management
• Reduced Costs: Efficient DO usage reduces resource consumption

Usage Examples

During DO Creation

// Developer types: const id = env.MY_DO.newUniqueId();
// SKILL immediately activates: "⚠️ HIGH: Using newUniqueId for every request. Consider idFromName for named resources or if this should be stateless."

During State Management

// Developer types: this.count = 0; in constructor
// SKILL immediately activates: "❌ CRITICAL: State not persisted to storage. Use this.state.storage.put() to persist data."

During Hibernation

// Developer types: DO without alarm() method
// SKILL immediately activates: "⚠️ HIGH: Durable Object missing hibernation. Add alarm() method and setAlarm() for resource efficiency."

Performance Targets

DO Creation

• Excellent: Reuse existing DOs (idFromName)
• Good: Minimal new DO creation
• Acceptable: Appropriate DO usage patterns
• Needs Improvement: Creating new DOs per request

State Persistence

• Excellent: All state persisted to storage
• Good: Critical state persisted
• Acceptable: Basic state management
• Needs Improvement: State not persisted

Hibernation

• Excellent: Proper hibernation implementation
• Good: Basic hibernation setup
• Acceptable: Some hibernation consideration
• Needs Improvement: No hibernation (resource waste)

This SKILL ensures Durable Objects are used correctly by providing immediate, autonomous validation of DO patterns, preventing common mistakes and ensuring efficient state management.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.