rails_respond_to_pb 0.1.1 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6aead0d00f97d47b6b8131b96ba6aed319349e8f12c9b3ac5eeddc1a75becfa
-  data.tar.gz: 7d2a51d4f9b722b9143e74c7796a89f0de75e7211a42b6b5f356745ddf5c23f2
+  metadata.gz: '09ed10071e15cae2742131c4b74c13bac6b3cc80b2edc6ee60b81ff5e91bdee2'
+  data.tar.gz: c78440085c1a1d54ec466914b72f69de3f9494a7a3017bb29f47c28b6ac4cbcd
 SHA512:
-  metadata.gz: 6e266a4185a7d352ae3dd8c1c20f0edb6eb5b92911d72bce0fc98eca995dd9bbfd74dd29c9de82297a2b1e4a89ceb7733779c911bd7f31f6ec15e41ddcf526cc
-  data.tar.gz: bba14ac758f6cdcde1ba40d1f48edac8b193c1ad481340f0dd96ddf2faf67f664aba61a7fa5b1666b2fff9cd6f117275c9638742d655ab845a34d1eac4d724a6
+  metadata.gz: 9cdbb62f49ac387715472fb81df4ed0808df18746821e26e2bfd08ecf1e6bd0022a0791ed726c5a6282fd875092cde6a463f40ab2e739184d3c2a24d21607003
+  data.tar.gz: 3154c18d4cb1282193bd117c556713bed7b21724a86e1dca42f603a3417162c69dd3e05316c86393a91e50823eb08d903e0681a29eeade13305a7c47c84db9ef

data/CHANGELOG.md

@@ -5,6 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.1.1
+## 0.1.3
 
 - In the beginning...

data/README.md

