From 0597b720c25d4b4f81bcc8cf8c18a6598ed5cd03 Mon Sep 17 00:00:00 2001 From: Joshua Howard Date: Thu, 10 Oct 2024 10:46:54 -0500 Subject: [PATCH] fixup! Move reference documentation out of Durable Objects best practices --- .../docs/durable-objects/api/namespace.mdx | 5 ++--- .../get-started/tutorial-with-sql-api.mdx | 3 +-- .../get-started/walkthrough.mdx | 3 +-- .../durable-objects/reference/websockets.mdx | 19 ++++++------------- .../use-queues-with-durable-objects.mdx | 9 ++++----- .../gradual-deployments.mdx | 2 +- 6 files changed, 15 insertions(+), 26 deletions(-) diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index c50a18f8cae6e87..946c10aad081c2c 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -71,7 +71,7 @@ export default { ### `idFromName` -`idFromName` creates a [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class from a particular name. +`idFromName` creates a unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. Named Durable Object instances are the most common method of referring to Durable Object instances. ```js const fooId = env.MY_DURABLE_OBJECT.idFromName("foo"); @@ -88,7 +88,7 @@ const barId = env.MY_DURABLE_OBJECT.idFromName("bar"); ### `newUniqueId` -`newUniqueId` creates a `DurableObjectId` which refers to an individual instance of the Durable Object class. When using `newUniqueId`, you need to store the ID as a string in order to refer to the same Durable Object again in the future. For example, the ID can be stored in Workers KV, another Durable Object instance, or in a cookie in the user's browser. +`newUniqueId` creates a randomly generated and unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. IDs created using `newUniqueId`, will need to be stored as a string in order to refer to the same Durable Object again in the future. For example, the ID can be stored in Workers KV, another Durable Object instance, or in a cookie in the user's browser. ```js const id = env.MY_DURABLE_OBJECT.newUniqueId(); @@ -165,4 +165,3 @@ const euId = subnamespace.idFromName("foo"); ## Related resources - [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). -- [Durable Objects best practices](/durable-objects/best-practices/access-durable-objects-from-a-worker/). diff --git a/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx index 4c2e79e2a6144c6..a87688cd7b381a2 100644 --- a/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx +++ b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx @@ -185,7 +185,7 @@ export default { In the code above, you have: 1. Exported your Worker's main event handlers, such as the `fetch()` handler for receiving HTTP requests. -2. Passed `env` into the `fetch()` handler. Bindings are delivered as a property of the environment object passed as the second parameter when an event handler or class constructor is invoked. By calling the `idFromName()` function on the binding, you use a string-derived object ID. You can also ask the system to [generate random unique IDs](/durable-objects/best-practices/access-durable-objects-from-a-worker/#generate-ids-randomly). System-generated unique IDs have better performance characteristics, but require you to store the ID somewhere to access the Object again later. +2. Passed `env` into the `fetch()` handler. Bindings are delivered as a property of the environment object passed as the second parameter when an event handler or class constructor is invoked. By calling the `idFromName()` function on the binding, you use a string-derived object ID. You can also ask the system to [generate random unique IDs](/durable-objects/api/namespace/#newuniqueid). System-generated unique IDs have better performance characteristics, but require you to store the ID somewhere to access the Object again later. 3. Derived an object ID from the URL path. `MY_DURABLE_OBJECT.idFromName()` always returns the same ID when given the same string as input (and called on the same class), but never the same ID for two different strings (or for different classes). In this case, you are creating a new object for each unique path. 4. Constructed the stub for the Durable Object using the ID. A stub is a client object used to send messages to the Durable Object. 5. Called a Durable Object by invoking a RPC method, `sayHello()`, on the Durable Object, which returns a `Hello, World!` string greeting. @@ -258,7 +258,6 @@ By finishing this tutorial, you have successfully created, tested and deployed a ### Related resources -- [Access a Durable Object from a Worker](/durable-objects/best-practices/access-durable-objects-from-a-worker/) - [Create Durable Object stubs](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) - [Access Durable Objects Storage](/durable-objects/best-practices/access-durable-objects-storage/) - [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare) - Helpful tools for mocking and testing your Durable Objects. diff --git a/src/content/docs/durable-objects/get-started/walkthrough.mdx b/src/content/docs/durable-objects/get-started/walkthrough.mdx index 8a1154602e4b02f..feada4dea356241 100644 --- a/src/content/docs/durable-objects/get-started/walkthrough.mdx +++ b/src/content/docs/durable-objects/get-started/walkthrough.mdx @@ -258,6 +258,5 @@ By finishing this tutorial, you have successfully created, tested and deployed a ### Related resources -- [Access a Durable Object from a Worker](/durable-objects/best-practices/access-durable-objects-from-a-worker/) -- [Create Durable Object stubs](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) +- [Send requests to Durable Objects](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) - [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare) - Helpful tools for mocking and testing your Durable Objects. diff --git a/src/content/docs/durable-objects/reference/websockets.mdx b/src/content/docs/durable-objects/reference/websockets.mdx index fc32364f937c402..0345fa49d578645 100644 --- a/src/content/docs/durable-objects/reference/websockets.mdx +++ b/src/content/docs/durable-objects/reference/websockets.mdx @@ -3,7 +3,6 @@ pcx_content_type: concept title: Durable Objects with WebSockets sidebar: order: 3 - --- [WebSockets](/durable-objects/api/websockets/) allow real time communication between a client and server. Both Cloudflare Durable Objects and Workers can act as WebSocket endpoints – either as a client or as a server. @@ -14,16 +13,14 @@ Durable Objects provide a single-point-of-coordination for [Cloudflare Workers]( While there are other use cases for using Workers exclusively with WebSockets, WebSockets are most useful when combined with Durable Objects. -When a client connects to your application using a WebSocket, you need a way for server-generated messages to be sent using the existing socket connection. Multiple clients can establish a WebSocket connection with a specific Durable Object addressed by its [unique ID](/durable-objects/best-practices/access-durable-objects-from-a-worker/#1-create-durable-object-ids). The Durable Object can then send messages to each client over the WebSocket connection. +When a client connects to your application using a WebSocket, you need a way for server-generated messages to be sent using the existing socket connection. Multiple clients can establish a WebSocket connection with a specific Durable Object addressed by its unique ID. The Durable Object can then send messages to each client over the WebSocket connection. Durable Objects can use the web standard APIs described in [WebSockets API](/durable-objects/api/websockets/). Refer to [Cloudflare Edge Chat Demo](https://github.com/cloudflare/workers-chat-demo) for an example of using Durable Objects with WebSockets. :::caution[WebSockets disconnection] - Code updates will disconnect all WebSockets. If you deploy a new version of a Worker, every Durable Object is restarted. Any connections to old Durable Objects will be disconnected. - ::: ## WebSocket Hibernation @@ -32,19 +29,17 @@ The WebSocket Hibernation API allows a Durable Object that is not currently runn :::note - Hibernation is only supported when a Durable Object acts as a WebSocket server. Outgoing WebSockets cannot be hibernated as of now. - ::: A Durable Object with WebSockets created via the Hibernation API will not incur billable [Duration (GB-s) charges](/durable-objects/platform/pricing/) during periods of inactivity, unlike Durable Objects using the [regular WebSockets API](/workers/runtime-apis/websockets/). The WebSocket Hibernation API includes: -* Cloudflare-specific extensions to the web standard WebSocket API. -* Related methods on the [`state`](/durable-objects/api/websockets/#state-methods) of the Durable Object. -* [Handler methods](/durable-objects/api/websockets/#handler-methods) that a Durable Object can implement for processing WebSocket events. +- Cloudflare-specific extensions to the web standard WebSocket API. +- Related methods on the [`state`](/durable-objects/api/websockets/#state-methods) of the Durable Object. +- [Handler methods](/durable-objects/api/websockets/#handler-methods) that a Durable Object can implement for processing WebSocket events. The WebSocket Hibernation API enables you to terminate (not proxy) WebSocket connections within a Durable Object, and push messages to all connected clients based on state stored within the [Storage API](/durable-objects/api/storage-api/), HTTP fetches to external services, and/or data stored in [R2](/r2/) and [Workers KV](/kv/api/). @@ -54,16 +49,14 @@ If an event occurs for a hibernated Durable Object's corresponding handler metho :::caution[Support for local development] - 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/api/websockets/#websocketmessage) will still be delivered, the Durable Object will never be evicted from memory. - ::: -*** +--- ## Related resources -* Refer to [Build a WebSocket server with WebSocket Hibernation](/durable-objects/examples/websocket-hibernation-server/) to learn more about building a WebSocket server using WebSocket Hibernation on Durable Objects and Workers. +- Refer to [Build a WebSocket server with WebSocket Hibernation](/durable-objects/examples/websocket-hibernation-server/) to learn more about building a WebSocket server using WebSocket Hibernation on Durable Objects and Workers. diff --git a/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx b/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx index 851a909d53430d2..3c420b8009d766f 100644 --- a/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx +++ b/src/content/docs/queues/examples/use-queues-with-durable-objects.mdx @@ -8,16 +8,15 @@ head: - tag: title content: Queues - Use Queues and Durable Objects description: Publish to a queue from within a Durable Object. - --- The following example shows you how to write a Worker script to publish to [Cloudflare Queues](/queues/) from within a [Durable Object](/durable-objects/). Prerequisites: -* A [queue created](/queues/get-started/#3-create-a-queue) via the Cloudflare dashboard or the [wrangler CLI](/workers/wrangler/install-and-update/). -* A [configured **producer** binding](/queues/configuration/configure-queues/#producer) in the Cloudflare dashboard or `wrangler.toml` file. -* A [Durable Object namespace binding](/workers/wrangler/configuration/#durable-objects). +- A [queue created](/queues/get-started/#3-create-a-queue) via the Cloudflare dashboard or the [wrangler CLI](/workers/wrangler/install-and-update/). +- A [configured **producer** binding](/queues/configuration/configure-queues/#producer) in the Cloudflare dashboard or `wrangler.toml` file. +- A [Durable Object namespace binding](/workers/wrangler/configuration/#durable-objects). Configure your `wrangler.toml` file as follows: @@ -44,7 +43,7 @@ The following Worker script: 2. Passes request data to the Durable Object. 3. Publishes to a queue from within the Durable Object. -The `constructor()` in the Durable Object makes your `Environment` available (in scope) on `this.env` to the [`fetch()` handler](/durable-objects/best-practices/access-durable-objects-from-a-worker/#3-use-fetch-handler-method) in the Durable Object. +The `constructor()` in the Durable Object makes your `Environment` available (in scope) on `this.env` to the [`fetch()` handler](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) in the Durable Object. ```ts interface Env { diff --git a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx b/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx index 333cc558fbc3e90..b7652480d2c2e7a 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx +++ b/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx @@ -205,7 +205,7 @@ When you create a new gradual deployment for a Durable Object Worker, each Durab ### Example -This example assumes that you have previously created 3 Durable Objects and [derived their IDs from the names](/durable-objects/best-practices/access-durable-objects-from-a-worker/#derive-ids-from-names) "foo", "bar" and "baz". +This example assumes that you have previously created 3 Durable Objects and [derived their IDs from the names](/durable-objects/api/namespace/#idfromname) "foo", "bar" and "baz". Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.