gRPC Connectivity Semantics and API =================================== This document describes the connectivity semantics for gRPC channels and the corresponding impact on RPCs. We then discuss an API. States of Connectivity ---------------------- gRPC Channels provide the abstraction over which clients can communicate with servers.The client-side channel object can be constructed using little more than a DNS name. Channels encapsulate a range of functionality including name resolution, establishing a TCP connection (with retries and backoff) and TLS handshakes. Channels can also handle errors on established connections and reconnect, or in the case of HTTP/2 GO_AWAY, re-resolve the name and reconnect. To hide the details of all this activity from the user of the gRPC API (i.e., application code) while exposing meaningful information about the state of a channel, we use a state machine with four states, defined below: CONNECTING: The channel is trying to establish a connection and is waiting to make progress on one of the steps involved in name resolution, TCP connection establishment or TLS handshake. This is the initial state for all channels upon creation. READY: The channel has successfully established a connection all the way through TLS handshake (or equivalent) and all subsequent attempt to communicate have succeeded (or are pending without any known failure ). TRANSIENT_FAILURE: There has been some transient failure (such as a TCP 3-way handshake timing out or a socket error). Channels in this state will eventually switch to the CONNECTING state and try to establish a connection again. Since retries are done with exponential backoff, channels that fail to connect will start out spending very little time in this state but as the attempts fail repeatedly, the channel will spend increasingly large amounts of time in this state. For many non-fatal failures (e.g., TCP connection attempts timing out because the server is not yet available), the channel may be stuck in this state for an indefinitely large amount of time. FATAL_FAILURE: There has been a fatal failure and the channel will never attempt to establish a connection again. (e.g., a server presenting an invalid TLS certificate) Channels that enter this state never leave this state. The following table lists the legal transitions from one state to another and corresponding reasons. Empty cells denote disallowed transitions.
From/To | CONNECTING | READY | TRANSIENT_FAILURE | FATAL_FAILURE |
---|---|---|---|---|
CONNECTING | Incremental progress during connection establishment | All steps needed to establish a connection succeeded | Any failure in any of the steps needed to establish connection | Fatal failure encountered while attempting a connection. |
READY | Incremental successful communication on established channel. | Any failure encountered while expecting successful communication on established channel. | ||
TRANSIENT_FAILURE | Wait time required to implement (exponential) backoff is over. | |||
FATAL_FAILURE |