{"id":13508976,"url":"https://github.com/pinterest/riffed","last_synced_at":"2025-09-02T10:33:36.234Z","repository":{"id":66170235,"uuid":"43903016","full_name":"pinterest/riffed","owner":"pinterest","description":"Provides idiomatic Elixir bindings for Apache Thrift","archived":false,"fork":false,"pushed_at":"2020-06-17T22:14:32.000Z","size":189,"stargazers_count":306,"open_issues_count":9,"forks_count":37,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-06-09T15:11:37.667Z","etag":null,"topics":["elixir","thrift"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinterest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-10-08T16:41:29.000Z","updated_at":"2025-04-17T05:58:11.000Z","dependencies_parsed_at":"2023-03-24T22:33:32.561Z","dependency_job_id":null,"html_url":"https://github.com/pinterest/riffed","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pinterest/riffed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Friffed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Friffed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Friffed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Friffed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinterest","download_url":"https://codeload.github.com/pinterest/riffed/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Friffed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273271495,"owners_count":25075966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","thrift"],"created_at":"2024-08-01T02:01:01.228Z","updated_at":"2025-09-02T10:33:36.205Z","avatar_url":"https://github.com/pinterest.png","language":"Elixir","funding_links":[],"categories":["Protocols","Elixir"],"sub_categories":[],"readme":"# Riffed\n\n![Version](https://img.shields.io/github/tag/pinterest/riffed.svg)\n[![Build Status](https://travis-ci.org/pinterest/riffed.svg?branch=master)](https://travis-ci.org/pinterest/riffed)\n[![Coverage Status](https://coveralls.io/repos/pinterest/riffed/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/pinterest/riffed?branch=master)\n![Issues](https://img.shields.io/github/issues/pinterest/riffed.svg)\n![License](https://img.shields.io/badge/license-Apache%202-blue.svg)\n\n### Healing the rift between Elixir and Thrift.\n\nThrift'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.\n\n\n## Getting Started\n\nFor a detailed guide on how to get started with Riffed, and creating your first Riffed server and client, see the [Getting Started Guide](https://github.com/pinterest/riffed/blob/master/doc/GettingStarted.md). For a general summary of some of the features Riffed provides, continue reading.\n\nYou can also generate Riffed documentation by running `mix docs`.\n\nRiffed Provides three modules, `Riffed.Struct`, `Riffed.Client`, and `Riffed.Server` which will help you manage this impedence mismatch.\n\n\n## Elixir-style structs with `Riffed.Struct`\n\n`Riffed.Struct` provides functionality for converting Thrift types into Elixir structs.\n\nYou 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.\n\nAssuming you have a Thrift module called `pinterest_types` in your `src` directory:\n\n```elixir\ndefmodule Structs do\n  use Riffed.Struct, pinterest_types: [:User, :Pin, :Board]\nend\n```\n\nThen you can do the following:\n\n```elixir\niex\u003e user = Structs.User.new(firstName: \"Stinky\", lastName: \"Stinkman\")\niex\u003e user_tuple = Structs.to_erlang(user, {:pinterest_types, :User}\n{:User, \"Stinky\", \"Stinkman\"}\n\niex\u003e Structs.to_elixir(user_tuple)\n%Structs.User{firstName: \"Stinky\", lastName: \"Stinkman\"}\n```\n\n...but you'll rarely use the Struct module directly. Instead, you'll use the `Riffed.Client` or `Riffed.Server` modules.\n\nIf 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`.\n\n\n## Generating Servers with `Riffed.Server`\n\n`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:\n\n```thrift\nenum UserState {\n  ACTIVE,\n  INACTIVE,\n  BANNED;\n}\n\nstruct User {\n  1: string username,\n  2: string firstName,\n  3: string lastName;\n  4: UserState state;\n}\n\nservice PinterestRegister {\n  User register(1: string firstName, 2: string lastName);\n  bool isRegistered(1: User user);\n  UserState getState(1: string username);\n  void setState(1: User user, 2: UserState state);\n  void setStatesForUser(1: map\u003ci64, UserState\u003e stateMap);\n}\n```\n\nYou can set it up like this:\n\n```elixir\ndefmodule Server do\n  use Riffed.Server,\n  service: :pinterest_thrift,\n  structs: Data,\n  functions: [register: \u0026ThriftHandlers.register/3,\n              isRegistered: \u0026ThriftHandlers.is_registered/1,\n              getState: \u0026ThriftHandlers.get_state/1,\n              setState: \u0026ThriftHandlers.set_state/2\n              setStatesForUser: \u0026ThriftHandlers.set_states_for_user/1\n  ],\n  server: {:thrift_socket_server,\n           port: 2112,\n           framed: true,\n           max: 10_000,\n           socket_opts: [\n                   recv_timeout: 3000,\n                   keepalive: true]\n          }\n\n  defenum UserState do\n    :active -\u003e 1\n    :inactive -\u003e 2\n    :banned -\u003e 3\n  end\n\n  enumerize_struct User, state: UserState\n  enumerize_function setUserState(_, UserState)\n  enumerize_function getState(_), returns: UserState\nend\n\ndefmodule ThriftHandlers do\n\n  def register(username, first_name, last_name) do\n    # registration logic. Return a new user\n    Data.User.new(username: username, firstName: \"Stinky\", lastName: \"Stinkman\")\n  end\n\n  def is_registered(user=%Data.User{}) do\n    true\n  end\n\n  def get_state(username) do\n    user = Models.User.fetch(username)\n    case user.state do\n      :active -\u003e Data.UserState.active\n      :banned -\u003e Data.UserState.banned\n      _ -\u003e Data.UserState.inactive\n    end\n  end\n\n  def set_state(user=%Data.User{}, state=%Data.UserState{}) do\n    ...\n  end\n\nend\n```\n\n`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.\n\nThese handler functions also process the values your code returns and hands them back to thrift.\n\nThe 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.\n\nThe 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.\n\n\n## Generating a client with `Riffed.Client`\n\nGenerating 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.\n\nAssuming the same configuration above, the following block will generate a client:\n\n```elixir\ndefmodule RegisterClient do\n  use Riffed.Client,\n  structs: Models,\n  client_opts: [host: \"localhost\", port: 1234, framed: true],\n  service: :pinterest_thrift,\n  import: [:register,\n         :isRegistered,\n         :getState]\n\n  defenum UserState do\n    :active -\u003e 1\n    :inactive -\u003e 2\n    :banned -\u003e 3\n  end\n\n  enumerize_struct User, state: UserState\n  enumerize_function getState(_), returns: UserState\nend\n```\n\nYou start the client by calling start_link:\n\n```elixir\nRegisterClient.start_link\n```\n\nYou can then issue calls against the client:\n\n```elixir\niex\u003e user = RegisterClient.register(\"Stinky\", \"Stinkman\")\n%Models.User{firstName: \"Stinky\", lastName: \"Stinkman\")\n\niex\u003e is_registered = RegisterClient.isRegistered(user)\ntrue\n\niex\u003e state = RegisterClient.getState(user)\n%Models.UserState{ordinal: :active, value: 1}\n```\n\nClients support the same callbacks and enumeration transformations that the server suports, and they're configured identically.\n\n## Sharing Structs\nSometimes, 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:\n\n```elixir\ndefmodule SharedStructs do\n  use Riffed.Struct, shared_types: [:User, :Account, :Profile]\nend\n\ndefmodule UserService do\n  use Riffed.Server, service: :user_thrift,\n  auto_import_structs: false,\n  structs: SharedStructs\n  ...\nend\n\ndefmodule ProfileService do\n  use Riffed.Server, service: :profile_thrift,\n  auto_import_structs: false,\n  structs: SharedStructs\n  ...\nend\n```\n\n## Advanced Struct Packaging\n\nOften, 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.\n\nThis 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:\n\n```elixir\ndefmodule Models do\n  use Riffed.Struct, dest_modules: [common_types: Common,\n                                    server_types: Server,\n                                    client_types: Client],\n                    common_types: [:RequestContext, :User],\n                    server_types: [:AccessControlList],\n                    client_types: [:UserList]\n\n  defenum Common.UserState do\n    :inactive -\u003e 1\n    :active -\u003e 2\n    :core -\u003e 3\n  end\n\n  enumerize_struct Common.User, state: Common.UserState\nend\n\ndefmodule Server do\n  use Riffed.Server, service: :server_thrift,\n  auto_import_structs: false,\n  structs: Models\n  ...\nend\n\ndefmodule Client do\n  use Riffed.Client,\n  auto_import_structs: false,\n  structs: Models\n  ...\nend\n```\n\nThe above configuration will produce three different modules, `Models.Common`, `Models.Server` and `Models.Client`. The `Models` module\nis 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.\n\nAs you can see above, you can also namespace enumerations.\n\n\n## Handling Thrift Enumerations\n\nUnfortunately, 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.\n\nTo do this, Riffed supports a syntax to re-define enumerations, and this syntax is available when you use `Riffed.Server` and `Riffed.Client`.\n\nThe following examples assume these RPC calls and enumeration:\n\n```thrift\nenum DayOfTheWeek {\n  SUNDAY,\n  MONDAY,\n  TUESDAY,\n  WEDNESDAY,\n  THURSDAY,\n  FRIDAY\n}\n\nvoid setCreatedDay(1: User user, 2: DayOfTheWeek day);\nDayOfTheWeek getCreatedDay(1: User user);\n```\n\nFirst 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:\n\n```elixir\ndefenum DayOfTheWeek do\n  :sunday -\u003e 1\n  :monday -\u003e 2\n  :tuesday -\u003e 3\n  :wednesday -\u003e 4\n  :thursday -\u003e 5\n  :friday -\u003e 6\n  :saturday -\u003e 7\nend\n```\n\n##### Converting enumerations in structs\nNow you'll need to tell Riffed where this enum appears in your other data structures. To do that, use the enumerize_struct macro:\n\n```elixir\nenumerize_struct User, sign_up_day: DayOfTheWeek, last_login_day: DayOfTheWeek\n```\n\nNow all Users will have their sign_up_day and last_login_day fields automatically converted to enumerations.\n\n##### Converting enumerations in functions\n\nIf 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:\n\n```elixir\nenumerize_function setCreatedDay(_, DayOfTheWeek)\nenumerize_function getCreatedDay(_) returns: DayOfTheWeek\n```\n\nThe `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.\n\nSimilarly, the function `getCreatedDay` will have its argument left alone and its return value converted into a DayOfTheWeek enumeration\n\nComplex types are also handled in both arguments and return types:\n\n```elixir\nenumerize_function setStatesForUser({:map, {:i64, UserState}})\n```\n\n##### Using enumerations in code\nEnumerations are elixir structs whose modules support converting between the struct and integer representation. This shows how to convert integers to enumerations and vice-versa\n\n```elixir\niex\u003e x = DayOfWeek.monday\n%DayOfWeek{ordinal: :monday, value: 2}\n\niex\u003e x.value\n1\n\niex\u003e x = DayOfWeek.value(4)\n%DayOfWeek{ordinal: :thursday, value: 4}\n\niex\u003e x.ordinal\n:thursday\n```\n\nSince they're just maps, enumerations support pattern matching.\n\n```elixir\ndef handle_user(user=%User{sign_up_day: DayOfTheWeek.monday}) do\n  # code for users that signed up on monday\nend\n\ndef handle_user(user=%User{})\n  # code for everyone else\nend\n```\n\nYou can also retrieve the ordinals, values, or mappings from an enumeration.\n\n```elixir\niex\u003e DayOfWeek.ordinals\n[:sunday, :monday, :tuesday, ...]\n\niex\u003e DayOfWeek.values\n[1, 2, 3, ...]\n\niex\u003e DayOfWeek.mappings\n[sunday: 1, monday: 2, tuesday: 3, ...]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinterest%2Friffed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinterest%2Friffed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinterest%2Friffed/lists"}