Package com.google.cloud.grpc

Class GcpMultiEndpointChannel

java.lang.Object
io.grpc.Channel
io.grpc.ManagedChannel
com.google.cloud.grpc.GcpMultiEndpointChannel
public class GcpMultiEndpointChannel extends io.grpc.ManagedChannel
The purpose of GcpMultiEndpointChannel is twofold:
  1. Fallback to an alternative endpoint (host:port) of a gRPC service when the original endpoint is completely unavailable.
  2. Be able to route an RPC call to a specific group of endpoints.

A group of endpoints is called a MultiEndpoint and is essentially a list of endpoints where priority is defined by the position in the list with the first endpoint having top priority. A MultiEndpoint tracks endpoints' availability. When a MultiEndpoint is picked for an RPC call, it picks the top priority endpoint that is currently available. More information on the MultiEndpoint class.

GcpMultiEndpointChannel can have one or more MultiEndpoint identified by its name -- arbitrary string provided in the GcpMultiEndpointOptions when configuring MultiEndpoints. This name can be used to route an RPC call to this MultiEndpoint by setting the ME_KEY key value of the RPC CallOptions.

GcpMultiEndpointChannel receives a list of GcpMultiEndpointOptions for initial configuration. An updated configuration can be provided at any time later using setMultiEndpoints(List). The first item in the GcpMultiEndpointOptions list defines the default MultiEndpoint that will be used when no MultiEndpoint name is provided with an RPC call.

Example:

Let's assume we have a service with read and write operations and the following backends:

  • service.example.com -- the main set of backends supporting all operations
  • service-fallback.example.com -- read-write replica supporting all operations
  • ro-service.example.com -- read-only replica supporting only read operations

Example configuration:

  • MultiEndpoint named "default" with endpoints:
    1. service.example.com:443
    2. service-fallback.example.com:443
  • MultiEndpoint named "read" with endpoints:
    1. ro-service.example.com:443
    2. service-fallback.example.com:443
    3. service.example.com:443

With the configuration above GcpMultiEndpointChannel will use the "default" MultiEndpoint by default. It means that RPC calls by default will use the main endpoint and if it is not available then the read-write replica.

To offload some read calls to the read-only replica we can specify "read" MultiEndpoint in the CallOptions. Then these calls will use the read-only replica endpoint and if it is not available then the read-write replica and if it is also not available then the main endpoint.

