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

references/websocket-hibernation.md

View on GitHub
# WebSocket Hibernation API Deep Dive

Complete guide to WebSocket hibernation for cost savings.

---

## Why WebSocket Hibernation?

Traditional WebSocket connections keep the Durable Object **active in memory**, incurring duration charges even when idle.

**With Hibernation:**
- ✅ DO hibernates when idle (~10 seconds no activity)
- ✅ WebSocket clients **stay connected** to Cloudflare edge
- ✅ DO wakes up automatically when messages arrive
- ✅ **Massive cost savings** for long-lived connections

**Cost Example:**
- 1000 WebSocket connections for 1 hour
- Without hibernation: ~$0.50/hour (assuming 90% idle time)
- With hibernation: ~$0.05/hour
- **~90% savings**

---

## Hibernation Lifecycle

```
1. ACTIVE     → DO in memory, handling messages
2. IDLE       → No messages for ~10 seconds
3. HIBERNATE  → In-memory state cleared, WebSockets stay connected
4. WAKE       → New message → constructor runs → handler called
```

**CRITICAL:** In-memory state is **LOST** on hibernation!

---

## Enable Hibernation

### Use `ctx.acceptWebSocket()`

```typescript
// ✅ CORRECT: Enables hibernation
this.ctx.acceptWebSocket(server);

// ❌ WRONG: Standard API, NO hibernation
server.accept();
```

**Only works for server-side (incoming) WebSockets.**

---

## Handler Methods

### `webSocketMessage(ws, message)`

Called when WebSocket receives a message (even if hibernated).

```typescript
async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
  if (typeof message === 'string') {
    const data = JSON.parse(message);
    // Handle message
  }
}
```

**Parameters:**
- `ws` (WebSocket): The WebSocket that received the message
- `message` (string | ArrayBuffer): The message data

### `webSocketClose(ws, code, reason, wasClean)`

Called when WebSocket closes.

```typescript
async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void> {
  // Cleanup
  this.sessions.delete(ws);

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

**Parameters:**
- `ws` (WebSocket): The WebSocket that closed
- `code` (number): Close code
- `reason` (string): Close reason
- `wasClean` (boolean): True if closed cleanly

### `webSocketError(ws, error)`

Called on WebSocket errors (not disconnections).

```typescript
async webSocketError(ws: WebSocket, error: any): Promise<void> {
  console.error('WebSocket error:', error);
  this.sessions.delete(ws);
}
```

---

## Persist Metadata with Attachments

Use `serializeAttachment()` / `deserializeAttachment()` to persist per-WebSocket metadata across hibernation.

### Serialize on Accept

```typescript
const metadata = { userId: '123', username: 'Alice' };

// Persist metadata
server.serializeAttachment(metadata);

// Track in-memory
this.sessions.set(server, metadata);
```

### Deserialize in Constructor

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

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

  ctx.getWebSockets().forEach((ws) => {
    // Restore metadata
    const metadata = ws.deserializeAttachment();
    this.sessions.set(ws, metadata);
  });
}
```

**CRITICAL:** Metadata is **persisted to storage**, not just memory.

---

## Get Active WebSockets

```typescript
// Get all WebSockets accepted by this DO
const webSockets = this.ctx.getWebSockets();

console.log(`${webSockets.length} active connections`);

// Filter by tag (if tagged)
const taggedWs = this.ctx.getWebSockets('room:123');
```

---

## Tag WebSockets (Optional)

Tag WebSockets for grouping (e.g., by room, channel).

```typescript
// Accept with tag
this.ctx.acceptWebSocket(server, ['room:123']);

// Get by tag
const roomSockets = this.ctx.getWebSockets('room:123');

// Get all tags
const tags = ws.getTags();
```

---

## When Hibernation Does NOT Occur

Hibernation is **blocked** if:

❌ `setTimeout` or `setInterval` callbacks are pending
❌ In-progress `fetch()` request (awaited I/O)
❌ Standard WebSocket API used (not hibernation API)
❌ Request/event still being processed
❌ Outgoing WebSocket (DO is client, not server)

---

## Best Practices

### Minimize Constructor Work

Heavy work in constructor **delays wake-up**.

```typescript
// ✅ GOOD: Minimal constructor
constructor(ctx, env) {
  super(ctx, env);

  this.sessions = new Map();

  ctx.getWebSockets().forEach((ws) => {
    const metadata = ws.deserializeAttachment();
    this.sessions.set(ws, metadata);
  });
}

// ❌ BAD: Heavy work delays wake-up
constructor(ctx, env) {
  super(ctx, env);

  // Don't do expensive I/O here
  await this.loadLotsOfData();
}
```

### Use Alarms, Not setTimeout

```typescript
// ❌ WRONG: Prevents hibernation
setTimeout(() => {
  this.doSomething();
}, 60000);

// ✅ CORRECT: Use alarms
await this.ctx.storage.setAlarm(Date.now() + 60000);

async alarm() {
  this.doSomething();
}
```

### Persist Critical State

```typescript
// ❌ WRONG: Only in-memory (lost on hibernation)
this.userCount = 42;

// ✅ CORRECT: Persist to storage
await this.ctx.storage.put('userCount', 42);

// Or use serializeAttachment for per-WebSocket data
ws.serializeAttachment({ userId, username });
```

---

## Debugging Hibernation

### Check if DO is Hibernating

```typescript
// Log in constructor
constructor(ctx, env) {
  super(ctx, env);
  console.log('DO woke up! Active WebSockets:', ctx.getWebSockets().length);
}

// If you see this log frequently, DO is hibernating
```

### Common Issues

**Issue:** DO never hibernates (high duration charges)

**Possible Causes:**
- `setTimeout`/`setInterval` active
- In-progress `fetch()` requests
- Standard WebSocket API used (`ws.accept()` instead of `ctx.acceptWebSocket()`)

**Solution:** Check for blocking operations, use alarms instead.

---

## Limitations

⚠️ **Hibernation only for server-side WebSockets**
- DO must be WebSocket server (accept connections)
- Outgoing WebSockets (DO as client) **cannot hibernate**

⚠️ **In-memory state is lost**
- Restore state in constructor
- Use `serializeAttachment()` for per-WebSocket metadata
- Use storage for DO-wide state

⚠️ **No WebSocket Standard API** with hibernation
- Cannot use `addEventListener('message', ...)`
- Must use handler methods (`webSocketMessage`, etc.)

---

**Official Docs**: https://developers.cloudflare.com/durable-objects/best-practices/websockets/
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