API Reference

gRPCServer

A native Julia implementation of a gRPC server library.

gRPCServer enables Julia developers to expose services over the gRPC protocol with support for all four RPC patterns (unary, server streaming, client streaming, bidirectional), interceptors, health checking, reflection, TLS/mTLS, and compression.

Quick Start

using gRPCServer

# Create server
server = GRPCServer("127.0.0.1", 50051)

# Register your service
register!(server, MyService())

# Start server
run(server)

See the documentation for more examples and API reference.

GRPCServer

The main gRPC server managing connections, services, and lifecycle.

Fields

• host::String: Server bind address
• port::Int: Server port
• config::ServerConfig: Server configuration
• status::ServerStatus.T: Current lifecycle state
• dispatcher::RequestDispatcher: Request dispatcher
• health_status::Dict{String, HealthStatus.T}: Per-service health status

Example

server = GRPCServer("0.0.0.0", 50051)
register!(server, GreeterService())
run(server)

ServerConfig

Configuration container for gRPC server options.

Fields

Connection Limits

• max_connections::Union{Int, Nothing}: Maximum concurrent connections (nothing = unlimited)
• max_concurrent_streams::Int: Maximum streams per connection (default: 100)
• max_concurrent_requests::Union{Int, Nothing}: Maximum concurrent requests (nothing = unlimited)
• max_queued_requests::Int: Maximum queued requests when at capacity (default: 1000)

Message Limits

• max_message_size::Int: Maximum message size in bytes (default: 4MB)

Timeouts (in seconds)

• keepalive_interval::Union{Float64, Nothing}: Interval for keepalive pings (nothing = disabled)
• keepalive_timeout::Float64: Timeout for keepalive response (default: 20.0)
• idle_timeout::Union{Float64, Nothing}: Close idle connections after this time (nothing = never)
• drain_timeout::Float64: Maximum time to wait for graceful shutdown (default: 30.0)

TLS

• tls::Union{TLSConfig, Nothing}: TLS configuration (nothing = insecure)

Feature Toggles

• enable_health_check::Bool: Enable built-in health checking service (default: false)
• enable_reflection::Bool: Enable gRPC reflection service (default: false)
• debug_mode::Bool: Include exception details in error responses (default: false)
• log_requests::Bool: Log all incoming requests (default: false)

Compression

• compression_enabled::Bool: Enable message compression (default: true)
• compression_threshold::Int: Minimum bytes before compression (default: 1024)
• supported_codecs::Vector{CompressionCodec.T}: Supported compression codecs

Example

config = ServerConfig(
    max_message_size = 8 * 1024 * 1024,  # 8MB
    enable_health_check = true,
    enable_reflection = true,
    debug_mode = false
)

TLSConfig

TLS/mTLS configuration for secure connections.

Fields

• cert_chain::String: Path to server certificate chain (PEM)
• private_key::String: Path to server private key (PEM)
• client_ca::Union{String, Nothing}: Path to client CA certificate for mTLS
• require_client_cert::Bool: Whether to require client certificates
• min_version::Symbol: Minimum TLS version (:TLSv1_2 or :TLSv1_3)
• alpn_protocols::Vector{String}: Ordered ALPN protocol preference list (default ["h2"])
• handshake_timeout_ns::Int64: Optional per-handshake timeout in nanoseconds; 0 leaves it unset

Example

tls = TLSConfig(
    cert_chain = "/path/to/server.crt",
    private_key = "/path/to/server.key",
    client_ca = "/path/to/ca.crt",  # For mTLS
    require_client_cert = true,
    min_version = :TLSv1_2,
    alpn_protocols = ["h2"],
)

ServerStatus

Represents the lifecycle state of a gRPC server.

States

• STOPPED: Server is not running
• STARTING: Server is binding to address
• RUNNING: Server is accepting connections
• DRAINING: Server is completing in-flight requests
• STOPPING: Server is releasing resources

ServerContext

Request-scoped context provided to handler functions.

Fields

