Service Bindings — RPC
Service bindings allow one Worker to call into another, without going through a publicly-accessible URL.
You can use Service bindings to create your own internal APIs that your Worker makes available to other Workers. This can be done by extending the built-in WorkerEntrypoint class, and adding your own public methods. These public methods can then be directly called by other Workers on your Cloudflare account that declare a binding to this Worker.
The RPC system in Workers is designed feel as similar as possible to calling a JavaScript function in the same Worker. In most cases, you should be able to write code in the same way you would if everything was in a single Worker.
Example
For example, the following Worker implements the public method add(a, b):
For example, if Worker B implements the public method add(a, b):
Worker A can declare a binding to Worker B:
Making it possible for Worker A to call the add() method from Worker B:
You do not need to learn, implement, or think about special protocols to use the RPC system. The client, in this case Worker A, calls Worker B and tells it to execute a specific procedure using specific arguments that the client provides. This is accomplished with standard JavaScript classes.
The WorkerEntrypoint Class
To provide RPC methods from your Worker, you must extend the WorkerEntrypoint class, as shown in the example below:
A new instance of the class is created every time the Worker is called. Note that even though the Worker is implemented as a class, it is still stateless — the class instance only lasts for the duration of the invocation. If you need to persist or coordinate state in Workers, you should use Durable Objects.
Bindings (env)
The env object is exposed as a class property of the WorkerEntrypoint class.
For example, a Worker that declares a binding to the environment variable GREETING:
Can access it by calling this.env.GREETING:
You can use any type of binding this way.
Lifecycle methods (ctx)
The ctx object is exposed as a class property of the WorkerEntrypoint class.
For example, you can extend the lifetime of the invocation context by calling the waitUntil() method:
Named entrypoints
You can also export any number of named WorkerEntrypoint classes from within a single Worker, in addition to the default export. You can then declare a Service binding to a specific named entrypoint.
You can use this to group multiple pieces of compute together. For example, you might create a distinct WorkerEntrypoint for each permission role in your application, and use these to provide role-specific RPC methods:
You can then declare a Service binding directly to AdminEntrypoint in another Worker:
You can learn more about how to configure D1 in the D1 documentation.
You can try out a complete example of this to do app, as well as a Discord bot built with named entrypoints, by cloning the cloudflare/js-rpc-and-entrypoints-demo repository from GitHub.
Further reading
- Lifecycle: Memory management, resource management, and the lifecycle of RPC stubs.
- Reserved Methods: Reserved methods with special behavior that are treated differently.
- Visibility and Security Model: Which properties are and are not exposed to clients that communicate with your Worker or Durable Object via RPC
- TypeScript: How TypeScript types for your Worker or Durable Object's RPC methods are generated and exposed to clients
- Error handling: How exceptions, stack traces, and logging works with the Workers RPC system.