Durable Objects в Cloudflare

Помогает писать и ревьюить Durable Objects в Cloudflare: объект на сущность, хранилище SQLite и миграции, RPC-методы, alarms, WebSocket и тесты на Vitest. Для случаев, когда приложению на Workers нужны общее состояние и координация.

РазработкаПак: Скиллы Cloudflare184 строкиdurable-objects
Автор
Источник
cloudflare/skills/skills/durable-objects @ 5108325
Лицензия
Apache-2.0

Об этом скилле

Что делает

Скилл помогает агенту писать, отлаживать и ревьюить Durable Objects в Cloudflare — классы, которые держат состояние и хранилище одной сущности, например чат-комнаты или пользователя. В SKILL.md перечислено, где они к месту: координация, строгая согласованность для складских остатков или бронирований, хранилище на сущность, WebSocket, отложенная работа для каждой сущности.

Основное — семь правил. Первые четыре: один объект на единицу координации, а не один глобальный; getByName() для детерминированной маршрутизации; хранилище SQLite через миграции new_sqlite_classes; blockConcurrencyWhile() только для схемы в конструкторе. Ещё три: RPC-методы вместо обработчика fetch(); сначала запись в хранилище, потом в память; один alarm на объект, потому что setAlarm() заменяет прежний. Антипаттерны добавляют: никаких await между связанными записями — это ломает атомарность — и никакого внешнего I/O внутри blockConcurrencyWhile(). Доступ определяется тем Worker, который реализует объект; отдельных ролей нет.

references/rules.md сводит вопросы проектирования — от выбора между SQLite и старым KV-хранилищем до миграций и гибернации WebSocket — к страницам документации. testing.md ведёт к документации интеграции с Vitest и перечисляет, что проверять: например, состояние между вызовами и alarms без ожидания реального времени. workers.md — сторона Worker: конфигурация с биндингами KV, R2 и D1, валидация на Zod, CORS, таймауты, трейсы и Local Explorer. skill-feedback.md отправляет сообщение об ошибке в cloudflare/skills после того, как вы одобрите текст.

Когда включать и когда не надо

Для нового класса Durable Object, alarms, RPC и обработчиков WebSocket, миграций и ревью готовых объектов.

Сам скилл не советует их для обработчиков без состояния, максимального географического распределения и веерной рассылки множества независимых запросов.

Как поставить и вызвать

Команда установки ниже скачивает SKILL.md, четыре справочника и лицензию. Агент читает документацию по ссылкам, так что нужен доступ в сеть. Вызвать вручную:

  • Claude Code: /durable-objects или попросить скилл по имени.
  • Codex: $durable-objects.
  • Cursor: наберите / в чате Agent и выберите durable-objects.

Пример: /durable-objects Спроектируй объект чат-комнаты с историей сообщений в SQLite и alarm на случай бездействия.

Чем отличается от похожих

Agents SDK от Cloudflare построен на тех же объектах: каждый класс агента — это Durable Object, к которому добавлены синхронизация состояния, расписания и RPC; этот скилл — для тех, кто пишет объекты сам. Лучшие практики Cloudflare Workers отвечают за Worker вокруг объектов и вопросы по Durable Objects отправляют сюда; учтите, что workers.md описывает Env вручную, а тот скилл считает это антипаттерном и предлагает wrangler types. Функции Neon Functions тоже держат WebSocket-соединения и состояние в памяти, но в одной долгоживущей функции рядом с Postgres, а не в отдельном объекте на сущность.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/durable-objects/SKILL.md https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md -o ~/.claude/skills/durable-objects/LICENSE https://anymodel.org/en/skills/cloudflare/durable-objects/LICENSE -o ~/.claude/skills/durable-objects/references/rules.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/rules.md -o ~/.claude/skills/durable-objects/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/skill-feedback.md -o ~/.claude/skills/durable-objects/references/testing.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/testing.md -o ~/.claude/skills/durable-objects/references/workers.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/workers.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/durable-objects/SKILL.md https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md -o ~/.agents/skills/durable-objects/LICENSE https://anymodel.org/en/skills/cloudflare/durable-objects/LICENSE -o ~/.agents/skills/durable-objects/references/rules.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/rules.md -o ~/.agents/skills/durable-objects/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/skill-feedback.md -o ~/.agents/skills/durable-objects/references/testing.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/testing.md -o ~/.agents/skills/durable-objects/references/workers.md https://anymodel.org/en/skills/cloudflare/durable-objects/references/workers.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/rules.md','references/skill-feedback.md','references/testing.md','references/workers.md') { $p = Join-Path "$HOME\.claude\skills\durable-objects" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/durable-objects/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/rules.md','references/skill-feedback.md','references/testing.md','references/workers.md') { $p = Join-Path "$HOME\.agents\skills\durable-objects" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/durable-objects/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/cloudflare/durable-objects/SKILL.md

