Examples

This guide walks you through gRPCServer.jl examples in progressive order, from basic concepts to advanced patterns.

Learning Path

Getting Started

Prerequisites

1. Install gRPCServer.jl:

   using PkgPkg.add("gRPCServer")

2. Install grpcurl for testing:

   # macOS
   brew install grpcurl
   
   # Linux (download binary from releases)
   # Windows (download binary from releases)

Running Examples

Each example directory contains:

• *.proto - Protocol buffer service definition
• server.jl - Julia server implementation
• generated/ - Auto-generated Julia types, client stubs, and registration functions
• README.md - Detailed usage instructions

To run any example:

cd examples/<example_name>
julia --project=../.. server.jl

Example Workflow

1. Start simple: Begin with 01_hello_world to understand basic unary RPC
2. Server streaming: Move to 02_hello_stream to learn single request → multiple responses
3. Client streaming: Try 03_sum_numbers for multiple requests → single response
4. Bidirectional: Explore 04_chat for simultaneous bidirectional streaming
5. Multi-method: See 05_calculator for multiple methods with error handling
6. Production: Read advanced documentation for interceptors, TLS, compression

Quick Reference

Every example registers its handlers with the generated codegen registration functions (one protojl run emits messages, client stubs, and registration functions together).

Unary RPC (01helloworld)

Single request, single response:

function handler(ctx::ServerContext, request::RequestType)::ResponseType    return ResponseType(...)endregister_Greeter_SayHello!(server) do ctx, req    ResponseType(...)end

Server Streaming (02hellostream)

Single request, multiple responses:

function handler(ctx::ServerContext, request::RequestType, stream::ServerStream{ResponseType})::Nothing    for item in items        send!(stream, ResponseType(...))    end    return nothingendregister_Greeter_SayHelloStream!(server, handler)

Client Streaming (03sumnumbers)

Multiple requests, single response:

function handler(ctx::ServerContext, stream::ClientStream{RequestType})    for request in stream        # Process each request    end    return ResponseType(...)endregister_Math_Sum!(server, handler)

Bidirectional Streaming (04_chat)

Multiple requests and responses:

function handler(ctx::ServerContext, stream::BidiStream{RequestType, ResponseType})    for request in stream        send!(stream, ResponseType(...))    end    close!(stream)    return nothingendregister_Chat_Chat!(server, handler)

Error Handling (05_calculator)

Return appropriate gRPC status codes:

if invalid_input    throw(GRPCError(StatusCode.INVALID_ARGUMENT, "Error message"))end

Port Assignments

Each example uses a different port:

Next Steps

After completing the examples, explore:

• Quick Start - Comprehensive setup guide
• API Reference - Detailed API documentation