gRPC.jl

A comprehensive gRPC package for Julia implementing the full gRPC protocol over HTTP/2.

Features

• Complete HTTP/2 Transport – From-scratch implementation with HPACK header compression
• All Four RPC Types – Unary, server-streaming, client-streaming, and bidirectional streaming
• Protocol Buffers – Integrated with ProtoBuf.jl
• TLS Support – Secure channels via MbedTLS.jl, including mutual TLS
• Interceptors – Client and server middleware chains (logging, auth, retry, metadata injection)
• Code Generation – Generate Julia client stubs and server handlers from .proto files
• gRPC Status Codes – Full implementation of all 17 status codes with error handling

Installation

using Pkg
Pkg.add(url="https://github.com/your-org/gRPC.jl")

Quick Start

Client

using gRPC

# Create a channel
channel = GrpcChannel("localhost:50051")
connect!(channel)

# Make a unary call (using raw bytes with IdentityCodec)
response, metadata, status = grpc_request(
    channel, "helloworld.Greeter", "SayHello",
    request_bytes, Vector{UInt8};
    options=GrpcCallOptions(codec=IdentityCodec())
)

# Server-streaming call
reader = grpc_server_stream(channel, "svc", "StreamMethod", request, ResponseType)
for response in reader
    println(response)
end

# Client-streaming call
writer, response_task = grpc_client_stream(channel, "svc", "Collect", RequestType, ResponseType)
write!(writer, msg1)
write!(writer, msg2)
close_writer!(writer)
response, meta, status = fetch(response_task)

# Bidirectional streaming
writer, reader = grpc_bidi_stream(channel, "svc", "BidiChat", ReqType, RespType)
@async for resp in reader
    println(resp)
end
write!(writer, msg)
close_writer!(writer)

# Close when done
close_channel!(channel)

Server

using gRPC

# Create server
server = GrpcServer("0.0.0.0", 50051)

# Define service
desc = ServiceDescriptor("helloworld.Greeter", "helloworld")
add_method!(desc, MethodDescriptor("SayHello", "helloworld.Greeter", UNARY,
    HelloRequest, HelloReply))

# Register handlers
handlers = Dict{String,Function}(
    "SayHello" => (ctx, req) -> HelloReply(message="Hello $(req.name)"),
)
add_service!(server, desc, handlers)

# Start serving (blocking)
serve!(server)

With Interceptors

# Client interceptors
channel = GrpcChannel("localhost:50051",
    interceptors=[
        LoggingInterceptor(),
        MetadataInterceptor([("authorization", "Bearer token")]),
        RetryInterceptor(max_retries=3),
    ]
)

# Server interceptors
server = GrpcServer("0.0.0.0", 50051,
    interceptors=[
        ServerLoggingInterceptor(),
        AuthInterceptor(meta -> any(kv -> kv[1] == "authorization", meta)),
        DeadlineInterceptor(),
    ]
)

Code Generation

using gRPC

# Generate from .proto file
generate_services("hello.proto", "gen/")
# Creates gen/hello_grpc.jl with:
#   - GreeterStub (client)
#   - AbstractGreeterHandler (server)
#   - Greeter_descriptor()
#   - register_greeter!(server, handler)

TLS

# Client with TLS
channel = GrpcChannel("secure.example.com:443",
    credentials=ChannelCredentials(root_certs="ca.pem"))

# Mutual TLS
channel = GrpcChannel("mtls.example.com:443",
    credentials=ChannelCredentials(
        root_certs="ca.pem",
        client_cert="client.pem",
        client_key="client-key.pem"))

# Server with TLS
server = GrpcServer("0.0.0.0", 443,
    credentials=ServerCredentials(
        cert_chain="server.pem",
        private_key="server-key.pem"))

Architecture

src/
├── gRPC.jl              # Main module
├── status.jl            # gRPC status codes & errors
├── protocol.jl          # Wire protocol (LPM, headers, trailers)
├── codec.jl             # Serialization (ProtoBuf, Identity)
├── service.jl           # Service/method descriptors
├── tls.jl               # TLS credentials & wrapping
├── codegen.jl           # Proto → Julia code generation
├── http2/
│   ├── frames.jl        # HTTP/2 frame encoding/decoding
│   ├── hpack.jl         # HPACK header compression
│   ├── stream.jl        # Stream state machine
│   └── connection.jl    # Connection management
├── client/
│   ├── channel.jl       # GrpcChannel
│   ├── call.jl          # RPC call primitives
│   └── interceptor.jl   # Client interceptors
└── server/
    ├── handler.jl        # Server context & stream types
    ├── server.jl         # GrpcServer core
    └── server_interceptor.jl  # Server interceptors

Testing

using Pkg
Pkg.test("gRPC")

Dependencies

Package	Purpose
ProtoBuf.jl	Protocol Buffers serialization
MbedTLS.jl	TLS/SSL support
Sockets (stdlib)	TCP networking

License

MIT