HTTP/2-based gRPC client (h2c cleartext, or TLS with ALPN "h2"). More...

#include <cwist/net/grpc/grpc.h>

Include dependency graph for grpc_client.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	cwist_grpc_client_options

Typedefs
typedef struct cwist_grpc_client	cwist_grpc_client

typedef struct cwist_grpc_call	cwist_grpc_call

typedef struct cwist_grpc_client_options	cwist_grpc_client_options

Functions
cwist_grpc_client *	cwist_grpc_client_connect (const char host, uint16_t port, const cwist_grpc_client_options options)
	Connect to a gRPC server and complete the HTTP/2 handshake.

void	cwist_grpc_client_close (cwist_grpc_client *client)
	Close the client: send GOAWAY, tear down TLS and the socket, free all state.

cwist_grpc_call *	cwist_grpc_call_start (cwist_grpc_client client, const char method, const void *request, size_t request_len, uint64_t timeout_ms)
	Start a unary call (no previous-attempt marker).

cwist_grpc_call *	cwist_grpc_call_start_ex (cwist_grpc_client client, const char method, const void *request, size_t request_len, uint64_t timeout_ms, uint32_t previous_attempts)
	Start a unary call, with a gRFC A6 retry-attempt marker.

int	cwist_grpc_call_await_headers (cwist_grpc_call *call)
	Block until response headers arrive or the stream ends.

int	cwist_grpc_call_committed (const cwist_grpc_call *call)
	Whether response headers have committed the RPC (gRFC A6).

int	cwist_grpc_call_refused (const cwist_grpc_call *call)
	Whether the call failed before commit in a retryable way (gRFC A6 case 3: REFUSED_STREAM before headers, or GOAWAY below our stream id).

int	cwist_grpc_call_retry_pushback_ms (const cwist_grpc_call call, int32_t out_ms)
	Report the server-provided retry pushback delay, if any.

int	cwist_grpc_client_dead (cwist_grpc_client *client)
	Whether the client connection is unusable.

cwist_grpc_status_t	cwist_grpc_call_status (const cwist_grpc_call *call)
	Current gRPC status code of a call.

int	cwist_grpc_call_recv (cwist_grpc_call call, cwist_grpc_message out)
	Receive the next response message of a call.

cwist_grpc_status_t	cwist_grpc_call_finish (cwist_grpc_call call, const char *message)
	Drain the call to completion and return its final status.

void	cwist_grpc_call_cancel (cwist_grpc_call *call)
	Cancel a call: send RST_STREAM(CANCEL), mark it failed with CWIST_GRPC_CANCELLED, and end its stream.

void	cwist_grpc_call_destroy (cwist_grpc_call *call)
	Destroy a call: cancel it if still open, release it as the client's active call, and free all queued and buffered state.

Detailed Description

HTTP/2-based gRPC client (h2c cleartext, or TLS with ALPN "h2").

One active call per connection: cwist_grpc_call_start() fails while another call on the same client is still open. Payloads are opaque serialized protobuf messages; the 5-byte gRPC framing is applied here.

Definition in file grpc_client.h.

Typedef Documentation

◆ cwist_grpc_call

typedef struct cwist_grpc_call cwist_grpc_call

Definition at line 20 of file grpc_client.h.

◆ cwist_grpc_client

typedef struct cwist_grpc_client cwist_grpc_client

Definition at line 19 of file grpc_client.h.

◆ cwist_grpc_client_options

typedef struct cwist_grpc_client_options cwist_grpc_client_options

Function Documentation

◆ cwist_grpc_call_await_headers()

int cwist_grpc_call_await_headers ( cwist_grpc_call * call )

Block until response headers arrive or the stream ends.

Pump until the call's response headers arrive or the stream ends. Returns 0 when Response-Headers were received (the call is committed, gRFC A6), 1 when the stream ended first (status available via cwist_grpc_call_finish), -1 on bad arguments. Queued messages stay buffered for cwist_grpc_call_recv().

Parameters

call The call.

Return values

0	Response headers received (the RPC is committed).
1	The stream ended before any response headers (retryable).
-1	Invalid call, error, or deadline.

Definition at line 1228 of file grpc_client.c.

Referenced by cwist_grpc_channel_call_start().

◆ cwist_grpc_call_cancel()

void cwist_grpc_call_cancel ( cwist_grpc_call * call )

Cancel a call: send RST_STREAM(CANCEL), mark it failed with CWIST_GRPC_CANCELLED, and end its stream.

Abort the call: sends RST_STREAM(CANCEL) unless the stream already ended.

Parameters

call	The call; NULL or an already-ended call is a no-op.

Definition at line 1308 of file grpc_client.c.

References cap, CWIST_GRPC_CANCELLED, and H2_FRAME_RST_STREAM.

Referenced by cwist_grpc_call_destroy(), and cwist_grpc_channel_call_cancel().

◆ cwist_grpc_call_committed()

int cwist_grpc_call_committed ( const cwist_grpc_call * call )

Whether response headers have committed the RPC (gRFC A6).

