Grapesy

https://github.com/well-typed/grapesy
Admin
Grapesy is an industrial-strength gRPC library for Haskell that provides client and server...
Tokens:13,276
Snippets:89
Trust Score:7.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Server Setup and Configuration

Source: https://context7.com/well-typed/grapesy/llms.txt

Provides examples for setting up a gRPC server with different configurations, including insecure, TLS-secured, and Unix domain socket connections.

```APIDOC
## Server Configuration

### Description
This section details how to configure and run a gRPC server using `runServerWithHandlers`. It covers basic insecure setups, TLS-secured connections, and servers listening on Unix domain sockets.

### Basic Server Configuration

#### Method
Server Initialization

#### Endpoint
N/A

#### Parameters
None

#### Request Body
None

### Request Example
```haskell
main :: IO ()
main = runServerWithHandlers def config handlers
  where
    config :: ServerConfig
    config = ServerConfig {
        serverInsecure = Just $ InsecureConfig (Just "0.0.0.0") defaultInsecurePort,
        serverSecure   = Nothing
    }
    handlers :: [SomeRpcHandler IO]
    handlers = fromMethods methods
```

### Server with TLS Configuration

#### Method
Server Initialization

#### Endpoint
N/A

#### Parameters
None

#### Request Body
None

### Request Example
```haskell
mainSecure :: IO ()
mainSecure = runServerWithHandlers def config handlers
  where
    config :: ServerConfig
    config = ServerConfig {
        serverInsecure = Nothing,
        serverSecure   = Just $ SecureConfig {
            secureHost       = "0.0.0.0",
            securePort       = defaultSecurePort,
            securePubCert    = "server.pem",
            secureChainCerts = [],
            securePrivKey    = "server.key",
            secureSslKeyLog  = SslKeyLogNone
        }
    }
    handlers :: [SomeRpcHandler IO]
    handlers = fromMethods methods
```

### Unix Domain Socket Server Configuration

#### Method
Server Initialization

#### Endpoint
N/A

#### Parameters
None

#### Request Body
None

### Request Example
```haskell
mainUnix :: IO ()
mainUnix = runServerWithHandlers def config handlers
  where
    config = ServerConfig {
        serverInsecure = Just $ InsecureUnix "/tmp/grpc.sock",
        serverSecure   = Nothing
    }
    handlers :: [SomeRpcHandler IO]
    handlers = fromMethods methods
```

### Response
#### Success Response (200)
Server starts listening on the configured address and port.

#### Response Example
N/A (Server startup confirmation is typically logged to the console.)
```

--------------------------------

### Grapesy Server Setup - Basic and Secure Haskell

Source: https://context7.com/well-typed/grapesy/llms.txt

Demonstrates how to start a gRPC server using `runServerWithHandlers` from `Network.GRPC.Server.Run`. It shows configurations for both insecure (TCP) and secure (TLS) connections, including specifying host, port, certificates, and private keys. The server can be configured to run with only insecure, only secure, or both simultaneously.

```haskell
import Network.GRPC.Common
import Network.GRPC.Server.Run

-- Basic server configuration
main :: IO ()
main = do
    runServerWithHandlers def config handlers
  where
    config :: ServerConfig
    config = ServerConfig {
        serverInsecure = Just $ InsecureConfig (Just "0.0.0.0") defaultInsecurePort,
        serverSecure   = Nothing
    }

    handlers :: [SomeRpcHandler IO]
    handlers = fromMethods methods

-- Server with TLS
mainSecure :: IO ()
mainSecure = do
    runServerWithHandlers def config handlers
  where
    config :: ServerConfig
    config = ServerConfig {
        serverInsecure = Nothing,
        serverSecure   = Just $ SecureConfig {
            secureHost       = "0.0.0.0",
            securePort       = defaultSecurePort,
            securePubCert    = "server.pem",
            secureChainCerts = [],
            securePrivKey    = "server.key",
            secureSslKeyLog  = SslKeyLogNone
        }
    }

-- Unix domain socket server
mainUnix :: IO ()
mainUnix = do
    runServerWithHandlers def config handlers
  where
    config = ServerConfig {
        serverInsecure = Just $ InsecureUnix "/tmp/grpc.sock",
        serverSecure   = Nothing
    }
```

