pinterest/riffed

Name: riffed

Owner: Pinterest

Description: Provides idiomatic Elixir bindings for Apache Thrift

Created: 2015-10-08 16:41:29.0

Updated: 2018-04-12 18:26:29.0

Pushed: 2017-03-22 04:16:59.0

Homepage: null

Size: 187

Language: Elixir

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Riffed

Healing the rift between Elixir and Thrift.

Thrift's Erlang implementation isn't very pleasant to use in Elixir. It prefers records to structs, littering your code with tuples. It swallows enumerations you've defined, banishing them to the realm of wind and ghosts. It requires that you write a bunch of boilerplate handler code, and client code that's not very Elixir-y. Riffed fixes this.

Getting Started

For a detailed guide on how to get started with Riffed, and creating your first Riffed server and client, see the Getting Started Guide. For a general summary of some of the features Riffed provides, continue reading.

You can also generate Riffed documentation by running mix docs.

Riffed Provides three modules, Riffed.Struct, Riffed.Client, and Riffed.Server which will help you manage this impedence mismatch.

Elixir-style structs with Riffed.Struct

Riffed.Struct provides functionality for converting Thrift types into Elixir structs.

You tell Riffed.Struct about your Erlang Thrift modules and which structs you would like to import. It then looks at the thrift files, parses their metadata and builds Elixir structs for you. It also creates to_elixir and to_erlang functions that will handle converting Erlang records into Elixir structs and vice versa.

Assuming you have a Thrift module called pinterest_types in your src directory:

odule Structs do
e Riffed.Struct, pinterest_types: [:User, :Pin, :Board]

Then you can do the following:

 user = Structs.User.new(firstName: "Stinky", lastName: "Stinkman")
 user_tuple = Structs.to_erlang(user, {:pinterest_types, :User}
er, "Stinky", "Stinkman"}

 Structs.to_elixir(user_tuple)
ucts.User{firstName: "Stinky", lastName: "Stinkman"}

…but you'll rarely use the Struct module directly. Instead, you'll use the Riffed.Client or Riffed.Server modules.

If your Thrift structs define default values for fields, these will be preserved in Elixir structs, using appropiate types. The only exception is that Riffed cannot handle default values that reference other structs; the default value for these fields will always be :undefined.

Generating Servers with Riffed.Server

