← Cloudflare Workers / workers / runtime-apis

WebSockets

WebSockets vám umožňují komunikovat v reálném čase s vašimi serverless funkcemi Cloudflare Workers. Kompletní příklad najdete v Použití WebSockets API.

// { 0: <WebSocket>, 1: <WebSocket> }
let websocketPair = new WebSocketPair();

WebSocketPair vrácený tímto konstruktorem je Object se dvěma WebSockety na klíčích 0 a 1.

Tyto WebSockets se běžně označují jako client a server. Následující příklad kombinuje Object.values a ES6 destrukturalizaci k získání WebSocketů jako client a server:

let [client, server] = Object.values(new WebSocketPair());

• accept(options?)
  • Přijme WebSocket připojení a začne ukončovat požadavky na WebSocket v rámci globální sítě Cloudflare. To umožní běhovému prostředí Workers reagovat na WebSocket požadavky a zpracovávat je.

• options objekt volitelný

  • Volitelný konfigurační objekt s následujícími vlastnostmi:

    • allowHalfOpen boolean volitelné: Když true, runtime automaticky neodešle odpovídající Close frame, když od protistrany přijme Close frame. Místo toho readyState zůstává CLOSING dokud výslovně nezavoláte close(). Toto se hodí pro Proxování WebSocket kde potřebujete koordinovat uzavření na obou stranách proxy. Výchozí hodnota je false.

• addEventListener(eventWebSocketEvent, callbackFunctionFunction)
  • Přidejte funkce zpětného volání, které se spustí, když na WebSocketu dojde k události.

• event WebSocketEvent

  • Událost WebSocket (viz Události) ke kterému má naslouchat.

• callbackFunction(messageMessage) Funkce

  • Funkce, která se zavolá, když WebSocket zareaguje na konkrétní událost.

• close(codenumber, reasonstring)
  • Zavřete připojení WebSocket.

• codeinteger volitelné

  • Celé číslo udávající kód uzavření odeslaný serverem. Mělo by odpovídat jedné z možností v seznam stavových kódů ↗ poskytovaná specifikací WebSocket.

• reasonstring volitelné

  • Člověku srozumitelný řetězec udávající, proč bylo spojení WebSocket uzavřeno.

• send(messagestring | ArrayBuffer | ArrayBufferView)
  • Odešlete zprávu druhému WebSocketu v tomto páru WebSocket.

• messagestring
  • Zpráva, která se odešle přes WebSocket připojení odpovídajícímu klientovi. Měla by to být řetězec nebo něco, co lze na řetězec převést. Řetězce a čísla se jednoduše převedou na řetězec, ale objekty a pole je třeba převést na řetězec JSON pomocí JSON.stringify, a zpracována na straně klienta.

• readyState number

  • Vrátí aktuální stav připojení WebSocket. Možné hodnoty:

    Konstanta	Hodnota	Popis
    WebSocket.CONNECTING	0	Spojení ještě není otevřeno.
    WebSocket.OPEN	1	Spojení je otevřené a připravené ke komunikaci.
    WebSocket.CLOSING	2	Spojení se právě uzavírá.
    WebSocket.CLOSED	3	Spojení je uzavřeno.

• binaryType string

  • Ovládá, jak jsou binární rámce přijaté na tomto WebSocketu předávány do message událost. Platné hodnoty jsou "blob" a "arraybuffer". Hodnota se ověřuje při doručení každého příchozího binárního rámce, takže přiřazení nové hodnoty ovlivní až následující zprávy. Výchozí hodnotu řídí websocket_standard_binary_type příznak kompatibility. Další informace najdete v Binární zprávy s podrobnostmi.

• close
  • Událost indikující, že se WebSocket uzavřel. CloseEvent zahrnuje code (číslo), reason (řetězec), a wasClean (boolean) vlastnosti.
• error
  • Událost indikující, že došlo k chybě u WebSocketu.
• message
  • Událost indikující novou zprávu přijatou od klienta, včetně dat předaných klientem.

• data any - Data vrácená druhým WebSocketem z vaší dvojice.
• type string: výchozí hodnota je message.

S web_socket_auto_reply_to_close příznak kompatibility (ve výchozím nastavení povolen u dat kompatibility od 2026-04-07), běhové prostředí Workers automaticky odešle odpovídající rámec Close, jakmile od protistrany obdrží rámec Close. Toto readyState přechází do CLOSED před close se spustí událost. To odpovídá Specifikace WebSocket ↗ a standardní chování prohlížeče.

