← Cloudflare Durable Objects / durable-objects / api

Durable Object State

DurableObjectState rozhraní je dostupné jako instanční vlastnost na Třída Durable Object. Toto rozhraní zapouzdřuje metody, které mění stav Durable Object, například které WebSockety jsou k Durable Object připojené nebo jak má runtime zacházet se souběžnými požadavky na Durable Object.

DurableObjectState rozhraní se liší od Storage API v tom, že nemá metody nejvyšší úrovně pro manipulaci s trvalými daty aplikace. Tyto metody jsou místo toho zapouzdřeny v DurableObjectStorage rozhraní a je přístupné z 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)
  # ...

Obsahuje loopback bindings k vlastním exportům nejvyšší úrovně Workeru. Má to úplně stejný význam jako ExecutionContext: ctx.exports.

waitUntil je dostupný na DurableObjectState kvůli kompatibilitě API s Workers Runtime APIs.

• Povinný promise libovolného typu.

• Žádné.

blockConcurrencyWhile spustí asynchronní callback a zároveň zablokuje doručování všech ostatních událostí do Durable Object, dokud se callback nedokončí. Tato metoda zaručuje pořadí a zabraňuje souběžným požadavkům. Všechny události, které nebyly výslovně zahájeny jako součást samotného callbacku, budou zablokovány. Jakmile se callback dokončí, doručí se všechny ostatní události.

• blockConcurrencyWhile se běžně používá uvnitř konstruktoru třídy Durable Object, aby se zajistilo, že inicializace proběhne dříve, než jsou doručeny jakékoli požadavky.
• Dalším případem použití je spouštění async operace na základě aktuálního stavu Durable Object a s použitím blockConcurrencyWhile aby zabránil změně tohoto stavu při uvolňování smyčky událostí.
• Pokud callback vyhodí výjimku, objekt se ukončí a resetuje. Díky tomu nemůže objekt v případě neočekávaného selhání zůstat uvízlý v neinicializovaném stavu.
• Abyste se tomuto chování vyhnuli, uzavřete tělo svého callbacku do try...catch blok, abyste zajistili, že nemůže vyvolat výjimku.

Pro omezení rizika deadlocků platí při provádění callbacku 30sekundový timeout. Pokud je tento timeout překročen, Durable Object se resetuje. Osvědčeným postupem je, aby callback dělal co nejméně práce, což zlepší celkovou propustnost požadavků na 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)
	# ...

• Povinný callback, který vrací Promise<T>.

• A Promise<T> vrácenou callbackem.

acceptWebSocket je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

acceptWebSocket přidá WebSocket do sady WebSockets připojených k Durable Object. Po zavolání budou všechny příchozí zprávy doručovány voláním webSocketMessage handler a webSocketClose se vyvolá při odpojení. Po zavolání acceptWebSocket, WebSocket se přijme a jeho send a close metody lze použít.

WebSocket Hibernation API nahrazuje standardní WebSockets API. Proto ws.accept nesměla být volána samostatně a ws.addEventListener metoda události nedostane, protože se doručí přímo do Durable Object.

WebSocket Hibernation API povoluje maximálně 32,768 spojení WebSocket na jeden Durable Object, skutečný počet současných spojení však může dále omezovat využití CPU a paměti dané úlohy.

• Povinný WebSocket s názvem ws.
• Volitelný Array<string> přidružených tagů. Tagy lze použít k získání WebSocketů pomocí DurableObjectState::getWebSockets. Každý tag má maximálně 256 znaků a k jednomu WebSocketu může být přiřazeno nejvýše 10 tagů.

• Žádné.

getWebSockets je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

getWebSockets vrací Array<WebSocket> což je sada WebSocketů připojených k Durable Object. Volitelný argument tag lze použít k filtrování seznamu podle štítků zadaných při volání DurableObjectState::acceptWebSocket.

• Volitelný tag typu string.

• Array<WebSocket>.

setWebSocketAutoResponse je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

