skip to content

In Cloudflare Workers RPC, how does a Worker expose methods with WorkerEntrypoint, which members can a caller reach, and what do named entrypoints add?

level: middleimportance: should knowfreq 30%

answer

  1. a class, not an object literal
  2. prototype methods only
  3. fresh instance per call
  4. this.env and this.ctx
  5. entrypoint key picks the export

basics

~20 s

A Worker extends WorkerEntrypoint from cloudflare:workers and its public prototype methods and getters become RPC methods; private fields, instance properties and arrow-function fields stay hidden. Each named export is a separate entrypoint a binding selects with entrypoint.

solid answer

~50 s

To serve RPC, a Worker exports a class extending `WorkerEntrypoint` from `cloudflare:workers`. Its public methods and getters, declared on the class, are what a caller can invoke; `#private` members, properties assigned in the constructor and arrow-function class fields are not exposed, and calling one fails with `TypeError: The RPC receiver does not implement the method ...`. The runtime creates a new instance for every invocation, so the class is still stateless, and it reads bindings through `this.env` and the execution context through `this.ctx`. A Worker can export any number of named `WorkerEntrypoint` classes beside its default export, and a caller's binding picks one with the `entrypoint` key, so an admin interface and a session interface can live in one Worker and be handed out separately. `fetch()` keeps its handler meaning, and names such as `dup` and `constructor` cannot be RPC methods.

code

javascript · 25 lines
javascript
import { WorkerEntrypoint } from "cloudflare:workers";

export class SessionApi extends WorkerEntrypoint {
  #signingKey = "kept-private";

  async verify(token) {
    const valid = token === "demo-token";
    return { valid, userId: valid ? "u_123" : null };
  }

  // An arrow function lives on the instance, not the prototype: not callable over RPC.
  revokeAll = async () => "never exposed";
}

export class AdminApi extends WorkerEntrypoint {
  async revokeSessions(userId) {
    return { userId, revoked: true };
  }
}

export default class extends WorkerEntrypoint {
  async fetch() {
    return new Response("Not found", { status: 404 });
  }
}

go deeper

for a junior

Recall the shape: import WorkerEntrypoint from cloudflare:workers, extend it, add async methods, and call them through a binding as env.NAME.method().

for a middle

Explain the visibility rules: prototype methods and getters are exposed; private fields, constructor-assigned properties and arrow-function fields are not. Add the per-invocation instance and this.env and this.ctx.

for a senior

Show how you split one Worker into SessionApi and AdminApi entrypoints, recognise the 'does not implement the method' TypeError, and know which names are reserved.

for a principal

Treat entrypoints as interface scoping rather than access control, since callers choose them; the account's deploy permission is the boundary to govern.

