← Cloudflare Durable Objects / durable-objects / api

Состояние Durable Object

DurableObjectState интерфейс доступен как свойство экземпляра на Durable Object class. Этот интерфейс объединяет методы, изменяющие состояние Durable Object, например какие WebSocket подключены к Durable Object или как runtime должен обрабатывать параллельные запросы к Durable Object.

DurableObjectState интерфейс отличается от Storage API тем, что у него нет методов верхнего уровня, управляющих постоянными данными приложения. Эти методы вместо этого инкапсулированы в DurableObjectStorage интерфейс и доступен через DurableObjectState::storage.

import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx, env) {
		super(ctx, env);
	}
  ...
}

import { DurableObject } from "cloudflare:workers";

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

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}
  ...
}

from workers import DurableObject

# Durable Object
class MyDurableObject(DurableObject):
  # DurableObjectState is accessible via the ctx instance property
  def __init__(self, ctx, env):
    super().__init__(ctx, env)
  # ...

Содержит обратные (loopback) привязки к собственным экспортам верхнего уровня Worker. Это имеет точно такое же значение, как ExecutionContext: ctx.exports.

waitUntil доступен в DurableObjectState для совместимости API с Workers Runtime APIs.

• Обязательный promise любого типа.

• Нет.

blockConcurrencyWhile выполняет асинхронный колбэк, блокируя доставку любых других событий в Durable Object до его завершения. Этот метод гарантирует порядок выполнения и предотвращает параллельные запросы. Все события, не инициированные явно в рамках самого колбэка, будут заблокированы. После завершения колбэка все остальные события будут доставлены.

• blockConcurrencyWhile обычно используется в конструкторе класса Durable Object, чтобы гарантировать выполнение инициализации до поступления каких-либо запросов.
• Ещё один вариант использования: выполнение async операции на основе текущего состояния Durable Object и с использованием blockConcurrencyWhile чтобы предотвратить изменение этого состояния при передаче управления циклу событий.
• Если callback выбрасывает исключение, объект завершает работу и сбрасывается. Это гарантирует, что объект не останется в неинициализированном состоянии при неожиданном сбое.
• Чтобы избежать такого поведения, оберните тело своего колбэка в try...catch блок, чтобы гарантировать, что он не выбросит исключение.

Чтобы снизить риск взаимных блокировок, при выполнении колбэка применяется тайм-аут 30 секунд. Если этот тайм-аут превышен, Durable Object будет перезапущен. Рекомендуется, чтобы колбэк выполнял как можно меньше работы: это повышает общую пропускную способность запросов к Durable Object.

// Durable Object
export class MyDurableObject extends DurableObject {
	initialized = false;

	constructor(ctx, env) {
		super(ctx, env);

		// blockConcurrencyWhile will ensure that initialized will always be true
		this.ctx.blockConcurrencyWhile(async () => {
			this.initialized = true;
		});
	}
  ...
}

# Durable Object
class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)
		self.initialized = False

		# blockConcurrencyWhile will ensure that initialized will always be true
		async def set_initialized():
			self.initialized = True
		self.ctx.blockConcurrencyWhile(set_initialized)
	# ...

• Обязательная функция обратного вызова, которая возвращает Promise<T>.

• A Promise<T> возвращаемое колбэком.

acceptWebSocket является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

acceptWebSocket добавляет WebSocket в набор WebSocket, подключённых к Durable Object. После вызова все входящие сообщения будут доставляться через вызов webSocketMessage-обработчик, а также webSocketClose будет вызван при отключении. После вызова acceptWebSocket, WebSocket принимается, и его send и close методы можно использовать.

WebSocket Hibernation API заменяет собой стандартный WebSockets API. Поэтому ws.accept не должны были вызываться отдельно, а ws.addEventListener метод не будет получать события, так как они будут доставляться напрямую в Durable Object.

WebSocket Hibernation API допускает не более 32,768 соединений WebSocket на один Durable Object, однако фактическое число одновременных соединений может быть дополнительно ограничено использованием CPU и памяти конкретной нагрузкой.

• Обязательный WebSocket с именем ws.
• Необязательный Array<string> связанных тегов. Теги можно использовать для получения WebSocket-соединений через DurableObjectState::getWebSockets. Длина каждого тега не превышает 256 символов, и с одним WebSocket может быть связано не более 10 тегов.

• Нет.

getWebSockets является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

