thrift_runtime

View Source

The runtime library of thrift-erl: everything Thrift-compatible generated code needs at run time — protocols, transports, a client, a server and the representation engine — with no dependencies beyond kernel and stdlib.

Wire compatibility with the stock Apache Thrift implementation is tested, not assumed: golden interop against the official Erlang runtime on all three protocols, over buffered, framed and HTTP transports, multiplexed services included.

Add to your project

%% rebar.config
{deps, [thrift_runtime]}.

In the common case you never call the runtime directly: generate Erlang code from your Thrift IDL with the thrift_generator package (or the rebar3_thrift plugin) and use the generated modules — specialized codecs, typed clients, servers and handler behaviours. The generated code depends on this package and nothing else.

A taste of the generated surface:

{ok, Server} = ping_api_ping_server:start_link(#{port => 9090, handler => ping_handler}),
{ok, Client} = ping_api_ping_client:start_link(#{host => "127.0.0.1", port => 9090}),
{ok, Reply} = ping_api_ping_client:ping(Client, #ping_api_ping_request{message = <<"hi">>}),
%% a declared exception comes back typed:
{error, {exception, #ping_api_no_such_message{}}} =
    ping_api_ping_client:ping(Client, #ping_api_ping_request{message = <<"bad">>}),
ok = ping_api_ping_client:stop(Client),
ok = ping_api_ping_server:stop(Server).

What the package provides

  • Protocols: binary, compact and json — or your own module implementing the thrift_runtime_protocol behaviour.
  • Transports: framed, buffered and http, over TCP or TLS.
  • Client: one connection per process, queued calls, per-call timeouts, statistics; a reconnecting wrapper with backoff for pool-style deployments.
  • Server: a supervisor with an acceptor and per-connection processes, graceful drain, multiplexed services, max-frame and max-connection limits.
  • Representations: records (default), plain atom maps, tagged struct maps or EEP-79 native records — selectable per struct, uniform all the way down, convertible without touching bytes.
  • A generic codec engine driven by hand-written struct descriptors, for introspection and wire work without generated code; generated modules feed it via struct_info/1, enum_info/1 and function_info/2.
  • Observability: crash-isolated on_event callbacks on clients, servers and connections.

See the repository README for the full guide: options, protocol and transport details, pooling, TLS, multiplexing and performance.

License

Apache-2.0 — see LICENSE.md.