SKILL.md

Исходник

Durable Objects

Build stateful, coordinated applications on Cloudflare's edge using Durable Objects.

Retrieval Sources

Your knowledge of Durable Objects APIs and configuration may be outdated. Prefer retrieval over pre-training for any Durable Objects task.

Resource URL
Docs https://developers.cloudflare.com/durable-objects/index.md
API Reference https://developers.cloudflare.com/durable-objects/api/index.md
Best Practices https://developers.cloudflare.com/durable-objects/best-practices/index.md
Examples https://developers.cloudflare.com/durable-objects/examples/index.md
Roles and permissions https://developers.cloudflare.com/workers/authorization/durable-objects/index.md

Fetch the relevant doc page when implementing features.

When to Use

  • Creating new Durable Object classes for stateful coordination
  • Implementing RPC methods, alarms, or WebSocket handlers
  • Reviewing existing DO code for best practices
  • Configuring wrangler.jsonc/toml for DO bindings and migrations
  • Writing tests with Cloudflare’s Vitest integration
  • Designing sharding strategies and parent-child relationships

Reference Documentation

  • ./references/rules.md - Core rules, storage, concurrency, RPC, alarms
  • Testing reference - Current Vitest documentation, migration choices, and test selection
  • Workers reference - Workers handlers, types, configuration, tracing, and local debugging

Search: blockConcurrencyWhile, idFromName, getByName, setAlarm, sql.exec

Core Principles

Use Durable Objects For

Need Example
Coordination Chat rooms, multiplayer games, collaborative docs
Strong consistency Inventory, booking systems, turn-based games
Per-entity storage Multi-tenant SaaS, per-user data
Persistent connections WebSockets, real-time notifications
Scheduled work per entity Subscription renewals, game timeouts

Do NOT Use For

  • Stateless request handling (use plain Workers)
  • Maximum global distribution needs
  • High fan-out independent requests

Quick Reference

Wrangler Configuration

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
}