getWebSockets возвращает Array<WebSocket> представляющий собой набор WebSocket-соединений, привязанных к Durable Object. Необязательный аргумент tag позволяет отфильтровать список по тегам, указанным при вызове DurableObjectState::acceptWebSocket.

• Необязательный тег типа string.

• Одна Array<WebSocket>.

setWebSocketAutoResponse является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

setWebSocketAutoResponse задаёт автоматический ответ, auto-response, на указанный запрос для всех WebSocket, подключённых к Durable Object. Если поступает запрос, совпадающий с заданным, auto-response возвращается без пробуждения WebSocket из гибернации и без начисления платы за длительность.

setWebSocketAutoResponse является распространённой альтернативой настройке сервера для статических сообщений ping/pong, поскольку это можно обработать без пробуждения «спящих» WebSocket-соединений.

• Необязательный WebSocketRequestResponsePair(request string, response string) позволяя любому WebSocket, принятому через DurableObjectState::acceptWebSocket чтобы автоматически отвечать указанным ответом на входящий запрос. И запрос, и ответ ограничены 2,048 символами каждый. Если параметр не указан, ранее заданная конфигурация автоответа будет удалена. DurableObjectState::getWebSocketAutoResponseTimestamp всё ещё будет отражать последнюю метку времени отправки автоответа.

• Нет.

getWebSocketAutoResponse возвращает WebSocketRequestResponsePair объект, последний раз установленный DurableObjectState::setWebSocketAutoResponse, или null, если автоответ не установлен.

• Нет.

• A WebSocketRequestResponsePair или null.

getWebSocketAutoResponseTimestamp является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

getWebSocketAutoResponseTimestamp возвращает самый последний Date в которое данный WebSocket отправил автоответ, или null, если этот WebSocket никогда не отправлял автоответ.

• Обязательный WebSocket.

• A Date или null.

setHibernatableWebSocketEventTimeout является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

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

Если не указан параметр или указан параметр 0 указан, а тайм-аут уже был установлен ранее, этот тайм-аут будет сброшен. Максимальное значение тайм-аута составляет 604,800,000 мс (7 дней).

• Необязательный number.

• Нет.

getHibernatableWebSocketEventTimeout является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

getHibernatableWebSocketEventTimeout возвращает текущий тайм-аут событий для гибернируемых WebSocket, если он был задан через DurableObjectState::setHibernatableWebSocketEventTimeout.

• Нет.

• Число или null, если тайм-аут не установлен.

getTags является частью WebSocket Hibernation API, что позволяет выгружать Durable Object из памяти для экономии затрат, сохраняя при этом подключение его WebSocket.

getTags возвращает теги, связанные с указанным WebSocket. Этот метод выбрасывает исключение, если WebSocket не был связан с Durable Object через DurableObjectState::acceptWebSocket.

• Обязательный WebSocket.

• Одна Array<string> тегов.

Вызов abort немедленно сбрасывает Durable Object. Среда выполнения регистрирует в журнале JavaScript Error с сообщением, переданным в abort. Код приложения не может перехватить эту ошибку.

По умолчанию будильник, прерванный abort повторяется после сброса Durable Object. Durable Object может выполнять alarm одновременно с обработкой другого запроса, и в рамках этого запроса можно вызвать abort пока alarm еще выполняется.

Повтор по умолчанию предотвращает окончательную отмену alarm посторонним запросом. Передайте { retryAlarm: false } при любом вызове abort, который должен предотвратить повторную попытку прерванного alarm, включая вызовы abort вне обработчика alarm.

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

  async sayHello() {
    // Error: Hello, World! will be logged
    this.ctx.abort("Hello, World!");
  }

  async alarm() {
    // Reset this instance without retrying the alarm
    this.ctx.abort("Alarm complete", { retryAlarm: false });
  }
}

# Durable Object
class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)

	async def say_hello(self):
		# Error: Hello, World! will be logged
		self.ctx.abort("Hello, World!")

• Необязательный string содержащий сообщение об ошибке для логирования.
• Необязательный DurableObjectAbortOptions объект:
  • retryAlarm boolean: управляет тем, повторяется ли будильник, прерванный этим abort. По умолчанию используется true.

• Нет.

id является доступным только для чтения свойством типа DurableObjectId соответствующий DurableObjectId Durable Object.

storage является доступным только для чтения свойством типа DurableObjectStorage инкапсулирующий Storage API.

• Durable Objects: Easy, Fast, Correct - Choose Three ↗.