{"id":16549675,"url":"https://github.com/uiur/protorails","last_synced_at":"2025-07-16T08:40:59.563Z","repository":{"id":141425042,"uuid":"363826885","full_name":"uiur/protorails","owner":"uiur","description":"A toolkit to build type-safe Rails API with protocol buffers","archived":false,"fork":false,"pushed_at":"2021-12-17T08:38:13.000Z","size":54,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-08T22:11:07.129Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uiur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-03T05:34:51.000Z","updated_at":"2024-06-19T04:45:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"3668d252-40e4-43c4-8eb7-045f6f41d522","html_url":"https://github.com/uiur/protorails","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uiur/protorails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uiur%2Fprotorails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uiur%2Fprotorails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uiur%2Fprotorails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uiur%2Fprotorails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uiur","download_url":"https://codeload.github.com/uiur/protorails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uiur%2Fprotorails/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259293094,"owners_count":22835538,"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":[],"created_at":"2024-10-11T19:30:16.013Z","updated_at":"2025-06-11T16:04:29.091Z","avatar_url":"https://github.com/uiur.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protorails ![test](https://github.com/uiur/protorails/actions/workflows/ruby.yml/badge.svg)\n\n`protorails` is a toolkit to build type-safe API on Rails with Protocol Buffers (protobuf).\nIt's built on twitch's battle-tested [Twirp protocol](https://github.com/twitchtv/twirp). \n\nWrite API schema in protobuf, and it can generate API client for [TypeScript, Ruby or Java etc](https://github.com/twitchtv/twirp#implementations-in-other-languages).\n\nThe deployment is easy. [Twirp protocol](https://github.com/twitchtv/twirp/blob/master/PROTOCOL.md) is over HTTP 1.1. The server is just an ordinary Rails application.\nYou can integrate it easily onto an existing Rails application.\n\n## Features\n- Generators to generate protobuf definitions from models\n- Auto-reloading protobuf definitions in development\n- Zeitwerk support (Rails 6)\n\n## Overview\n\n### schema\nFirst, you need to define API interfaces. (They can be defined with generators)\n\n\nIn twirp, schema of API endpoints is defined by service and rpc.\n\n```proto\n// app/protos/minishop/order/order_service.proto\nsyntax = \"proto3\";\n\nimport \"minishop/order/show_request.proto\";\nimport \"minishop/order/order_resource.proto\";\n\npackage minishop.order;\n\nservice Order {\n  rpc Show(ShowRequest) returns (OrderResource);\n}\n```\n\nAnd schema of request and response is protobuf message.\n\n```proto\n// app/protos/minishop/order/show_request.proto\nsyntax = \"proto3\";\n\npackage minishop.order;\n\nmessage ShowRequest {\n  string id = 1;\n}\n```\n\n```proto\n// app/protos/minishop/order/order_resource.proto\nsyntax = \"proto3\";\n\nimport \"google/protobuf/timestamp.proto\";\npackage minishop.order;\n\nmessage OrderResource {\n  enum Status {\n    CART = 0;\n    ORDERED = 1;\n  }\n  string id = 1;\n  Status status = 2;\n  google.protobuf.Timestamp created_at = 5;\n  google.protobuf.Timestamp updated_at = 6;\n}\n```\n\n### implementation\nAnd compile the protobuf files to Ruby:\n\n```sh\n$ bin/rails proto:compile\n# This runs protobuf compilers (protoc)\n```\n\nImplement API actions just like usual Rails controllers:\n\nReturn value of an action must match the schema of API response (`minishop.order.OrderResource`).\n\n```ruby\n# app/controllers/orders_controller.rb\nclass OrdersController \u003c Protorails::BaseController\n  # ::Minishop::Order::OrderService is generated by protoc in: app/gens/minishop/order/order_service_twirp.rb\n  service ::Minishop::Order::OrderService\n\n  def show\n    order = Order.find(rpc_request.id)\n    order.as_json(only: [:id, :status, :created_at, :updated_at])\n  end\nend\n```\n\nThe routing is defined automatically.\n\n```ruby\n# config/routes.rb\nRails.application.routes.draw do\n  define_protorails_routes\n  # This automatically defines: POST /twirp/minishop.order.Order/Show =\u003e orders#show\nend\n```\n\n### api client\n\nYou can generate API clients from these definitions with protoc plugins.\n\nIf you want one in TypeScript, combine protoc and [its ts plugin](https://github.com/timostamm/protobuf-ts) with it:\n\n```sh\nprotoc -I=../app/protos --ts_out=front/src/gen $(find ../app/protos -name '*.proto')\n```\n\nIt generates api clients and type interface like:\n\n```typescript\nconst client = new OrderClient(transport)\nconst { response } = await client.show({ id: orderId })\n```\n\n```typescript\n/**\n * @generated from protobuf message minishop.order.OrderResource\n */\nexport interface OrderResource {\n  /**\n   * @generated from protobuf field: string id = 1;\n   */\n  id: string\n  /**\n   * @generated from protobuf field: minishop.order.OrderResource.Status status = 2;\n   */\n  status: OrderResource_Status\n  /**\n   * @generated from protobuf field: int32 amount = 3;\n   */\n  amount: number\n}\n```\n\n## Usage\n\nBy default, this gem assumes a project has:\n\n- protobuf files under `app/protos`\n- compiled Ruby protobuf files in `app/gens`\n\n\nUse generator to bootstrap service:\n\n```sh\n$ bin/rails g proto:service order show\n  create  app/protos/minishop/order/order_service.proto\n  create  app/protos/minishop/order/show_request.proto\n  create  app/protos/minishop/order/show_response.proto\n```\n\nYou can specify package name:\n\n```sh\n$ bin/rails g proto:service order show --package minishop.v1.order\n  create  app/protos/minishop/v1/order/order_service.proto\n  create  app/protos/minishop/v1/order/show_request.proto\n  create  app/protos/minishop/v1/order/show_response.proto\n```\n\nGenerate an equivalent protobuf definition from a model:\n\n```sh\n$ bin/rails g proto:resource order\n```\n\n## Status\nalpha: prototype for proof of concept\n\nThere's a sample application: https://github.com/uiur/minishop\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'protorails'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n\n```bash\n$ gem install protorails\n```\n\n## Contributing\n\nContribution directions go here.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuiur%2Fprotorails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuiur%2Fprotorails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuiur%2Fprotorails/lists"}