• request_id::UUID: Unique identifier for this request
• method::String: Full method path (e.g., "/helloworld.Greeter/SayHello")
• authority::String: Authority from :authority pseudo-header
• metadata::Dict{String, Union{String, Vector{UInt8}}}: Request metadata
• response_headers::Dict{String, Union{String, Vector{UInt8}}}: Response headers to send
• trailers::Dict{String, Union{String, Vector{UInt8}}}: Trailing metadata to send
• deadline::Union{DateTime, Nothing}: Request deadline (nothing = no deadline)
• cancelled::Bool: Whether the request has been cancelled
• peer::PeerInfo: Client connection information
• trace_context::Union{Vector{UInt8}, Nothing}: Distributed tracing context

Example

function say_hello(ctx::ServerContext, request::HelloRequest)::HelloReply
    @info "Request" id=ctx.request_id method=ctx.method

    # Check cancellation
    if is_cancelled(ctx)
        throw(GRPCError(StatusCode.CANCELLED, "Request cancelled"))
    end

    # Set response header
    set_header!(ctx, "x-request-id", string(ctx.request_id))

    # Check deadline
    remaining = remaining_time(ctx)
    if remaining !== nothing && remaining < 0
        throw(GRPCError(StatusCode.DEADLINE_EXCEEDED, "Deadline exceeded"))
    end

    HelloReply(message = "Hello, $(request.name)!")
end

PeerInfo

Client connection information.

Fields

• address::Union{IPv4, IPv6}: Client IP address
• port::Int: Client port
• certificate::Union{Vector{UInt8}, Nothing}: Client certificate for mTLS (DER-encoded)

Example

peer = ctx.peer
@info "Client connected from $(peer.address):$(peer.port)"

ServiceDescriptor

Describes a gRPC service and its methods.

Fields

• name::String: Fully-qualified service name (e.g., "helloworld.Greeter")
• methods::Dict{String, MethodDescriptor}: Methods keyed by name
• file_descriptor::Union{Vector{UInt8}, Nothing}: File descriptor for reflection (optional)

Example

service = ServiceDescriptor(
    "helloworld.Greeter",
    Dict(
        "SayHello" => MethodDescriptor(
            "SayHello",
            MethodType.UNARY,
            "helloworld.HelloRequest",
            "helloworld.HelloReply",
            say_hello
        )
    ),
    nothing
)

MethodDescriptor

Describes a single RPC method.

Fields

• name::String: Method name (e.g., "SayHello")
• method_type::MethodType.T: RPC pattern type
• input_type::String: Fully-qualified request message type name
• output_type::String: Fully-qualified response message type name
• handler::Function: Handler function reference

Handler Signatures by MethodType

• UNARY: (ctx::ServerContext, request::T) -> R
• SERVER_STREAMING: (ctx::ServerContext, request::T, stream::ServerStream{R}) -> Nothing
• CLIENT_STREAMING: (ctx::ServerContext, stream::ClientStream{T}) -> R
• BIDI_STREAMING: (ctx::ServerContext, stream::BidiStream{T,R}) -> Nothing

Example

method = MethodDescriptor(
    "SayHello",
    MethodType.UNARY,
    "helloworld.HelloRequest",
    "helloworld.HelloReply",
    say_hello
)

MethodType

Classifies RPC method patterns.

Values

• UNARY: Single request, single response
• SERVER_STREAMING: Single request, multiple responses
• CLIENT_STREAMING: Multiple requests, single response
• BIDI_STREAMING: Multiple requests, multiple responses

register!(registry::ServiceRegistry, descriptor::ServiceDescriptor)

Register a service in the registry. Also auto-registers protobuf types if Julia types were provided in MethodDescriptor.

register!(server::GRPCServer, service)

Register a service with the server.

The service must implement service_descriptor(service) to provide its ServiceDescriptor.

Arguments

• server::GRPCServer: The server to register with
• service: A service implementation

Throws

• InvalidServerStateError: If server is not in STOPPED state
• ServiceAlreadyRegisteredError: If service is already registered

Example

