rpc
@rtorcato/cf-common/rpc is for Worker-to-Worker calls. getService reads a
Service Binding from env typed by the callee's entrypoint, so its public
methods are checked RPC calls. callService maps a failed call to a
CloudflareError.
Define the callee
The callee is a normal WorkerEntrypoint. Its public methods are the contract.
// auth-worker/src/index.ts
import { WorkerEntrypoint } from 'cloudflare:workers'
export class AuthService extends WorkerEntrypoint<Env> {
async verify(token: string): Promise<{ userId: string } | null> {
// look the token up in this Worker's own D1/KV
return token === 'valid' ? { userId: 'u_1' } : null
}
}
export default {
fetch: () => new Response('auth worker'),
} satisfies ExportedHandler<Env>
Bind it in the caller's wrangler.jsonc:
"services": [
{ "binding": "AUTH", "service": "auth-worker", "entrypoint": "AuthService" }
]
Call it
Share the contract by importing the class as a type, so the callee's code isn't bundled into the caller. Publish it from the callee's package, or point a workspace import at it.
import { getService, callService } from '@rtorcato/cf-common/rpc'
import { defineFetch } from '@rtorcato/cf-common/http'
import { bearerToken } from '@rtorcato/cf-common/request'
import type { AuthService } from 'auth-worker'
export default defineFetch(async (request, env: Env) => {
const auth = getService<typeof AuthService>(env, 'AUTH')
const user = await callService('AUTH', () => auth.verify(bearerToken(request) ?? ''))
return Response.json({ user })
})
getService<typeof AuthService> is getBinding with the type filled in. A
missing binding throws a non-exposed 500, since that is a deploy
misconfiguration. auth.fetch(request) is there too, for entrypoints that also
serve HTTP.
Failures
callService runs the call and turns any failure (the callee threw, the binding
is unreachable, the callee hit its limits) into a CloudflareError with status
502, code RPC_CALL_FAILED, expose: false, and the original error as cause.
defineFetch then returns it as Internal error, so the callee's message never
reaches the client.
A callee's own status and code do not cross the RPC boundary. For an expected
failure such as "token invalid", return a value (null, or a result object)
instead of throwing, as verify does above.
Good to know
- Only the entrypoint's public methods are callable, and arguments and results must be serializable by Workers RPC.
- A binding to the callee's default export (
export default { fetch }) has no RPC methods. Name the entrypoint in the binding. - Calls to a Worker on the same account don't go over the public internet and aren't billed as extra requests.
See the rpc API reference for every export.