Wait-for-Ready

Overview

This is a feature which can be used on a stub which will cause the RPCs to wait for the server to become available before sending the request. This allows for robust batch workflows since transient server problems won’t cause failures. The deadline still applies, so the wait will be interrupted if the deadline is passed.

When an RPC is created when the channel has failed to connect to the server, without Wait-for-Ready it will immediately return a failure; with Wait-for-Ready it will simply be queued until the connection becomes ready. The default is without Wait-for-Ready.

For detailed semantics see this.

How to use Wait-for-Ready

You can specify for a stub whether or not it should use Wait-for-Ready, which will automatically be passed along when an RPC is created.

The following shows the sequence of events that occur, when a client sends a message to a server, based upon channel state and whether or not Wait-for-Ready is set.

sequenceDiagram
participant A as Application
participant RPC
participant CH as Channel
participant S as Server 
A->>RPC: Create RPC using stub
RPC->>CH: Initiate Communication
alt channel state: READY
  CH->>S: Send message
else Channel state: IDLE or CONNECTING
  CH-->>CH: Wait for state change
else Channel state: TRANSIENT_FAILURE
  alt with Wait-for-Ready
    CH-->>CH: Wait for channel<br>becoming READY<br>(or a permanent failure)
    CH->>S: Send message
  else without Wait-for-Ready
    CH->>A: Failure
  end
else Channel state is a Permanent Failure
    CH->>A: Failure
end

The following is a state based view

stateDiagram-v2
   state "Initiating Communication" as IC
   state "Channel State" as CS
   IC-->CS: Check Channel State
   state CS {
      state "Permanent Failure" as PF
      state "TRANSIENT_FAILURE" as TF
      IDLE --> CONNECTING
      CONNECTING --> READY
      READY-->[*]
      CONNECTING-->TF
      CONNECTING-->PF
      TF-->READY
      TF -->[*]: without\n wait-for-ready
      TF-->PF
      PF-->[*]
   }
  state "MSG sent" as MS
  state "RPC Failed" as RF
  CS-->WAIT:From IDLE /\nCONNECTING
  CS-->WAIT:From Transient\nFailure with\nWait-for-Ready
  WAIT-->CS:State Change 
  CS-->MS: From READY
  CS-->RF: From Permanent failure or\nTransient Failure without\nWait-for-Ready
  MS-->[*]
  RF-->[*]

Alternatives

• Loop (with exponential backoff) until the RPC stops returning transient failures.
  • This could be combined, for efficiency, with implementing an onReady Handler (for languages that support this).
• Accept failures that might have been avoided by waiting because you want to fail fast

Language Support