server = GRPCServer("0.0.0.0", 50051)
register!(server, GreeterService())

services(server::GRPCServer) -> Vector{String}

Get a list of registered service names.

Example

for service_name in services(server)
    println(service_name)
end

service_descriptor(service) -> ServiceDescriptor

Get the service descriptor for a service implementation.

This function should be overloaded for custom service types.

Example

struct GreeterService end

function gRPCServer.service_descriptor(::GreeterService)
    ServiceDescriptor(
        "helloworld.Greeter",
        Dict(
            "SayHello" => MethodDescriptor(
                "SayHello", MethodType.UNARY,
                "helloworld.HelloRequest", "helloworld.HelloReply",
                say_hello
            )
        ),
        nothing
    )
end

ServerStream{T}

Outgoing stream for server streaming and bidirectional RPCs.

Type parameter T is the response message type.

Methods

• send!(stream, message): Send a message
• close!(stream): End the stream

Example

function list_features(ctx::ServerContext, request::Rectangle, stream::ServerStream{Feature})
    for feature in find_features(request)
        send!(stream, feature)
    end
end

ClientStream{T}

Incoming stream for client streaming and bidirectional RPCs.

Type parameter T is the request message type.

Implements the Julia iterator interface for use in for loops.

Example

function record_route(ctx::ServerContext, stream::ClientStream{Point})::RouteSummary
    point_count = 0
    for point in stream
        point_count += 1
        # Process each point
    end
    return RouteSummary(point_count=point_count)
end

BidiStream{T, R}

Bidirectional stream combining input (T) and output (R) streams.

Type parameters:

• T: Request message type (incoming)
• R: Response message type (outgoing)

Implements the iterator interface for incoming messages and provides send! for outgoing messages.

Example

function route_chat(ctx::ServerContext, stream::BidiStream{RouteNote, RouteNote})
    for note in stream  # Iterate incoming messages
        # Echo back each note
        send!(stream, note)
    end
end

send!(stream::ServerStream{T}, message::T) where T
send!(stream::ServerStream{T}, message::T; compress::Bool=true) where T

Send a message on the server stream.

Arguments

• stream::ServerStream{T}: The stream to send on
• message::T: The message to send
• compress::Bool=true: Whether to compress the message (if compression is negotiated)

Throws

• StreamCancelledError: If the stream has been cancelled
• ArgumentError: If the stream is closed

Example

send!(stream, Feature(name="Feature 1", location=Point(latitude=1, longitude=2)))

send!(stream::BidiStream{T, R}, message::R) where {T, R}
send!(stream::BidiStream{T, R}, message::R; compress::Bool=true) where {T, R}

Send a message on the bidirectional stream.

Example

send!(stream, RouteNote(message="Hello", location=point))

close!(stream::BidiStream)

Close the output side of the bidirectional stream.

StatusCode

Standard gRPC status codes per specification.

Status Codes

• OK (0): Not an error; returned on success
• CANCELLED (1): Operation was cancelled
• UNKNOWN (2): Unknown error
• INVALID_ARGUMENT (3): Invalid argument provided
• DEADLINE_EXCEEDED (4): Deadline expired before completion
• NOT_FOUND (5): Requested entity not found
• ALREADY_EXISTS (6): Entity already exists
• PERMISSION_DENIED (7): Permission denied
• RESOURCE_EXHAUSTED (8): Resource exhausted
• FAILED_PRECONDITION (9): Precondition check failed
• ABORTED (10): Operation aborted
• OUT_OF_RANGE (11): Value out of range
• UNIMPLEMENTED (12): Operation not implemented
• INTERNAL (13): Internal error
• UNAVAILABLE (14): Service unavailable
• DATA_LOSS (15): Data loss or corruption
• UNAUTHENTICATED (16): Request not authenticated

GRPCError <: Exception

Exception type for gRPC errors with status code, message, and optional details.

Fields

• code::StatusCode.T: The gRPC status code
• message::String: Human-readable error message
• details::Vector{Any}: Additional error details (rich error model)

Example