--------------------------------

### Start gRPC Reference Servers

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Starts the Python, C++, Go, and Java gRPC reference servers using shell scripts. Each server is typically run in its own terminal.

```bash
grpc-repo$ bash ./python_server.sh
grpc-repo$ bash ./cxx_server.sh
grpc-repo$ bash ./go_server.sh
grpc-repo$ bash ./java_server.sh
```

--------------------------------

### Setup Local Repository for Automatic Testing

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Configures a local repository clone to run automatic interop tests by adding a remote, fetching, checking out a branch, and updating submodules.

```bash
grpc-repo$ git remote add edsko git@github.com:edsko/grpc.git
grpc-repo$ git fetch --all
grpc-repo$ git checkout --track edsko/grapesy
grpc-repo$ git submodule update --init
```

--------------------------------

### Run Grapesy Interop Tests Against Itself (Bash)

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Commands to run Grapesy's own interop tests. This involves starting the Grapesy server and then running the client, or executing both in a single command. No external gRPC repository checkout is needed.

```bash
grapesy$ cabal run grapesy-interop -- --server
grapesy$ cabal run grapesy-interop -- --client
```

```bash
grapesy$ cabal run grapesy-interop -- --self-test
```

--------------------------------

### Install Python Dependencies for gRPC Interop Tests

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Installs necessary Python packages for the gRPC interop test infrastructure using pip. This includes google-auth, google-api-python-client, and oauth2client with specific version constraints.

```bash
sudo apt-get install python3 python3-pip python3-setuptools python3-yaml
grpc-repo$ python3 -m venv ./python-venv
export PATH=$PWD/python-venv/bin:$PATH
grpc-repo$ python3 -m pip install --upgrade \
  google-auth==1.23.0 \
  google-api-python-client==1.12.8 \
  oauth2client==4.1.0
```

--------------------------------

### Run Grapesy as a Server

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Starts the Grapesy interop server on the default port 50052. The port can be changed using the --port flag.

```bash
grapesy$ cabal run grapesy-interop -- --server
```

--------------------------------

### Build gRPC Interop Clients and Servers for Multiple Languages

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Prepares reference clients and servers for various programming languages (Python, C++, Go, Java) using the run_interop_tests.py script. It also renames the generated command files for clarity.

```bash
grpc-repo$ tools/run_tests/run_interop_tests.py -l python -s python --use_docker --manual && \
  mv interop_server_cmds.sh python_server.sh && \
  mv interop_client_cmds.sh python_client.sh
grpc-repo$ tools/run_tests/run_interop_tests.py -l c++ -s c++ --use_docker --manual && \
  mv interop_server_cmds.sh cxx_server.sh && \
  mv interop_client_cmds.sh cxx_client.sh
grpc-repo$ tools/run_tests/run_interop_tests.py -l go -s go --use_docker --manual && \
  mv interop_server_cmds.sh go_server.sh && \
  mv interop_client_cmds.sh go_client.sh
grpc-repo$ tools/run_tests/run_interop_tests.py -l java -s java --use_docker --manual && \
  mv interop_server_cmds.sh java_server.sh && \
  mv interop_client_cmds.sh java_client.sh
```

--------------------------------

### Clone gRPC Reference Implementation Repositories (Bash)

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Commands to clone the official gRPC repository and language-specific implementations (Go and Java) for running interop tests. It's crucial to clone these without shallow checkouts to avoid test failures. The repositories should be checked out alongside each other.

```bash
$ git clone https://github.com/grpc/grpc.git -b v1.72.2 ./grpc-repo
grpc-repo$ git switch -c v1.72.2
grpc-repo$ git submodule update --init --recursive
```

```bash
$ git clone https://github.com/grpc/grpc-java.git -b v1.73.0
grpc-java$ git switch -c v1.73.0
```

```bash
$ git clone https://github.com/grpc/grpc-go.git -b v1.72.2
grpc-go$ git switch -c v1.72.2
```

--------------------------------

### Build Docker Image for Grapesy Dependencies

Source: https://github.com/well-typed/grapesy/blob/main/dev/grapesy-deps-docker/README.md

Builds the Docker image containing grapesy's dependencies. This command should be run from the directory containing the Dockerfile.

