[Durable Objects] Initial DO JS RPC docs#13765
[Durable Objects] Initial DO JS RPC docs#13765irvinebroque merged 1 commit intobib/jsrpc-api-docsfrom
Conversation
|
This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:
|
content/durable-objects/best-practices/access-durable-object-from-a-worker.md
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.md
Show resolved
Hide resolved
|
|
||
| {{<Aside type="note">}} | ||
|
|
||
| Prior to [RPC introduction](/workers/configuration/compatibility-dates/#remote-procedure-call-rpc), the `ctx` object for Durable Objects was known as `state`. `state` was the name of the Durable Object constructor parameter, so an application could use any other name. With RPC, the `DurableObject` superclass defines these values as properties, so they must have official names. `ctx` was chosen for consistency between `DurableObject` and `WorkerEntrypoint`. |
There was a problem hiding this comment.
| Prior to [RPC introduction](/workers/configuration/compatibility-dates/#remote-procedure-call-rpc), the `ctx` object for Durable Objects was known as `state`. `state` was the name of the Durable Object constructor parameter, so an application could use any other name. With RPC, the `DurableObject` superclass defines these values as properties, so they must have official names. `ctx` was chosen for consistency between `DurableObject` and `WorkerEntrypoint`. | |
| When you write a Worker that does not extend the [`DurableObject` class](/workers/configuration/compatibility-dates/#remote-procedure-call-rpc), the `ctx` object for Durable Objects was known as `state`. `state` was the name of the Durable Object constructor parameter, so an application could use any other name. With RPC, the `DurableObject` superclass defines these values as properties, so they must have official names. `ctx` was chosen for consistency between `DurableObject` and `WorkerEntrypoint`. |
it's this, right? that it still works the same way as before if you don't extend from DurableObject
There was a problem hiding this comment.
added suggestion and tweaked wording some more
There was a problem hiding this comment.
Yeah. Also if you really want, you can do:
export class Counter extends DurableObject {
state = this.ctx
// rest of your code here
}It's just that you'll end up with both this.state and this.ctx pointing to the same thing
There was a problem hiding this comment.
Separately, we will replace all mentions of state with ctx. @Maddy-Cloudflare are you able to tackle this next week?
content/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.md
Outdated
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.md
Show resolved
Hide resolved
content/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.md
Outdated
Show resolved
Hide resolved
| {{</table-wrap>}} | ||
|
|
||
| <sup>1</sup> A request is needed to create a WebSocket connection. There is no charge for outgoing WebSocket messages, nor for incoming [WebSocket protocol pings](https://www.rfc-editor.org/rfc/rfc6455#section-5.5.2). For compute requests billing-only, a 20:1 ratio is applied to incoming WebSocket messages to factor in smaller messages for real-time communication. For example, 100 WebSocket incoming messages would be charged as 5 requests for billing purposes. The 20:1 ratio does not affect Durable Object metrics and analytics, which reflect actual usage. | ||
| <sup>1</sup> A [RPC session](/workers/runtime-apis/rpc/lifecycle/) represents a billed request. Every [RPC method call](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#call-rpc-methods) on a [Durable Objects stub](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#get-a-durable-object-stub) is its own RPC session and therefore a single billed request. |
There was a problem hiding this comment.
| <sup>1</sup> A [RPC session](/workers/runtime-apis/rpc/lifecycle/) represents a billed request. Every [RPC method call](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#call-rpc-methods) on a [Durable Objects stub](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#get-a-durable-object-stub) is its own RPC session and therefore a single billed request. | |
| <sup>1</sup> Each [RPC session](/workers/runtime-apis/rpc/lifecycle/) is billed as one request to your Durable Object. Every [RPC method call](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#call-rpc-methods) on a [Durable Objects stub](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#get-a-durable-object-stub) is its own RPC session and therefore a single billed request. |
Think that this needs to be tweaked a bit based on content below?
Since only that top-level calls to create new stubs are billed as requests?
i.e.:
using foo = await env.MY_DO.bar(); // billed as a request
await foo.baz(); // treated as part of the same session, not billed^ where both of these calls would be considered calls on a stub from a Durable Object?
I wonder if one way to approach would be something like:
"Every time you call a public class method of your Durable Object via RPC, this creates a session, and each session is billed as one request"
@kentonv for correctness ^ — accurate?
There was a problem hiding this comment.
^ where both of these calls would be considered calls on a stub from a Durable Object?
but the second line await foo.baz() is not a call on the Durable Object stub itself. That's the difference to highlight.
There was a problem hiding this comment.
yeah, i think we are agreeing, just trying to figure out how to clarify what "is a Durable Object stub" i.e. I read that as somewhat ambiguous, could mean either:
- Any stub returned by a Durable Object
- Specifically, the stub "of" the Durable Object itself (in contrast to the stub provided by an
RpcTarget
Think what you have probably fine since clarified below? Was just wondering about if way to be super explicit
* Update DO counter example with RPC * Clarify RPC pricing * Rename "Configuration" to "Best Practices" section
* [do not merge] Revamp Service Bindings docs for RPC - Consolidates Service binding documentation to be within the Runtime APIs section of the docs. Currently docs for configuring a Service binding, and docs for how to write code around Service bindings are in separate sections of the docs, which makes getting started hard, requires jumping back and forth between pages. Relevant content from [the configuration section](https://github.com/cloudflare/cloudflare-docs/blob/production/content/workers/configuration/bindings/about-service-bindings.md) has been moved here, and will be removed. - Explains what Service bindings are and what to use them for. - Provides separate code examples RPC and HTTP modes of working with Service bindings. refs cloudflare/workerd#1658, cloudflare/workerd#1692, cloudflare/workerd#1729, cloudflare/workerd#1756, cloudflare/workerd#1757 * Remove Service bindings config page, update links, redirects * Apply suggestions from code review * Further consolidate bindings content within Runtime APIs, link from config section * Redirect from config bindings to Runtime APIs bindings * Update links to point to Runtime APIs bindings section * Fix redirects * Fix linter warnings * Bold bullet points for Service Bindings explainer * Add missing bindings to /runtime-apis/bindings * Add env vars and secrets links to /runtime-apis/bindings/ section * Update content/workers/runtime-apis/bindings/ai.md * Update content/workers/runtime-apis/bindings/service-bindings.md * Apply suggestions from code review Co-authored-by: Matt Silverlock <msilverlock@cloudflare.com> * Break docs into RPC and HTTP sections * Moving over more docs * Fix titles * Fixes * More docs * More, need to break apart into pages * more * fixup * Apply suggestions from code review Co-authored-by: Michael Hart <michael.hart.au@gmail.com> Co-authored-by: Kenton Varda <kenton@cloudflare.com> * Remove unnecessary changes * Create RPC and Context sections * Rename to /visibility * Edits * Fix naming * Edits * Add note about Queues to context docs * Clarify language in RPC example * Clarify service binding performance * Link to fetch handler in describing HTTP service bindings * Move remaining content over from tour doc * Add limits section, note about Smart Placement * Edits * WorkerB => MyWorker * Edits plus partial * Update content/workers/runtime-apis/bindings/service-bindings/rpc.md * Edits * Making sure internal doc covered, minus Durable Objects docs * Remove extraneous section * Call out RPC lifecycle docs in Service Bindings section * Update content/workers/runtime-apis/rpc/lifecycle.md * Edits to JSRPC API docs (#13801) * Clarify structured clonability. - Let's not talk about class instances being an exception to structured clone early on. Instead, we can have an aside later down the page. Most people probably wouldn't even expect structured clone to treat classes this way anyway, so telling the about it just to tell them that we don't do that is distracting. - Adjust the wording in anticipation of the fact that we're likely to add many more types that can be serialized, and this list will likely not keep up. The important thing here is to explain the types that have special behavior (they aren't just data structures treated in the obivous way). - Briefly describe these special semantics in the list, to get people excited to read more. * Minor wording clarification. It was confusing whether "object" here meant a plain object or a class instance. * Clarify garbage collection discussion. The language here was not very precise, and would have confused people who have a deep understanding of garbage collectors. * Better link for V8 explicit resource management. The previous link pointed to a mailing list thread of messages generated by the bug tracker. Let's link directly to the bug tracker. * Fix typo. * Clarify language about disposers. The language here said that stubs "can be disposed" at the end of a using block, which implies that they might not be, or that this is some sort of hint to the GC. It's more accurate to say that they *will* be disposed, that is, their disposer *will* be called, completely independent of GC. The advice about when to use `using` was unclear. I've changed the advice to simply say that the return value of any call should be stored into `using`, which is an easy rule to follow. * Remove "Sessions" section from lifecycle. This section was placed under "automatic disposal" but doesn't seem to belong here. I don't think it's really necessary to define a "session" unless we are then going to say something about sessions, but the word doesn't appear anywhere else on the page. Sessions are closely related to execution contexts, but execution contexts were already described earlier. * Clarify section on automatic disposal. * Correct docs on promise pipelining. The previous language incorrectly suggested that promise pipelining would kick in even if the caller awaited each promise. In fact, it is necessary to remove the `await` in order to get the benefits. * Fix reserved methods doc. The doc incorrectly stated that `fetch` and `connect` were special on `RpcTarget` in addition to `WorkerEntrypoint` and `DurableObject`. This is not correct. The doc didn't cover the numerous other reserved method names. * elide -> omit Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com> --------- Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com> * Apply suggestions from code review Co-authored-by: Greg Brimble <gbrimble@cloudflare.com> Co-authored-by: Kenton Varda <kenton@cloudflare.com> * Apply suggestions from code review Co-authored-by: Greg Brimble <gbrimble@cloudflare.com> * More RPC doc tweaks: Move stuff around! (#13808) * Move section on proxying stubs to compatible-types. This isn't really lifecycle-related. But it is another kind of thing that can be sent over RPC. * Move "promise pipelining" to compatible-types under "class instances". Promise pipelining isn't really about lifecycle. I think it fits under "class instances" because it is motivated by class instances. * Merge compatible-types into RPC root doc. The compatible-types list ends up highlighting the key exciting features of the RPC system. This should be at the root. * Tweak RPC root page. I'm removing "How it Works" with the function example because: 1. The example itself doesn't really explain "how it works". 2. We now present this same example down the page under "Functions". * Add changelog entry * Update content/workers/runtime-apis/rpc/lifecycle.md Co-authored-by: Greg Brimble <gbrimble@cloudflare.com> * More more JSRPC doc tweaks (#13840) * Add documentation for `rpc` compat flag. * Update links to about-service-bindings. * Update content/workers/_partials/_platform-compatibility-dates/rpc.md * Update content/workers/runtime-apis/rpc/_index.md Co-authored-by: James M Snell <jasnell@gmail.com> * Update content/workers/_partials/_platform-compatibility-dates/rpc.md Co-authored-by: James M Snell <jasnell@gmail.com> * Named entrypoints (#13861) * Named entrypoint configuration in `wrangler.toml` * Named entrypoints example * Apply suggestions from code review * Apply suggestions from code review --------- Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com> * Apply suggestions from code review * Clarify RPC unsupported errors (#13863) * * Add Durable Objects RPC docs (#13765) * Update DO counter example with RPC * Clarify RPC pricing * Rename "Configuration" to "Best Practices" section * Fix some redirects (#13865) * Order the RPC docs sections in nav (#13866) * Fix links * Fix more redirects * Fix DO redirect in Versions & Deployments * fix merge conflict --------- Co-authored-by: Matt Silverlock <msilverlock@cloudflare.com> Co-authored-by: Michael Hart <michael.hart.au@gmail.com> Co-authored-by: Kenton Varda <kenton@cloudflare.com> Co-authored-by: Greg Brimble <gbrimble@cloudflare.com> Co-authored-by: James M Snell <jasnell@gmail.com> Co-authored-by: Vy Ton <vy@cloudflare.com> Co-authored-by: Rita Kozlov <rita@cloudflare.com> Co-authored-by: Rita Kozlov <2414910+rita3ko@users.noreply.github.com>
TODO:
Configurationsection, addSend requests to a Durable ObjectMust merge after #13252 which has Workers RPC links
DEFER to next PR:
statetoctxGet startedtutorial to RPC (maybe let JS RPC bake for a bit?)