throw(GRPCError(StatusCode.NOT_FOUND, "User not found", []))
throw(GRPCError(StatusCode.INVALID_ARGUMENT, "Name cannot be empty"))

BindError <: Exception

Exception thrown when the server fails to bind to the configured address.

Fields

• message::String: Description of the bind failure
• cause::Union{Exception, Nothing}: Underlying exception if available

ServiceAlreadyRegisteredError <: Exception

Exception thrown when attempting to register a service with a name that already exists.

Fields

• service_name::String: The duplicate service name

InvalidServerStateError <: Exception

Exception thrown when an operation is attempted in an invalid server state.

Fields

• expected::ServerStatus.T: The expected server state
• actual::ServerStatus.T: The actual server state

MethodSignatureError <: Exception

Exception thrown when a handler method has an invalid signature.

Fields

• method_name::String: The method with invalid signature
• expected::String: Description of expected signature
• actual::String: Description of actual signature

StreamCancelledError <: Exception

Exception thrown when a stream operation is attempted on a cancelled stream.

Fields

• reason::String: The reason for cancellation

status_code_to_http(code::StatusCode.T) -> Int

Map a gRPC status code to the appropriate HTTP status code.

exception_to_status_code(e::Exception) -> StatusCode.T

Map a Julia exception to a gRPC status code.

http2_to_grpc_status(http2_error_code::UInt32) -> StatusCode.T

Map an HTTP/2 error code to a gRPC status code.

This mapping is per the gRPC HTTP/2 protocol specification: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md

HTTP/2 Error Code Mappings

• NOERROR (0x0) → INTERNAL (unexpected for RSTSTREAM)
• PROTOCOL_ERROR (0x1) → INTERNAL
• INTERNAL_ERROR (0x2) → INTERNAL
• FLOWCONTROLERROR (0x3) → INTERNAL
• SETTINGS_TIMEOUT (0x4) → INTERNAL
• STREAM_CLOSED (0x5) → INTERNAL
• FRAMESIZEERROR (0x6) → INTERNAL
• REFUSED_STREAM (0x7) → UNAVAILABLE
• CANCEL (0x8) → CANCELLED
• COMPRESSION_ERROR (0x9) → INTERNAL
• CONNECT_ERROR (0xa) → INTERNAL
• ENHANCEYOURCALM (0xb) → RESOURCE_EXHAUSTED
• INADEQUATESECURITY (0xc) → PERMISSIONDENIED
• HTTP11_REQUIRED (0xd) → INTERNAL

Example

grpc_status = http2_to_grpc_status(0x08)  # CANCEL → CANCELLED

http2_to_grpc_status(http2_error_code::Integer) -> StatusCode.T

Convenience method accepting any integer type.

Interceptor

Abstract type for gRPC interceptors.

Interceptors are callables that wrap handler execution, allowing for cross-cutting concerns like logging, authentication, metrics, and error handling.

Required Interface

Subtypes must be callable with signature:

(interceptor)(ctx::ServerContext, request_or_stream, info::MethodInfo, next::Function) -> response

Arguments

• ctx::ServerContext: Request context
• request_or_stream: Request message (unary/server streaming) or stream (client/bidi streaming)
• info::MethodInfo: Method information
• next::Function: Next handler in the chain (call to continue processing)

Example

struct AuthInterceptor <: Interceptor
    required_scope::String
end

function (i::AuthInterceptor)(ctx, request, info, next)
    token = get_metadata_string(ctx, "authorization")
    if token === nothing
        throw(GRPCError(StatusCode.UNAUTHENTICATED, "Missing authorization"))
    end

    # Validate token and check scope
    if !validate_token(token, i.required_scope)
        throw(GRPCError(StatusCode.PERMISSION_DENIED, "Insufficient scope"))
    end

    return next(ctx, request)
end

MethodInfo

Information about the method being called, provided to interceptors.

Fields

• service_name::String: Fully-qualified service name (e.g., "helloworld.Greeter")
• method_name::String: Method name (e.g., "SayHello")
• method_type::MethodType.T: RPC pattern type