```bash
grapesy-deps-docker$ docker build . -t edsko/grapesy-deps:latest
```

--------------------------------

### Define gRPC Service and Messages in Protocol Buffer

Source: https://context7.com/well-typed/grapesy/llms.txt

Defines a simple 'Greeter' gRPC service with 'SayHello' and 'SayHelloStreamReply' RPC methods, along with 'HelloRequest' and 'HelloReply' messages. This `.proto` file serves as the contract for communication between gRPC clients and servers.

```protobuf
// helloworld.proto
syntax = "proto3";
package helloworld;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  rpc SayHelloStreamReply (HelloRequest) returns (stream HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

```

--------------------------------

### Configure Compression in gRPC with grapesy (Haskell)

Source: https://context7.com/well-typed/grapesy/llms.txt

Illustrates how to configure compression settings for gRPC connections using grapesy. It covers enabling gzip compression, disabling compression entirely, and forcing a specific compression algorithm, highlighting client-side configuration.

```Haskell
import Network.GRPC.Client
import Network.GRPC.Common
import Network.GRPC.Common.Compression qualified as Compr

-- Client with gzip compression
mainWithCompression :: IO ()
mainWithCompression = do
    let params = def {
            -- Negotiate gzip compression
            connCompression = Compr.only Compr.gzip
        }
    withConnection params server $ \conn -> do
        -- All messages will be compressed with gzip if server supports it
        performRpcCalls conn
  where
    server = ServerInsecure $ Address "127.0.0.1" 50051 Nothing

-- Disable compression entirely
mainNoCompression :: IO ()
mainNoCompression = do
    let params = def {
            connCompression = Compr.none
        }
    withConnection params server $ \conn -> do
        -- Messages will never be compressed
        performRpcCalls conn

-- Force specific compression (use with caution)
mainInsistCompression :: IO ()
mainInsistCompression = do
    let params = def {
            connCompression = Compr.insist Compr.gzip
        }
    withConnection params server $ \conn -> do
        -- Always use gzip, even if server doesn't advertise support
        performRpcCalls conn

```

--------------------------------

### Run Automatic Grapesy Interop Tests

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Executes the automatic interop tests for Grapesy against reference servers for Python, C++, Go, and Java, using Docker for isolation.

```bash
grpc-repo$ tools/run_tests/run_interop_tests.py -l python -s grapesy --use_docker
grpc-repo$ tools/run_tests/run_interop_tests.py -l c++    -s grapesy --use_docker
grpc-repo$ tools/run_tests/run_interop_tests.py -l go     -s grapesy --use_docker
grpc-repo$ tools/run_tests/run_interop_tests.py -l java   -s grapesy --use_docker
```

--------------------------------

### Run Reference Clients Against Grapesy Server

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Executes the Python, C++, Go, and Java reference gRPC clients against a Grapesy server running on port 50052.

```bash
grpc-repo$ SERVER_PORT=50052 bash ./python_client.sh
grpc-repo$ SERVER_PORT=50052 bash ./cxx_client.sh
grpc-repo$ SERVER_PORT=50052 bash ./go_client.sh
grpc-repo$ SERVER_PORT=50052 bash ./java_client.sh
```

--------------------------------

### Test Grapesy Docker Image

Source: https://github.com/well-typed/grapesy/blob/main/dev/grapesy-deps-docker/README.md

Runs an interactive bash session within the grapesy-deps Docker image. This allows for testing the prebuilt dependencies by cloning and building grapesy inside the container.

```bash
$ docker run --rm -it edsko/grapesy-deps bash
git clone https://github.com/well-typed/grapesy
grapesy$ cabal build all
```

--------------------------------

### Run Grapesy Client Against Reference Servers

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Executes the Grapesy client against different gRPC reference servers, specifying the server port and optional flags to skip certain tests or compression features.

```bash
grapesy$ cabal run grapesy-interop -- --client \
  --server_port=32768 \
  --skip_compression # Python

grapesy$ cabal run grapesy-interop -- --client \
  --server_port=32769 # C++

grapesy$ cabal run grapesy-interop -- --client \
  --server_port=32770 \
  --skip_compression # Go

grapesy$ cabal run grapesy-interop -- --client \
  --server_port=32771 \
  --skip_client_compression \
  --skip_test=server_compressed_streaming \
  --skip_test=timeout_on_sleeping_server # Java
```

