From 46edf373e8d10f4bc1a44bafb36f0dd7d5effa25 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 26 Nov 2024 17:23:03 +0000 Subject: [PATCH 01/12] Adding a new --- src/content/docs/durable-objects/api/base.mdx | 46 +++++++++++++++++++ .../best-practices/websockets.mdx | 3 +- 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/durable-objects/api/base.mdx diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx new file mode 100644 index 000000000000000..5acd37a78e875ef --- /dev/null +++ b/src/content/docs/durable-objects/api/base.mdx @@ -0,0 +1,46 @@ +--- +title: Durable Object Base Class +pcx_content_type: concept +sidebar: + order: 1 +--- + +import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; + +{/* DEFINITION OF DO BASE CLASS TBC */} + +## Methods + +### `webSocketMessage` + +- webSocketMessage(ws , message{" "} ): + + - Called by the system when an accepted WebSocket receives a message. + + - This method can be `async`. + + - This method is not called for WebSocket control frames. The system will respond to an incoming [WebSocket protocol ping](https://www.rfc-editor.org/rfc/rfc6455#section-5.5.2) automatically without interrupting hibernation. + +### `webSocketClose` + +- webSocketClose(ws , code ,reason , wasClean ): + + - Called by the system when a WebSocket is closed. `wasClean()` is true if the connection closed cleanly, false otherwise. + + - This method can be `async`. + +### `webSocketError` + +- webSocketError(ws , error ) : + + - Called by the system when any non-disconnection related errors occur. + + - This method can be `async`. + +## Properties + +{/* Properties of DO Base Class TBC */} + +## Related resources + +- Refer to [Use WebSockets](/durable-objects/best-practices/websockets/) for more information on examples of WebSocket methods and best practices. \ No newline at end of file diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index d280b53feb23332..e1a7d9a1fe53d85 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -375,7 +375,7 @@ A full example can be found in [Build a WebSocket server with WebSocket Hibernat Prior to `wrangler@3.13.2` and Miniflare `v3.20231016.0`, WebSockets did not hibernate when using local development environments such as `wrangler dev` or Miniflare. -If you are using older versions, note that while hibernatable WebSocket events such as [`webSocketMessage()`](/durable-objects/best-practices/websockets/#websocketmessage) will still be delivered, the Durable Object will never be evicted from memory. +If you are using older versions, note that while hibernatable WebSocket events such as [`webSocketMessage()`](/durable-objects/api/base/#websocketmessage) will still be delivered, the Durable Object will never be evicted from memory. ::: @@ -383,3 +383,4 @@ If you are using older versions, note that while hibernatable WebSocket events s - [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) - [Cloudflare's WebSocket template for building applications on Workers using WebSockets](https://github.com/cloudflare/websocket-template) +- [Methods of Durable Object base class](/durable-objects/api/base/) \ No newline at end of file From 06904e0747b766e950d3aa4de1829307b38aec21 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 26 Nov 2024 17:24:37 +0000 Subject: [PATCH 02/12] Adding Durable Object Base Class chapter. Adding cross-references. --- src/content/docs/durable-objects/api/alarms.mdx | 2 +- src/content/docs/durable-objects/api/id.mdx | 2 +- src/content/docs/durable-objects/api/namespace.mdx | 2 +- src/content/docs/durable-objects/api/sql-storage.mdx | 2 +- src/content/docs/durable-objects/api/state.mdx | 2 +- src/content/docs/durable-objects/api/storage-api.mdx | 2 +- src/content/docs/durable-objects/api/stub.mdx | 2 +- src/content/docs/durable-objects/api/webgpu.mdx | 2 +- src/content/docs/durable-objects/api/workers-rs.mdx | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index 42e1515cd1892b8..555e26177fa630c 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -2,7 +2,7 @@ title: Alarms pcx_content_type: concept sidebar: - order: 7 + order: 8 --- import { Type, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 246de21c9e6188f..aa8f990bd4f69e8 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -2,7 +2,7 @@ title: Durable Object ID pcx_content_type: concept sidebar: - order: 2 + order: 3 --- import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index ba5f2ce58d15a50..624629688822528 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -2,7 +2,7 @@ title: Durable Object Namespace pcx_content_type: concept sidebar: - order: 1 + order: 2 --- import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/sql-storage.mdx b/src/content/docs/durable-objects/api/sql-storage.mdx index 293ea6c05e81dd3..3c92e3445336c51 100644 --- a/src/content/docs/durable-objects/api/sql-storage.mdx +++ b/src/content/docs/durable-objects/api/sql-storage.mdx @@ -2,7 +2,7 @@ title: SQL Storage pcx_content_type: concept sidebar: - order: 5 + order: 6 --- diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index d19a63f2836a8c3..aa1e860ed493c73 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -2,7 +2,7 @@ title: Durable Object State pcx_content_type: concept sidebar: - order: 4 + order: 5 --- import { Tabs, TabItem, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index b988dfaeeeff1a0..a656a4670baab19 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -2,7 +2,7 @@ title: Durable Object Storage pcx_content_type: concept sidebar: - order: 5 + order: 6 --- import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/stub.mdx b/src/content/docs/durable-objects/api/stub.mdx index 1a277e4c0bb932b..69b9b5c5f61cf42 100644 --- a/src/content/docs/durable-objects/api/stub.mdx +++ b/src/content/docs/durable-objects/api/stub.mdx @@ -2,7 +2,7 @@ title: Durable Object Stub pcx_content_type: concept sidebar: - order: 3 + order: 4 --- import { Render, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/durable-objects/api/webgpu.mdx b/src/content/docs/durable-objects/api/webgpu.mdx index 194d0857b8d1d25..eea471fb178acba 100644 --- a/src/content/docs/durable-objects/api/webgpu.mdx +++ b/src/content/docs/durable-objects/api/webgpu.mdx @@ -2,7 +2,7 @@ pcx_content_type: configuration title: WebGPU sidebar: - order: 8 + order: 9 --- :::caution diff --git a/src/content/docs/durable-objects/api/workers-rs.mdx b/src/content/docs/durable-objects/api/workers-rs.mdx index 59416eac283e978..22f283891d63f29 100644 --- a/src/content/docs/durable-objects/api/workers-rs.mdx +++ b/src/content/docs/durable-objects/api/workers-rs.mdx @@ -3,6 +3,6 @@ pcx_content_type: navigation title: Rust API external_link: https://github.com/cloudflare/workers-rs?tab=readme-ov-file#durable-objects sidebar: - order: 10 + order: 11 --- From d713eff7d995417dafd0f84ebc879dfd9154314d Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 26 Nov 2024 17:28:27 +0000 Subject: [PATCH 03/12] Adding link to related resources. --- src/content/docs/durable-objects/best-practices/websockets.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index e1a7d9a1fe53d85..204e172c2f915fe 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -383,4 +383,5 @@ If you are using older versions, note that while hibernatable WebSocket events s - [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) - [Cloudflare's WebSocket template for building applications on Workers using WebSockets](https://github.com/cloudflare/websocket-template) -- [Methods of Durable Object base class](/durable-objects/api/base/) \ No newline at end of file +- [Durable Object base class](/durable-objects/api/base/) +- [Durable Object State interface](/durable-objects/api/state/) \ No newline at end of file From e34e07ee3aba55aba57cbf7f57f444c959ceddd6 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 26 Nov 2024 17:45:42 +0000 Subject: [PATCH 04/12] Adding extended methods to DO State page. --- src/content/docs/durable-objects/api/state.mdx | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index aa1e860ed493c73..eb83212ac73c844 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -5,7 +5,7 @@ sidebar: order: 5 --- -import { Tabs, TabItem, GlossaryTooltip } from "~/components"; +import { Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; ## Description @@ -267,6 +267,22 @@ export class MyDurableObject extends DurableObject { - None. +## Extended methods + +### `serializeAttachment` + +- serializeAttachment(value ): + + - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. + + - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. + +### `deserializeAttachment` + +- `deserializeAttachment()`: + + - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. + ## Properties ### `id` From 6088c072c164d7787508f6b633deecdcf1ecec2c Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 09:15:50 +0000 Subject: [PATCH 05/12] Adding fetch and alarm. Actioning PR comments. --- package-lock.json | 25 ++++-------- src/content/docs/durable-objects/api/base.mdx | 40 +++++++++++++++++-- .../docs/durable-objects/api/state.mdx | 16 -------- .../best-practices/websockets.mdx | 16 ++++++++ 4 files changed, 61 insertions(+), 36 deletions(-) diff --git a/package-lock.json b/package-lock.json index a13f8ca5a0ee9ff..2b2b367ae63a453 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6541,10 +6541,11 @@ } }, "node_modules/cross-spawn": { - "version": "7.0.3", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", - "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", "dev": true, + "license": "MIT", "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", @@ -17696,27 +17697,17 @@ } }, "node_modules/youch": { - "version": "3.3.3", - "resolved": "https://registry.npmjs.org/youch/-/youch-3.3.3.tgz", - "integrity": "sha512-qSFXUk3UZBLfggAW3dJKg0BMblG5biqSF8M34E06o5CSsZtH92u9Hqmj2RzGiHDi64fhe83+4tENFP2DB6t6ZA==", + "version": "3.3.4", + "resolved": "https://registry.npmjs.org/youch/-/youch-3.3.4.tgz", + "integrity": "sha512-UeVBXie8cA35DS6+nBkls68xaBBXCye0CNznrhszZjTbRVnJKQuNsyLKBTTL4ln1o1rh2PKtv35twV7irj5SEg==", "dev": true, "license": "MIT", "dependencies": { - "cookie": "^0.5.0", + "cookie": "^0.7.1", "mustache": "^4.2.0", "stacktracey": "^2.1.8" } }, - "node_modules/youch/node_modules/cookie": { - "version": "0.5.0", - "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.5.0.tgz", - "integrity": "sha512-YZ3GUyn/o8gfKJlnlX7g7xq4gyO6OSuhGPKaaGssGB2qgDUS0gPgtTvoyZLTt9Ab6dC4hfc9dV5arkvc/OCmrw==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">= 0.6" - } - }, "node_modules/zod": { "version": "3.23.8", "resolved": "https://registry.npmjs.org/zod/-/zod-3.23.8.tgz", diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index 5acd37a78e875ef..d7ad2b4be59e624 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -5,12 +5,40 @@ sidebar: order: 1 --- -import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo, TypeScriptExample } from "~/components"; -{/* DEFINITION OF DO BASE CLASS TBC */} +The `DurableObject` base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the [WebSocket Hibernation API](#/durable-objects/best-practices/websockets/#websocket-hibernation-api). To provide a concrete example, here is a Durable Object `MyDurableObject` which extends `DurableObject` and implements the fetch handler to return "Hello, World!" to the calling Worker. + + +```ts +export class MyDurableObject extends DurableObject { + constructor(ctx: DurableObjectState, env: Env) { + super(ctx, env); + } + + async fetch(request: Request) { + return new Response("Hello, World!"); + } +} +``` + ## Methods +### `fetch` + +- fetch(): | + + - Takes an HTTP request object and returns an HTTP response object. This method allows the Durable Object to emulate an HTTP server where a Worker with a binding to that object is the client. + + - This method can be `async`. + +### `alarm` + +- alarm(): + + - See [Alarms](/durable-objects/api/alarms/). + ### `webSocketMessage` - webSocketMessage(ws , message{" "} ): @@ -39,7 +67,13 @@ import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/compon ## Properties -{/* Properties of DO Base Class TBC */} +### `DurableObjectState` + +See [`DurableObjectState` documentation](/durable-objects/api/state/). + +### `Env` + +A list of bindings which are available to the Durable Object. ## Related resources diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index eb83212ac73c844..2dfae8fd0eca3a2 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -267,22 +267,6 @@ export class MyDurableObject extends DurableObject { - None. -## Extended methods - -### `serializeAttachment` - -- serializeAttachment(value ): - - - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. - - - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. - -### `deserializeAttachment` - -- `deserializeAttachment()`: - - - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. - ## Properties ### `id` diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index 204e172c2f915fe..997d857f25d11c2 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -379,6 +379,22 @@ If you are using older versions, note that while hibernatable WebSocket events s ::: +## Extended methods + +### `serializeAttachment` + +- serializeAttachment(value ): + + - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. + + - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. + +### `deserializeAttachment` + +- `deserializeAttachment()`: + + - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. + ## Related resources - [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) From 5a9944d9d8ae781969b95747579338f919a8130e Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 09:18:11 +0000 Subject: [PATCH 06/12] Revert "Adding fetch and alarm. Actioning PR comments." This reverts commit 6088c072c164d7787508f6b633deecdcf1ecec2c. --- package-lock.json | 25 ++++++++---- src/content/docs/durable-objects/api/base.mdx | 40 ++----------------- .../docs/durable-objects/api/state.mdx | 16 ++++++++ .../best-practices/websockets.mdx | 16 -------- 4 files changed, 36 insertions(+), 61 deletions(-) diff --git a/package-lock.json b/package-lock.json index 2b2b367ae63a453..a13f8ca5a0ee9ff 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6541,11 +6541,10 @@ } }, "node_modules/cross-spawn": { - "version": "7.0.6", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", - "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", + "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", "dev": true, - "license": "MIT", "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", @@ -17697,17 +17696,27 @@ } }, "node_modules/youch": { - "version": "3.3.4", - "resolved": "https://registry.npmjs.org/youch/-/youch-3.3.4.tgz", - "integrity": "sha512-UeVBXie8cA35DS6+nBkls68xaBBXCye0CNznrhszZjTbRVnJKQuNsyLKBTTL4ln1o1rh2PKtv35twV7irj5SEg==", + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/youch/-/youch-3.3.3.tgz", + "integrity": "sha512-qSFXUk3UZBLfggAW3dJKg0BMblG5biqSF8M34E06o5CSsZtH92u9Hqmj2RzGiHDi64fhe83+4tENFP2DB6t6ZA==", "dev": true, "license": "MIT", "dependencies": { - "cookie": "^0.7.1", + "cookie": "^0.5.0", "mustache": "^4.2.0", "stacktracey": "^2.1.8" } }, + "node_modules/youch/node_modules/cookie": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.5.0.tgz", + "integrity": "sha512-YZ3GUyn/o8gfKJlnlX7g7xq4gyO6OSuhGPKaaGssGB2qgDUS0gPgtTvoyZLTt9Ab6dC4hfc9dV5arkvc/OCmrw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, "node_modules/zod": { "version": "3.23.8", "resolved": "https://registry.npmjs.org/zod/-/zod-3.23.8.tgz", diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index d7ad2b4be59e624..5acd37a78e875ef 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -5,40 +5,12 @@ sidebar: order: 1 --- -import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo, TypeScriptExample } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; -The `DurableObject` base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the [WebSocket Hibernation API](#/durable-objects/best-practices/websockets/#websocket-hibernation-api). To provide a concrete example, here is a Durable Object `MyDurableObject` which extends `DurableObject` and implements the fetch handler to return "Hello, World!" to the calling Worker. - - -```ts -export class MyDurableObject extends DurableObject { - constructor(ctx: DurableObjectState, env: Env) { - super(ctx, env); - } - - async fetch(request: Request) { - return new Response("Hello, World!"); - } -} -``` - +{/* DEFINITION OF DO BASE CLASS TBC */} ## Methods -### `fetch` - -- fetch(): | - - - Takes an HTTP request object and returns an HTTP response object. This method allows the Durable Object to emulate an HTTP server where a Worker with a binding to that object is the client. - - - This method can be `async`. - -### `alarm` - -- alarm(): - - - See [Alarms](/durable-objects/api/alarms/). - ### `webSocketMessage` - webSocketMessage(ws , message{" "} ): @@ -67,13 +39,7 @@ export class MyDurableObject extends DurableObject { ## Properties -### `DurableObjectState` - -See [`DurableObjectState` documentation](/durable-objects/api/state/). - -### `Env` - -A list of bindings which are available to the Durable Object. +{/* Properties of DO Base Class TBC */} ## Related resources diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index 2dfae8fd0eca3a2..eb83212ac73c844 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -267,6 +267,22 @@ export class MyDurableObject extends DurableObject { - None. +## Extended methods + +### `serializeAttachment` + +- serializeAttachment(value ): + + - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. + + - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. + +### `deserializeAttachment` + +- `deserializeAttachment()`: + + - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. + ## Properties ### `id` diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index 997d857f25d11c2..204e172c2f915fe 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -379,22 +379,6 @@ If you are using older versions, note that while hibernatable WebSocket events s ::: -## Extended methods - -### `serializeAttachment` - -- serializeAttachment(value ): - - - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. - - - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. - -### `deserializeAttachment` - -- `deserializeAttachment()`: - - - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. - ## Related resources - [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) From d9e77689126c218dcdac82a7f501571df7dfa069 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 09:21:35 +0000 Subject: [PATCH 07/12] Adding fetch and alarm to base class chapter. Actioning other PR comments. --- src/content/docs/durable-objects/api/base.mdx | 38 ++++++++++++++++++- .../docs/durable-objects/api/state.mdx | 16 -------- .../best-practices/websockets.mdx | 16 ++++++++ 3 files changed, 52 insertions(+), 18 deletions(-) diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index 5acd37a78e875ef..b59c2377aa31a52 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -7,10 +7,38 @@ sidebar: import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; -{/* DEFINITION OF DO BASE CLASS TBC */} +The `DurableObject` base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the [WebSocket Hibernation API](#/durable-objects/best-practices/websockets/#websocket-hibernation-api). To provide a concrete example, here is a Durable Object `MyDurableObject` which extends `DurableObject` and implements the fetch handler to return "Hello, World!" to the calling Worker. + + +```ts +export class MyDurableObject extends DurableObject { + constructor(ctx: DurableObjectState, env: Env) { + super(ctx, env); + } + + async fetch(request: Request) { + return new Response("Hello, World!"); + } +} +``` + ## Methods +### `fetch` + +- fetch(): | + + - Takes an HTTP request object and returns an HTTP response object. This method allows the Durable Object to emulate an HTTP server where a Worker with a binding to that object is the client. + + - This method can be `async`. + +### `alarm` + +- alarm(): + + - See [Alarms](/durable-objects/api/alarms/). + ### `webSocketMessage` - webSocketMessage(ws , message{" "} ): @@ -39,7 +67,13 @@ import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/compon ## Properties -{/* Properties of DO Base Class TBC */} +### `DurableObjectState` + +See [`DurableObjectState` documentation](/durable-objects/api/state/). + +### `Env` + +A list of bindings which are available to the Durable Object. ## Related resources diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index eb83212ac73c844..2dfae8fd0eca3a2 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -267,22 +267,6 @@ export class MyDurableObject extends DurableObject { - None. -## Extended methods - -### `serializeAttachment` - -- serializeAttachment(value ): - - - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. - - - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. - -### `deserializeAttachment` - -- `deserializeAttachment()`: - - - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. - ## Properties ### `id` diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index 204e172c2f915fe..997d857f25d11c2 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -379,6 +379,22 @@ If you are using older versions, note that while hibernatable WebSocket events s ::: +## Extended methods + +### `serializeAttachment` + +- serializeAttachment(value ): + + - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. + + - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. + +### `deserializeAttachment` + +- `deserializeAttachment()`: + + - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists. + ## Related resources - [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) From fadcb3be7160245c5239825232f57f7d31d5c306 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 09:29:35 +0000 Subject: [PATCH 08/12] Adding alarm handler method into DO base class. --- src/content/docs/durable-objects/api/base.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index b59c2377aa31a52..d9964df8b48e2ac 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -37,7 +37,13 @@ export class MyDurableObject extends DurableObject { - alarm(): - - See [Alarms](/durable-objects/api/alarms/). + - Called by the system when a scheduled alarm time is reached. + + - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. Retries will be performed if the method fails with an uncaught exception. + + - This method can be `async`. + + - Refer to [Alarms](/durable-objects/api/alarms/#alarm) for more information. ### `webSocketMessage` From cb2ba3e934f2dd2da4acf15510559cda8b7b2ecf Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 09:33:31 +0000 Subject: [PATCH 09/12] Importing missing package. --- src/content/docs/durable-objects/api/base.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index d9964df8b48e2ac..eaeeebbbbe13125 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 --- -import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo, TypeScriptExample } from "~/components"; The `DurableObject` base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the [WebSocket Hibernation API](#/durable-objects/best-practices/websockets/#websocket-hibernation-api). To provide a concrete example, here is a Durable Object `MyDurableObject` which extends `DurableObject` and implements the fetch handler to return "Hello, World!" to the calling Worker. @@ -43,7 +43,7 @@ export class MyDurableObject extends DurableObject { - This method can be `async`. - - Refer to [Alarms](/durable-objects/api/alarms/#alarm) for more information. + - Refer to [`alarm`](/durable-objects/api/alarms/#alarm) for more information. ### `webSocketMessage` From 1012ba578874db89c513cd88289e9ab2574c3798 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 10:33:02 +0000 Subject: [PATCH 10/12] Adding missing component x2 --- src/content/docs/durable-objects/best-practices/websockets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index 997d857f25d11c2..a4b635a436eda73 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -5,7 +5,7 @@ sidebar: order: 5 --- -import { Tabs, TabItem, GlossaryTooltip } from "~/components"; +import { Tabs, TabItem, GlossaryTooltip, Type } from "~/components"; WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server. Both Cloudflare Durable Objects and Workers can act as WebSocket endpoints – either as a client or as a server. Because WebSocket sessions are long-lived, applications commonly use Durable Objects to accept either the client or server connection. While there are other use cases for using Workers exclusively with WebSockets, for example proxying WebSocket messages, WebSockets are most useful when combined with Durable Objects. From 26a7a443d9a043daf93f83e0e75cdf02dc0e5aa1 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 14:47:22 +0000 Subject: [PATCH 11/12] Clarifying language on serializeAttachment method. --- src/content/docs/durable-objects/best-practices/websockets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/best-practices/websockets.mdx b/src/content/docs/durable-objects/best-practices/websockets.mdx index a4b635a436eda73..c77974e05b3cec8 100644 --- a/src/content/docs/durable-objects/best-practices/websockets.mdx +++ b/src/content/docs/durable-objects/best-practices/websockets.mdx @@ -385,7 +385,7 @@ If you are using older versions, note that while hibernatable WebSocket events s - serializeAttachment(value ): - - Keeps a copy of `value` in memory (not on disk) to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. + - Keeps a copy of `value` associated with the WebSocket to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. If the value needs to be durable please use [Durable Object Storage](/durable-objects/api/storage-api/). - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later. From 0ada43d5f50245c2d61505996507d9dd338789fa Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 4 Dec 2024 15:08:19 +0000 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: marciocloudflare <83226960+marciocloudflare@users.noreply.github.com> --- src/content/docs/durable-objects/api/base.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/api/base.mdx b/src/content/docs/durable-objects/api/base.mdx index eaeeebbbbe13125..2ca7fc160aad13f 100644 --- a/src/content/docs/durable-objects/api/base.mdx +++ b/src/content/docs/durable-objects/api/base.mdx @@ -39,7 +39,7 @@ export class MyDurableObject extends DurableObject { - Called by the system when a scheduled alarm time is reached. - - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. Retries will be performed if the method fails with an uncaught exception. + - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception. - This method can be `async`. @@ -57,7 +57,7 @@ export class MyDurableObject extends DurableObject { ### `webSocketClose` -- webSocketClose(ws , code ,reason , wasClean ): +- webSocketClose(ws , code , reason , wasClean ): - Called by the system when a WebSocket is closed. `wasClean()` is true if the connection closed cleanly, false otherwise.