thrift_runtime_connection (thrift_runtime v0.7.0)

View Source

One server-side connection: read message, dispatch, answer, repeat.

Runs as a gen_server owning the accepted socket in {active, N} delivery mode: incoming bytes arrive as tcp/ssl messages, complete messages are split off the buffer by thrift_runtime_socket:extract_message/4 and dispatched; the socket re-arms itself on tcp_passive/ssl_passive. A peer closing the connection is seen as tcp_closed/ssl_closed even while idle.

Timeouts: one timer guards the stream between messages (idle with an empty buffer, or a partial message mid-parse) — when it fires the connection stops. Handler crashes are contained per call and answered with TApplicationException (INTERNAL_ERROR); anything that breaks the stream (bad frame, socket error, timeout) closes the connection.

Configuration comes in at creation time as a map — never from the application environment:

  • socket (required) — the accepted, already handshaken socket;
  • transport — framed (default), buffered, or http: a Thrift message rides as the body of one HTTP/1.1 POST, answered by one response per request over a keep-alive connection. Even a oneway gets an (empty) response — HTTP is request/response. max_frame_size bounds the request body; a request that cannot be parsed is answered 400 (405 for a non-POST method) before the connection closes, a complete request with a bad Thrift payload inside gets 400 and the connection continues.
  • protocol — binary (default), or any thrift_runtime_protocol implementation module (see thrift_runtime:protocol_module/1);
  • max_frame_size — framed mode guard, default 64 MiB;
  • timeout / idle_timeout — maximum silence between messages, default 5000 ms (idle_timeout overrides the umbrella);
  • active_n — {active, N} batch size, default 100;
  • record_api — when true, handler arguments and results are records; types names the generated types module providing record_fields/1.

Exactly one service mode is required:

  • handler + service — single-service mode: service implements thrift_runtime_service, handler implements it;
  • services — multiplexed mode: a map from the service name (binary, as it appears in the Service:function message-name prefix) to #{handler := module(), service := module()}. Incoming message names are routed strictly by that prefix; replies are sent back with the plain function name, matching the Apache multiplexed protocol.

Summary

Types

options()
service_entry()

Functions

start(Opts)

Starts an unlinked connection process.

start_link(Opts)

Starts a linked connection process for an accepted socket.

stop(Pid)

Stops the connection (closes the socket).

Types

options()

-type options() ::
          #{socket := thrift_runtime_socket:socket(),
            transport => thrift_runtime_socket:transport(),
            protocol => binary | compact | module(),
            max_frame_size => pos_integer(),
            timeout => pos_integer() | infinity,
            idle_timeout => pos_integer() | infinity,
            active_n => pos_integer(),
            record_api => boolean(),
            types => module(),
            handler => module(),
            service => module(),
            services => #{binary() => service_entry()},
            on_event => thrift_runtime_events:handler()}.

service_entry()

-type service_entry() :: #{handler := module(), service := module()}.

Functions

start(Opts)

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

Starts an unlinked connection process.

The acceptor uses this plus a monitor, so a crashing connection does not affect the listener.

start_link(Opts)

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

Starts a linked connection process for an accepted socket.

stop(Pid)

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

Stops the connection (closes the socket).