--------------------------------

### Push Docker Image to Docker Hub

Source: https://github.com/well-typed/grapesy/blob/main/dev/grapesy-deps-docker/README.md

Uploads the newly built Docker image to Docker Hub. This command assumes you have already logged into Docker Hub.

```bash
$ docker push edsko/grapesy-deps:latest
```

--------------------------------

### Haskell Bindings and Message Handling with proto-lens

Source: https://context7.com/well-typed/grapesy/llms.txt

Generated Haskell code for interacting with Protocol Buffer definitions. It shows how to import generated types, reference RPC methods using type-level strings, create messages using lenses, and read message fields.

```haskell
-- Generated: Proto/API/Helloworld.hs
-- Use with proto-lens

import Network.GRPC.Common.Protobuf
import Proto.API.Helloworld

-- Reference RPC methods using type-level strings
type SayHello = Protobuf Greeter "sayHello"
type SayHelloStream = Protobuf Greeter "sayHelloStreamReply"

-- Create messages using defMessage and lens operators
createRequest :: Proto HelloRequest
createRequest = defMessage & #name .~ "World"

-- Read message fields
readResponse :: Proto HelloReply -> Text
readResponse resp = resp ^. #message

```

--------------------------------

### Inspect Docker Port Assignments

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Displays the port mappings for running Docker containers, showing which host ports are assigned to the gRPC server ports.

```bash
$ docker ps --format 'table {{.Image}}\t{{.Ports}}'
IMAGE                                                      PORTS
grpc_interop_java:0ac5c6f1-9835-45ee-9664-ad9925a41680     0.0.0.0:32771->8080/tcp
grpc_interop_go:b2a668d2-718c-4c66-b0e6-f7f6111974a6       0.0.0.0:32770->8080/tcp
grpc_interop_cxx:288ee67a-f462-40d1-b5a2-a29be5562fb2      0.0.0.0:32769->8080/tcp
grpc_interop_python:f558f1af-9ee5-41bc-8a6b-0b84a1a9e87a   0.0.0.0:32768->8080/tcp
```

--------------------------------

### Handle Custom Metadata in gRPC with grapesy (Haskell)

Source: https://context7.com/well-typed/grapesy/llms.txt

Demonstrates how to define, set, and retrieve custom metadata in gRPC requests and responses using grapesy's typed metadata support. This includes handling initial response metadata and trailing metadata for both server and client operations.

```Haskell
import Network.GRPC.Client
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Network.GRPC.Server
import Data.ByteString (ByteString)
import Data.Time.Clock (UTCTime)

-- Define custom metadata types
data DownloadStart = DownloadStart {
    downloadSize :: Integer,
    downloadTime :: Maybe UTCTime
}

data DownloadDone = DownloadDone {
    downloadHash :: ByteString
}

-- Server: Set initial response metadata
downloadHandler :: Call (Protobuf Fileserver "download") -> IO ()
downloadHandler call = do
    req <- recvFinalInput call

    -- Set response metadata before sending data
    setResponseInitialMetadata call $ DownloadStart 1024 Nothing
    initiateResponse call

    -- Send file chunks
    sendNextOutput call (defMessage & #chunk .~ "data...")

    -- Include trailing metadata
    sendFinalOutput call (defMessage & #chunk .~ "last", DownloadDone "hash")

-- Client: Read response metadata
downloadClient :: Connection -> IO ()
downloadClient conn = do
    withRPC conn def (Proxy @(Protobuf Fileserver "download")) $ \call -> do
        sendFinalInput call $ defMessage & #name .~ "file.txt"

        -- Wait for initial metadata
        DownloadStart{downloadSize} <- recvResponseInitialMetadata call
        putStrLn $ "File size: " ++ show downloadSize

        -- Process data and get trailing metadata
        (DownloadDone{downloadHash}, _) <- 
            StreamElem.whileNext_ (recvOutput call) $ \chunk ->
                print chunk

        putStrLn $ "Hash: " ++ show downloadHash

```

--------------------------------

### Run a Specific Grapesy Client Test Case

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Executes the Grapesy client against a specific server port and targets a single test case, such as 'timeout_on_sleeping_server'.

