TsgcGRPCClient

TsgcGRPCClient implements a gRPC client over HTTP/2 (using TsgcHTTP2Client as transport) and supports the four gRPC RPC patterns.

Introduction

TsgcGRPCClient implements a gRPC client that runs over HTTP/2. Follow the steps below to configure this component:

1. Assign a TsgcHTTP2Client instance to the Client property; this component is used as the HTTP/2 transport. Set the Host, Port and TLS of the transport to point to the gRPC server.

2. Handle the responses using the OnGRPCResponse event, then connect and call a unary method. example:


    oHTTP2 := TsgcHTTP2Client.Create(nil);
    oHTTP2.Host := 'grpc.example.com';
    oHTTP2.Port := 443;
    oHTTP2.TLS := True;

    oGRPC := TsgcGRPCClient.Create(nil);
    oGRPC.Client := oHTTP2;
    oGRPC.OnGRPCResponse := OnGRPCResponseEvent;
    oGRPC.CallAsync('helloworld.Greeter', 'SayHello', vRequestBytes);

    procedure OnGRPCResponseEvent(Sender: TObject; const aResponse: TsgcGRPCResponse);
    begin
      if aResponse.StatusCode = grpcOK then
        ShowMessage(aResponse.DataString);
    end;

RPC Patterns

gRPC defines four RPC patterns. TsgcGRPCClient exposes a set of members for each one:

Unary: use Call for a synchronous call that returns a TsgcGRPCResponse, or CallAsync to receive the response asynchronously through the OnGRPCResponse event.
Server streaming: use ServerStreamingCall; each message sent by the server arrives in OnGRPCStreamMessage and the stream completes in OnGRPCStreamEnd.
Client streaming: use OpenClientStream, then SendStreamMessage for one or more messages, and finish with CloseClientStream or CloseClientStreamAsync.
Bidirectional streaming: use OpenBidiStream, send messages with SendBidiMessage and finish with CloseBidiStream; incoming messages arrive in OnGRPCStreamMessage.

The following example performs a server-streaming call and reads every message delivered by the server:


    oGRPC.OnGRPCStreamMessage := OnGRPCStreamMessageEvent;
    oGRPC.ServerStreamingCall('routeguide.RouteGuide', 'ListFeatures', vRequestBytes);

    procedure OnGRPCStreamMessageEvent(Sender: TObject; const aMessage: TsgcGRPCStreamMessage);
    begin
      ShowMessage(aMessage.DataString);
    end;

Features

Channel Options

The ChannelOptions property configures channel-level behaviour such as message Compression, the ContentType, the maximum send and receive message sizes and HTTP/2 keep-alive pings.

Metadata

Use DefaultMetadata to attach custom headers to every call, or pass per-call metadata to any of the call methods. This is how authorization headers such as a Bearer token are sent to the server.

Deadlines and Retry

Each call accepts a deadline so it fails fast when the server is slow. The RetryPolicy controls automatic retries: MaxAttempts, exponential backoff and the set of retryable status codes.

Load Balancing

TsgcGRPCLoadBalancer distributes calls across several backends using a Pick First or Round Robin policy, and resolves backend addresses through a DNS name resolver.

Health Checking

TsgcGRPCHealthClient implements the standard grpc.health.v1.Health service, with Check for a one-shot status query and Watch to receive health-status changes as a stream.

Server Reflection

TsgcGRPCReflectionClient uses the gRPC Server Reflection service to list the services exposed by a server and to fetch their file descriptors at runtime.

Interceptors

Interceptors can be chained through the Interceptors property. The library includes TsgcGRPCLoggingInterceptor, TsgcGRPCTimeoutInterceptor and TsgcGRPCMetadataInterceptor.

Telemetry

The MetricsCollector exposes per-method telemetry, including call counts, success rate and latency, useful for monitoring and diagnostics.

Protocol Buffers

gRPC requests and responses are Protocol Buffers (protobuf) encoded. The library includes TsgcProtobufWriter and TsgcProtobufMessage to build and parse messages by field number. The Google Cloud interfaces provide typed request and response classes, so you do not need to encode protobuf by hand when calling those services.

Reference

Properties

Name	Description
Client	The TsgcHTTP2Client instance used as the HTTP/2 transport for all gRPC calls.
ChannelOptions	Channel-level options: compression, content-type, maximum message sizes and HTTP/2 keep-alive.
DefaultMetadata	Metadata (custom headers) added to every call, such as an authorization Bearer token.
Interceptors	Chain of interceptors applied to every call (logging, timeout, metadata).
RetryPolicy	Automatic retry configuration: maximum attempts, exponential backoff and retryable status codes.
ServiceConfig	Per-service configuration, including method defaults, retry settings and load-balancing policy.
MetricsCollector	Collects per-method telemetry: call counts, success rate and latency.

Methods

Name	Description
Call	Performs a synchronous unary call and returns the TsgcGRPCResponse.
CallAsync	Performs an asynchronous unary call; the response is delivered through the OnGRPCResponse event.
ServerStreamingCall	Starts a server-streaming call; each server message arrives in OnGRPCStreamMessage.
OpenClientStream	Opens a client-streaming call so the client can send a sequence of messages.
SendStreamMessage	Sends one message on an open client stream.
CloseClientStream	Closes a client stream synchronously and returns the server response.
CloseClientStreamAsync	Closes a client stream asynchronously; the response arrives through OnGRPCResponse.
OpenBidiStream	Opens a bidirectional streaming call where both sides exchange messages.
SendBidiMessage	Sends one message on an open bidirectional stream.
CloseBidiStream	Closes a bidirectional stream and signals end-of-stream to the server.
CancelCall	Cancels an active call or stream before it completes.
CallString	Unary helper that sends a request and returns the response as a string.

Events

Name	Description
OnGRPCConnect	Raised when the underlying HTTP/2 connection to the gRPC server is established.
OnGRPCDisconnect	Raised when the connection to the gRPC server is closed.
OnGRPCResponse	Raised when a unary call completes, delivering the TsgcGRPCResponse.
OnGRPCStreamMessage	Raised for every message received on a server-streaming or bidirectional stream.
OnGRPCStreamEnd	Raised when a stream completes, carrying the final gRPC status.
OnGRPCError	Raised when a call finishes with a non-OK gRPC status code.
OnGRPCException	Raised when an exception occurs while processing a call.
OnGRPCBeforeRequest	Raised before a request is sent, allowing the headers and metadata to be inspected or modified.