---
title: xxrpc_client
description: Generate typed HTTP and WebSocket RPC clients for ECMAScript or Go.
---

# `xxrpc_client`

`xxrpc_client` generates Protobuf messages and typed clients for every Protobuf RPC cardinality. Each endpoint associates one or more `.proto` sources with an HTTP URL. Generate exactly one language per call with `out_es` or `out_go`.

Only clients support Go output. [`xxrpc_handler`](xxrpc_handler.md) generates ECMAScript backends.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `endpoints` | Yes | Non-empty list of dictionaries containing `srcs` and `url`. |
| `out_es` | One output | Project-relative ECMAScript output directory. |
| `deps` | No | Dependencies activated before tool installation and generation. Defaults to `[]`. |
| `out_go` | One output | Project-relative Go output directory. |

Exactly one of `out_es` and `out_go` must be set. Each endpoint dictionary has exactly these fields:

| Field | Description |
| --- | --- |
| `srcs` | Non-empty list of project-relative `.proto` files. A source can occur in only one endpoint URL. |
| `url` | Absolute `http` or `https` URL embedded as the generated client's default endpoint. |

## Protocol

Unary methods use regular HTTP requests:

| Part | Value |
| --- | --- |
| HTTP method | `POST` |
| `Content-Type` | `application/protobuf` |
| `X-XXRPC-Service` | Fully qualified Protobuf service name, such as `example.greeter.v1.Greeter` |
| `X-XXRPC-Method` | Method name as declared in the `.proto` file, such as `Greet` |
| `X-XXRPC-Streaming` | `0`; a mismatch returns HTTP `400` |
| Body | Raw encoded input message |

Any streaming method uses one WebSocket per RPC call. The client changes the endpoint scheme from `http` to `ws` or from `https` to `wss`, preserves the configured path and query, and adds `xxrpc-service` and `xxrpc-method` query parameters.

The WebSocket requests subprotocol `xxrpc.streaming.v1`. Each binary WebSocket message contains one xxRPC control or Protobuf frame. Calls use a 4 MiB message limit, a 4 MiB byte-credit window, and a 1024-message credit window in each direction. `STATUS` is the canonical completion result; a socket closing without it is reported as unavailable.

## ECMAScript

ECMAScript output requires `protoc` and `protoc-gen-es` in the task environment. Load `protoc` from an exact [`@protobuf`](../protobuf/protoc.md) package. Install `@bufbuild/protoc-gen-es` version 2 in the project and expose `node_modules/.bin` through `deps`.

Protobuf-ES writes a `<source>_pb.js` module and a `<source>_pb.d.ts` declaration. Each generated `<source>_xxrpc.ts` exports one `<Service>Client` class per Protobuf service. Its constructor accepts an optional endpoint override and optional `XXRPCClientOptions` with a custom WebSocket factory. It defaults to the configured endpoint and the browser's global `WebSocket`.

| Protobuf method | Client input | Client result |
| --- | --- | --- |
| Unary | `Input` | `Promise<Output>` |
| Server streaming | `Input` | `AsyncIterable<Output>` |
| Client streaming | `AsyncIterable<Input>` | `Promise<Output>` |
| Bidirectional streaming | `AsyncIterable<Input>` | `AsyncIterable<Output>` |

All methods accept optional `XXRPCCallOptions` with an `AbortSignal`. Aborting cancels the call. Breaking out of a response `AsyncIterable` also cancels its WebSocket and closes the request iterator. `XXRPCError.code` contains the RPC status and unary failures additionally expose `httpStatus`.

```starlark
load("@nodejs@22.14.0", "npm_install")
load("@os@1", "env_prepend")
load("@protobuf@35.1", "protoc")
load("@xxrpc@1", "xxrpc_client")

install = npm_install()

rpc_client = xxrpc_client(
    endpoints=[
        {
            "srcs": ["contracts/greeter.proto"],
            "url": "http://localhost:4321/greeter",
        },
    ],
    out_es="frontend/generated",
    deps=[
        protoc,
        install,
        env_prepend("PATH", "node_modules/.bin"),
    ],
)
```

