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/rpc-patterns.md

View on GitHub
# RPC vs Fetch Patterns - Decision Guide

When to use RPC methods vs HTTP fetch handler.

---

## Quick Decision Matrix

| Requirement | Use | Why |
|-------------|-----|-----|
| **New project (compat_date >= 2024-04-03)** | RPC | Simpler, type-safe |
| **Type safety important** | RPC | TypeScript knows method signatures |
| **Simple method calls** | RPC | Less boilerplate |
| **WebSocket upgrade needed** | Fetch | Requires HTTP upgrade |
| **Complex HTTP routing** | Fetch | Full request/response control |
| **Need headers, cookies, status codes** | Fetch | HTTP-specific features |
| **Legacy compatibility** | Fetch | Pre-2024-04-03 projects |
| **Auto-serialization wanted** | RPC | Handles structured data automatically |

---

## RPC Pattern (Recommended)

### Enable RPC

Set compatibility date `>= 2024-04-03`:

```jsonc
{
  "compatibility_date": "2025-10-22"
}
```

### Define RPC Methods

```typescript
export class MyDO extends DurableObject {
  // Public methods are automatically exposed as RPC
  async increment(): Promise<number> {
    // ...
  }

  async get(): Promise<number> {
    // ...
  }

  // Private methods are NOT exposed
  private async internalHelper(): Promise<void> {
    // ...
  }
}
```

### Call from Worker

```typescript
const stub = env.MY_DO.getByName('my-instance');

// Direct method calls
const count = await stub.increment();
const value = await stub.get();
```

### Advantages

✅ **Type-safe** - TypeScript knows method signatures
✅ **Less boilerplate** - No HTTP ceremony
✅ **Auto-serialization** - Structured data works seamlessly
✅ **Exception propagation** - Errors thrown in DO received in Worker

### Limitations

❌ Cannot use HTTP-specific features (headers, status codes)
❌ Cannot handle WebSocket upgrades
❌ Requires compat_date >= 2024-04-03

---

## HTTP Fetch Pattern

### Define fetch() Handler

```typescript
export class MyDO extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/increment' && request.method === 'POST') {
      // ...
      return new Response(JSON.stringify({ count }), {
        headers: { 'content-type': 'application/json' },
      });
    }

    return new Response('Not found', { status: 404 });
  }
}
```

### Call from Worker

```typescript
const stub = env.MY_DO.getByName('my-instance');

const response = await stub.fetch('https://fake-host/increment', {
  method: 'POST',
});

const data = await response.json();
```

### Advantages

✅ **Full HTTP control** - Headers, cookies, status codes
✅ **WebSocket upgrades** - Required for WebSocket server
✅ **Complex routing** - Use path, method, headers for routing
✅ **Legacy compatible** - Works with pre-2024-04-03

### Limitations

❌ More boilerplate - Manual JSON parsing, response creation
❌ No type safety - Worker doesn't know what methods exist
❌ Manual error handling - Must parse HTTP status codes

---

## Hybrid Pattern (Both)

Use both RPC and fetch() in same DO:

```typescript
export class MyDO extends DurableObject {
  // RPC method for simple calls
  async getStatus(): Promise<{ active: boolean }> {
    return { active: true };
  }

  // Fetch for WebSocket upgrade
  async fetch(request: Request): Promise<Response> {
    const upgradeHeader = request.headers.get('Upgrade');

    if (upgradeHeader === 'websocket') {
      // Handle WebSocket upgrade
      const pair = new WebSocketPair();
      const [client, server] = Object.values(pair);

      this.ctx.acceptWebSocket(server);

      return new Response(null, {
        status: 101,
        webSocket: client,
      });
    }

    return new Response('Not found', { status: 404 });
  }
}
```

**Call from Worker:**

```typescript
const stub = env.MY_DO.getByName('my-instance');

// Use RPC for status
const status = await stub.getStatus();

// Use fetch for WebSocket upgrade
const response = await stub.fetch(request);
```

---

## RPC Serialization

**What works:**
- ✅ Primitives (string, number, boolean, null)
- ✅ Objects (plain objects)
- ✅ Arrays
- ✅ Nested structures
- ✅ Date objects
- ✅ ArrayBuffer, Uint8Array, etc.

**What doesn't work:**
- ❌ Functions
- ❌ Symbols
- ❌ Circular references
- ❌ Class instances (except basic types)

**Example:**

```typescript
// ✅ WORKS
async getData(): Promise<{ users: string[]; count: number }> {
  return {
    users: ['alice', 'bob'],
    count: 2,
  };
}

// ❌ DOESN'T WORK
async getFunction(): Promise<() => void> {
  return () => console.log('hello');  // Functions not serializable
}
```

---

## Error Handling

### RPC Error Handling

```typescript
// In DO
async doWork(): Promise<void> {
  if (somethingWrong) {
    throw new Error('Something went wrong');
  }
}

// In Worker
try {
  await stub.doWork();
} catch (error) {
  console.error('RPC error:', error.message);
  // Error propagated from DO
}
```

### Fetch Error Handling

```typescript
// In DO
async fetch(request: Request): Promise<Response> {
  if (somethingWrong) {
    return new Response(JSON.stringify({ error: 'Something went wrong' }), {
      status: 500,
    });
  }

  return new Response('OK');
}

// In Worker
const response = await stub.fetch(request);

if (!response.ok) {
  const error = await response.json();
  console.error('Fetch error:', error);
}
```

---

## Migration from Fetch to RPC

**Before (Fetch):**

```typescript
export class Counter extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/increment') {
      let count = await this.ctx.storage.get<number>('count') || 0;
      count += 1;
      await this.ctx.storage.put('count', count);

      return new Response(JSON.stringify({ count }), {
        headers: { 'content-type': 'application/json' },
      });
    }

    return new Response('Not found', { status: 404 });
  }
}
```

**After (RPC):**

```typescript
export class Counter extends DurableObject {
  async increment(): Promise<number> {
    let count = await this.ctx.storage.get<number>('count') || 0;
    count += 1;
    await this.ctx.storage.put('count', count);
    return count;
  }
}

// Worker before:
const response = await stub.fetch('https://fake-host/increment');
const { count } = await response.json();

// Worker after:
const count = await stub.increment();
```

**Benefits:**
- ✅ ~60% less code
- ✅ Type-safe
- ✅ Cleaner, more maintainable

---

**Official Docs**: https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/
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: 197kUpdated 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