Local Development

This page is for working on TrevRPC itself. Use Getting Started if you want to use TrevRPC in an application.

Requirements

• Nix for the project development shell and checks.

Enter the development shell from the repository root:

nix develop

Rust lives under trevrpc-rust/. Go lives under trevrpc-go/. Kotlin lives under trevrpc-kotlin/. JavaScript lives under trevrpc-js/.

Run the Rust Example

Start the Rust QUIC greeter server from the repository root:

cargo run --manifest-path trevrpc-rust/Cargo.toml --example greeter_server

In another shell, call it with the Rust client:

cargo run --manifest-path trevrpc-rust/Cargo.toml --example greeter_client -- TrevRPC

The Rust server listens on 127.0.0.1:5000 for native QUIC, ordinary HTTP/3, and WebTransport by default. It writes ~/.config/trevrpc/trevrpc-example-cert.pem for clients to read. Override the certificate path with TREVRPC_EXAMPLE_CERT.

The Rust example demonstrates:

• Unary RPCs with SayHello.
• Server streaming with LotsOfReplies.
• Client streaming with LotsOfGreetings.
• Bidirectional streaming with BidiHello.
• Native QUIC ALPN set to trevrpc/1 and WebTransport over HTTP/3.
• Bearer-token authorization through request metadata.
• Client call deadlines through trevrpc::client::CallOptions.
• The routine long-lived trevrpc::client::Channel API.
• Server concurrency limits through trevrpc::server::ServerOptions.
• Graceful shutdown through serve_quinn_and_webtransport_with_shutdown.

Run the Go Example

Start the Go QUIC greeter server from the Go module directory:

cd trevrpc-go
go run ./examples/greeter_server

In another shell from trevrpc-go/, call it with the Go client:

go run ./examples/greeter_client TrevRPC

The Go server listens on 127.0.0.1:50051 by default for native QUIC, ordinary HTTP/3, and WebTransport. It writes ~/.config/trevrpc/trevrpc-example-cert.pem for clients to read. Override the certificate path with TREVRPC_EXAMPLE_CERT.

The Go example demonstrates:

• The generated-style GreeterServer interface.
• A generated-style GreeterClient.
• A long-lived *trevrpc.Channel from trevrpc.Dial.
• trevrpc.FromSlice for simple client and server streams.
• trevrpc.ServeQUIC for serving a quic-go listener.
• WebTransport over HTTP/3 on the same UDP listener.
• Client call deadlines through trevrpc.WithTimeout.

Run the JavaScript WebTransport Example

Start either the Rust or Go example server first. Both serve WebTransport and write the local example certificate to ~/.config/trevrpc/trevrpc-example-cert.pem by default.

Then serve the browser client from the JavaScript package directory:

cd trevrpc-js
npm run example:greeter

Open http://127.0.0.1:8080/examples/greeter/ in a browser with WebTransport support. The static server exposes certificate-hash.json, which lets the page load the local self-signed certificate hash and example bearer token automatically.

The JavaScript example demonstrates:

• A browser WebTransport Channel from the root connect API.
• Generated .trevrpc.js clients with checked-in .trevrpc.d.ts types.
• Unary, server-streaming, client-streaming, and bidirectional-streaming calls.
• Request metadata through generated client call options.
• Local WebTransport certificate hash configuration for self-signed example certificates.

Check the Kotlin Example

The Kotlin examples module is a compile-tested consumer of the generator and runtime. It verifies generated Greeter bindings, all four RPC shapes, authorization, and malformed request decoding:

cd trevrpc-kotlin
./gradlew :examples:check

Cross-language native QUIC and browser WebTransport interoperability run through the benchmark campaigns rather than a separate example executable. Android Cronet provider selection remains application-owned and is documented in trevrpc-kotlin/examples/README.md.

Install Local Generators

Install the Rust generator while developing:

cargo install --path trevrpc-rust/crates/protoc-gen-trevrpc-rust

Install the Go generator while developing:

cd trevrpc-go
go install ./cmd/protoc-gen-trevrpc-go

Install or link the JavaScript generator while developing:

cd trevrpc-js
npm install
npm link

The package exposes protoc-gen-trevrpc-js from bin/protoc-gen-trevrpc-js.js.

Build the Kotlin generator while developing:

cd trevrpc-kotlin
./gradlew :protoc-gen-trevrpc-kotlin:installDist

The executable is under protoc-gen-trevrpc-kotlin/build/install/protoc-gen-trevrpc-kotlin/bin/. Use :examples:syncGeneratedTrevrpc to refresh the checked-in Greeter binding and :examples:verifyGeneratedTrevrpc to detect drift.

Format, Check, and Build

Format the repository:

nix fmt

Run all configured checks:

nix flake check

Build packages:

nix build

Release Helper

Prepare release changes with:

bumper

Releases are created automatically for significant conventional-commit changes.