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 Pkg
   Pkg.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
• 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

Unary RPC (01helloworld)

Single request, single response:

function handler(ctx::ServerContext, request::RequestType)::ResponseType
    return 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 nothing
end

Client Streaming (03sumnumbers)

Multiple requests, single response:

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

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 nothing
end

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