The Rpc_proxy module provides an improved reliability layer on top of [root:Rpc_client]. This layer especially features:

• automatic connection management: TCP connections are started and terminated as needed
• multiple connections can be held in parallel to a remote server to increase concurrency on the server
• failover to other servers when the orignal servers time out
• support for an initial ping at connection establishment time to test the availability of the connection
• retransmission of idempotent RPC calls

Proxies can only handle stream connections (TCP and Unix Domain). Also, the remote endpoints must already be specified by socket addresses. (No portmapper and other indirect lookup methods.)

The proxy functionality is implemented in two layers, the managed clients, and the managed sets. The former layer can handle only one TCP connection (with reconnect), whereas the latter is able to manage a bunch of connections to the same service. Both layers can profit from a reliability cache that knows which services had errors in the past.

See below for a tutorial.

There is also a blog article explaining RPC proxies: The next server, please!

A normal RPC client has a very limited lifecylce: It is created, then a connection is made to an RPC service, messages are exchanged, and finally the connection is terminated. After that the client becomes unusable. In short, it is "use once" client.

In contrast to this, managed clients can be recycled. This is especially useful for dealing with socket errors, and connection terminations triggered by the RPC server.

How to use managed clients: For a normal RPC client the generator ocamlrpcgen creates all required glue code to easily start RPC calls. For example, if a file proto.x is taken as input for ocamlrpcgen, a piece of code doing a call could look like:

      let client =
        Proto_clnt.PROG.VERS.create_client connector protocol
      let result =
        Proto_clnt.PROG.VERS.procedure client argument

(Here, PROG, VERS, procedure are just placeholders for the name of the program, the version identifier, and the procedure name.)

For RPC proxies, however, this is slightly more complicated. ocamlrpcgen does not produce a managed client that is ready for use. Instead, only a functor is provided that can take the Rpc_proxy.ManagedlClient module as input:

      module M = Proto_clnt.Make'PROG(Rpc_proxy.ManagedClient)

      let esys =
        Unixqueue.create_unix_event_system()
      let mclient_config =
        Rpc_proxy.ManagedClient.create_mclient_config
          ~programs:[ Proto_clnt.PROG.VERS._program ]
          () in
      let mclient =
        Rpc_proxy.ManagedClient.create_mclient mclient_config connector esys
      let result =
        M.VERS.procedure mclient argument

(The functor approach has been chosen, because it gives the user more flexibility - it is possible to apply the functor on other implementations of improved clients than Rpc_proxy.ManagedClient.)

Note that esys is always explicit, even in the case the user only performs synchronous calls - the user should create a new esys then, pass it to mclient, and ignore it otherwise.

Now, how does the recycling feature work? The managed client can be in one of three states:

• `Down: The client is not connected. This is the initial state, and the state after errors and terminated connections (no matter whether triggered by the client or by the server)
• `Connecting: The client is busy (re)connecting (only used in some cases)
• `Up sockaddr: The client is connected and has the socket address sockaddr

The state can be queried with Rpc_proxy.ManagedClient.mclient_state. When it is `Down, the next RPC call automatically starts the reconnect to the service. When the connection is established, the call is done, and the messages are exchanged that are representing the call. After that, the state remains `Up after the call.

When the call stops because of an error, the error is reported to the user in the normal way, and the client is shut down, i.e. after an error the state is `Down. If the user decides to try the call again, the client automatically reconnects following the outlined rules. Note that managed clients never automatically retry calls by themselves.