```bash
grapesy$ cabal run grapesy-interop -- --client \
  --server_port=32771 \
  --test_case=timeout_on_sleeping_server
```

--------------------------------

### Establish gRPC Client Connection with grapesy

Source: https://context7.com/well-typed/grapesy/llms.txt

The `withConnection` function in grapesy manages the lifecycle of a gRPC client connection. It supports both insecure (no TLS) and TLS-secured connections, with options for custom parameters like timeouts and automatic reconnection policies for enhanced reliability.

```haskell
import Network.GRPC.Client
import Network.GRPC.Common

-- Insecure connection (no TLS)
main :: IO ()
main = do
    withConnection def server $ \conn -> do
        -- Use connection for RPC calls
        putStrLn "Connected to server"
  where
    server :: Server
    server = ServerInsecure $ Address "127.0.0.1" defaultInsecurePort Nothing

-- Secure connection (with TLS)
mainSecure :: IO ()
mainSecure = do
    withConnection def server $ \conn -> do
        putStrLn "Securely connected"
  where
    server :: Server
    server = ServerSecure
        (ValidateServer certStoreFromSystem)  -- Server validation
        SslKeyLogNone                          -- SSL key logging
        (Address "myserver.com" defaultSecurePort Nothing)

-- Connection with custom parameters and reconnection policy
mainWithReconnect :: IO ()
mainWithReconnect = do
    let params = def {
            connDefaultTimeout = Just $ Timeout (TimeoutValue 30) TimeoutSeconds,
            connReconnectPolicy = exponentialBackoff
                threadDelay  -- Delay function
                2.0          -- Exponent
                (0.5, 1.0)   -- Initial delay range (seconds)
                10           -- Maximum attempts
        }
    withConnection params server $ \conn -> do
        -- Connection will auto-reconnect on failure
        performRpcCalls conn
  where
    server = ServerInsecure $ Address "127.0.0.1" 50051 Nothing

```

--------------------------------

### High-Level GRPC Server Handlers (Haskell)

Source: https://context7.com/well-typed/grapesy/llms.txt

Implements GRPC server handlers using the high-level API with automatic stream management. This approach simplifies handler creation for non-streaming, server streaming, client streaming, and bidirectional streaming RPCs. It requires importing necessary GRPC modules and protobuf definitions.

```haskell
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Network.GRPC.Server.Protobuf
import Network.GRPC.Server.Run
import Network.GRPC.Server.StreamType
import Network.GRPC.Common.NextElem qualified as NextElem

import Proto.API.RouteGuide

-- Non-streaming handler: receive one request, send one response
getFeature :: Proto Point -> IO (Proto Feature)
getFeature point = do
    let feature = defMessage
                    & #name     .~ "Some feature"
                    & #location .~ point
    return feature

-- Server streaming handler: receive one request, send multiple responses
listFeatures :: Proto Rectangle -> (NextElem (Proto Feature) -> IO ()) -> IO ()
listFeatures rect send = do
    -- Send multiple features
    send $ NextElem (defMessage & #name .~ "Feature 1")
    send $ NextElem (defMessage & #name .~ "Feature 2")
    send NoNextElem

-- Client streaming handler: receive multiple requests, send one response
recordRoute :: IO (NextElem (Proto Point)) -> IO (Proto RouteSummary)
recordRoute recv = do
    points <- NextElem.collect recv
    return $ defMessage
        & #pointCount .~ fromIntegral (length points)
        & #distance   .~ 1000

-- Bidirectional streaming handler
routeChat :: IO (NextElem (Proto RouteNote))
          -> (NextElem (Proto RouteNote) -> IO ()) 
          -> IO ()
routeChat recv send = do
    NextElem.whileNext_ recv $ \note -> do
        -- Echo back with modification
        let reply = note & #message %~ ("Echo: " <>)
        send (NextElem reply)
    send NoNextElem

-- Combine handlers into a server
methods :: Methods IO (ProtobufMethodsOf RouteGuide)
methods =
      Method (mkNonStreaming    getFeature)
    $ Method (mkServerStreaming listFeatures)
    $ Method (mkClientStreaming recordRoute)
    $ Method (mkBiDiStreaming   routeChat)
    $ NoMoreMethods

main :: IO ()
main = runServerWithHandlers def config $ fromMethods methods
  where
    config = ServerConfig {
        serverInsecure = Just (InsecureConfig (Just "0.0.0.0") defaultInsecurePort),
        serverSecure   = Nothing
    }
```