Riffed.Server assumes you have a module that has a bunch of handler functions in it. When a thrift RPC is called, your parameters will be converted into Elixir structs and then passed in to one of your handler functions. Let's assume you have the following thrift defined:

 UserState {
TIVE,
ACTIVE,
NNED;


ct User {
 string username,
 string firstName,
 string lastName;
 UserState state;


ice PinterestRegister {
er register(1: string firstName, 2: string lastName);
ol isRegistered(1: User user);
erState getState(1: string username);
id setState(1: User user, 2: UserState state);
id setStatesForUser(1: map<i64, UserState> stateMap);

You can set it up like this:

odule Server do
e Riffed.Server,
rvice: :pinterest_thrift,
ructs: Data,
nctions: [register: &ThriftHandlers.register/3,
          isRegistered: &ThriftHandlers.is_registered/1,
          getState: &ThriftHandlers.get_state/1,
          setState: &ThriftHandlers.set_state/2
          setStatesForUser: &ThriftHandlers.set_states_for_user/1

rver: {:thrift_socket_server,
       port: 2112,
       framed: true,
       max: 10_000,
       socket_opts: [
               recv_timeout: 3000,
               keepalive: true]
      }

fenum UserState do
:active -> 1
:inactive -> 2
:banned -> 3
d

umerize_struct User, state: UserState
umerize_function setUserState(_, UserState)
umerize_function getState(_), returns: UserState


odule ThriftHandlers do

f register(username, first_name, last_name) do
# registration logic. Return a new user
Data.User.new(username: username, firstName: "Stinky", lastName: "Stinkman")
d

f is_registered(user=%Data.User{}) do
true
d

f get_state(username) do
user = Models.User.fetch(username)
case user.state do
  :active -> Data.UserState.active
  :banned -> Data.UserState.banned
  _ -> Data.UserState.inactive
end
d

f set_state(user=%Data.User{}, state=%Data.UserState{}) do
...
d

Riffed.Server is doing a bunch of work for you. It's investigating your thrift files and figuring out which structs need to be imported by looking at the parameters, exceptions and return values. It then makes a module that imports your structs (Data in this case) and builds code for the thrift server that takes an incoming thrift request, converts its parameters into Elixir representations and then calls your handler. Notice how the handlers in ThriftHandlers take structs as arguments and return structs. That's what Riffed gets you.

These handler functions also process the values your code returns and hands them back to thrift.

The above example also shows how to handle Thrift enums. Due to the way thrift enums are handled by the erlang generator, there's no way for Riffed to convert them into a friendly structure for you, so they need to be defined and pointed out to Riffed.

The thrift server is configured in the server block. The first element of the tuple is the module of the server you wish to instantiate. In this case, we're using thrift_socket_server. The second element is a Keyword list of configuration options for the server. You cannot set the :name, :handler or :service params. The name and handler are set to the current module. The service is given as the thrift_module option.

Generating a client with Riffed.Client

Generating a client is similarly simple. Riffed.Client just asks that you point it at the erlang module that was generated by thrift, tell it what the client's configuration is and tell it what functions you'd like to import. When that's done, it examines the thrift module, figures out what types you need, creates structs for them and generates helper functions for calling your thrift RPC calls.

Assuming the same configuration above, the following block will generate a client:

odule RegisterClient do
e Riffed.Client,
ructs: Models,
ient_opts: [host: "localhost", port: 1234, framed: true],
rvice: :pinterest_thrift,
port: [:register,
     :isRegistered,
     :getState]

fenum UserState do
:active -> 1
:inactive -> 2
:banned -> 3
d

umerize_struct User, state: UserState
umerize_function getState(_), returns: UserState

You start the client by calling start_link:

sterClient.start_link

You can then issue calls against the client:

 user = RegisterClient.register("Stinky", "Stinkman")
els.User{firstName: "Stinky", lastName: "Stinkman")

 is_registered = RegisterClient.isRegistered(user)


 state = RegisterClient.getState(user)
els.UserState{ordinal: :active, value: 1}

Clients support the same callbacks and enumeration transformations that the server suports, and they're configured identically.

Sharing Structs

Sometimes, you have common structs that are shared between services. Due to Riffed auto-importing structs based on the server definition, Riffed will duplicate shared structs. This auto-import feature can be disabled by specifying auto_import_structs: false when creating a client or server. You can then use Riffed.Struct to build a struct module:

odule SharedStructs do
e Riffed.Struct, shared_types: [:User, :Account, :Profile]


odule UserService do
e Riffed.Server, service: :user_thrift,
to_import_structs: false,
ructs: SharedStructs
.


odule ProfileService do
e Riffed.Server, service: :profile_thrift,
to_import_structs: false,
ructs: SharedStructs
.

Advanced Struct Packaging

Often, thrift files will make use of include statements to share structs. This can present a namespacing problem if you're running several thrift servers or clients that all make use of a common thrift file. This is because each server or client will import the struct separately and produce incompatible structs.

This can be mitigated by using shared structs in a common module and controlling how they're imported. To control the destination module, use the dest_modules keyword dict:

odule Models do
e Riffed.Struct, dest_modules: [common_types: Common,
                                server_types: Server,
                                client_types: Client],
                common_types: [:RequestContext, :User],
                server_types: [:AccessControlList],
                client_types: [:UserList]

fenum Common.UserState do
:inactive -> 1
:active -> 2
:core -> 3
d

umerize_struct Common.User, state: Common.UserState


odule Server do
e Riffed.Server, service: :server_thrift,
to_import_structs: false,
ructs: Models
.


odule Client do
e Riffed.Client,
to_import_structs: false,
ructs: Models
.

The above configuration will produce three different modules, Models.Common, Models.Server and Models.Client. The Models module is capable of serializing and deserializing all the types defined in the three submodules, and should be used as your :structs module in your client and servers.

As you can see above, you can also namespace enumerations.

Handling Thrift Enumerations

Unfortunately, enumeration support in Erlang thrift code is lossy and because of this Riffed can't tell where the enumerations you worked so tirelessly to define appear in the generated code. Unfortunately, you have to re-define them and tell Riffed where they are; otherwise, all you'll see are integers.

To do this, Riffed supports a syntax to re-define enumerations, and this syntax is available when you use Riffed.Server and Riffed.Client.

The following examples assume these RPC calls and enumeration:

 DayOfTheWeek {
NDAY,
NDAY,
ESDAY,
DNESDAY,
URSDAY,
IDAY


 setCreatedDay(1: User user, 2: DayOfTheWeek day);
fTheWeek getCreatedDay(1: User user);

First off, you'll need to re-define your enumeration. To do that, use the defenum macro inside of your Riffed.Server or Riffed.Client module:

num DayOfTheWeek do
unday -> 1
onday -> 2
uesday -> 3
ednesday -> 4
hursday -> 5
riday -> 6
aturday -> 7

Converting enumerations in structs

Now you'll need to tell Riffed where this enum appears in your other data structures. To do that, use the enumerize_struct macro:

erize_struct User, sign_up_day: DayOfTheWeek, last_login_day: DayOfTheWeek

Now all Users will have their sign_up_day and last_login_day fields automatically converted to enumerations.

Converting enumerations in functions

If the enumeration is the argument or return value of a RPC call, you'll need to identify it there too. Use the enumerize_function macro:

erize_function setCreatedDay(_, DayOfTheWeek)
erize_function getCreatedDay(_) returns: DayOfTheWeek

The enumerize_function macro allows you to mark function arguments and return values with the enumeration you would like to use. Unconverted arguments are signaled by using the _ character. In the example above, setCreatedDay's second argument will be converted to a DayOfTheWeek enumeration and its first argument will be left alone.

Similarly, the function getCreatedDay will have its argument left alone and its return value converted into a DayOfTheWeek enumeration

Complex types are also handled in both arguments and return types:

erize_function setStatesForUser({:map, {:i64, UserState}})

Using enumerations in code

Enumerations are elixir structs whose modules support converting between the struct and integer representation. This shows how to convert integers to enumerations and vice-versa

 x = DayOfWeek.monday
OfWeek{ordinal: :monday, value: 2}

 x.value


 x = DayOfWeek.value(4)
OfWeek{ordinal: :thursday, value: 4}

 x.ordinal
rsday

Since they're just maps, enumerations support pattern matching.

handle_user(user=%User{sign_up_day: DayOfTheWeek.monday}) do
code for users that signed up on monday


handle_user(user=%User{})
code for everyone else

You can also retrieve the ordinals, values, or mappings from an enumeration.

 DayOfWeek.ordinals
nday, :monday, :tuesday, ...]

 DayOfWeek.values
2, 3, ...]

 DayOfWeek.mappings
day: 1, monday: 2, tuesday: 3, ...]