## Go

Go output requires `protoc` and `go` in the task environment. xxRPC automatically installs Google's official `google.golang.org/protobuf/cmd/protoc-gen-go` at the latest `v1` release into an isolated tool directory. Do not install or pass `protoc-gen-go` yourself.

Every input and imported `.proto` file must provide the Go import path required by `protoc-gen-go`, normally with `go_package`. Well-known Protobuf types already provide it.

```proto
option go_package = "example.com/project/generated/contracts;contracts";
```

Generation uses source-relative paths. It writes the official `<source>.pb.go`, an xxRPC `<source>_xxrpc.go` for files containing services, and one `xxrpc_runtime.go` per generated Go package directory. Generated runtime code imports `google.golang.org/protobuf/proto` and `github.com/coder/websocket`; declare those modules in the consuming Go module.

Each service exposes `New<Service>XXRPCClient(options...)`. The configured URL is used by default. `XXRPCWithEndpoint`, `XXRPCWithHTTPClient`, and `XXRPCWithWebSocketDialer` provide explicit overrides.

| Protobuf method | Generated Go API |
| --- | --- |
| Unary | `Method(ctx, *Input) (*Output, error)` |
| Server streaming | `Method(ctx, *Input) (*ServiceMethodXXRPCClient, error)` and `Recv` |
| Client streaming | `Method(ctx) (*ServiceMethodXXRPCClient, error)`, `Send`, and `CloseAndRecv` |
| Bidirectional streaming | `Method(ctx) (*ServiceMethodXXRPCClient, error)`, `Send`, `Recv`, and `CloseSend` |

Streaming constructors return after the WebSocket handshake and xxRPC `ACCEPT`. `Recv` returns `io.EOF` only after a successful terminal status. `Close` cancels a stream immediately, and `CloseSend` is idempotent. A stream safely supports one sender and one receiver at the same time.

Failures can be inspected with `errors.As` into `*XXRPCError`. It exposes `Code`, `Message`, `HTTPStatus`, and an underlying `Cause`. Context cancellation and deadlines remain available through `errors.Is`.

```starlark
load("@go@1.26.5", "go")
load("@protobuf@35.1", "protoc")
load("@xxrpc@1", "xxrpc_client")

rpc_client = xxrpc_client(
    endpoints=[
        {
            "srcs": ["contracts/greeter.proto"],
            "url": "http://localhost:4321/greeter",
        },
    ],
    out_go="generated",
    deps=[protoc, go],
)
```

```go
client, err := contracts.NewGreeterXXRPCClient()
if err != nil {
	return err
}

response, err := client.Greet(ctx, &contracts.GreetRequest{Name: "Go"})
if err != nil {
	return err
}
```

## Output Ownership

The selected output directory is owned by the xxRPC task. Obsolete Protobuf and xxRPC generated files from preceding generations are removed before generation; unmanaged files are retained.

See a complete example in `examples/rpc`.

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/lsp.md
Title: Editor Support
Description: Configure an editor to use xx's built-in Starlark language server.

URL: https://withxx.dev/packages/cloudflare/cf_d1_create.md
Title: cf_d1_create
Description: Provision a Cloudflare D1 database with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_kv_create.md
Title: cf_kv_create
Description: Provision a Cloudflare Workers KV namespace with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_queue_create.md
Title: cf_queue_create
Description: Provision and configure a Cloudflare Queue with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_r2_create.md
Title: cf_r2_create
Description: Provision and configure a Cloudflare R2 bucket with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_worker_config.md
Title: cf_worker_config
Description: Define an in-memory Cloudflare Worker configuration.

URL: https://withxx.dev/packages/cloudflare/cf_wrangler_deploy.md
Title: cf_wrangler_deploy
Description: Deploy a Cloudflare Worker with a temporary Wrangler configuration.

