thrift_runtime_reconnecting_client (thrift_runtime v0.7.0)

View Source

One connection to a Thrift server with automatic reconnection and call statistics.

A gen_server wrapper over thrift_runtime_client. The wrapped client keeps its no-reconnect contract — any connection failure kills it — and this process observes the death, reconnects with exponential backoff and fails the calls that arrive in between with {error, disconnected}. Declared and application exceptions are protocol replies: the client survives them, so they only count in the statistics, they never reconnect.

Reconnection is event-driven: a 'DOWN' from the client (or a failed connect) schedules the next attempt after a delay that starts at reconnect_min (default 500 ms) and doubles up to reconnect_max (default 30000 ms); a successful connect resets it. Calls fail fast instead of blocking on a reconnect — a pool can route to another worker immediately. Only the initial connect blocks the start (at most the timeout option): like the reference Apache thrift_reconnecting_client, the wrapper starts happily against a server that is down and keeps trying.

get_stats/1 is the health-check surface for pool owners:

#{connected := boolean(), calls_ok := N, calls_failed := N,
  connects := N, connect_failures := N}

get_and_reset_stats/1 returns the same map and zeroes the counters (connected stays live). Options are the thrift_runtime_client map plus reconnect_min and reconnect_max (milliseconds).

The on_event handler passes through to the wrapped client unchanged, so it sees the call-level call_ok / call_error events; the connection axis adds this wrapper's own events — connected, connect_failed, disconnected (see thrift_runtime_events).

Summary

Types

options()
stats()

Functions

call(Pid, Function, Args, Timeout)

Calls Function with Args (declaration order, wire representation) through the wrapped client.

get_and_reset_stats(Pid)

Returns the statistics and zeroes the counters (connected stays live).

get_stats(Pid)

Returns the connection state and the call/connect counters.

oneway(Pid, Function, Args, Timeout)

Sends a one-way call; the server never answers.

start(Opts)

Starts the reconnecting client without linking — for owners that monitor instead, such as pool workers.

start_link(Opts)

Starts the reconnecting client and links it to the caller.

stop(Pid)

Stops the wrapper and the client it currently holds.

Types

options()

-type options() ::
          #{host := inet:socket_address() | inet:hostname(),
            port := inet:port_number(),
            service := module(),
            transport => thrift_runtime_socket:transport(),
            protocol => binary | compact | module(),
            timeout => pos_integer(),
            max_frame_size => pos_integer(),
            http_path => binary(),
            ssl_opts => [ssl:tls_client_option()],
            multiplex => binary(),
            active_n => pos_integer(),
            reconnect_min => pos_integer(),
            reconnect_max => pos_integer(),
            on_event => thrift_runtime_events:handler()}.

stats()

-type stats() ::
          #{connected := boolean(),
            calls_ok := non_neg_integer(),
            calls_failed := non_neg_integer(),
            connects := non_neg_integer(),
            connect_failures := non_neg_integer()}.

Functions

call(Pid, Function, Args, Timeout)

-spec call(pid(), binary(), [term()], pos_integer() | infinity) -> {ok, term()} | {error, term()}.

Calls Function with Args (declaration order, wire representation) through the wrapped client.

Fails immediately with {error, disconnected} while the wrapper has no connection; exceptions reported by the server come back unchanged and keep the connection.

get_and_reset_stats(Pid)

-spec get_and_reset_stats(pid()) -> stats().

Returns the statistics and zeroes the counters (connected stays live).

get_stats(Pid)

-spec get_stats(pid()) -> stats().

Returns the connection state and the call/connect counters.

oneway(Pid, Function, Args, Timeout)

-spec oneway(pid(), binary(), [term()], pos_integer() | infinity) -> ok | {error, term()}.

Sends a one-way call; the server never answers.

start(Opts)

-spec start(options()) -> gen_server:start_ret().

Starts the reconnecting client without linking — for owners that monitor instead, such as pool workers.

start_link(Opts)

-spec start_link(options()) -> gen_server:start_ret().

Starts the reconnecting client and links it to the caller.

The initial connect attempt blocks for at most the timeout option, but a server that is down does not fail the start — the wrapper keeps retrying in the background. A failed init (a bad protocol or on_event option) answers {error, Reason} only: the trapping around the start shields the caller from the failed child's exit race, the same dance thrift_runtime_client does.

stop(Pid)

-spec stop(pid()) -> ok.

Stops the wrapper and the client it currently holds.