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/websocket-hibernation-do.ts

View on GitHub
/**
 * WebSocket Hibernation Example: Chat Room
 *
 * Demonstrates:
 * - WebSocket Hibernation API
 * - ctx.acceptWebSocket() for cost savings
 * - WebSocket handler methods (webSocketMessage, webSocketClose, webSocketError)
 * - serializeAttachment / deserializeAttachment for metadata persistence
 * - State restoration in constructor after hibernation
 */

import { DurableObject, DurableObjectState } from 'cloudflare:workers';

interface Env {
  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
}

interface SessionMetadata {
  userId: string;
  username: string;
}

export class ChatRoom extends DurableObject<Env> {
  // In-memory state (restored after hibernation)
  sessions: Map<WebSocket, SessionMetadata>;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);

    // Restore WebSocket connections after hibernation
    this.sessions = new Map();

    // Get all active WebSockets and restore their metadata
    ctx.getWebSockets().forEach((ws) => {
      // Deserialize metadata (persisted via serializeAttachment)
      const metadata = ws.deserializeAttachment<SessionMetadata>();
      this.sessions.set(ws, metadata);
    });

    console.log(`ChatRoom constructor: restored ${this.sessions.size} connections`);
  }

  /**
   * Accept WebSocket connections
   */
  async fetch(request: Request): Promise<Response> {
    // Expect WebSocket upgrade request
    const upgradeHeader = request.headers.get('Upgrade');
    if (upgradeHeader !== 'websocket') {
      return new Response('Expected Upgrade: websocket', { status: 426 });
    }

    if (request.method !== 'GET') {
      return new Response('Expected GET method', { status: 400 });
    }

    // Get user info from URL parameters
    const url = new URL(request.url);
    const userId = url.searchParams.get('userId') || 'anonymous';
    const username = url.searchParams.get('username') || 'Anonymous';

    // Create WebSocket pair
    const webSocketPair = new WebSocketPair();
    const [client, server] = Object.values(webSocketPair);

    // CRITICAL: Use ctx.acceptWebSocket (NOT ws.accept())
    // This enables hibernation to save costs
    this.ctx.acceptWebSocket(server);

    // Serialize metadata to persist across hibernation
    const metadata: SessionMetadata = { userId, username };
    server.serializeAttachment(metadata);

    // Track in-memory (will be restored after hibernation)
    this.sessions.set(server, metadata);

    // Notify others that user joined
    this.broadcast({
      type: 'system',
      text: `${username} joined the room`,
      timestamp: Date.now(),
    }, server);

    // Send welcome message to new user
    server.send(JSON.stringify({
      type: 'system',
      text: `Welcome to the chat room! ${this.sessions.size} user(s) online.`,
      timestamp: Date.now(),
    }));

    // Return client WebSocket to browser
    return new Response(null, {
      status: 101,
      webSocket: client,
    });
  }

  /**
   * Called when WebSocket receives a message
   * This method is called even if the DO was hibernated
   */
  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
    const session = this.sessions.get(ws);

    if (!session) {
      console.error('WebSocket not found in sessions');
      return;
    }

    // Handle text messages
    if (typeof message === 'string') {
      try {
        const data = JSON.parse(message);

        if (data.type === 'chat') {
          // Broadcast chat message to all connections
          this.broadcast({
            type: 'chat',
            userId: session.userId,
            username: session.username,
            text: data.text,
            timestamp: Date.now(),
          });
        }

        if (data.type === 'typing') {
          // Broadcast typing indicator to others
          this.broadcast({
            type: 'typing',
            userId: session.userId,
            username: session.username,
          }, ws);
        }

      } catch (error) {
        console.error('Failed to parse message:', error);
      }
    }
  }

  /**
   * Called when WebSocket closes
   */
  async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void> {
    const session = this.sessions.get(ws);

    // Close the WebSocket
    ws.close(code, 'Durable Object closing WebSocket');

    // Remove from sessions
    this.sessions.delete(ws);

    // Notify others
    if (session) {
      this.broadcast({
        type: 'system',
        text: `${session.username} left the room`,
        timestamp: Date.now(),
      });
    }

    console.log(`WebSocket closed: ${session?.username || 'unknown'}, code: ${code}, clean: ${wasClean}`);
  }

  /**
   * Called on WebSocket errors
   */
  async webSocketError(ws: WebSocket, error: any): Promise<void> {
    console.error('WebSocket error:', error);

    const session = this.sessions.get(ws);
    this.sessions.delete(ws);

    if (session) {
      this.broadcast({
        type: 'system',
        text: `${session.username} disconnected (error)`,
        timestamp: Date.now(),
      });
    }
  }

  /**
   * Broadcast message to all connections (except sender)
   */
  private broadcast(message: any, except?: WebSocket): void {
    const messageStr = JSON.stringify(message);

    this.sessions.forEach((session, ws) => {
      if (ws !== except && ws.readyState === WebSocket.OPEN) {
        ws.send(messageStr);
      }
    });
  }
}

// CRITICAL: Export the class
export default ChatRoom;

/**
 * Worker that creates and routes to chat rooms
 */
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    // Extract room ID from path (e.g., /room/abc123)
    const match = url.pathname.match(/^\/room\/([^/]+)/);

    if (!match) {
      return new Response('Usage: /room/{roomId}?userId={userId}&username={username}', {
        status: 400,
      });
    }

    const roomId = match[1];

    // Get or create chat room DO
    const id = env.CHAT_ROOM.idFromName(roomId);
    const stub = env.CHAT_ROOM.get(id);

    // Forward request to DO
    return stub.fetch(request);
  },
};
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