setWebSocketAutoResponse nastaví automatickou odpověď (auto-response) pro daný požadavek u všech WebSocketů připojených k Durable Objectu. Pokud je přijat požadavek odpovídající zadanému požadavku, vrátí se auto-response, aniž by se probouzely hibernující WebSockety a účtovala se doba běhu.

setWebSocketAutoResponse je běžnou alternativou k nastavení serveru pro statické zprávy ping/pong, protože ji lze zpracovat bez probuzení hibernujících WebSocketů.

• Volitelný WebSocketRequestResponsePair(request string, response string) což umožňuje, aby jakýkoli WebSocket přijatý pomocí DurableObjectState::acceptWebSocket pro automatické zaslání zadané odpovědi při přijetí zadaného požadavku. Požadavek i odpověď jsou omezeny na 2,048 znaků každý. Pokud parametr vynecháte, veškerá dříve nastavená konfigurace automatické odpovědi se odstraní. DurableObjectState::getWebSocketAutoResponseTimestamp bude stále odrážet poslední časové razítko odeslání automatické odpovědi.

• Žádné.

getWebSocketAutoResponse vrací WebSocketRequestResponsePair objekt naposledy nastavený pomocí DurableObjectState::setWebSocketAutoResponse, nebo null, pokud není nastavena žádná automatická odpověď.

• Žádné.

• A WebSocketRequestResponsePair nebo null.

getWebSocketAutoResponseTimestamp je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

getWebSocketAutoResponseTimestamp vrátí nejnovější Date ve kterém dané WebSocket odeslalo automatickou odpověď, nebo null, pokud dané WebSocket žádnou automatickou odpověď neodeslalo.

• Povinný WebSocket.

• A Date nebo null.

setHibernatableWebSocketEventTimeout je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

setHibernatableWebSocketEventTimeout nastaví maximální dobu v milisekundách, po kterou může běžet událost WebSocketu.

Pokud není zadán žádný parametr nebo parametr typu 0 je zadán a timeout již byl dříve nastaven, timeout se zruší. Maximální hodnota timeoutu je 604,800,000 ms (7 dní).

• Volitelný number.

• Žádné.

getHibernatableWebSocketEventTimeout je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

getHibernatableWebSocketEventTimeout vrátí aktuálně nastavený časový limit pro hibernovatelnou událost WebSocket, pokud byl nastaven pomocí DurableObjectState::setHibernatableWebSocketEventTimeout.

• Žádné.

• Číslo, nebo null, pokud časový limit nebyl nastaven.

getTags je součástí WebSocket Hibernation API, díky které lze Durable Object odstranit z paměti kvůli úspoře nákladů a přitom zachovat jeho WebSockets připojené.

getTags vrátí tagy přiřazené danému WebSocketu. Tato metoda vyvolá výjimku, pokud WebSocket nebyl s Durable Objectem asociován pomocí DurableObjectState::acceptWebSocket.

• Povinný WebSocket.

• Array<string> tagů.

Volání abort okamžitě resetuje Durable Object. Runtime zaznamená do protokolu JavaScriptovou Error se zprávou předanou do abort. Kód aplikace tuto chybu nemůže zachytit.

Ve výchozím nastavení se alarm přerušený abort se po resetu Durable Objectu opakuje. Durable Object může spouštět alarm souběžně s jiným požadavkem a tento požadavek může volat abort zatímco alarm ještě běží.

Výchozí opakování zabraňuje tomu, aby nesouvisející požadavek alarm trvale zrušil. Předejte { retryAlarm: false } při jakémkoli volání abort, které má zabránit opakování přerušeného alarmu, včetně volání abort mimo obslužnou rutinu alarmu.

// 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!")

• Volitelný string obsahující chybovou zprávu k zaznamenání.
• Volitelný DurableObjectAbortOptions objekt:
  • retryAlarm boolean: Určuje, zda se alarm přerušený tímto abort zopakuje. Výchozí hodnota je true.

• Žádné.

id je vlastnost pouze pro čtení typu DurableObjectId odpovídající DurableObjectId Durable Object.

storage je vlastnost pouze pro čtení typu DurableObjectStorage zapouzdřující Storage API.

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