URL: https://withxx.dev/packages/cloudflare/cf_wrangler_dev.md
Title: cf_wrangler_dev
Description: Run one or more Cloudflare Workers with Wrangler dev.

URL: https://withxx.dev/packages/cmake/cmake.md
Title: cmake
Description: Activate managed CMake for dependent tasks.

URL: https://withxx.dev/packages/cmake/cmake_build.md
Title: cmake_build
Description: Build a generated project with managed CMake.

URL: https://withxx.dev/packages/cmake/cmake_generate.md
Title: cmake_generate
Description: Generate a project build system with managed CMake.

URL: https://withxx.dev/packages/doppler/doppler_secrets.md
Title: doppler_secrets
Description: Load Doppler secrets into dependent task environments.

URL: https://withxx.dev/packages/git/git_clone.md
Title: git_clone
Description: Materialize a pinned Git source tree with host Git configuration and access.

URL: https://withxx.dev/packages/git/git_commit.md
Title: git_commit
Description: Stage and commit changes in a Git repository.

URL: https://withxx.dev/packages/git/git_init_repository.md
Title: git_init_repository
Description: Ensure an empty SHA-1 or SHA-256 Git repository exists.

URL: https://withxx.dev/packages/git/git_push.md
Title: git_push
Description: Push commits from a Git repository.

URL: https://withxx.dev/packages/git/git_semver_latest.md
Title: git_semver_latest
Description: Read the latest semantic version from local Git tags.

URL: https://withxx.dev/packages/git/git_semver_next.md
Title: git_semver_next
Description: Calculate the next semantic version from local Conventional Commits.

URL: https://withxx.dev/packages/git/git_sha.md
Title: git_sha
Description: Resolve a local Git revision to its commit ID.

URL: https://withxx.dev/packages/git/git_tag.md
Title: git_tag
Description: Create a lightweight or annotated Git tag.

URL: https://withxx.dev/packages/go/go.md
Title: go
Description: Activate a managed Go SDK for dependent tasks.

URL: https://withxx.dev/packages/go/go_binary.md
Title: go_binary
Description: Build a Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_install.md
Title: go_install
Description: Install a versioned Go command for dependent tasks.

URL: https://withxx.dev/packages/go/go_protobuf.md
Title: go_protobuf
Description: Install protoc-gen-go and provide it as a Protobuf generator.

URL: https://withxx.dev/packages/go/go_run.md
Title: go_run
Description: Run a local program or versioned Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_test.md
Title: go_test
Description: Test Go packages with a managed SDK.

URL: https://withxx.dev/packages/http/http_proxy.md
Title: http_proxy
Description: Route local HTTP and WebSocket traffic between development servers.

URL: https://withxx.dev/packages/io/io_append_text.md
Title: io_append_text
Description: Append text to a file asynchronously.

URL: https://withxx.dev/packages/io/io_copy.md
Title: io_copy
Description: Copy a file or directory asynchronously.

URL: https://withxx.dev/packages/io/io_glob.md
Title: io_glob
Description: Find project files and directories with recursive glob patterns.

URL: https://withxx.dev/packages/io/io_read_text.md
Title: io_read_text
Description: Read a text file during build evaluation.

URL: https://withxx.dev/packages/io/io_rm.md
Title: io_rm
Description: Remove a file asynchronously.

URL: https://withxx.dev/packages/io/io_rmdir.md
Title: io_rmdir
Description: Remove a directory tree asynchronously.

URL: https://withxx.dev/packages/io/io_stat.md
Title: io_stat
Description: Read file information during build evaluation.

URL: https://withxx.dev/packages/io/io_write_text.md
Title: io_write_text
Description: Write text to a file asynchronously.

URL: https://withxx.dev/packages/ninja/ninja.md
Title: ninja
Description: Activate managed Ninja for dependent tasks.

URL: https://withxx.dev/packages/nodejs/nodejs.md
Title: nodejs
Description: Activate managed Node.js for dependent tasks.

