{"id":21657990,"url":"https://github.com/pinterest/elixir-thrift","last_synced_at":"2025-07-17T20:32:33.401Z","repository":{"id":3057790,"uuid":"43914111","full_name":"pinterest/elixir-thrift","owner":"pinterest","description":"A Pure Elixir Thrift Implementation","archived":false,"fork":false,"pushed_at":"2023-07-10T13:15:57.000Z","size":1079,"stargazers_count":214,"open_issues_count":34,"forks_count":44,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-11-14T22:10:44.767Z","etag":null,"topics":["elixir","rpc","thrift"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/thrift/","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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2015-10-08T20:17:30.000Z","updated_at":"2024-10-05T03:59:19.000Z","dependencies_parsed_at":"2023-07-06T10:01:59.655Z","dependency_job_id":null,"html_url":"https://github.com/pinterest/elixir-thrift","commit_stats":{"total_commits":544,"total_committers":21,"mean_commits":"25.904761904761905","dds":0.4834558823529411,"last_synced_commit":"7aecbfb10580113f524ad10f3b0304f30543621a"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Felixir-thrift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Felixir-thrift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Felixir-thrift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinterest%2Felixir-thrift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinterest","download_url":"https://codeload.github.com/pinterest/elixir-thrift/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226304252,"owners_count":17603545,"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","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","rpc","thrift"],"created_at":"2024-11-25T09:28:27.740Z","updated_at":"2024-11-25T09:28:30.189Z","avatar_url":"https://github.com/pinterest.png","language":"Elixir","funding_links":[],"categories":["Elixir"],"sub_categories":[],"readme":"# Elixir Thrift\n\n[![Hex Version](https://img.shields.io/hexpm/v/thrift.svg)](https://hex.pm/packages/thrift)\n[![Hex Docs](https://img.shields.io/badge/docs-hexpm-blue.svg)](https://hexdocs.pm/thrift/)\n[![Build Status](https://travis-ci.org/pinterest/elixir-thrift.svg?branch=master)](https://travis-ci.org/pinterest/elixir-thrift)\n[![Coverage Status](https://coveralls.io/repos/pinterest/elixir-thrift/badge.svg?branch=master)](https://coveralls.io/github/pinterest/elixir-thrift?branch=master)\n\nThis package contains an implementation of [Thrift](https://thrift.apache.org/)\nfor Elixir. It includes a Thrift IDL parser, an Elixir code generator, and\nbinary framed client and server implementations.\n\nThe generated serialization code is highly optimized and has been measured at\n**10 and 25 times faster**\u003csub\u003e[why?](#why-is-it-faster-than-the-apache-implementation)\u003c/sub\u003e\nthan the code generated by the Apache Thrift Erlang implementation.\n\n## Project Status\n\n[Version 2.0](https://github.com/pinterest/elixir-thrift/milestone/1) is under\nactively development and should be released soon. It is a complete rewrite\nthat drops the Apache Thrift dependency and implements everything in pure\nElixir.\n\n## Getting Started\n\nUntil version 2.0 is released, you'll need to track the master branch\ndirectly:\n\n```elixir\n{:thrift, github: \"pinterest/elixir-thrift\"}\n```\n\nThis package includes a Mix compiler task that automates Thrift code\ngeneration. Prepend `:thrift` to your project's `:compilers` list and add a\nnew top-level `:thrift` configuration key. The only necessary compiler option\nis `:files`, which defines the list of Thrift files that should be compiled.\n\n```elixir\n# mix.exs\ndefmodule MyProject.Mixfile do\n  # ...\n  def project do\n    [\n      # ...\n      compilers: [:thrift | Mix.compilers],\n      thrift: [\n        files: Path.wildcard(\"thrift/**/*.thrift\")\n      ]\n    ]\n  end\nend\n```\n\n## RPC Service Support\n\nWe provide full client and server support for Thrift RPC services. The examples\nbelow are based on this simplified service definition:\n\n```thrift\nservice Service {\n  i64 add(1: i64 left, 2: i64 right)\n}\n```\n\nYou can also check out the [full example project](example/) for a complete\nclient and server implementation of the sample calculator application.\n\n### Clients\n\nYou interact with Thrift services using generated, service-specific interface\nmodules. These modules handle type conversions and make calling the service's\nremote functions easier.\n\n```elixir\niex\u003e alias Calculator.Generated.Service.Binary.Framed.Client\niex\u003e {:ok, client} = Client.start_link(\"localhost\", 9090, [])\niex\u003e {:ok, result} = Client.add(client, 10, 20)\n{:ok, 30}\n```\n\nWe generate two versions of each function defined by the Thrift service's\ninterface: one that returns a standard result tuple, and a `!` variant that\nreturns a single result value but raises an exception if an error occurs.\n\n```elixir\n@spec add(pid(), integer(), integer(), Client.options()) :: {:ok, integer()} | {:error, any()}\ndef add(client, left, right, rpc_opts \\\\ [])\n\n@spec add!(pid(), integer(), integer(), Client.options()) :: integer()\ndef add!(client, left, right, rpc_opts \\\\ [])\n```\n\n### Servers\n\nIn order to start a Thrift server, you will need to provide a callback module\nthat implements the functions described by its service interface. Fortunately,\na [behaviour] module will be automatically generated for you, complete with\nsuccess typing.\n\n```elixir\ndefmodule Calculator.ServiceHandler do\n  @behaviour Calculator.Generated.Service.Handler\n\n  @impl true\n  def add(left, right) do\n    left + right\n  end\nend\n```\n\nThen provide your handler module when starting the server process:\n\n```elixir\niex\u003e alias Calculator.Generated.Service.Binary.Framed.Server\niex\u003e {:ok, server} = Server.start_link(Calculator.ServiceHandler, 9090, [])\n```\n\nAll RPC calls to the server will be delegated to the handler module. The server\nprovides a [supervisor] which can be added to your application's supervision\ntree. It's important to add it to your supervision tree with type `:supervisor`\nand not `:worker`.\n\n```elixir\ndefmodule Calculator.Application\n  alias Calculator.Generated.Service.Binary.Framed.Server\n\n  def start(_type, _args) do\n    children = [\n      server_child_spec(9090)\n    ]\n\n    opts = [strategy: :one_for_one, name: Calculator.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\n\n  defp server_child_spec(port) do\n    %{\n      id: Server,\n      start: {Server, :start_link, [Calculator.ServiceHandler, port]},\n      type: :supervisor\n    }\n  end\nend\n```\n\n[behaviour]: https://elixir-lang.org/getting-started/typespecs-and-behaviours.html#behaviours\n[supervisor]: https://elixir-lang.org/getting-started/mix-otp/supervisor-and-application.html\n\n## Serialization\n\nA `BinaryProtocol` module is generated for each Thrift struct, union, and\nexception type. You can use this interface to easily serialize and deserialize\nyour own types.\n\n```elixir\niex\u003e alias Calculator.Generated.Vector\niex\u003e data = %Vector{x: 1, y: 2, z: 3}\n|\u003e Vector.BinaryProtocol.serialize\n|\u003e IO.iodata_to_binary\niex\u003e Vector.BinaryProtocol.deserialize(data)\n{%Calculator.Generated.Vector{x: 1.0, y: 2.0, z: 3.0}, \"\"}\n```\n\n## Thrift IDL Parsing\n\nThe `Thrift.Parser` module parses [Thrift IDL][idl] documents and produces an\nabstract syntax tree. You can use these features to support additional\nlanguages, protocols, and servers.\n\n```elixir\nThrift.Parser.parse(\"enum Colors { RED, GREEN, BLUE }\")\n%Thrift.AST.Schema{constants: %{},\n enums: %{Colors: %Thrift.AST.TEnum{name: :Colors,\n    values: [RED: 1, GREEN: 2, BLUE: 3]}}, exceptions: %{}, includes: [],\n namespaces: %{}, services: %{}, structs: %{}, thrift_namespace: nil,\n typedefs: %{}, unions: %{}}\n```\n\n[idl]: https://thrift.apache.org/docs/idl\n\n## Debugging\n\nIn order to debug your Thrift RPC calls, we recommend you use [`thrift-tools`](https://github.com/pinterest/thrift-tools). It is a set of tools to introspect Apache Thrift traffic.\n\nTry something like:\n\n```\n$ pip install thrift-tools\n$ sudo thrift-tool --iface eth0 --port 9090 dump --show-all --pretty\n```\n\n## FAQ\n\n### Why is it faster than the Apache implementation?\n\nThe Apache Thrift implementation uses C++ to write Erlang modules that describe\nThrift data structures and then uses these descriptions to turn your Thrift\ndata into bytes. It consults these descriptions every time Thrift data is\nserialized/deserialized. This on-the-fly conversion costs CPU time.\n\nAdditionally, this separation of concerns in Apache Thrift prevent the Erlang\nVM from doing the best job that it can do during serialization.\n\nOur implementation uses Elixir to write Elixir code that's specific to _your_\nThrift structures. This serialization logic is then compiled, and that compiled\ncode is what converts your data to and from serialized bytes. We've spent a lot\nof time making sure that the generated code takes advantage of several of the\noptimizations that the Erlang VM provides.\n\n### What tradeoffs have you made to get this performance?\n\nThrift has the following concepts:\n\n1. **Protocols** Define a conversion of data into bytes.\n2. **Transports** Define how bytes move; across a network or in and out of a file.\n3. **Processors** Encapsulate reading from streams and doing something with the data. Processors are generated by the Thrift compiler.\n\nIn Apache Thrift, Protocols and Transports can be mixed and matched. However,\nour implementation does the mixing and matching for you and generates a\ncombination of (Protocol + Transport + Processor). This means that if you need\nto support a new Protocol or Transport, you will need to integrate it into this\nproject.\n\nPresently, we implement:\n\n* Binary Protocol, Framed Client\n* Binary Protocol, Framed Server\n\nWe are more than willing to accept contributions that add more!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinterest%2Felixir-thrift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinterest%2Felixir-thrift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinterest%2Felixir-thrift/lists"}