Example

struct LoggingInterceptor <: Interceptor end

function (::LoggingInterceptor)(ctx, request, info::MethodInfo, next)
    @info "Calling" service=info.service_name method=info.method_name
    return next(ctx, request)
end

LoggingInterceptor <: Interceptor

Built-in interceptor that logs request/response information.

Fields

• log_requests::Bool: Log incoming requests (default: true)
• log_responses::Bool: Log responses (default: true)
• log_errors::Bool: Log errors (default: true)

Example

add_interceptor!(server, LoggingInterceptor())

MetricsInterceptor <: Interceptor

Built-in interceptor that collects request metrics.

Fields

• on_request::Function: Called with (method, request_size) on each request
• on_response::Function: Called with (method, status, durationms, responsesize) on each response

Example

metrics = MetricsInterceptor(
    on_request = (method, size) -> increment_counter("grpc_requests", method),
    on_response = (method, status, ms, size) -> record_histogram("grpc_duration", ms, method, status)
)
add_interceptor!(server, metrics)

TimeoutInterceptor <: Interceptor

Built-in interceptor that enforces request deadlines.

Fields

• default_timeout_ms::Union{Int, Nothing}: Default timeout in milliseconds if none specified

Example

add_interceptor!(server, TimeoutInterceptor(default_timeout_ms=30000))  # 30 second default

RecoveryInterceptor <: Interceptor

Built-in interceptor that catches panics and converts them to gRPC errors.

Fields

• include_stack_trace::Bool: Include stack trace in error message (debug mode only)

Example

add_interceptor!(server, RecoveryInterceptor(include_stack_trace=true))

add_interceptor!(dispatcher::RequestDispatcher, interceptor::Interceptor)

Add a global interceptor.

add_interceptor!(dispatcher::RequestDispatcher, service_name::String, interceptor::Interceptor)

Add a service-specific interceptor.

add_interceptor!(server::GRPCServer, interceptor::Interceptor)

Add a global interceptor that applies to all services.

Example

add_interceptor!(server, LoggingInterceptor())
add_interceptor!(server, MetricsInterceptor())

add_interceptor!(server::GRPCServer, service_name::String, interceptor::Interceptor)

Add an interceptor for a specific service.

Example

add_interceptor!(server, "helloworld.Greeter", AuthInterceptor())

HealthStatus

Service health state for the health checking service.

Values

• UNKNOWN: Health status is unknown
• SERVING: Service is healthy and accepting requests
• NOT_SERVING: Service is not healthy
• SERVICE_UNKNOWN: Service is not registered

set_health!(server::GRPCServer, status::HealthStatus.T)

Set the health status for the overall server.

Example

set_health!(server, HealthStatus.NOT_SERVING)  # Server entering maintenance

set_health!(server::GRPCServer, service_name::String, status::HealthStatus.T)

Set the health status for a specific service.

Example

set_health!(server, "helloworld.Greeter", HealthStatus.NOT_SERVING)

get_health(server::GRPCServer, service_name::String="") -> HealthStatus.T

Get the health status for a service (or overall server if empty string).

HEALTH_DESCRIPTOR::Vector{Vector{UInt8}}

Extracted FileDescriptorProto messages for the gRPC Health service (grpc.health.v1). Each element is a serialized FileDescriptorProto that can be returned by the reflection service.

Generated from: specs/001-grpc-server/contracts/health.proto

REFLECTION_DESCRIPTOR::Vector{Vector{UInt8}}

Extracted FileDescriptorProto messages for the gRPC Server Reflection service (grpc.reflection.v1alpha). Each element is a serialized FileDescriptorProto that can be returned by the reflection service.

Generated from: specs/001-grpc-server/contracts/reflection.proto

has_health_descriptor() -> Bool

Check if the Health service descriptor is available.

has_reflection_descriptor() -> Bool

Check if the Reflection service descriptor is available.

start!(server::GRPCServer)

Start the server and begin accepting connections.

This is a non-blocking call. Use run(server) for blocking operation.

Throws

