juliaio/grpcclient.jl/grpcclient-jl-dev

Developing gRPCClient.jl

Repository map

Formatting

The repository is formatted with Runic.jl, and contributed code is expected to be run through it before a pull request goes up:

] app add Runic          # once, Julia 1.12 or newer

runic --inplace .        # from the repository root

Use --check --diff in place of --inplace to verify without writing. Runic takes no configuration. CONTRIBUTING.md states this for human contributors.

Test server

cd test/go
go build -o grpc_test_server
./grpc_test_server              # listens on :8001

The server accepts the bearer token test-secret-token, mirrored by _TEST_BEARER_TOKEN in test/runtests.jl. Requests carrying an authorization header must present exactly that value; requests without one are unaffected.

Running tests

# Server already running on localhost:8001
julia --project test/runtests.jl
 
# Let the suite start and stop the Go server itself, which is what CI does
JULIA_GRPCCLIENT_TEST_START_SERVER=go julia --project test/runtests.jl
 
# Point at a server elsewhere
GRPC_TEST_SERVER_HOST=myhost GRPC_TEST_SERVER_PORT=9000 julia --project test/runtests.jl

JULIA_GRPCCLIENT_TEST_START_SERVER accepts go or false; any other value is an error. With go, the suite runs ./go/grpc_test_server from the test directory, so build it first, and reads its output until the startup line appears, giving up after 10 seconds. Host and port default to localhost and 8001.

CI covers Julia 1.10, 1.12, and nightly across Linux, Windows, macOS 15 x64, and macOS aarch64, with a 5 minute timeout on the test job. The workflow only triggers on changes under src/, test/, Project.toml, or the workflow file, so documentation and utils changes skip the matrix.

Regenerating stubs

cd test
bash protoc.sh

This regenerates the Python stubs in test/python/ with grpc_tools.protoc through uv, then regenerates test/gen/ by running protojl("proto/test.proto", ".", "gen") in a fresh Julia process. Changes to src/ProtoBuf.jl are only visible in the checked-in stubs after running it, and the Code Generation testset asserts on the generated text. Its Codegen: New API subset regenerates into a temp dir under each grpc_register_service_codegen combination and asserts on the # gRPCClient.jl BEGIN/END markers, the version guard, the baremodule TestService, the per-RPC method counts (3 for a unary-request RPC, 2 for a streaming-request one), the type-alias consts, the typeof(RPC) trait methods, and the generated docstrings' request/response type tables.

Docs

julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
julia --project=docs docs/make.jl

docs/src/index.md uses @docs blocks that name method signatures explicitly, so renaming or re-signing a public method breaks the docs build. Documenter is strict about docstrings it cannot resolve, which is the usual cause of a red docs job after an API change.

Test suite conventions

The suite is one top-level @testset "gRPCClient.jl" with nested sets per area. Points worth matching when adding tests:

• Concurrency is covered twice over, under @async and under Threads.@spawn, because the two exercise different sticky paths
• Failure paths are exercised directly, including deadline expiry, cancellation of a never-ready connection, oversized messages, shutdown during concurrent requests, and exceptions raised inside the streaming pumps
• Internal names used by tests are imported explicitly at the top of test/runtests.jl, for example grpc_timeout_header_val and the GRPC_* constants, since the constants are not exported
• Tests that need a connection which never becomes ready open a listening socket that accepts TCP without completing the HTTP/2 handshake, which is the scenario the deadline watchdog exists for

Reference files