gRPC Client

1: gRPC BasicAuth
2: gRPC KeepAlive
3: gRPC Resilience

GRPC Clients

In order to talk to a - not in process - factstore (which is the usual setup for non-test applications), GRPC is the communication protocol used.

Using FactCast client in Spring boot via GRPC

If you use Spring take the easy path in your Spring Boot Application by adding the appropriate dependencies to your application:

   <dependency>
     <groupId>org.factcast</groupId>
     <artifactId>factcast-client-grpc</artifactId>
   </dependency>
   <dependency>
     <groupId>org.factcast</groupId>
     <artifactId>factcast-spring-boot-autoconfigure</artifactId>
   </dependency>

There are example projects: factcast-examples/factcast-example-client-spring-boot2 and factcast-examples/factcast-example-client-spring-boot1 respectively, that you can use as a template.

Note that factcast-client-grpc is built on top of (https://github.com/yidongnan/grpc-spring-boot-starter). If you are looking for the basic configuration properties, that is where you can find the latest version.

At the time of writing, the most relevant are:

Name	Example Value	required
grpc.client.factstore.address	static://localhost:9090	yes
grpc.client.factstore.negotiationType	PLAINTEXT	no
grpc.client.factstore.enable-keep-alive	true	no

1 - gRPC BasicAuth

Using BasicAuth from a client

From a client’s perspective, all you need to do is to provide credentials. Once the credentials are configured, they are used on every request in a Basic-Auth fashion (added header to request).

In order to define credentials, just set the appropriate property to a value of the format ‘username:password’, just as you would type them into your browser when a basic-auth popup appears.

# if this property is set with a value of the format 'username:password', basicauth will be used.
grpc.client.factstore.credentials=myUserName:mySecretPassword

You can always use environment variables or a -D switch in order to inject the credentials.

see module examples/factcast-example-client-basicauth for an example

2 - gRPC KeepAlive

keep-alive settings

Here are some good settings for an initial configuration of a SpringBoot FactCast client/server setup in case you ran into gRPC related client server communication troubles.

Sending keep-alive HTTP/2 PINGs on the connection is useful in case you are running on infrastructure that doesn’t support configurable idle timeouts, and therefore closes connections.
The proposed values are defining a scenario where the client sends keep-alive HTTP/2 PINGs every 300s and the server accepts this behavior without sending GO_AWAY ENHANCE_YOUR_CALM to the client. Please adapt to your specific needs.

Client side

Property	Description	Recommended	Default
`grpc.client.factstore.enable-keep-alive`	Configures whether keepAlive should be enabled.	true	false
`grpc.client.factstore.keep-alive-time`	The default delay before sending keepAlives. Please note that shorter intervals increase the network burden for the server.	300	60
`grpc.client.factstore.keep-alive-without-calls`	Configures whether keepAlive will be performed when there are no outstanding RPCs on a connection.	true	false

Further details can be found here : net.devh.boot.grpc.client.config.GrpcChannelProperties.

Server side

Property	Description	Recommended	Default
`grpc.server.permit-keep-alive-without-calls`	Configures whether clients are allowed to send keep-alive HTTP/2 PINGs even if there are no outstanding RPCs on the connection.	true	false
`grpc.server.permit-keep-alive-time`	Specifies the most aggressive keep-alive time in seconds clients are permitted to configure.	100	300

Further details can be found here : net.devh.boot.grpc.server.config.GrpcServerProperties.

3 - gRPC Resilience

Resilience approach

In order to make it easier for clients to deal with errors, we try to mitigate connection or network errors, or RetryableExceptions in general by just retrying. There are two types of gRPC communications within the FactCast gRPC API:

synchronous, request / response
asynchronous, request / streaming response

While the first can be mitigated easily by retrying the call, things get more complicated in an asynchronous, streaming scenario. Imagine a subscription to particular facts (let’s say 10) from scratch, where after 5 successfully received facts the network connection fails. Now simply retrying would mean to receive those 5 facts again, which is not only wasteful, but also hard to handle, as you’d need to skip those rather than process them a second time. Here the FactCast gRPC client keeps track of the facts successfully processed and resubscribes to the ones missing. In this example, it’ll try to subscribe to the same factstream but starting after the fifth fact.

Resilience is supposed to “just work” and let you deal with just the non-transient errors. This is why it is enabled by default with sane defaults.

If you want to disable it completely for any reason, you always can use

factcast.grpc.client.resilience.enabled=false

See properties for the defaults.