URL: https://withxx.dev/packages/nodejs/npm_install.md
Title: npm_install
Description: Install dependencies with the package.json-selected manager.

URL: https://withxx.dev/packages/nodejs/npm_run.md
Title: npm_run
Description: Run a project package script with the package.json-selected manager.

URL: https://withxx.dev/packages/nodejs/npx_run.md
Title: npx_run
Description: Run a versioned npm package command with managed npx.

URL: https://withxx.dev/packages/os/env_append.md
Title: env_append
Description: Append an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_get.md
Title: env_get
Description: Read a value from a task environment while evaluating Starlark.

URL: https://withxx.dev/packages/os/env_prepend.md
Title: env_prepend
Description: Prepend an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_set.md
Title: env_set
Description: Set an environment variable for dependent tasks.

URL: https://withxx.dev/packages/os/env_unset.md
Title: env_unset
Description: Remove an environment variable from dependent tasks.

URL: https://withxx.dev/packages/os/os_arch.md
Title: os_arch
Description: Identify the host processor architecture.

URL: https://withxx.dev/packages/os/os_kernel.md
Title: os_kernel
Description: Identify the host operating system kernel.

URL: https://withxx.dev/packages/os/os_msvc.md
Title: os_msvc
Description: Activate the host Microsoft Visual C++ tools.

URL: https://withxx.dev/packages/os/os_run.md
Title: os_run
Description: Run a command from a project directory.

URL: https://withxx.dev/packages/os/os_system_tools.md
Title: os_system_tools
Description: Activate standard host operating-system utilities.

URL: https://withxx.dev/packages/os/os_xcode.md
Title: os_xcode
Description: Activate the host Xcode tools.

URL: https://withxx.dev/packages/os/path_make_absolute.md
Title: path_make_absolute
Description: Resolve a relative path from the project root.

URL: https://withxx.dev/packages/protobuf/protobuf_generate.md
Title: protobuf_generate
Description: Generate source code with a managed Protobuf compiler.

URL: https://withxx.dev/packages/protobuf/protobuf_generator.md
Title: protobuf_generator
Description: Adapt an installed protoc plugin dependency for code generation.

URL: https://withxx.dev/packages/protobuf/protoc.md
Title: protoc
Description: Activate a managed Protobuf compiler for dependent tasks.

URL: https://withxx.dev/packages/secrets/xx_secrets.md
Title: xx_secrets
Description: Load xx project secrets into dependent task environments.

URL: https://withxx.dev/packages/stripe/stripe.md
Title: stripe
Description: Activate a managed Stripe CLI for dependent tasks.

URL: https://withxx.dev/packages/stripe/stripe_listen.md
Title: stripe_listen
Description: Forward Stripe webhook events to a local endpoint.

URL: https://withxx.dev/packages/text/text_template.md
Title: text_template
Description: Render Go text templates from Starlark data and functions.

URL: https://withxx.dev/packages/xxrpc/xxrpc_client.md
Title: xxrpc_client
Description: Generate typed HTTP and WebSocket RPC clients for ECMAScript or Go.

URL: https://withxx.dev/packages/xxrpc/xxrpc_handler.md
Title: xxrpc_handler
Description: Generate typed framework-neutral ECMAScript RPC handler classes.

URL: https://withxx.dev/packages/zig/zig.md
Title: zig
Description: Activate managed Zig for dependent tasks.

URL: https://withxx.dev/packages/zig/zig_cc.md
Title: zig_cc
Description: Configure managed Zig as a C and C++ compiler.

URL: https://withxx.dev/packages.md
Title: Built-in Packages
Description: Versioned toolchains, commands, and task environment helpers provided by xx.

URL: https://withxx.dev/secrets.md
Title: Secret manager
Description: Store project secrets locally and provide them to xx tasks.

URL: https://withxx.dev/xxrpc.md
Title: xxRPC
Description: Design portable xxRPC contracts that keep application semantics in Protobuf.
-->