Basic Durable Object Pattern

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DO: DurableObjectNamespace<MyDurableObject>;
}

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS items (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          data TEXT NOT NULL
        )
      `);
    });
  }

  async addItem(data: string): Promise<number> {
    const result = this.ctx.storage.sql.exec<{ id: number }>(
      "INSERT INTO items (data) VALUES (?) RETURNING id",
      data
    );
    return result.one().id;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.MY_DO.getByName("my-instance");
    const id = await stub.addItem("hello");
    return Response.json({ id });
  },
};

Critical Rules

  1. Model around coordination atoms - One DO per chat room/game/user, not one global DO
  2. Use getByName() for deterministic routing - Same input = same DO instance
  3. Use SQLite storage - Configure new_sqlite_classes in migrations
  4. Initialize in constructor - Use blockConcurrencyWhile() for schema setup only
  5. Use RPC methods - Not fetch() handler (compatibility date >= 2024-04-03)
  6. Persist first, cache second - Always write to storage before updating in-memory state
  7. One alarm per DO - setAlarm() replaces any existing alarm

Authorization

Durable Objects do not have separate roles or permissions; access follows the Worker that implements them. Retrieve the current Durable Objects authorization guidance before granting observability or Data Studio access, and scope the Workers role to the intended Worker or Workers product.

Anti-Patterns (NEVER)

  • Single global DO handling all requests (bottleneck)
  • Using blockConcurrencyWhile() on every request (kills throughput)
  • Storing critical state only in memory (lost on eviction/crash)
  • Using await between related storage writes (breaks atomicity)
  • Holding blockConcurrencyWhile() across fetch() or external I/O

Stub Creation

// Deterministic - preferred for most cases
const stub = env.MY_DO.getByName("room-123");

// From existing ID string
const id = env.MY_DO.idFromString(storedIdString);
const stub = env.MY_DO.get(id);

// New unique ID - store mapping externally
const id = env.MY_DO.newUniqueId();
const stub = env.MY_DO.get(id);

Storage Operations

// SQL (synchronous, recommended)
this.ctx.storage.sql.exec("INSERT INTO t (c) VALUES (?)", value);
const rows = this.ctx.storage.sql.exec<Row>("SELECT * FROM t").toArray();

// KV (async)
await this.ctx.storage.put("key", value);
const val = await this.ctx.storage.get<Type>("key");

Alarms

// Schedule (replaces existing)
await this.ctx.storage.setAlarm(Date.now() + 60_000);

// Handler
async alarm(): Promise<void> {
  // Process scheduled work
  // Optionally reschedule: await this.ctx.storage.setAlarm(...)
}

// Cancel
await this.ctx.storage.deleteAlarm();

Testing

Read the testing reference before configuring a suite or writing Durable Object tests. It routes to current setup, APIs, and examples and identifies the behavior to cover.

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Скиллы Cloudflare

Лучшие практики Cloudflare Workers

Проверяет код и конфигурацию Cloudflare Workers по правилам для прода: даты совместимости, логи и трейсы, стриминг, waitUntil, биндинги вместо REST, Web Crypto, типы Env. Для случаев, когда Worker пишут, ревьюят или готовят к выкладке.

Wrangler CLI для Cloudflare

Ведёт команды и конфигурацию Wrangler в проектах с wrangler.jsonc или wrangler.toml: сверяется со справкой и документацией, бережёт секреты, окружения и Previews. Для случаев, когда Worker деплоят, настраивают или чинят через Wrangler.

Agents SDK от Cloudflare

Помогает строить приложения на Agents SDK от Cloudflare: агенты с состоянием на Durable Objects, RPC, расписания, очереди, Workflows, чат на AIChatAgent, MCP и почта. Для случаев, когда нужен ИИ-агент или чат на Workers.

Веб-фреймворки на Cloudflare Workers

Настраивает приложения на Astro, SvelteKit, React Router, TanStack Start, Nuxt, Hono и SPA под Cloudflare Workers, выбирая C3, Wrangler или cf по состоянию проекта. Для случаев, когда приложение создают, переносят или деплоят на Workers.

Локальная разработка Workers

Запускает и отлаживает Workers локально через cf dev, wrangler dev или плагин Vite, а в Local Explorer читает и наполняет данные биндингов и смотрит трейсы. Для случаев, когда локальный запрос падает или непонятно, что вернул биндинг.

CLI cf для API Cloudflare

Находит и выполняет команды CLI cf от Cloudflare (бета) через cf cli search, cf schema и пробные прогоны, выбирает между cf и Wrangler. Для случаев, когда нужно работать с DNS, зонами, D1, KV или R2 из терминала или начать проект на Workers.

Аудит скорости сайта

Проводит аудит скорости страницы через Chrome DevTools MCP: трейс, Core Web Vitals по порогам, сеть, снимок доступности и настройки сборки, с исправлениями по приоритету. Для случаев, когда страница тормозит или оценка Lighthouse низкая.