thrifter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fd99b7900e55cc7abcfe145198cb184b4dd27d28
+  data.tar.gz: b5aeb9adef656c411b43327a619496f0dd46b429
+SHA512:
+  metadata.gz: 30d3d385ef740047a5dae0b0f704518a5e9c77e551bd29d7cf991a65b33fb5255a4b246571e6088ae36a457bb5ca37a9d90dda2c949efd50f3bfcb7431ce09be
+  data.tar.gz: c0c644e11697991a4f2187dd505906a53de4829d74f7653b7f65ef25965ddf6649a78caca0f5d5e05a64ab9385d805f6c981a6cadbc380c43b898391f73711e0

data/.dockerignore

@@ -0,0 +1,3 @@
+.vagrant
+.git
+tmp

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Dockerfile

@@ -0,0 +1,15 @@
+FROM ruby:2.1
+
+RUN mkdir -p /app/lib/thrifter
+
+WORKDIR /app
+
+# Add only the files that are required to run bundle installer.
+# Remaining library code will be provided via a volume
+ADD Gemfile /app/
+ADD thrifter.gemspec /app/
+ADD lib/thrifter/version.rb /app/lib/thrifter/
+
+RUN bundle install -j $(nproc)
+
+CMD [ "bundle", "console" ]

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in thrifter.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 ahawkins
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Makefile

@@ -0,0 +1,57 @@
+THRIFT:=vendor/gen-rb/test_types.rb
+
+BUNDLE:=tmp/bundle
+DOCKER_IMAGES:=tmp/docker_images
+
+BUNDLE_IMAGE:=thrifter/bundle
+
+# CircleCI does not support --rm, so if the environment variable has
+# value, then don't include --rm.
+ifneq ($(shell echo $$CIRCLECI),)
+DOCKER_RUN:=docker run -it
+else
+DOCKER_RUN:=docker run --rm -it
+endif
+
+$(THRIFT): test.thrift
+	mkdir -p $(@D)
+	thrift -o vendor --gen rb test.thrift
+
+$(DOCKER_IMAGES):
+	mkdir -p $(@D)
+	touch $@
+		
+$(BUNDLE): Dockerfile thrifter.gemspec $(DOCKER_IMAGES)
+	docker build -t $(BUNDLE_IMAGE) .
+	docker inspect -f '{{ .Id }}' $(BUNDLE_IMAGE) >> $(DOCKER_IMAGES)
+
+.PHONY: test
+# For quick and easy access to the most common thing
+test: test-lib
+
+.PHONY: test-lib
+test-lib: $(THRIFT) $(BUNDLE)
+	$(DOCKER_RUN) -v $(CURDIR):/app $(BUNDLE_IMAGE) bundle exec rake test
+
+.PHONY: test-ci
+test-ci: test-lib test-monkey
+
+.PHONY: test-monkey
+test-monkey: teardown
+	docker run -d -v $(CURDIR):/app --name server $(BUNDLE_IMAGE) script/server
+	$(DOCKER_RUN) --link server:server -v $(CURDIR):/app \
+		$(BUNDLE_IMAGE) script/monkey-client server:9090
+
+.PHONY:
+release:
+	bundle exec rake release
+
+.PHONY: treadown
+teardown:
+	-docker stop server 2> /dev/null
+	-docker rm server 2> /dev/null
+
+.PHONY: clean
+clean: $(DOCKER_IMAGES) teardown
+	-sort -u $(DOCKER_IMAGES) | xargs --no-run-if-empty docker rmi 2> /dev/null
+	rm -f $(DOCKER_IMAGES) $(APP)

data/README.md