--------------------------------

### Stop All Docker Containers

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Stops all currently running Docker containers, useful for cleaning up after testing.

```bash
$ docker stop $(docker ps -q)
```

--------------------------------

### Low-Level GRPC Server Handlers (Haskell)

Source: https://context7.com/well-typed/grapesy/llms.txt

Implements GRPC server handlers using the low-level API, providing direct access to the `Call` object for fine-grained control over message sending and receiving. This is useful for custom metadata handling and offers more explicit stream management. It requires importing GRPC server modules and protobuf definitions.

```haskell
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Network.GRPC.Server
import Network.GRPC.Server.Protobuf
import Network.GRPC.Server.Run
import Network.GRPC.Server.StreamType (Methods(..), fromMethods)
import Network.GRPC.Common.StreamElem qualified as StreamElem

import Proto.API.RouteGuide

-- Low-level non-streaming handler
getFeature :: Call (Protobuf RouteGuide "getFeature") -> IO ()
getFeature call = do
    point <- recvFinalInput call
    let feature = defMessage & #location .~ point
    sendFinalOutput call (feature, NoMetadata)

-- Low-level server streaming with custom metadata
listFeatures :: Call (Protobuf RouteGuide "listFeatures") -> IO ()
listFeatures call = do
    rect <- recvFinalInput call
    -- Send multiple responses
    sendNextOutput call (defMessage & #name .~ "Feature 1")
    sendNextOutput call (defMessage & #name .~ "Feature 2")
    sendTrailers call NoMetadata

-- Low-level client streaming
recordRoute :: Call (Protobuf RouteGuide "recordRoute") -> IO ()
recordRoute call = do
    (points, NoMetadata) <- StreamElem.collect (recvInput call)
    let summary = defMessage & #pointCount .~ fromIntegral (length points)
    sendFinalOutput call (summary, NoMetadata)

-- Low-level bidirectional streaming
routeChat :: Call (Protobuf RouteGuide "routeChat") -> IO ()
routeChat call = do
    NoMetadata <- StreamElem.whileNext_ (recvInput call) $ \note -> do
        sendNextOutput call (note & #message %~ ("Echo: " <>))
    sendTrailers call NoMetadata

-- Register handlers
methods :: Methods IO (ProtobufMethodsOf RouteGuide)
methods =
      RawMethod (mkRpcHandler getFeature)
    $ RawMethod (mkRpcHandler listFeatures)
    $ RawMethod (mkRpcHandler recordRoute)
    $ RawMethod (mkRpcHandler routeChat)
    $ NoMoreMethods

```

--------------------------------

### Handle Server-Streaming RPC with grapesy Client

Source: https://context7.com/well-typed/grapesy/llms.txt

The `serverStreaming` function in grapesy facilitates RPCs where a single request yields a stream of responses. It takes a `Connection`, RPC details, and a callback function that processes each element received from the server stream.

```haskell
import Network.GRPC.Client
import Network.GRPC.Client.StreamType.IO
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Network.GRPC.Common.NextElem qualified as NextElem

import Proto.API.RouteGuide

type ListFeatures = Protobuf RouteGuide "listFeatures"

-- Server streaming: receive multiple responses for one request
listFeatures :: Connection -> IO ()
listFeatures conn = do
    let lo = defMessage & #latitude .~ 400000000 & #longitude .~ -750000000
        hi = defMessage & #latitude .~ 420000000 & #longitude .~ -730000000
        rect = defMessage & #lo .~ lo & #hi .~ hi

    serverStreaming conn (rpc @ListFeatures) rect $ \recv -> do
        -- Process each feature as it arrives
        NextElem.whileNext_ recv $ \feature -> do
            putStrLn $ "Found feature: " ++ show (feature ^. #name)

```

--------------------------------

### Handle gRPC Errors with grapesy (Haskell)

Source: https://context7.com/well-typed/grapesy/llms.txt

