Cloudflare Workers · Runtime APIs · all subjects

rpc & service bindings

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

ctx.props: pass configuration through service bindings

ctx.props provides a way to pass additional configuration to a worker based on the context in which it was invoked. When a Worker is called by another Worker via a Service Binding, ctx.props can provide information about the calling worker. The props value is configured in wrangler.json under the service binding configuration and can be an arbitrary JSON value. The Workers platform ensures ctx.props can only be set by someone with permission to edit and deploy the worker, making the content of ctx.props authentic without needing secret keys or cryptographic signatures.

ctx.exports: automatic loopback bindings for top-level exports

ctx.exports requires the enable_ctx_exports compatibility flag. For each top-level export that extends WorkerEntrypoint (or implements a fetch handler), ctx.exports automatically contains a Service Binding. For each top-level export that extends DurableObject (and has been configured with storage via migration), ctx.exports automatically contains a Durable Object namespace binding. No external configuration is required; ctx.exports is populated automatically from top-level exports.

Specifying ctx.props dynamically with ctx.exports

Loopback Service Bindings in ctx.exports allow the caller to specify the value of ctx.props delivered to the callee using the syntax: let binding = ctx.exports.ClassName({ props: { key: value } }). This is permitted because the caller is the same Worker and can be presumed trusted. Props values specified this way can contain any persistently serializable type, including all basic structured clonable data types, and can even include Service Bindings themselves.

Example: ctx.exports with dynamic props in TypeScript

The following TypeScript example demonstrates using ctx.exports with dynamic props: type Props = { greeting: string; }; export class Greeter extends WorkerEntrypoint<Env, Props> { greet(name) { return `${this.ctx.props.greeting}, ${name}!`; } } export default { async fetch(request, env, ctx) { let greeter = ctx.exports.Greeter({ props: { greeting: "Welcome" } }); let greeting = await greeter.greet("World"); return new Response(greeting); }, } satisfies ExportedHandler<Env>;

Enhanced error serialization in Workers RPC

Enhanced error serialization preserves the effective name and message and serializable own properties of errors thrown by RPC methods, including non-enumerable properties such as cause. It uses the enhanced_error_serialization compatibility flag and is on by default for compatibility dates on or after 2026-04-21. For earlier compatibility dates, the flag must be added to both the RPC provider and consumer. A Worker can opt out with legacy_error_serialization.

Error propagation in RPC methods

An error thrown by an RPC method or used to reject the method's returned Promise propagates to the caller as a new error object. The provider must be able to serialize the error and its own property values, and public error properties should be kept small and serializable.

What is NOT preserved when RPC errors are serialized

Workers does not preserve or guarantee the source object's identity, custom prototype, or constructor; the results of instanceof checks, especially for custom error classes; prototype methods or property descriptors; the provider's original stack trace (the consumer may see a new stack from error reconstruction); or non-serializable property values.

Checking error identity in RPC consumers

Instead of relying on instanceof checks for custom error classes, check documented fields such as name and code. For example, an instance of ProviderError extends Error can arrive with name set to "ProviderError" and with serializable own fields such as code, but it is not an instance of a consumer-side ProviderError class.

Additional runtime properties on RPC exceptions

For some remote exceptions, the runtime may add properties to the propagated exception, such as retry or Durable Object metadata. These properties are separate from the provider's custom properties.

Give your agent this brain