@@ -0,0 +1,283 @@
+# Thrifter
+
+Thrifter addresses the shortcoming in the official library for
+production uses. It's most important features are:
+
+* Thread safe via connection pool
+* Safe for use in long running processes
+* Simple RPC queuing
+* Retry support
+* Proper timeouts by default
+* Metrics
+* Better error handling
+* Middleware
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'thrifter'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install thrifter
+
+## Usage
+
+`Thrifer` is a factory (similar to `DelegateClass`) for building
+client classes. It can be used like `DelegateClass` or like `Struct`.
+The result is subclasses of `Thrifter::Client`. The classes use the
+same methods to make RPCs. For example if the thrift service has a
+`fooBar` RPC, the generated class has a `fooBar` method to invoke the
+RPC. Here are some examples.
+
+```ruby
+# Struct style
+ServiceClient = Thrifter.build(MyService::Client)
+
+The struct style take a block as well
+ServiceClient = Thrifer.build(MyService::Client) do
+  def custom_method(args)
+    # something something
+  end
+end
+
+# Delegate class style (easiest to add abstractions)
+class MyServiceClient < Thrifter.build(MyService::Client)
+  def custom_method(args)
+    # something something
+  end
+end
+```
+
+### Configuration
+
+`Thrifter` uses a configuration object on each class to track
+dependent objects. Configured objects are injected into each instance.
+This makes it easy to configure classes in different environment (e.g.
+production vs test). All settings are documented below. `uri` is the
+most important! It must be set to instantiate clients.
+
+```ruby
+class MyClient < Thrifer.build(MyService::Client)
+  # Thrift specific things
+  config.transport = Thrift::FramedTransport
+  config.protocol = Thrift::BinaryTransport
+
+  # Pool settings
+  config.pool_size = 12
+  config.pool_timeout = 0.15
+
+  # Network Settings
+  config.rpc_timeout = 0.15
+
+  # Required to instantiate the client!
+  config.uri = 'tcp://foo:2383'
+end
+
+#The common block form is supported as well
+MyClient.configure do |config|
+  # ... same as above
+end
+```
+
+### RPC Metrics with Statsd
+
+Statsd metrics are **opt-in**. By default, `Thrifter` sets the statsd
+client to a null implementation. If you want metrics, set
+`config.statsd` to an object that implements the [statsd-ruby][]
+interface. `Thrifter` emits the following metrics:
+
+* time on each rpc calls
+* number of `Thrift::TransportException`
+* number of `Thrift::ProtocolExeption`
+* number of `Thrift::ApplicationExeption`
+* number of `Timeout::Error`
+* number of generic errors (e.g. none of the above known errors)
+
+It's recommended that the `statsd` object do namespacing
+(statsd-ruby has it built in). This ensures client metrics don't
+get intermingled with wider application metrics. Here's an example:
+
+```ruby
+ServiceClient = Thrifter.build(MyService::Client)
+# Now in production.rb
+ServiceClient.config.statsd = Statsd.new namespace: 'my_service'
+```
+
+### RPC Queuing
+
+Certain systems may need to queue RPCs to other systems. This is only
+useful for `void` RPCs or for when an outside system may be flaky.
+Assume `MyService` has a `logStats` RPC. Your application is producing
+stats that should make it upstream, but there are intermitent network
+problems effeciting stats collection. Include `Thrift::Queueing` and
+any RPC will automatically be sent to sidekiq for eventual processing.
+
+```ruby
+class ServiceClient < Thrifter.build(MyService::Client)
+  include Thrifter::Queuing
+end
+```
+
+Now instances of `ServiceClient` now respond to `queued`. This returns
+a queue based instance. All RPC methods will work as usual. Here's an
+example:
+
+```ruby
+# Assume client is an instance of ServiceClient
+my_service.queued.logStats({ 'users' => 5 })
+
+# Naturally the block form may be used as well
+my_service.queued do |queue|
+  queue.logStats({ 'sessions' => 50 })
+  queue.logStats({ 'posts' => 30 })
+end
+```
+
+All RPCs will be sent to the `thrift` sidekiq queue. They will follow
+default sidekiq retry backoff and the like.
+
+### RPC Retrying
+
+Systems have syncrhonous RPCs. Unfortunately sometimes these don't
+work for whatever reason. It's good practice to retry these RPCs
+(within certain limits) if they don't succeed the first time.
+`Thrift::Retriable` is perfect for this use case.
+
+```ruby
+class ServiceClient < Thrifter.build(MyService::Client)
+  include Thrifter::Retriable
+end
+```
+
+```ruby
+# Assume client is an instance of ServiceClient
+
+# logStats will be retried 3 times at 0.1 second intervals if any
+# known thrift or network errors happen.
+my_service.with_retry.logStats({ 'users' => 5 })
+
+# These settings can be customized by the retriable method.
+my_sevice.with_retry({tries: 10, delay: 0.3 }).logStats({ 'sessions' => 50 })
+
+# Naturally the block form may be used as well
+my_service.with_retry do |with_retry|
+  with_retry.logStats({ 'sessions' => 50 })
+  with_retry.logStats({ 'posts' => 30 })
+end
+```
+
+`Thrift::Retriable` is a simple retry solution for syncronous RPCs.
+Look into something like [retriable][] if you want a more robust
+solution for different use cases.
+
+### Middleware
+
+The middleware approach is great for providing a flexible extension
+points to hook into the RPC process. `Thrifter::Client` provides a
+middleware implementation to common to many other ruby libraries.
+Middleware can only be customized at the class level. This ensures
+middleware applies when used in extensions.
+
+```ruby
+class MyClient < Thrifter.build(MyService::Client)
+  use MyMiddlware
+  use MySecondMiddleware
+end
+```
+
+Since middleware must defined at the class level, you should defer
+setting up middleware that depend on objects until process boot. For
+example, if you have `LoggingMiddleware` and you need to log to
+different places depending on environment, you should add the
+middleware in whatever code configurres that environment. Only static
+middleware should be configured directly in the class itself.
+
+A middleware must implement the `call` method and accept at least one
+argument to `initialize`. The `call` method recieves a `Thrifer::RPC`.
+`Thrifter::RPC` is a sipmle struct with a `name` and `args` methods.
+Here's an example:
+
+```ruby
+class LoggingMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(rpc)
+    puts "Running #{rp.name} with #{rpc.args.inspect}"
+	@app.call rpc
+  end
+end
+```
+
+### Error Wrapping
+
+A lot of things can go wrong in the thrift stack. This means the
+caller may need to deal with a large amount of different exceptions.
+For example, does it really matter if `Thrift::ProtocolException` or
+`Thrift::TransportException` was raied? Can the caller recover from
+either of them? No. So instead of allowing these semantics to
+propogate up abstraction levels, it's better to encapsulate them in a
+single error. This is easily implemented with a middleware and once is
+included in the library. When this middleare is used, all known
+networking & thrift exceptions will be raised as
+`Thrifter::ClientError`.
+
+```ruby
+class MyService < Thrifter.build(MyService::Client)
+  use Thrifter::ErrorWrapping
+end
+```
+
+A list of other known error classes can be provided to wrap more than
+the library's known set.
+
+```ruby
+class MyService < Thrifter.build(MyService::Client)
+  use Thrifter::ErrorWrapping, [ SomeErrorClass ]
+end
+```
+
+Note, `Thrifter` will still count individual errors as described in
+the metrics section.
+
+### Pinging
+
+Components in a system may need to inquire if other systems are
+available before continuing. `Thrifer::Ping` is just that.
+`Thrifter::Ping` assumes the service has a `ping` RPC. If your
+service does not have one (or is named differently) simply implement
+the `ping` method on the class. Any successful response will count as
+up, anything else will not.
+
+```ruby
+class MyService < Thrifer.build(MyService::Client)
+  include Thrifer::Ping
+
+  # Define a ping method if the service does not have one
+  def ping
+    my_other_rpc
+  end
+end
+
+# my_service.up? # => true
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/saltside/thrifter/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+[retriable]: https://github.com/kamui/retriable
+[statsd-ruby]: https://github.com/reinh/statsd

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.test_files = Rake::FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/Vagrantfile

@@ -0,0 +1,126 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  # All Vagrant configuration is done here. The most common configuration
+  # options are documented and commented below. For a complete reference,
+  # please see the online documentation at vagrantup.com.
+
+  # Every Vagrant virtual environment requires a box to build off of.
+  config.vm.box = "ubuntu/trusty64"
+
+  config.vm.provision "docker" do |docker|
+    docker.pull_images "ruby:2.1"
+  end
+
+  # Disable automatic box update checking. If you disable this, then
+  # boxes will only be checked for updates when the user runs
+  # `vagrant box outdated`. This is not recommended.
+  # config.vm.box_check_update = false
+
+  # Create a forwarded port mapping which allows access to a specific port
+  # within the machine from a port on the host machine. In the example below,
+  # accessing "localhost:8080" will access port 80 on the guest machine.
+  # config.vm.network "forwarded_port", guest: 80, host: 8080
+
+  # Create a private network, which allows host-only access to the machine
+  # using a specific IP.
+  # config.vm.network "private_network", ip: "192.168.33.10"
+
+  # Create a public network, which generally matched to bridged network.
+  # Bridged networks make the machine appear as another physical device on
+  # your network.
+  # config.vm.network "public_network"
+
+  # If true, then any SSH connections made will enable agent forwarding.
+  # Default value: false
+  # config.ssh.forward_agent = true
+
+  # Share an additional folder to the guest VM. The first argument is
+  # the path on the host to the actual folder. The second argument is
+  # the path on the guest to mount the folder. And the optional third
+  # argument is a set of non-required options.
+  # config.vm.synced_folder "../data", "/vagrant_data"
+
+  # Provider-specific configuration so you can fine-tune various
+  # backing providers for Vagrant. These expose provider-specific options.
+  # Example for VirtualBox:
+  #
+  # config.vm.provider "virtualbox" do |vb|
+  #   # Don't boot with headless mode
+  #   vb.gui = true
+  #
+  #   # Use VBoxManage to customize the VM. For example to change memory:
+  #   vb.customize ["modifyvm", :id, "--memory", "1024"]
+  # end
+  #
+  # View the documentation for the provider you're using for more
+  # information on available options.
+
+  # Enable provisioning with CFEngine. CFEngine Community packages are
+  # automatically installed. For example, configure the host as a
+  # policy server and optionally a policy file to run:
+  #
+  # config.vm.provision "cfengine" do |cf|
+  #   cf.am_policy_hub = true
+  #   # cf.run_file = "motd.cf"
+  # end
+  #
+  # You can also configure and bootstrap a client to an existing
+  # policy server:
+  #
+  # config.vm.provision "cfengine" do |cf|
+  #   cf.policy_server_address = "10.0.2.15"
+  # end
+
+  # Enable provisioning with Puppet stand alone.  Puppet manifests
+  # are contained in a directory path relative to this Vagrantfile.
+  # You will need to create the manifests directory and a manifest in
+  # the file default.pp in the manifests_path directory.
+  #
+  # config.vm.provision "puppet" do |puppet|
+  #   puppet.manifests_path = "manifests"
+  #   puppet.manifest_file  = "site.pp"
+  # end
+
+  # Enable provisioning with chef solo, specifying a cookbooks path, roles
+  # path, and data_bags path (all relative to this Vagrantfile), and adding
+  # some recipes and/or roles.
+  #
+  # config.vm.provision "chef_solo" do |chef|
+  #   chef.cookbooks_path = "../my-recipes/cookbooks"
+  #   chef.roles_path = "../my-recipes/roles"
+  #   chef.data_bags_path = "../my-recipes/data_bags"
+  #   chef.add_recipe "mysql"
+  #   chef.add_role "web"
+  #
+  #   # You may also specify custom JSON attributes:
+  #   chef.json = { mysql_password: "foo" }
+  # end
+
+  # Enable provisioning with chef server, specifying the chef server URL,
+  # and the path to the validation key (relative to this Vagrantfile).
+  #
+  # The Opscode Platform uses HTTPS. Substitute your organization for
+  # ORGNAME in the URL and validation key.
+  #
+  # If you have your own Chef Server, use the appropriate URL, which may be
+  # HTTP instead of HTTPS depending on your configuration. Also change the
+  # validation key to validation.pem.
+  #
+  # config.vm.provision "chef_client" do |chef|
+  #   chef.chef_server_url = "https://api.opscode.com/organizations/ORGNAME"
+  #   chef.validation_key_path = "ORGNAME-validator.pem"
+  # end
+  #
+  # If you're using the Opscode platform, your validator client is
+  # ORGNAME-validator, replacing ORGNAME with your organization name.
+  #
+  # If you have your own Chef Server, the default validation client name is
+  # chef-validator, unless you changed the configuration.
+  #
+  #   chef.validation_client_name = "ORGNAME-validator"
+end