skip to content

Service Bindings & RPC

Service bindings let one Worker call another without a public URL, by fetch or by RPC on a WorkerEntrypoint. Interviewers ask how RPC passes objects and how an internal Worker stays private.

on this pageshow

explore

questions

5

In Cloudflare Workers, what is a service binding, how is it declared, and how does a fetch() call through it differ from an RPC call?

level: juniorimportance: should knowfreq 42%

answer

  1. Worker to Worker, no public URL
  2. declared by the caller
  3. services array in the Wrangler file
  4. Request in, Response out versus method call
  5. await it or lose it

basics

~20 s

A service binding lets one Worker call another on the same account without a public URL. The caller lists it under services in its Wrangler file, then forwards a Request with env.NAME.fetch() or calls a WorkerEntrypoint method as env.NAME.method().

solid answer

~50 s

A service binding is a capability on the caller's `env` that points at another Worker on the same Cloudflare account, so the call never goes through a public hostname. The caller declares it in its own Wrangler file under `services`, with `binding` (the `env` key) and `service` (the target Worker's name), plus an optional `entrypoint`. There are two ways to use it. `env.AUTH.fetch(request)` has Fetch API semantics: it sends a `Request` to the target's `fetch()` handler and gets a `Response` back. `env.AUTH.verify(token)` is RPC: the target extends `WorkerEntrypoint` and the call looks like a local async method returning a JavaScript value. RPC is the recommended form for internal APIs. Either way the caller must `await` the call (or hand it to `ctx.waitUntil()`), the target must exist before the caller's first deploy, and on Workers Standard pricing the pair is billed as one request plus the CPU time of both Workers.

code

json · 8 lines
json
{
  "name": "gateway",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "services": [
    { "binding": "AUTH", "service": "auth-worker" }
  ]
}

go deeper

for a junior

Recall that the caller declares the binding under services with binding and service, and that env.NAME.fetch(request) and env.NAME.method() are the two ways to call it.

for a middle

Explain the difference in semantics: fetch() follows the Fetch API with a Request and a Response, while RPC returns JavaScript values from WorkerEntrypoint methods. Mention the await requirement and the compatibility date RPC needs.

for a senior

Show you have shipped this: deploy order for a contract change, the non-inheritable services key in each environment, the 32-invocation and subrequest limits, and billing as one request plus both Workers' CPU time.

for a principal

Frame bindings as capabilities: a binding needs no credential or public address, which lets internal Workers stay private, but the trust boundary is everyone who can deploy to the account.