• InvalidServerStateError: If server is not in STOPPED state
• BindError: If the server cannot bind to the address

Example

start!(server)
# Server is now running in background

stop!(server::GRPCServer; force::Bool=false, timeout::Float64=0.0)

Stop the server.

Arguments

• server::GRPCServer: The server to stop
• force::Bool=false: If true, immediately close all connections
• timeout::Float64=0.0: Override drain timeout (0 = use config)

Throws

• InvalidServerStateError: If server is not running

Example

stop!(server)  # Graceful shutdown
stop!(server; force=true)  # Immediate shutdown

reload_tls!(server::GRPCServer)

Reload TLS certificates from disk.

This allows certificate rotation without server restart.

Throws

• InvalidServerStateError: If server is not running
• ArgumentError: If TLS is not configured

Example

reload_tls!(server)  # Reload certificates

set_header!(ctx::ServerContext, key::String, value::String)
set_header!(ctx::ServerContext, key::String, value::Vector{UInt8})

Set a response header to be sent before the response body.

Headers must be set before the first response message is sent. Binary headers should have a "-bin" suffix in the key name.

Example

set_header!(ctx, "x-custom-header", "custom-value")
set_header!(ctx, "x-binary-data-bin", UInt8[0x01, 0x02, 0x03])

set_trailer!(ctx::ServerContext, key::String, value::String)
set_trailer!(ctx::ServerContext, key::String, value::Vector{UInt8})

Set trailing metadata to be sent after the response body.

Trailers are sent at the end of the response stream and can be used to communicate status information determined during processing.

Example

set_trailer!(ctx, "x-processing-time", "150ms")

get_metadata(ctx::ServerContext, key::String) -> Union{String, Vector{UInt8}, Nothing}

Get request metadata by key (case-insensitive).

Example

auth = get_metadata(ctx, "authorization")
if auth === nothing
    throw(GRPCError(StatusCode.UNAUTHENTICATED, "Missing authorization"))
end

get_metadata_string(ctx::ServerContext, key::String) -> Union{String, Nothing}

Get request metadata as a string (returns nothing for binary metadata).

get_metadata_binary(ctx::ServerContext, key::String) -> Union{Vector{UInt8}, Nothing}

Get request metadata as binary (converts strings to bytes if needed).

remaining_time(ctx::ServerContext) -> Union{Float64, Nothing}

Get the remaining time until the deadline in seconds.

Returns nothing if no deadline is set. Returns negative value if deadline has passed.

Example

remaining = remaining_time(ctx)
if remaining !== nothing && remaining < 0
    throw(GRPCError(StatusCode.DEADLINE_EXCEEDED, "Deadline exceeded"))
end

is_cancelled(ctx::ServerContext) -> Bool

Check if the request has been cancelled by the client.

Example

if is_cancelled(ctx)
    throw(GRPCError(StatusCode.CANCELLED, "Request cancelled by client"))
end

is_cancelled(stream::ClientStream) -> Bool

Check if the stream has been cancelled.

is_cancelled(stream::BidiStream) -> Bool

Check if the stream has been cancelled.

CompressionCodec

Supported compression algorithms for gRPC messages.

Values

• IDENTITY: No compression
• GZIP: Gzip compression
• DEFLATE: Deflate compression

compress(data::Vector{UInt8}, codec::CompressionCodec.T) -> Vector{UInt8}

Compress data using the specified codec.

decompress(data::Vector{UInt8}, codec::CompressionCodec.T) -> Vector{UInt8}

Decompress data using the specified codec.

codec_name(codec::CompressionCodec.T) -> String

Get the gRPC encoding name for a compression codec.

parse_codec(name::AbstractString) -> Union{CompressionCodec.T, Nothing}

Parse a gRPC encoding name to a compression codec. Returns nothing if the encoding is not supported.

negotiate_compression(
    client_encodings::Vector{CompressionCodec.T},
    server_codecs::Vector{CompressionCodec.T}
) -> CompressionCodec.T