Shows how to implement error handling for gRPC communications using grapesy. This includes catching gRPC-specific exceptions on the client-side and sending gRPC errors from the server-side, along with throwing custom gRPC errors.

```Haskell
import Network.GRPC.Client
import Network.GRPC.Common
import Network.GRPC.Server
import Control.Exception (catch, throwIO)

-- Client: Handle gRPC errors
clientWithErrorHandling :: Connection -> IO ()
clientWithErrorHandling conn = do
    result <- try $ nonStreaming conn (rpc @GetFeature) req
    case result of
        Left (GrpcException status msg _) -> do
            putStrLn $ "gRPC error: " ++ show status
            putStrLn $ "Message: " ++ show msg
        Right feature ->
            print feature
  where
    req = defMessage & #latitude .~ 0 & #longitude .~ 0

-- Server: Send gRPC error
serverWithError :: Call (Protobuf RouteGuide "getFeature") -> IO ()
serverWithError call = do
    point <- recvFinalInput call

    -- Check for invalid input
    if point ^. #latitude == 0 && point ^. #longitude == 0 then
        sendGrpcException call $ GrpcException {
            grpcError         = GrpcInvalidArgument,
            grpcErrorMessage  = Just "Invalid coordinates",
            grpcErrorMetadata = []
        }
    else do
        let feature = defMessage & #location .~ point
        sendFinalOutput call (feature, NoMetadata)

-- Throw gRPC error from handler
handlerWithThrow :: Proto Point -> IO (Proto Feature)
handlerWithThrow point = do
    when (point ^. #latitude < -90000000) $ 
        throwGrpcError GrpcOutOfRange "Latitude out of range"
    return $ defMessage & #location .~ point

```

--------------------------------

### Bidirectional Streaming RPC - Client

Source: https://context7.com/well-typed/grapesy/llms.txt

Handles RPCs where both the client and server send streams of messages simultaneously. Messages can be sent and received independently, allowing for real-time, two-way communication.

```APIDOC
## POST /routeguide.RouteGuide/RouteChat

### Description
Enables a chat-like interaction where the client sends a stream of messages (route notes) and receives a stream of replies from the server. This is suitable for real-time collaboration or chat applications.

### Method
POST

### Endpoint
/routeguide.RouteGuide/RouteChat

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **messages** (array of Proto RouteNote) - Required - A stream of route notes containing messages and location information.

### Request Example
```json
{
  "messages": [
    { "message": "Hello!", "location": { "latitude": 0, "longitude": 0 } },
    { "message": "How are you?", "location": { "latitude": 0, "longitude": 1 } },
    { "message": "Goodbye!", "location": { "latitude": 1, "longitude": 0 } }
  ]
}
```

### Response
#### Success Response (200)
- **note** (Proto RouteNote) - A stream of route notes received from the server, containing replies and potentially location updates.

#### Response Example
```json
{
  "message": "Received your message!",
  "location": { "latitude": 409660403, "longitude": -742006351 }
}
```
```

--------------------------------

### Client Streaming RPC with Grapesy Haskell

Source: https://context7.com/well-typed/grapesy/llms.txt

Handles RPCs where the client sends a stream of messages and receives a single response. It uses `clientStreaming_` from `Network.GRPC.Client` and requires `Network.GRPC.Common.Protobuf` for message serialization. The function takes a connection and a list of points, sending each point and signaling the end of the stream to receive a route summary.

```haskell
import Network.GRPC.Client
import Network.GRPC.Client.StreamType.IO
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Control.Monad (replicateM_)

import Proto.API.RouteGuide

type RecordRoute = Protobuf RouteGuide "recordRoute"

-- Client streaming: send multiple requests, receive one response
recordRoute :: Connection -> [Proto Point] -> IO ()
recordRoute conn points = do
    summary <- clientStreaming_ conn (rpc @RecordRoute) $ \send -> do
        -- Send each point
        forM_ points $ \p -> send (NextElem p)
        -- Signal end of stream
        send NoNextElem

    putStrLn $ "Route summary:"
    putStrLn $ "  Points: " ++ show (summary ^. #pointCount)
    putStrLn $ "  Features: " ++ show (summary ^. #featureCount)
    putStrLn $ "  Distance: " ++ show (summary ^. #distance) ++ " meters"
```

--------------------------------

