thrift_runtime (thrift_runtime v0.7.0)

View Source

High-level facade over the runtime codecs: two independent axes.

The protocol axis picks the wire format; the default is the Thrift binary protocol, compact and json are the built-in Apache protocols, and any module implementing thrift_runtime_protocol plugs in without code changes here. The representation axis picks the in-process shape of struct values:

  • record — tuple records as declared by generated <mod>_types.erl (the default for record-mode structs);
  • map — plain maps with atom keys matching the IDL field names;
  • struct — #{__struct__ => Tag, Field => Value, ...}, the Elixir-style tagged map that survives round-trips without the record definitions in scope;
  • native — EEP-79 native records (OTP 29+): values minted by thrift_runtime_native from the descriptor, fields readable through the records module without any compiled definitions. Releases older than 29 answer {error, {unsupported_repr, native}} from decode and convert.

Sum unions (erl.union_type = "sum") are their own representation: the value is a {FieldAtom, Value} tuple — one variant by construction — unchanged across all four axes (only the nested payloads convert). A wire union with zero or several set fields is malformed and answers {error, {invalid_union, Map}}.

encode/2,3 accepts any representation on input and auto-detects it; decode/3,4 produces the requested one. convert/3 reshapes typed values without touching bytes: pass the tag index emitted by the generator (the TagIndex/0 export of generated types modules) and any record or struct-map value.

All functions are pure; the network API lives in thrift_runtime_client and thrift_runtime_server.

Summary

Types

protocol()
repr()
tag_index()

Functions

convert(TagIndex, Value, Repr)

Reshapes a typed value (record, struct-map or native record, nested structures included) into Repr, without encoding bytes.

decode(Desc, Binary, Repr)

Decodes the whole binary into a record with the binary protocol.

decode(Desc, Binary, Repr, Protocol)

Decodes the whole binary into the given representation and protocol.

encode(Desc, Value)

Encodes a value in any representation with the binary protocol.

encode(Desc, Value, Protocol)

Encodes a value in any representation with the given protocol.

encode(Desc, Value, Protocol, Opts)

Encodes a value with the given protocol and encode options.

protocol_module/1

Resolves a protocol axis value to its implementation module.

Types

protocol()

-type protocol() :: thrift_runtime_protocol:protocol() | module().

repr()

-type repr() :: record | map | struct | native.

tag_index()

-type tag_index() :: #{atom() => thrift_runtime_protocol:type_desc()}.

Functions

convert(TagIndex, Value, Repr)

-spec convert(tag_index(), term(), repr()) -> {ok, term()} | {error, term()}.

Reshapes a typed value (record, struct-map or native record, nested structures included) into Repr, without encoding bytes.

Value carries its own identity — a record tag, the __struct__ key or the native record's module/name — which is looked up in TagIndex (the TagIndex/0 export of generated types modules). Unknown tags and values without identity crash: this function is for values the caller knows to be service structs. The record representation of a map-representation or native-representation struct answers {error, {no_record, Tag}} — there is no record to produce.

decode(Desc, Binary, Repr)

-spec decode(thrift_runtime_binary:type_desc(), binary(), repr()) -> {ok, term()} | {error, term()}.

Decodes the whole binary into a record with the binary protocol.

Unlike the streaming thrift_runtime_binary:decode/2, this is strict: a truncated input fails with {error, truncated}, trailing bytes with {error, trailing}. A map-representation or native-representation struct has no record to produce: record fails with {error, {no_record, Name}}.

decode(Desc, Binary, Repr, Protocol)

-spec decode(thrift_runtime_binary:type_desc(), binary(), repr(), protocol()) ->
                {ok, term()} | {error, term()}.

Decodes the whole binary into the given representation and protocol.

encode(Desc, Value)

-spec encode(thrift_runtime_binary:type_desc(), term()) -> {ok, binary()} | {error, term()}.

Encodes a value in any representation with the binary protocol.

encode(Desc, Value, Protocol)

-spec encode(thrift_runtime_binary:type_desc(), term(), protocol()) -> {ok, binary()} | {error, term()}.

Encodes a value in any representation with the given protocol.

encode(Desc, Value, Protocol, Opts)

-spec encode(thrift_runtime_binary:type_desc(), term(), protocol(), map()) ->
                {ok, binary()} | {error, term()}.

Encodes a value with the given protocol and encode options.

strict => true checks the top-level map/struct-map input against the struct's declared fields and fails with {error, {unknown_fields, Keys}} instead of silently dropping the keys that match nothing (the default). Every other value shape the codecs reject on their own with {error, {value_does_not_match_type, Value}}.

protocol_module/1

-spec protocol_module(protocol()) -> {ok, module()} | {error, term()}.

Resolves a protocol axis value to its implementation module.

binary, compact and json are the built-in protocols; a module name is accepted after verifying it exports every thrift_runtime_protocol callback.