[Durable Objects] Docs enhancement part 1 (#17794)

* Adding glossary terms for DO where relevant.

* Lifting text from the Blog to define DO, adding one paragraph which talks about the strength of DO.

* Moving the Glossary into "Reference" section.

* General reordering of sidebar.
Moving Changelog out of Platform into its own item.
Moving Glossary into Reference.
Updating Changelog YAML with new Changelog location.

* Adding redirects.

* Adding missing /

* Reverting Overview text for now.

Author: Oxyjun

public/_redirects

@@ -368,6 +368,8 @@
 /durable-objects/reference/troubleshooting/ /durable-objects/observability/troubleshooting/ 301
 /durable-objects/reference/graphql-analytics/ /durable-objects/observability/graphql-analytics/ 301
 /durable-objects/api/transactional-storage-api/ /durable-objects/api/storage-api/ 301
+/durable-objects/platform/changelog/ /durable-objects/changelog/ 301
+/durable-objects/glossary/ /durable-objects/reference/glossary/ 301
 
 # email-routing
 /email-routing/enable-email-routing/ /email-routing/get-started/enable-email-routing/ 301
@@ -379,7 +381,7 @@
 /email-security/setup/api-deployment/ /email-security/setup/post-delivery-deployment/api/ 301
 /email-security/setup/api-deployment/office365-api/ /email-security/setup/post-delivery-deployment/api/office365-api/ 301
 /email-security/email-configuration/retract-settings/gmail-retraction/ /email-security/deployment/api/setup/gsuite-bcc-setup/add-retraction/ 301
- 
+
 
 # firewall
 /firewall/api/cf-lists/ /waf/tools/lists/lists-api/ 301

src/content/changelogs/durable-objects.yaml

@@ -1,5 +1,5 @@
 ---
-link: "/durable-objects/platform/changelog/"
+link: "/durable-objects/changelog/"
 productName: Durable Objects
 productLink: "/durable-objects/"
 productArea: Developer platform

src/content/docs/durable-objects/api/alarms.mdx

@@ -5,11 +5,11 @@ sidebar:
   order: 6
 ---
 
-import { Type } from "~/components";
+import { Type, GlossaryTooltip } from "~/components";
 
 ## Background
 
-Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm's scheduled time comes, the `alarm()` handler method will be called. Alarms are modified using the [Storage API](/durable-objects/api/storage-api/), and alarm operations follow the same rules as other storage operations.
+Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm's scheduled time comes, the `alarm()` handler method will be called. Alarms are modified using the <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip>, and alarm operations follow the same rules as other storage operations.
 
 Notably:
 
@@ -37,10 +37,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w
 
 ### setAlarm
 
-- <code>
-  	{" "}
-  	setAlarm(scheduledTimeMs <Type text="number" />)
-  </code>
+- <code>{" "}setAlarm(scheduledTimeMs <Type text="number" />)</code>
   : <Type text="void" />
 
   - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch.

src/content/docs/durable-objects/api/id.mdx

@@ -5,11 +5,11 @@ sidebar:
   order: 2
 ---
 
-import { Render, Tabs, TabItem } from "~/components";
+import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components";
 
 ## Description
 
-A Durable Object ID is a 64-digit hexadecimal number used to identify a Durable Object. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface.
+A Durable Object ID is a 64-digit hexadecimal number used to identify a <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip>. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface.
 
 The `DurableObjectId` interface refers to a new or existing Durable Object. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a [`DurableObjectStub`](/durable-objects/api/stub) for submitting requests to a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after creating a stub from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
 

src/content/docs/durable-objects/api/namespace.mdx

@@ -5,11 +5,11 @@ sidebar:
   order: 1
 ---
 
-import { Render, Tabs, TabItem } from "~/components";
+import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components";
 
 ## Description
 
-A Durable Object namespace is a set of Durable Objects that are backed by the same Durable Object class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.
+A Durable Object namespace is a set of Durable Objects that are backed by the same <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.
 
 The `DurableObjectNamespace` interface is used to obtain a reference to new or existing Durable Objects. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface when referencing bindings declared in `wrangler.toml`.
 
@@ -129,7 +129,7 @@ After this first use, the location of the Durable Object will be cached around t
 
 `get` obtains a [`DurableObjectStub`](/durable-objects/api/stub) from a [`DurableObjectId`](/durable-objects/api/id) which can be used to invoke methods on a Durable Object.
 
-This method returns the stub immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip.
+This method returns the <GlossaryTooltip term="stub">stub</GlossaryTooltip> immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip.
 
 ```js
 const id = env.MY_DURABLE_OBJECT.newUniqueId();

src/content/docs/durable-objects/api/state.mdx

@@ -9,9 +9,9 @@ import { Tabs, TabItem, GlossaryTooltip } from "~/components";
 
 ## Description
 
-The `DurableObjectState` interface is accessible as an instance property on the Durable Objects class. This interface encapsulates methods that modify the state of a Durable Object, for example which WebSockets are attached to a Durable Object or how the runtime should handle concurrent Durable Object requests.
+The `DurableObjectState` interface is accessible as an instance property on the <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. This interface encapsulates methods that modify the state of a Durable Object, for example which WebSockets are attached to a Durable Object or how the runtime should handle concurrent Durable Object requests.
 
-The `DurableObjectState` interface is different from the [Storage API](/durable-objects/api/storage-api) in that it does not have top-level methods which manipulate persistent application data. These methods are instead encapsulated in the [`DurableObjectStorage`](/durable-objects/api/storage-api) interface and accessed by [`DurableObjectState::storage`](/durable-objects/api/state/#storage).
+The `DurableObjectState` interface is different from the <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip> in that it does not have top-level methods which manipulate persistent application data. These methods are instead encapsulated in the [`DurableObjectStorage`](/durable-objects/api/storage-api) interface and accessed by [`DurableObjectState::storage`](/durable-objects/api/state/#storage).
 
 <Tabs> <TabItem label="JavaScript" icon="seti:javascript">
 

src/content/docs/durable-objects/api/storage-api.mdx

@@ -6,9 +6,9 @@ sidebar:
 
 ---
 
-import { Render, Type, MetaInfo } from "~/components";
+import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components";
 
-The Storage API allows Durable Objects to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.
+The Storage API allows <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.
 
 Durable Objects gain access to a persistent Storage API via `ctx.storage`, on the `ctx` parameter passed to the Durable Object constructor.
 

src/content/docs/durable-objects/api/stub.mdx

@@ -5,15 +5,15 @@ sidebar:
   order: 3
 ---
 
-import { Render } from "~/components";
+import { Render, GlossaryTooltip } from "~/components";
 
 ## Description
 
-The `DurableObjectStub` interface is a client used to invoke methods on a remote Durable Object. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub.
+The `DurableObjectStub` interface is a client used to invoke methods on a remote <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip>. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub.
 
 Durable Objects implement E-order semantics, a concept deriving from the [E distributed programming language](<https://en.wikipedia.org/wiki/E_(programming_language)>). When you make multiple calls to the same Durable Object, it is guaranteed that the calls will be delivered to the remote Durable Object in the order in which you made them. E-order semantics makes many distributed programming problems easier. E-order is implemented by the [Cap'n Proto](https://capnproto.org) distributed object-capability RPC protocol, which Cloudflare Workers uses for internal communications.
 
-If an exception is thrown by a Durable Object stub all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs.
+If an exception is thrown by a Durable Object <GlossaryTooltip term="stub">stub</GlossaryTooltip> all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs.
 
 <Render file="example-rpc" />
 

src/content/docs/durable-objects/api/websockets.mdx

@@ -5,13 +5,13 @@ sidebar:
   order: 5
 ---
 
-import { Render, Type, MetaInfo } from "~/components";
+import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components";
 
 ## Background
 
 WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server.
 
-Durable Objects support the Workers Runtime [WebSocket API](/workers/runtime-apis/websockets/). Your Durable Object can act as a single point-of-coordination for WebSocket sessions, giving you full control over messages sent to and from clients, allowing you to build applications like chat rooms and multiplayer games.
+<GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> support the Workers Runtime [WebSocket API](/workers/runtime-apis/websockets/). Your Durable Object can act as a single point-of-coordination for WebSocket sessions, giving you full control over messages sent to and from clients, allowing you to build applications like chat rooms and multiplayer games.
 
 For more information beyond the API reference, refer to the [Build a WebSocket server](/durable-objects/examples/websocket-server/) example.
 

src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx

@@ -6,17 +6,17 @@ sidebar:
 
 ---
 
-import { Render } from "~/components";
+import { Render, GlossaryTooltip } from "~/components";
 
-Durable Objects are a powerful compute API that provides a compute with storage building block. Each Durable Object has its own private, transactional and strongly consistent storage. Durable Objects [Storage API](/durable-objects/api/storage-api/#methods) provides access to a Durable Object's attached storage.
+<GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> are a powerful compute API that provides a compute with storage building block. Each Durable Object has its own private, transactional and strongly consistent storage. Durable Objects <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip> provides access to a Durable Object's attached storage.
 
 A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/configuration/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects.
 
 ## Access storage
 
-By default, a Durable Object class leverages a key-value storage backend. New Durable Object classes can opt-in to using a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).
+By default, a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip> leverages a key-value storage backend. New Durable Object classes can opt-in to using a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).
 
-[Storage API](/durable-objects/api/storage-api/#methods) methods are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API.
+[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API.
 
 A common pattern is to initialize a Durable Object from [persistent storage](/durable-objects/api/storage-api/) and set instance variables the first time it is accessed. Since future accesses are routed to the same Durable Object, it is then possible to return any initialized values without making further calls to persistent storage.
 
@@ -44,7 +44,7 @@ export class Counter extends DurableObject {
 ```
 ### Removing a Durable Object's storage
 
-A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting alarms), then storage remains empty, and so the Durable Object will no longer exist once it shuts down.
+A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting <GlossaryTooltip term="alarm">alarms</GlossaryTooltip>), then storage remains empty, and so the Durable Object will no longer exist once it shuts down.
 
 However if you ever write using [Storage API](/durable-objects/api/storage-api/), including setting alarms, then you must explicitly call [`storage.deleteAll()`](/durable-objects/api/storage-api/#deleteall) to empty storage. It is not sufficient to simply delete the specific data that you wrote, such as deleting a key or dropping a table, as some metadata may remain. The only way to remove all storage is to call `deleteAll()`. Calling `deleteAll()` ensures that a Durable Object will not be billed for storage.