Non-zero once Response-Headers arrived: the RPC is committed (gRFC A6).

Returns: Nonzero if committed; 0 for a NULL call or not yet committed.

Definition at line 1241 of file grpc_client.c.

◆ cwist_grpc_call_destroy()

void cwist_grpc_call_destroy ( cwist_grpc_call * call )

Destroy a call: cancel it if still open, release it as the client's active call, and free all queued and buffered state.

Parameters

call	The call; NULL is a no-op.

Definition at line 1323 of file grpc_client.c.

References cap, cwist_free(), cwist_grpc_call_cancel(), and cwist_grpc_decoder_destroy().

Referenced by cwist_grpc_channel_call_destroy(), cwist_grpc_channel_call_start(), and cwist_grpc_client_close().

◆ cwist_grpc_call_finish()

cwist_grpc_status_t cwist_grpc_call_finish	(	cwist_grpc_call *	call,
		const char **	message
	)

Drain the call to completion and return its final status.

Finish the call: waits for the server trailers when they have not arrived yet, and returns the grpc-status code. message receives the grpc-message trailer value (valid until cwist_grpc_call_destroy), or NULL.

Parameters

call	The call.
message	When non-NULL, set to the status message text; the pointer is owned by the call and stays valid until cwist_grpc_call_destroy.

Returns: The final gRPC status code; CWIST_GRPC_INTERNAL for a NULL call.

Definition at line 1291 of file grpc_client.c.

References cap, and CWIST_GRPC_INTERNAL.

Referenced by cwist_grpc_channel_call_finish().

◆ cwist_grpc_call_recv()

int cwist_grpc_call_recv	(	cwist_grpc_call *	call,
		cwist_grpc_message *	out
	)

Receive the next response message of a call.

Receive the next response message. Returns 1 and fills out when a message arrived, 0 when the stream ended, -1 on transport/protocol error. out->data is owned by the call and stays valid until the next recv or cwist_grpc_call_destroy().

Parameters

call	The call.
out	Filled with the next message; out->data is owned by the call and stays valid until the next recv or cwist_grpc_call_destroy.

Return values

1	A message was returned.
0	The stream ended cleanly and no more messages will arrive.
-1	The call failed (see cwist_grpc_call_status).

Definition at line 1203 of file grpc_client.c.

References cap, cwist_grpc_message::compressed, cwist_free(), cwist_grpc_message::data, and cwist_grpc_message::len.

Referenced by cwist_grpc_channel_call_recv().

◆ cwist_grpc_call_refused()

int cwist_grpc_call_refused ( const cwist_grpc_call * call )

Whether the call failed before commit in a retryable way (gRFC A6 case 3: REFUSED_STREAM before headers, or GOAWAY below our stream id).

Non-zero when the RPC provably never reached server application logic (RST_STREAM REFUSED_STREAM, or GOAWAY with a last-stream-id below this stream): gRFC A6 transparent-retry case 3.

Returns: Nonzero if retryable; 0 otherwise (NULL, committed, or trailers seen).

Definition at line 1250 of file grpc_client.c.

Referenced by cwist_grpc_channel_call_start().

◆ cwist_grpc_call_retry_pushback_ms()

int cwist_grpc_call_retry_pushback_ms	(	const cwist_grpc_call *	call,
		int32_t *	out_ms
	)

Report the server-provided retry pushback delay, if any.

gRFC A6 server pushback. Returns 1 and fills out_ms when the server sent "grpc-retry-pushback-ms"; a negative value asks the client not to retry. Returns 0 when the trailer was absent.

Parameters

call	The call.
out_ms	Set to the pushback delay in ms (negative = do not retry) when present.

Returns: Nonzero if the grpc-retry-pushback-ms trailer arrived; 0 otherwise.

Definition at line 1261 of file grpc_client.c.

References cap.

Referenced by cwist_grpc_channel_call_start().

◆ cwist_grpc_call_start()

cwist_grpc_call * cwist_grpc_call_start	(	cwist_grpc_client *	c,
		const char *	method,
		const void *	request,
		size_t	request_len,
		uint64_t	timeout_ms
	)

Start a unary call (no previous-attempt marker).

Start a call to a full method path ("/package.Service/Method"). request is one serialized protobuf message (may be NULL/0); it is framed and sent with END_STREAM, so the call covers unary and server-streaming methods. timeout_ms maps to the grpc-timeout header and is also enforced locally: on expiry the stream is reset and the call ends with CWIST_GRPC_DEADLINE_EXCEEDED. Returns NULL on failure (including when another call on this client is still active).

Parameters

c	Client; must be connected and have no active call.
method	gRPC method path (e.g. "/pkg.Service/Method").
request	Request message bytes; may be NULL when request_len is 0.
request_len	Request length in bytes.
timeout_ms	Per-call deadline in ms; 0 means no deadline.

Returns: The started call, or NULL on invalid arguments, a busy/dead client, or a transport error while sending.

See also: cwist_grpc_call_start_ex

Definition at line 1094 of file grpc_client.c.

References cap, and cwist_grpc_call_start_ex().