Negotiate compression codec between client and server. Returns the first codec supported by both, preferring client order. Falls back to IDENTITY if no common codec.

AbstractHTTP2Backend

Abstract type representing an HTTP/2 backend for gRPCServer.jl.

Any HTTP/2 backend must subtype AbstractHTTP2Backend and implement create_connection to return an HTTP/2 connection object.

The connection object returned by create_connection must be compatible with PureHTTP2.jl's HTTP2Connection interface, supporting:

• Connection lifecycle: process_preface, process_frame, is_open
• Stream management: get_stream, remove_stream, can_send_on_stream
• Sending: send_headers, send_data, send_trailers, send_rst_stream, send_goaway
• Frame I/O: Frame, encode_frame, decode_frame_header

See the HTTP/2 Backends documentation page for details on implementing a custom backend.

PureHTTP2Backend <: AbstractHTTP2Backend

Default HTTP/2 backend using PureHTTP2.jl.

This backend delegates all HTTP/2 operations to the PureHTTP2 package, which provides a pure-Julia implementation of the HTTP/2 protocol (RFC 7540) including HPACK header compression (RFC 7541), stream management, and flow control.

create_connection(backend::AbstractHTTP2Backend)

Create a new HTTP/2 connection using the specified backend.

Returns an HTTP/2 connection object that will be used to manage a single client connection. The returned object must support the full HTTP/2 connection interface (see AbstractHTTP2Backend for requirements).

Examples

backend = PureHTTP2Backend()
conn = create_connection(backend)  # Returns a PureHTTP2.HTTP2Connection

HTTPjlBackend <: AbstractHTTP2Backend

HTTP/2 backend backed by HTTP.jl (>= 2.0.0).

HTTP.jl owns the TCP listener and the TLS/ALPN handshake; this backend delegates the HTTP/2 protocol (frames, HPACK, flow control, trailers) to HTTP.jl and adapts each HTTP.Stream to the AbstractGRPCStream contract.

Constructing an HTTPjlBackend validates that the loaded HTTP.jl can serve HTTP/2 and raises a clear error otherwise.

Known limitations (current HTTP.jl)

• No configurable max-concurrent-streams limit (HTTP.jl advertises none).
• No live TLS certificate reload (reload_tls!); HTTP.jl owns the TLS context.

Select PureHTTP2Backend() if you need either capability.

Nghttp2Backend <: AbstractHTTP2Backend

HTTP/2 backend backed by the nghttp2 C library through Nghttp2Wrapper.jl.

Nghttp2Wrapper is an optional dependency. Load it before constructing the backend:

using gRPCServer, Nghttp2Wrapper
server = GRPCServer("127.0.0.1", 50051; http2_backend = Nghttp2Backend())

Supported RPC types

Unary and client-streaming calls only. Nghttp2Wrapper's server handler receives a fully buffered request and returns a fully buffered response, so a handler cannot emit messages as it produces them — server-streaming and bidirectional calls are rejected at dispatch rather than silently truncated. Its ROADMAP Milestone 7 tracks the incremental handler that would lift this.

Select HTTPjlBackend for the full set.

AbstractGRPCStream

Represents a single in-flight gRPC call (one HTTP/2 stream) as seen by the gRPC dispatch layer, independent of which HTTP/2 backend produced it.

A backend adapter presents each incoming call as an AbstractGRPCStream and implements the stream operations: grpc_path, request_metadata, read_message!, is_cancelled, send_response_headers!, send_message!, send_trailers!, and reset!.

serve_grpc(backend::AbstractHTTP2Backend, server, on_call) -> Nothing

Own the accept loop for server and invoke on_call(stream::AbstractGRPCStream) once per incoming gRPC call. Backends must validate the HTTP/2 connection preface (h2c) and/or negotiate ALPN h2 (TLS), surface each request's :path and metadata via the stream, honor graceful shutdown when the server leaves the RUNNING state, and fail fast (before accepting traffic) when the backend cannot serve gRPC HTTP/2.

This is the higher-level extension point that complements create_connection; see the HTTP/2 Backends documentation for details.