## What a service binding is A **service binding** is one of the Workers **bindings**: an object the runtime puts on the caller's `env` that lets code reach a resource without holding a credential or a network address. For a service binding, the resource is **another Worker on the same Cloudflare account**. The call does not travel over the public internet and does not need the target to have a public hostname at all, which is why a team can put an auth Worker or a billing Worker behind a public gateway Worker and keep them unreachable from outside. The binding is declared by the **caller**. The target Worker does not list who may call it; any Worker on the account whose Wrangler file names it can bind to it. ## Declaring the binding The caller's `wrangler.jsonc` gets a `services` array. Each entry has these keys: | Key | Required | Meaning | |---|---|---| | `binding` | yes | The name that appears on `env`, for example `AUTH` | | `service` | yes | The target Worker's `name`; for a Wrangler environment, `<worker>-<environment>` | | `entrypoint` | no | A named `WorkerEntrypoint` export to bind to instead of the default export | | `props` | no | A JSON value the target reads as `ctx.props` | `services` is a **non-inheritable** key: a named Wrangler environment does not pick it up from the top level, so each environment block declares its own list. ## Two ways to call the bound Worker | | HTTP style | RPC style | |---|---|---| | Caller code | `env.AUTH.fetch(request)` | `env.AUTH.verify(token)` | | Target code | a `fetch()` handler | public methods on a class extending `WorkerEntrypoint` | | What travels | a `Request` and a `Response` | arguments and return values as JavaScript values | | Semantics | the Fetch API, including redirect handling | a function call that always returns something awaitable | Points worth knowing about each: - **HTTP style** suits forwarding an incoming request unchanged. If the caller builds a new `Request`, it must use a valid, fully qualified URL such as `https://auth.internal/session`; the hostname does not route the call, the binding does, but a relative URL such as `/session` throws a `TypeError` (`Invalid URL: /session`). - **RPC style** removes the work of encoding JSON bodies, status codes and routes for an internal API. It needs a compatibility date of `2024-04-03` or later (or the `rpc` flag), and Cloudflare recommends it for most Worker-to-Worker calls. - Both styles are **asynchronous**. If the caller does not `await` the call and returns, the target Worker is terminated early. - Calling another Worker on the same zone with the global `fetch()` and its public URL, instead of a binding, fails; a binding (or a Custom Domain on the target) is the supported path. ## Cost and limits - On **Workers Standard pricing**, a request to Worker A that calls Worker B through a binding is billed as **one request** plus the **CPU time of both Workers**. Only the deprecated Bundled and Unbound plans charge the bound call as a second request. - Each call through a binding counts toward the caller's **subrequest limit**. - One incoming request can involve at most **32 Worker invocations**; each binding call counts, and further calls throw an exception. - By default both Workers run on the **same thread of the same server**, so a binding call adds no network hop. ## Deploying and running two Workers Each Worker is deployed separately, so order matters: 1. Deploy the **target** first. Deploying the caller while the target does not exist fails, because its binding points at nothing. 2. To change the contract, deploy the target with the **new method added**, keeping the old one. 3. Deploy the **caller** so that it uses the new method. 4. Remove the old method from the target in a later deploy. Locally, each Worker can run in its own `wrangler dev` session (the caller's binding then shows as connected), or several `--config` files can be passed to one `wrangler dev`, where the first is the primary Worker; the local development material covers the details. Splitting a system into many Workers as an architecture choice is a separate topic; this one is about how one Worker reaches another.

  • How does a caller bind to the staging copy of a Worker that is deployed with Wrangler environments?
    Set `service` to the environment's Worker name, `<worker>-<environment>`, for example `auth-worker-staging`. Because `services` is non-inheritable, the caller's own `env.staging` block must declare its `services` list again; the top-level entry does not carry over, and the binding does not follow the caller's `--env` flag on its own.
  • Why can the very first deploy of the gateway fail even though its code is fine?
    Workers with service bindings deploy separately, and the gateway's binding names a target that must already exist. If the auth Worker has never been deployed, deploying the gateway fails. Deploy the target first, and for later contract changes add the new method to the target before the caller starts using it, removing the old one afterwards.
  • What happens if the gateway calls the auth Worker without awaiting it and returns its response?
    The binding API is asynchronous, and when the caller does not wait for the callee, the callee is terminated early. The work is not queued or retried. If the gateway wants the call to finish after its response, it passes the call to `ctx.waitUntil()`, as in `ctx.waitUntil(env.AUTH.audit(event))`; otherwise it awaits the call.

  • A service binding call goes out over the public internet to the target Worker's URL.
  • The target Worker lists which callers may bind to it in its own Wrangler file.
  • A Request sent with env.AUTH.fetch() must use the target Worker's real hostname to reach it.
  • On Workers Standard pricing every call through a service binding is billed as an extra request.
  • Worker-to-Worker RPC needs an interface definition file and generated client code.
  • An un-awaited binding call keeps running to completion after the caller returns.
open as a page

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%

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.

open as a page

In Cloudflare Workers RPC over a service binding, what can a method accept and return, and what happens to functions, class instances, streams and errors?

level: middleimportance: should knowfreq 25%

basics

~20 s

Structured-clonable values are copied. Functions and RpcTarget instances become stubs that call back to their origin, other classes fail to serialize, byte streams, Request and Response stream with flow control, and errors arrive by name and fields, not class.

open as a page

An internal Cloudflare billing Worker must be reachable only through service bindings; which Wrangler settings keep it off the internet, and how does it know which Worker called it?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Set workers_dev and preview_urls to false and configure no routes or custom domains, in the Wrangler file so every deploy keeps them. The Worker identifies callers by ctx.props, which each caller's binding sets and only those allowed to deploy the billing Worker can change.

open as a page

A Cloudflare billing Worker keeps an RPC stub received as a parameter and uses it later in ctx.waitUntil(), getting 'RPC stub used after being disposed'; why, and how should stub lifetimes be managed?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

A parameter stub is disposed when the RPC method returns, and it calls back through the caller, so it cannot outlive the caller's request. Read the values later work needs before returning, and use dup() only inside that window.

open as a page