juliaio/grpcserver.jl/grpcserver-jl-dev

Developing gRPCServer.jl

Repository map

The codegen contract (do not break)

The generated output is the package's user-facing interface. Invariants:

• One protojl run with both gRPCServer and gRPCClient loaded emits messages,

client stubs, and registration functions (the test/gen/test/test_pb.jl shape).

• Every emitted server-side registration symbol is exported and carries a

static docstring with the typed handler contract.

• Registration functions come in both argument orders (do-block form works)

plus the aggregate.

• Emission is byte-stable for a given ProtoBuf + Julia version.

The runtime layer the codegen sits on is documented in docs/src/api.md (all exported symbols — checkdocs = :exports fails if a new export is missing from the @docs blocks) and docs/src/examples/advanced.md (the labeled "runtime interface beneath the codegen" section).

Regenerating example stubs

Run from the example directory with the root project active (the examples have no Project.toml; the root project carries ProtoBuf, gRPCServer, gRPCClient):

cd examples/01_hello_world
julia --project=../.. -e 'using ProtoBuf; using gRPCServer; import gRPCClient; ProtoBuf.protojl("greeter.proto", ".", "generated"; always_use_modules = true, add_kwarg_constructors = true)'

Proto files per example: greeter.proto (01, 02), sum.proto (03), chat.proto (04), calculator.proto (05). Output lands in generated/<package>/ with the module wrapper and <proto>_pb.jl.

Byte-stability gate: after regenerating, run the same command again in a FRESH Julia process and diff -r the two trees. They must be byte-identical. Any diff means a ProtoBuf version drift — pin and redo. Never hand-edit generated files.

Test suite

timeout 3000 julia --project=. -e 'using Pkg; Pkg.test()'

Baseline: 1,023,518 pass / 2 broken / exit 0. The root project has gRPCClient in [deps] (used by the examples and the codegen tests); test/aqua.jl ignores it in the stale-deps check (stale_deps = (; ignore = [:gRPCClient])) because the package itself never loads it. Keep that pair consistent: if gRPCClient ever leaves [deps], drop the Aqua ignore; if it moves to [weakdeps], neither is needed.

Docs build

# first time only: docs env has no committed Manifest
julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
# then
julia --project=docs docs/make.jl

docs/make.jl uses doctest = false and checkdocs = :exports. Nav order: index → quickstart → code_generation → tls → http2-backends → performance → api → examples. Orphan legacy pages (handlers/getting_started/streaming/ concurrency/security) were deleted — do not re-add them.

Skills and plugin layout

• skills/grpcserver-jl/ — user-facing skill (codegen interface; the primary

one for porting a project onto gRPCServer.jl).

• skills/grpcserver-jl-dev/ — this skill (package development).
• .claude-plugin/{plugin.json, marketplace.json} — Claude Code registry

wiring, mirroring gRPCClient.jl.