@@ -1,8 +1,10 @@
-# RailsRespondToPb
+# rails_respond_to_pb
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rails_respond_to_pb`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/rails_respond_to_pb.svg)](https://badge.fury.io/rb/rails_respond_to_pb)
 
-TODO: Delete this and the text above, and describe your gem
+This gem allows you to route RPC calls via protobuf to an existing rails controller. Currently supporting:
+
+- [Twirp](https://github.com/twitchtv/twirp-ruby)
 
 ## Installation
 
@@ -14,25 +16,171 @@ gem 'rails_respond_to_pb'
 
 And then execute:
 
-    $ bundle install
+```sh
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install rails_respond_to_pb
+```sh
+gem install rails_respond_to_pb
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+This gem loads Rails middleware that routes to services with Controllers as Handlers.
+
+- assumes a single `ThingsService` per controller
+  - Typical Rails namey-ness conventions are followed here
+    - assumes a `ThingsService` routes to a `ThingsController`
+    - looking into building generating proto files from controllers
+- loads any `_twirp.rb` files that exist within your app's `lib` directory
+- allows a controller to `respond_to` the `pb` format
+  - currently you'd respond with a `render plain: ThingResponse.new(id: 1, name: 'Foo').to_proto`
+    - looking into `render pb:`
+
+Generate a proto like this for each of your controllers (`rpc` methods should match your controller methods. `message` is to your discretion):
+
+```proto
+syntax = "proto3";
+
+service Things {
+  // these rpc methods are important - use what's in the corresponding ThingsController.
+  // whatever is sent as an argument will be made available to the controller as `params`
+  rpc Create (ThingParams) returns (ThingResponse);
+  rpc Show (ThingParams) returns (ThingResponse);
+  rpc Index (ThingFilter) returns (ThingList);
+  rpc Update (ThingParams) returns (ThingResponse);
+  rpc Destroy (ThingParams) returns (ThingResponse);
+}
+
+message ThingParams {
+  int32 id = 1;
+  string name = 2;
+}
+
+message ThingFilter {
+  string name = 1;
+}
+
+message ThingResponse {
+  int32 id = 1;
+  string name = 2;
+}
+
+message ThingList {
+  repeated ThingResponse things = 1;
+}
+```
+
+### Server
+
+This gem will allow your app to respond to Twirp requests. There is little setup required, other than having the prerequisite Service files loaded in your application.
+
+Given a Service file of `ThingsService`, this gem assumes the presence of a `ThingsController` with actions corresponding with `rpc` methods. To allow your controller to respond to the RPC request, simply update the action accordingly:
+
+```ruby
+def index
+  # ... business as usual
+
+  respond_to do |format|
+    format.pb do
+      render plain: ThingList.new(things: Thing.all.map { |r| ThingResponse.new(r.as_json) }).to_proto
+    end
+    format.json { render: Thing.all.as_json } # or whatever your controller responds to usually
+  end
+end
+```
+
+The **required** setup here is:
+
+```ruby
+respond_to do |format|
+    format.pb do
+      render plain: YourProtoResponse.to_proto
+```
+
+Of note, if you're trying to wire up **entirely new** methods, you do **NOT** need this gem at all, and you can simply add this to your routes file:
+
+```ruby
+handler = ThingsHandler.new()
+service = ThingsService.new(handler)
+
+mount service, at: service.full_name
+```
+
+### Client
+
+Assuming you have the prerequisite Client files loaded in your application, you can connect to a Twirp server as usual:
+
+```ruby
+client = ThingsClient.new('http://localhost:3000')
+query = ThingFilter.new name: 'foo'
+client.index(query)
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+I typically add an alias to make working with dockerized apps easier. This assumes [docker](https://docs.docker.com/get-docker/) is running.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```sh
+alias dr="docker compose run --rm "
+```
+
+After checking out the repo, run `dr bundle install` to spin up a container, and install dependencies. Then, run `dr rspec spec` to run the tests. You can also run `dr bundle console` for an interactive prompt that will allow you to experiment.
+
+To release a new version, update the version number in `version.rb`, and then run `dr bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Building protos
+
+For inspiration on how to build proto files locally (and working with docker-compose), here are some services to use within your application:
+
+```yaml
+services:
+  bundle: &bundle # run your typical bundle commands
+    env_file: .env
+    stdin_open: true
+    tty: true
+    build: .
+    entrypoint: bundle
+    command: check
+    volumes:
+      - .:/usr/src/app:delegated # hot reload your application's code
+      - bundle:/usr/local/bundle:delegated # cache bundle installs
+      - ~/Projects:/local # used to install gems locally rename ~/Projects to whichever dir your code lives in
+
+  rspec: # run your tests!!
+    <<: *bundle
+    entrypoint: bundle exec rspec
+    command: --version
+
+  protoc: # generate code from proto files
+    build: .
+    entrypoint: bundle
+    command: |
+      exec grpc_tools_ruby_protoc
+      -I ./lib/protos --ruby_out=./lib/protobuf --twirp_ruby_out=./lib/protobuf
+      ./lib/protos/things.proto
+    volumes:
+      - .:/usr/src/app:delegated
+      - bundle:/usr/local/bundle:delegated
+```
+
+The `twirp_ruby_out` function needs to be made available to your environment. Use a multistage file, like so:
+
+```dockerfile
+FROM golang:1 AS go
+RUN go get github.com/twitchtv/twirp-ruby/protoc-gen-twirp_ruby
+
+# or whatever version of ruby you're using
+FROM ruby:3
+# Install necessary executable to build protos
+COPY --from=go /go/bin /usr/local/bin
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rails_respond_to_pb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/[USERNAME]/rails_respond_to_pb). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +188,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the RailsRespondToPb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the RailsRespondToPb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/main/CODE_OF_CONDUCT.md).

data/docker-compose.yml

@@ -9,6 +9,10 @@ services:
     volumes:
       - .:/usr/src/gem:delegated
       - bundle:/usr/local/bundle:delegated
+      - ~/.gitconfig:/etc/gitconfig:ro
+      - ~/.ssh:/root/.ssh:ro
+      - ~/.gemrc:/etc/.gemrc:ro
+      - ~/.local/share/gem/credentials:/root/.local/share/gem/credentials:ro
 
   rspec:
     <<: *bundle

data/lib/rails_respond_to_pb/respond_to_pb.rb

@@ -33,10 +33,10 @@ class RespondToPb
   end
 
   def service_class
-    ::ActiveSupport::Dependencies.constantize("#{@resource}Service")
+    "#{@resource}Service".constantize
   end
 
   def controller_class
-    ::ActiveSupport::Dependencies.constantize("#{@resource}Controller")
+    "#{@resource}Controller".constantize
   end
 end

data/lib/rails_respond_to_pb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsRespondToPb
-  VERSION = '0.1.1'
+  VERSION = '0.1.5'
 end

data/rails_respond_to_pb.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Middleware for a Rails App providing functionality for gRPC and Twirp'
   spec.homepage      = 'https://github.com/dudo/rails_respond_to_pb'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7')
 
   # spec.metadata['allowed_push_host'] = 'http://mygemserver.com'
 
@@ -29,7 +29,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.add_runtime_dependency 'grpc-tools', '~> 1.38'
   spec.add_runtime_dependency 'rails', ENV['RAILS_VERSION'] || '>= 6'
+  spec.add_runtime_dependency 'twirp', '~> 1.7'
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rails_respond_to_pb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
 platform: ruby
 authors:
 - Brett C. Dudo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-08-18 00:00:00.000000000 Z
+date: 2021-12-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: grpc-tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.38'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.38'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6'
+- !ruby/object:Gem::Dependency
+  name: twirp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 description: Middleware for a Rails App providing functionality for gRPC and Twirp
 email:
 - brett@dudo.io
@@ -67,14 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: Middleware for a Rails App providing functionality for gRPC and Twirp