When the TCP connection is regularly shut down (either by the server or by the client calling Rpc_proxy.ManagedClient.shut_down), the client state is changed to `Down at the next opportunity. Especially a server-driven shutdown may first be detected when the next RPC call is tried on the connection. This may or may not lead to an error depending on the exact timing. In any way, the connection is finally established again.

Of course, managed clients must be shut down after use, because there is no other (automatic) way of recognizing that they are no longer used. Call Rpc_proxy.ManagedClient.shut_down for this.

Managed client also have a few more features that can be enabled in mclient_config, especially:

• Initial ping: This means that the TCP connection is tested before being used for user operations. The test is done by pinging the service once (via the RPC null procedure). This is recommended because some connectivity problems can first be detected when the TCP connection is actually used.
• Idle timeout: The TCP connection is closed after it is idle for some period of time. "Idle" means here that nothing is being transmitted, and that no response from the server is expected. The connection is closed at the first opportunity. The user should be aware that this can only happen when the event loop for esys is running. Especially for synchronous calls this is typically not the case, so one would have to call Unixqueue.run esys now and then to create opportunities for detecting the idle timeout.
• Reliability cache: The cache object counts errors, and can disable certain service endpoints if they only produce errors. This mostly makes sense when there are alternative endpoints, i.e. in the context of a managed set (see below).

Managed sets are another layer on top of the managed clients. These sets are able to manage several connections where each is implemented as managed client. The connections can go to the same server endpoint in order to parallelize RPCs at the client side, or to several server endpoints that provide the same service. The latter can be used for client-driven load balancing, and for client-driven failover management of HA setups (HA = high availability).

For creating a managed set, the code looks like

      module M = Proto_clnt.Make'PROG(Rpc_proxy.ManagedClient)

      let esys =
        Unixqueue.create_unix_event_system()
      let mclient_config =
        Rpc_proxy.ManagedClient.create_mclient_config
          ~programs:[ Proto_clnt.PROG.VERS._program ]
          () in
      let mset_config =
        Rpc_proxy.ManagedSet.create_mset_config
          ~mclient_config
          () in
      let services =
        [| connector, n_connections; ... |] in
      let mset =
        Rpc_proxy.ManagedSet.create_mset 
          mset_config 
          services
          esys in
      let mclient, idx =
        Rpc_proxy.ManagedSet.mset_pick mset in
      let result =
        M.VERS.procedure mclient argument

The managed clients are internally created by the set - one only should pass in mclient_config so the set knows what kind of client is preferred. For the simple application of maintaining several connections to the same server, one would create the mset with a one-element service array:

       let services =
          [| connector, n_connections |]

where connector describes the server port, and n_connections is the maximum number of connections to create and maintain. The Rpc_proxy.ManagedSet.mset_pick function creates internally up to n_connections managed clients, and returns one of them. By default, it is not guaranteed that the client is idle (meaning no previous call is pending) - if the connections are all already busy, mset_pick starts returning busy connections (but the least busy one first).

There are a number of options allowing to modify the default behavior:

• One can enforce that only idle clients are returned by mset_pick. To do this, pass the argument ~mset_pending_calls_max:1 to Rpc_proxy.ManagedSet.create_mset_config. It can then happen that no client is idle, and mset_pick will raise Rpc_proxy.ManagedSet.Cluster_service_unavailable.
• If the services array has more than one element, they are considered as equivalent service endpoints. mset_pick will pick one of the endpoints. There are two policies controlling the selection: With ~policy:`Balance_load it is aimed at sending roughly the same number of calls to all endpoints. With ~policy:`Failover the services are assigned precedences by the position in the array (i.e. the first service is used as long as possible, then the second service is used, etc.). The policy argument is again to be passed to Rpc_proxy.ManagedSet.create_mset_config.

Of course, managed sets must be shut down after use, because there is no other (automatic) way of recognizing that they are no longer used. Call Rpc_proxy.ManagedSet.shut_down for this.

The cache allows to disable certain hosts or ports when the error counter reaches a limit. The service is disabled for a limited time span. This is especially useful when there is an alternate port that can jump in for the failing one, i.e. when the services array of a managed set has two or more elements.

There is a single global cache object, but one can also create specific cache objects. Generally, cache objects can be shared by many managed clients and managed sets. The hope is that sharing is useful because more data can be made available to users of services. If you do not want to use the global cache object, you can create your own, and configure it in mclient_config.

The global cache object is automatically used when nothing else is specified. The global cache object is by default configured in a way so it does not have any effect, though. So we have to change this in order to enable the cache:

     let rcache_config =
       Rpc_proxy.ReliabilityCache.create_rcache_config
        ~policy:`Independent
        ~threshold:3
        () in
     Rpc_proxy.ReliabilityCache.set_global_rcache_config rcache_config

This means that 3 errors in sequence disable a service port. `Independent means that each port is handled independently in this respect.

At the first time, the port is only disabled for one second. The duration of the time span is increased by each additional error until it reaches 64 seconds. These durations can be changed, of course.

As the impact of changing the global cache object is sometimes unpredictable, one can also create a private cache object (Rpc_proxy.ReliabilityCache.create_rcache). Another way is to derive a semi-private object from the global one. This means that the error counters are global, but the interpretation can be set individually in each use. This would look like:

    let rcache_config =
      Rpc_proxy.ReliabilityCache.create_rcache_config
        ~policy:`Independent
        ~threshold:3
        () in
    let rcache =
      Rpc_proxy.ReliabilityCache.derive_rcache
        (Rpc_proxy.ReliabilityCache.global_rcache())
        rcache_config in
    ...
    let mclient_config =
      Rpc_proxy.ManagedClient.create_mclient_config
        ...
        ~rcache
        ...
        ()

In the layer of managed sets there is some limited support for automatically repeating failing idempotent RPC calls.

Instead of calling the RPC with

      let mclient, idx =
        Rpc_proxy.ManagedSet.mset_pick mset in
      let result =
        M.VERS.procedure mclient argument

one uses

      let result =
        Rpc_proxy.ManagedSet.idempotent_sync_call
          mset
          M.VERS.procedure'async
          argument

The effet is that Rpc_proxy.ManagedSet.idempotent_sync_call repeats automatically the call when an error occurs. It is assumed that the call is idempotent so it can be repeated without changing the meaning.

The call may be repeated several times. This is configured in the managed set mset (parameter mset_idempotent_max).

Note that one has to pass the asynchronous version (suffix 'async) of the RPC wrapper even when doing a synchronous call.

Also see the documentation for Rpc_proxy.ManagedSet.idempotent_async_call.