### Ping Grapesy Server

Source: https://github.com/well-typed/grapesy/blob/main/dev/interop.md

Tests if the Grapesy server is reachable by sending a ping request. This uses the --ping mode of the grapesy-interop executable.

```bash
grapesy$ cabal run grapesy-interop -- --ping
```

--------------------------------

### Client-Side Streaming RPC - Client

Source: https://context7.com/well-typed/grapesy/llms.txt

Handles RPCs where the client sends a stream of messages and receives a single response after all messages are sent. This is useful for operations like uploading a large file or sending a sequence of events.

```APIDOC
## POST /routeguide.RouteGuide/RecordRoute

### Description
Sends a stream of points from the client to the server and receives a route summary in return. The server computes the total distance and elapsed time for the points sent.

### Method
POST

### Endpoint
/routeguide.RouteGuide/RecordRoute

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **points** (array of Proto Point) - Required - A stream of points to be sent to the server.

### Request Example
```json
{
  "points": [
    { "latitude": 409660403, "longitude": -742006351 },
    { "latitude": 409660403, "longitude": -742006351 },
    { "latitude": 409660403, "longitude": -742006351 }
  ]
}
```

### Response
#### Success Response (200)
- **pointCount** (integer) - The total number of points received.
- **featureCount** (integer) - The number of features found along the route.
- **distance** (integer) - The total distance covered in meters.

#### Response Example
```json
{
  "pointCount": 3,
  "featureCount": 1,
  "distance": 1234
}
```
```

--------------------------------

### Bidirectional Streaming RPC with Grapesy Haskell

Source: https://context7.com/well-typed/grapesy/llms.txt

Manages RPCs where both client and server send streams of messages independently. This function utilizes `biDiStreaming` from `Network.GRPC.Client` and `Network.GRPC.Common.NextElem` for stream management. It sends a predefined list of messages and concurrently receives and prints responses from the server.

```haskell
import Network.GRPC.Client
import Network.GRPC.Client.StreamType.IO
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf
import Network.GRPC.Common.NextElem qualified as NextElem

import Proto.API.RouteGuide

type RouteChat = Protobuf RouteGuide "routeChat"

-- Bidirectional streaming: send and receive streams simultaneously
routeChat :: Connection -> IO ()
routeChat conn = do
    biDiStreaming conn (rpc @RouteChat) $ \send recv -> do
        -- Send all messages
        NextElem.forM_ messages send

        -- Receive all responses
        NextElem.whileNext_ recv $ \note ->
            putStrLn $ "Received: " ++ show (note ^. #message)
  where
    messages :: [Proto RouteNote]
    messages = [
        mkNote "Hello!" 0 0,
        mkNote "How are you?" 0 1,
        mkNote "Goodbye!" 1 0
      ]

    mkNote :: Text -> Int32 -> Int32 -> Proto RouteNote
    mkNote msg lat lon = defMessage
        & #message  .~ msg
        & #location .~ (defMessage & #latitude .~ lat & #longitude .~ lon)
```

--------------------------------

### Perform Unary RPC Calls with grapesy Client

Source: https://context7.com/well-typed/grapesy/llms.txt

The `nonStreaming` function in grapesy is used for making unary RPC calls, which involve a single request and a single response. This function requires a `Connection` object and the RPC method details, typically defined using `Protobuf`.

```haskell
import Network.GRPC.Client
import Network.GRPC.Client.StreamType.IO
import Network.GRPC.Common
import Network.GRPC.Common.Protobuf

import Proto.API.Helloworld

-- Simple unary RPC call
sayHello :: Connection -> IO ()
sayHello conn = do
    let req = defMessage & #name .~ "World"
    resp <- nonStreaming conn (rpc @(Protobuf Greeter "sayHello")) req
    putStrLn $ "Response: " ++ show (resp ^. #message)
    -- Output: Response: "Hello, World"

-- Unary RPC with type alias for cleaner code
type GetFeature = Protobuf RouteGuide "getFeature"

getFeature :: Connection -> IO ()
getFeature conn = do
    let point = defMessage
                  & #latitude  .~  409146138
                  & #longitude .~ -746188906
    feature <- nonStreaming conn (rpc @GetFeature) point
    print feature

```
Tokens:
Raw