◆ cwist_grpc_call_start_ex()

cwist_grpc_call * cwist_grpc_call_start_ex	(	cwist_grpc_client *	c,
		const char *	method,
		const void *	request,
		size_t	request_len,
		uint64_t	timeout_ms,
		uint32_t	previous_attempts
	)

Start a unary call, with a gRFC A6 retry-attempt marker.

cwist_grpc_call_start() variant that attaches the standard "grpc-previous-rpc-attempts" header (gRFC A6) when previous_attempts is non-zero. Used by the channel retry engine; plain callers want cwist_grpc_call_start().

Sends HEADERS (:method POST, :scheme, :path, :authority, content-type, te) followed by the framed request message, then commits the call as the client's active call. Serialized by the client mutex: one active call per connection.

Parameters

previous_attempts Value for grpc-previous-rpc-attempts; 0 omits the header.

Returns: The started call, or NULL on invalid arguments, a busy/dead client, or a transport error while sending (state is cleaned up).

Definition at line 1112 of file grpc_client.c.

References cap, cwist_alloc(), cwist_free(), cwist_grpc_decoder_destroy(), cwist_grpc_decoder_init(), cwist_grpc_encode_message(), CWIST_GRPC_OK, H2_FLAG_END_HEADERS, and H2_FRAME_HEADERS.

Referenced by cwist_grpc_call_start(), and cwist_grpc_channel_call_start().

◆ cwist_grpc_call_status()

cwist_grpc_status_t cwist_grpc_call_status ( const cwist_grpc_call * call )

Current gRPC status code of a call.

Last known grpc-status without pumping (CWIST_GRPC_OK until trailers).

Parameters

call The call.

Returns: The status code; CWIST_GRPC_INTERNAL for a NULL call.

Definition at line 1280 of file grpc_client.c.

References CWIST_GRPC_INTERNAL.

Referenced by cwist_grpc_channel_call_destroy(), and cwist_grpc_channel_call_start().

◆ cwist_grpc_client_close()

void cwist_grpc_client_close ( cwist_grpc_client * c )

Close the client: send GOAWAY, tear down TLS and the socket, free all state.

Parameters

c	Client to close; NULL is a no-op.

Definition at line 701 of file grpc_client.c.

References cap, cwist_free(), cwist_grpc_call_destroy(), H2_FRAME_GOAWAY, SSL_CTX_free, SSL_free, and SSL_shutdown.

Referenced by cwist_grpc_channel_close(), and cwist_grpc_client_connect().

◆ cwist_grpc_client_connect()

cwist_grpc_client * cwist_grpc_client_connect	(	const char *	host,
		uint16_t	port,
		const cwist_grpc_client_options *	options
	)

Connect to a gRPC server and complete the HTTP/2 handshake.

Connect to host:port and perform the HTTP/2 handshake (client preface, SETTINGS exchange). Returns NULL on failure.

Parameters

host	Server hostname or address.
port	TCP port number.
options	Optional TLS/timeout/authority options; NULL for defaults (no TLS, 10 s connect timeout, authority "host:port").

Returns: Connected client on success; NULL on any failure (partially built state is cleaned up before returning).

Note: Performs TCP connect, optional TLS with ALPN "h2", sends the client preface and SETTINGS, and waits for the server SETTINGS and the ACK of our own SETTINGS.

Definition at line 624 of file grpc_client.c.

References cwist_grpc_client_options::authority, cap, cwist_grpc_client_options::connect_timeout_ms, cwist_alloc(), cwist_free(), cwist_grpc_client_close(), GRPC_CLIENT_DEFAULT_WINDOW, GRPC_CLIENT_HEADER_TABLE, H2_FLAG_ACK, H2_FRAME_GOAWAY, H2_FRAME_PING, H2_FRAME_SETTINGS, cwist_grpc_client_options::tls_server_name, cwist_grpc_client_options::use_tls, and cwist_grpc_client_options::verify_peer.

◆ cwist_grpc_client_dead()

int cwist_grpc_client_dead ( cwist_grpc_client * c )

Whether the client connection is unusable.

Non-zero when the connection can no longer start calls (dead or GOAWAY).

Returns: Nonzero if the client is NULL, the transport died, or GOAWAY arrived.

Definition at line 1271 of file grpc_client.c.

References cap.

Referenced by cwist_grpc_channel_get_state().

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cwist_grpc_call

◆ cwist_grpc_client

◆ cwist_grpc_client_options

Function Documentation

◆ cwist_grpc_call_await_headers()

◆ cwist_grpc_call_cancel()

◆ cwist_grpc_call_committed()

◆ cwist_grpc_call_destroy()

◆ cwist_grpc_call_finish()

◆ cwist_grpc_call_recv()

◆ cwist_grpc_call_refused()

◆ cwist_grpc_call_retry_pushback_ms()

◆ cwist_grpc_call_start()

◆ cwist_grpc_call_start_ex()

◆ cwist_grpc_call_status()

◆ cwist_grpc_client_close()

◆ cwist_grpc_client_connect()

◆ cwist_grpc_client_dead()