Address confusing comment around input and output gates (cloudflare#19058)

* Address confusing comment around input and output gates

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

Co-authored-by: Jun Lee <[email protected]>

---------

Co-authored-by: Jun Lee <[email protected]>

Author: joshthoward

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

@@ -5,7 +5,13 @@ sidebar:
   order: 6
 ---
 
-import { Render, Type, MetaInfo, GlossaryTooltip, TypeScriptExample } from "~/components";
+import {
+	Render,
+	Type,
+	MetaInfo,
+	GlossaryTooltip,
+	TypeScriptExample,
+} from "~/components";
 
 The Durable Object 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.
 
@@ -18,9 +24,9 @@ Note that Durable Object storage is scoped by individual <GlossaryTooltip term="
 However, storage is scoped per individual Durable Object.
 :::
 
-Durable Objects gain access to a persistent Durable Object Storage API via `ctx.storage`, on the `ctx` parameter passed to the Durable Object constructor.
+Durable Objects gain access to a persistent Durable Object Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` when the `ctx` parameter passed to the Durable Object constructor.
 
-While access to a Durable Object is single-threaded, request executions can still interleave with each other when they wait on I/O, such as when waiting on the promises returned by persistent storage methods or `fetch()` requests.
+JavaScript is a single-threaded and event-driven programming language. This means that JavaScript runtimes, by default, allow requests to interleave with each other which can lead to concurrency bugs. The Durable Objects runtime uses a combination of <GlossaryTooltip term="input gate">input gates</GlossaryTooltip> and <GlossaryTooltip term="output gate">output gates</GlossaryTooltip> to avoid this type of concurrency bug when performing storage operations.
 
 The following code snippet shows you how to store and retrieve data using the Durable Object Storage API.
 
@@ -31,13 +37,15 @@ export class Counter extends DurableObject {
 		super(ctx, env);
 	}
 
-	async increment(): Promise<number> {
-		let value: number = (await this.ctx.storage.get('value')) || 0;
-		value += 1;
-		await this.ctx.storage.put('value', value);
-		return value;
-	}
+    async increment(): Promise<number> {
+    	let value: number = (await this.ctx.storage.get('value')) || 0;
+    	value += 1;
+    	await this.ctx.storage.put('value', value);
+    	return value;
+    }
+
 }
+
 ```
 </TypeScriptExample>
 
@@ -255,3 +263,4 @@ The `put()` method returns a `Promise`, but most applications can discard this p
 
 - [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/)
 - [WebSockets API](/durable-objects/best-practices/websockets/)
+```

src/content/glossary/durable-objects.yaml

@@ -63,3 +63,11 @@ entries:
   - term: "event context"
     general_definition: |-
       The duration of time that a Durable Object is processing an event, such as a remote procedure call. [Compute duration charges](/durable-objects/platform/pricing) are incurred for the duration of the event context.
+
+  - term: "input gate"
+    general_definition: |-
+      While a storage operation is executing, no events shall be delivered to a Durable Object except for storage completion events. Any other events will be deferred until such a time as the object is no longer executing JavaScript code and is no longer waiting for any storage operations. We say that these events are waiting for the "input gate" to open.
+
+  - term: "output gate"
+    general_definition: |-
+      When a storage write operation is in progress, any new outgoing network messages will be held back until the write has completed. We say that these messages are waiting for the "output gate" to open. If the write ultimately fails, the outgoing network messages will be discarded and replaced with errors, while the Durable Object will be shut down and restarted from scratch.