Pokud přesto zavoláte close() uvnitř close obslužné rutině události se volání tiše ignoruje. Stávající kód, který ručně odpovídá na rámce Close, bude fungovat i nadále beze změn.

server.addEventListener("close", (event) => {
  // readyState is already CLOSED — no need to call server.close().
  console.log(server.readyState); // WebSocket.CLOSED
  console.log(event.code);        // 1000
  console.log(event.wasClean);    // true
});

Automatické chování při uzavírání může narušit proxování WebSocket, kdy Worker stojí mezi klientem a backendem a potřebuje nezávisle koordinovat uzavření na obou stranách. Aby to bylo možné, předejte { allowHalfOpen: true } na accept():

server.accept({ allowHalfOpen: true });

server.addEventListener("close", (event) => {
  // readyState is still CLOSING here, giving you time
  // to coordinate the close on the other side.
  console.log(server.readyState); // WebSocket.CLOSING

  // Manually close when ready.
  server.close(event.code, "done");
});

U dat kompatibility před 2026-04-07 (nebo s web_socket_manual_reply_to_close příznak), přijetí rámce Close ponechá WebSocket ve CLOSING stavu a váš kód musí zavolat close() pro dokončení handshaku. Pokud tak neučiníte, může dojít k 1006 chyby neobvyklého ukončení spojení (abnormal closure) na straně klienta.

Rámce WebSocket nesou buď textový, nebo binární obsah a volbu mezi nimi provádí odesílatel v okamžiku odeslání rámce. Textové rámce se vždy doručují do message událost jako řetězce JavaScriptu. Binární rámce se doručují buď jako Blob ↗ nebo jako ArrayBuffer ↗, v závislosti na binaryType.

S websocket_standard_binary_type příznak kompatibility (ve výchozím nastavení povolen u dat kompatibility od 2026-03-17), binaryType má výchozí hodnotu "blob" a binární rámce jsou doručovány jako Blob objekty. To odpovídá Specifikace WebSocket ↗ a standardní chování prohlížeče. Bez tohoto příznaku binaryType má výchozí hodnotu "arraybuffer" a binární rámce jsou doručovány jako ArrayBuffer, což odpovídá dosavadnímu chování runtime.

binaryType vlastnost samotná je k dispozici vždy. Chcete-li se vrátit k ArrayBuffer doručování pro jediný WebSocket přiřaďte binaryType před voláním accept():

const resp = await fetch("https://example.com", {
  headers: { Upgrade: "websocket" },
});
const ws = resp.webSocket;

// Opt back into ArrayBuffer delivery for this WebSocket.
ws.binaryType = "arraybuffer";
ws.accept();

ws.addEventListener("message", (event) => {
  if (typeof event.data === "string") {
    // Text frame.
  } else {
    // event.data is an ArrayBuffer because we set binaryType above.
  }
});

Příchozí binární rámec je zcela bufferován před message se spustí událost, bez ohledu na binaryType. Volba mezi Blob a ArrayBuffer nemění, kdy nebo zda je snímek přijat, pouze způsob, jakým přistupujete k jeho bajtům:

• S "arraybuffer", event.data je ArrayBuffer ↗. Můžete zkontrolovat jeho velikost a synchronně číst bajty (například new Uint8Array(event.data)).
• S "blob", event.data je Blob ↗. Čtení bajtů probíhá asynchronně, například await event.data.arrayBuffer() nebo await event.data.bytes().

Podle nového výchozího chování musí být obslužná rutina binárních zpráv async abyste mohli přečíst payload. Pokud chcete zachovat stávající synchronní handler, nastavte binaryType na "arraybuffer" na WebSocketu.

Podle Specifikace WebSocket ↗, binaryType je proměnlivé: hodnota se zjišťuje ve chvíli, kdy je každý binární rámec odeslán do message událost, takže přiřazení nové hodnoty ovlivní jen následující zprávy. Pokud chcete, aby se každá binární zpráva na WebSocketu doručovala jako stejný typ, přiřaďte binaryType před voláním accept(). Tím je zaručeno, že nastavení je platné dříve, než runtime začne doručovat příchozí rámce.

Pokud ještě nejste připraveni k migraci a chcete ponechat ArrayBuffer jako výchozí hodnotu pro každý WebSocket ve vašem Workeru přidejte no_websocket_standard_binary_type příznak do svého Konfigurační soubor Wrangler. Jednotlivé WebSockety mohou výchozí hodnotu přepsat přiřazením binaryType.

• Dokumentace Mozilla Developer Network (MDN) ke třídě WebSocket ↗
• Naše šablona WebSocket pro vytváření aplikací na Workers pomocí WebSockets ↗