GcpMultiEndpointChannel creates a GcpManagedChannel channel pool for every unique endpoint. For the example above three channel pools will be created.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final io.grpc.Context.Key<String>
    ME_CONTEXT_KEY
     
    static final io.grpc.CallOptions.Key<String>
    ME_KEY
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    GcpMultiEndpointChannel(List<GcpMultiEndpointOptions> meOptions, ApiConfig apiConfig, GcpManagedChannelOptions gcpManagedChannelOptions)
    Constructor for GcpMultiEndpointChannel.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    authority()
    The authority of the current endpoint of the default MultiEndpoint.
    String
    authorityFor(String multiEndpointName)
    The authority of the current endpoint of the specified MultiEndpoint.
    boolean
    awaitTermination(long timeout, TimeUnit unit)
    Waits for the channel to become terminated, giving up if the timeout is reached.
    boolean
    isShutdown()
    Returns whether the channel is shutdown.
    boolean
    isTerminated()
    Returns whether the channel is terminated.
    <RequestT, ResponseT>
    io.grpc.ClientCall<RequestT,ResponseT>
    newCall(io.grpc.MethodDescriptor<RequestT,ResponseT> methodDescriptor, io.grpc.CallOptions callOptions)
    Check the value of ME_KEY key in the CallOptions and if found use the MultiEndpoint with the same name for this call.
    void
    setMultiEndpoints(List<GcpMultiEndpointOptions> meOptions)
    Update the list of MultiEndpoint configurations.
    io.grpc.ManagedChannel
    shutdown()
    Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.
    io.grpc.ManagedChannel
    shutdownNow()
    Initiates a forceful shutdown in which preexisting and new calls are cancelled.

    Methods inherited from class io.grpc.ManagedChannel

    enterIdle, getState, notifyWhenStateChanged, resetConnectBackoff

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • ME_KEY

      public static final io.grpc.CallOptions.Key<String> ME_KEY

    • ME_CONTEXT_KEY

      public static final io.grpc.Context.Key<String> ME_CONTEXT_KEY

  • Constructor Details

  • Method Details

    • setMultiEndpoints

      public void setMultiEndpoints(List<GcpMultiEndpointOptions> meOptions)
      Update the list of MultiEndpoint configurations.

      MultiEndpoints are matched with the current ones by name.

      • If a current MultiEndpoint is missing in the updated list, the MultiEndpoint will be removed.
      • A new MultiEndpoint will be created for every new name in the list.
      • For an existing MultiEndpoint only its endpoints will be updated (no recovery timeout change).

      Endpoints are matched by the endpoint address (usually in the form of address:port).

      • If an existing endpoint is not used by any MultiEndpoint in the updated list, then the channel poll for this endpoint will be shutdown.
      • A channel pool will be created for every new endpoint.
      • For an existing endpoint nothing will change (the channel pool will not be re-created, thus no channel credentials change, nor channel configurator change).

    • shutdown

      @CanIgnoreReturnValue public io.grpc.ManagedChannel shutdown()
      Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.
      Specified by:
      shutdown in class io.grpc.ManagedChannel
      Returns:
      this
      Since:
      1.0.0

    • isShutdown

      public boolean isShutdown()
      Returns whether the channel is shutdown. Shutdown channels immediately cancel any new calls, but may still have some calls being processed.
      Specified by:
      isShutdown in class io.grpc.ManagedChannel
      Since:
      1.0.0
      See Also:

    • isTerminated

      public boolean isTerminated()
      Returns whether the channel is terminated. Terminated channels have no running calls and relevant resources released (like TCP connections).
      Specified by:
      isTerminated in class io.grpc.ManagedChannel
      Since:
      1.0.0
      See Also:

    • shutdownNow

      @CanIgnoreReturnValue public io.grpc.ManagedChannel shutdownNow()
      Initiates a forceful shutdown in which preexisting and new calls are cancelled. Although forceful, the shutdown process is still not instantaneous; isTerminated() will likely return false immediately after this method returns.
      Specified by:
      shutdownNow in class io.grpc.ManagedChannel
      Returns:
      this
      Since:
      1.0.0

    • awaitTermination

      public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException
      Waits for the channel to become terminated, giving up if the timeout is reached.
      Specified by:
      awaitTermination in class io.grpc.ManagedChannel
      Returns:
      whether the channel is terminated, as would be done by isTerminated().
      Throws:
      InterruptedException
      Since:
      1.0.0

    • newCall

      public <RequestT, ResponseT> io.grpc.ClientCall<RequestT,ResponseT> newCall(io.grpc.MethodDescriptor<RequestT,ResponseT> methodDescriptor, io.grpc.CallOptions callOptions)
      Check the value of ME_KEY key in the CallOptions and if found use the MultiEndpoint with the same name for this call.

      Create a ClientCall to the remote operation specified by the given MethodDescriptor. The returned ClientCall does not trigger any remote behavior until ClientCall.start(Listener, Metadata) is invoked.

      Specified by:
      newCall in class io.grpc.Channel
      Parameters:
      methodDescriptor - describes the name and parameter types of the operation to call.
      callOptions - runtime options to be applied to this call.
      Returns:
      a ClientCall bound to the specified method.
      Since:
      1.0.0

    • authority

      public String authority()
      The authority of the current endpoint of the default MultiEndpoint. Typically, this is in the format host:port.

      To get the authority of the current endpoint of another MultiEndpoint use authorityFor(String) method.

      This may return different values over time because MultiEndpoint may switch between endpoints.

      Specified by:
      authority in class io.grpc.Channel
      Since:
      1.0.0

    • authorityFor

      public String authorityFor(String multiEndpointName)
      The authority of the current endpoint of the specified MultiEndpoint. Typically, this is in the format host:port.

      This may return different values over time because MultiEndpoint may switch between endpoints.