## The WorkerEntrypoint class Workers RPC is built into the runtime. To offer methods to other Workers, a Worker exports a class that **extends `WorkerEntrypoint`**, imported from `cloudflare:workers`. RPC needs a **compatibility date of `2024-04-03` or later**, or the `rpc` compatibility flag. Three facts shape how such a class behaves: - **A new instance per invocation.** The runtime constructs the class each time the Worker is called. A field set in one call is gone in the next, so the class is as stateless as a `fetch()` handler. State that must persist belongs in a store or a Durable Object. - **`this.env`** holds the Worker's bindings (KV, D1, vars, other service bindings), the same object a `fetch(request, env, ctx)` handler receives as `env`. - **`this.ctx`** is the execution context: `this.ctx.waitUntil()` keeps work running after a method returns, and `this.ctx.props` carries values the caller's binding configured. ## How one RPC call reaches the class Following a single call from the gateway to the auth Worker makes the rules below easier to remember: 1. The caller runs `await env.SESSIONS.verify(token)`. The binding already knows the target Worker (`service`) and the class (`entrypoint`, or the default export when it is omitted). 2. The runtime constructs a **fresh instance** of that class, with `this.env` and `this.ctx` set for this invocation, and an execution context begins. 3. It looks up `verify` among the members the class exposes. If the name is not an exposed method, the call rejects with a `TypeError`. 4. The method runs; its return value (or thrown error) is serialized and sent back, and the caller's awaited thenable resolves. 5. The instance is discarded. The next call, even from the same caller a millisecond later, gets a new one. ## Which members a caller can reach The RPC system follows an **object-capability** model: a caller can only invoke what it was handed, and Workers RPC is careful about what a class hands out. | Member | Callable or readable over RPC? | |---|---| | Public method declared in the class body | yes | | Getter declared in the class body | yes, by awaiting the property | | `#private` field or method | no | | Property assigned in the constructor, such as `this.key = ...` | no | | Arrow-function class field, such as `revoke = async () => ...` | no, it lives on the instance, not the prototype | When a caller asks for a hidden member, the call fails with `TypeError: The RPC receiver does not implement the method "revokeAll".`, the same error as for a method that does not exist. These rules hold for `WorkerEntrypoint`, `DurableObject` and `RpcTarget` classes; plain objects are passed by value with all their own properties. ## Reserved and disallowed names - **`fetch()`** is not an ordinary RPC method on a `WorkerEntrypoint`. It must accept one `Request` and return a `Response`, and on the caller's side `env.NAME.fetch()` behaves like the global `fetch()`. - **`connect()`** is reserved for socket-style connections to a Worker and is not implemented. - **`dup`** and **`constructor`** can never be RPC methods; calling `dup` remotely fails with `'dup' is a reserved method and cannot be called over RPC.` - **`alarm`**, **`webSocketMessage`**, **`webSocketClose`** and **`webSocketError`** are disallowed on `WorkerEntrypoint` (they carry Durable Object meaning) but allowed on `RpcTarget`. ## Named entrypoints A Worker can export several `WorkerEntrypoint` classes. The default export answers bindings that name no entrypoint; each **named export** is a separate entrypoint: 1. The auth Worker exports `SessionApi` (verify a token) and `AdminApi` (revoke a user's sessions) next to its default export. 2. The public gateway binds with `"entrypoint": "SessionApi"`, so `env.SESSIONS.verify()` works and `env.SESSIONS.revokeSessions()` fails with the "does not implement the method" `TypeError`. 3. An internal admin Worker binds with `"entrypoint": "AdminApi"` and gets only the admin methods. This keeps one deployable Worker while giving each caller the narrowest interface it needs. It is a **scoping tool, not an access list**: the caller's Wrangler file chooses the entrypoint, so any Worker deployed on the same account could bind to `AdminApi`. Who may deploy to the account is the real boundary, and `ctx.props` lets the callee see which binding a call arrived through. ## Types for callers `wrangler types` generates the caller's `Env` interface. Passing the target's config as well, for example `wrangler types -c ./wrangler.jsonc -c ../auth-worker/wrangler.jsonc`, types the binding as `Service<...SessionApi>`, so the editor knows `verify()` exists and that every remote method returns something awaitable.

  • Can a Worker keep `export default { fetch }` as an object and still offer RPC?
    Yes, and the clean way is a named export: the default export stays an object with its `fetch` handler while `export class BillingApi extends WorkerEntrypoint` serves RPC, and callers bind with `"entrypoint": "BillingApi"`. A function on the object itself can be called over RPC only with exactly one argument, receiving `env` and `ctx` after it; for normal method signatures the runtime's own error says to use the class syntax.
  • Why does a counter stored in a `WorkerEntrypoint` field read zero on every call?
    The runtime creates a new instance of the class for each invocation, and the instance lasts only for that invocation. Nothing in the class survives between calls by design. A value that must persist goes into a binding such as KV or D1, or into a Durable Object, which is the Workers primitive for coordinated state.

  • Properties set in a WorkerEntrypoint constructor can be read by any caller over RPC.
  • Arrow-function class fields work as RPC methods just like prototype methods.
  • A WorkerEntrypoint instance lives on between calls, so its fields hold state.
  • Naming an entrypoint in one caller's binding stops other Workers from binding to it.
  • fetch() on a WorkerEntrypoint can be an ordinary RPC method with any arguments.