thrift_server 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 41fa482d2834f442ecc5900d82d3042ac91512a7
-  data.tar.gz: 65b5c1e6814cf096dbe6ab3492d859adad5cbc06
+  metadata.gz: 3c56d48273a394c80954def741cd2a44a285a019
+  data.tar.gz: 81f9248137da46630ed0bb415245db3121cb7087
 SHA512:
-  metadata.gz: 1a51fac841e4c11faa84121d6b13cf20e068c62e323e7bcd4d3fca7d1541818df1417f5fe67951f7f7d22baa73b3d396b051bdf9e1d072abd5ceb584b1665416
-  data.tar.gz: 3dee701b61ca406d448684664ed5ddec2d7e1e02b55b421622d54bbd38676885d1f65e20278b9a44a258fb7d0e1837472c50970911885d911ac0fbc0c8e48a97
+  metadata.gz: bfb2867a32d7603d8f511bd35afe3e1df1b8f707c42829a4d9790de1b02e350586d7c237be54bd0b75b5310b6d70a75558762379c2ed13b3c8b6168f95a9f9be
+  data.tar.gz: 7ff824cc62f161ac6d18779b035632a081eefd9cfdb2b66d8d1e9a2745c239f242ccce628b8874fe7214c90778ba4a10afc14051849f151832efbf38f51e00e6

data/Dockerfile

@@ -9,4 +9,6 @@ ADD thrift_server.gemspec /usr/src/app/thrift_server.gemspec
 
 RUN bundle install
 
+ADD . /usr/src/app
+
 CMD [ "bundle", "console" ]

data/Makefile

@@ -2,16 +2,22 @@ APP:=thrift_server
 
 .DEFAULT_GOAL:=build
 
-APP_RUN:=docker run --rm -t -v $(CURDIR):/usr/src/app $(APP)
+# 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
 
 gen-rb/echo_service.rb: echo_service.thrift
-	docker run --rm -t -v $(CURDIR):/data thrift:0.9.2 \
+	$(DOCKER_RUN) -v $(CURDIR):/data thrift:0.9.2 \
 		thrift -o /data --gen rb /data/$<
 
 .PHONY: thrift
 thrift: gen-rb/echo_service.rb
 
-tmp/image: Dockerfile Gemfile lib/thrift_server/version.rb thrift_server.gemspec
+tmp/image: Dockerfile lib/thrift_server/version.rb thrift_server.gemspec gen-rb/echo_service.rb
 	docker build -t $(APP) .
 	mkdir -p $(@D)
 	docker inspect -f '{{.Id}}' $(APP) >> $@
@@ -19,24 +25,31 @@ tmp/image: Dockerfile Gemfile lib/thrift_server/version.rb thrift_server.gemspec
 .PHONY: build
 build: tmp/image
 
+.PHONY: test
+test: tmp/image
+	$(DOCKER_RUN) -v $(CURDIR):/usr/src/app $(APP) bundle exec rake
+
 .PHONY: test-unit
-test-unit: tmp/image
-	$(APP_RUN) bundle exec rake
+test-lib: tmp/image
+	$(DOCKER_RUN) $(APP) bundle exec rake
 
 .PHONY: test-network
-test-network: tmp/image gen-rb/echo_service.rb
-	-@docker stop server > /dev/null 2>&1
-	-@docker rm -v server > /dev/null 2>&1
-	docker run -d --name server -v $(CURDIR):/usr/src/app $(APP) ruby echo_server.rb
-	docker run --rm -t -v $(CURDIR):/usr/src/app --link server:server $(APP) ruby echo_client.rb server 9090
+test-network: tmp/image gen-rb/echo_service.rb clean-containers
+	docker run -d --name threaded_server $(APP) ruby echo_server.rb --threaded
+	docker run -d --name thread_pool_server $(APP) ruby echo_server.rb --thread-pool
+	$(DOCKER_RUN) --link threaded_server:server $(APP) ruby echo_client.rb server 9090
+	$(DOCKER_RUN) --link thread_pool_server:server $(APP) ruby echo_client.rb server 9090
 
 .PHONY: test-ci
-test-ci: test-unit test-network
+test-ci: test-lib test-network
+
+.PHONY: clean-containers
+clean-containers:
+	-@docker stop thread_pool_server threaded_server > /dev/null 2>&1
+	-@docker rm -v thread_pool_server threaded_server > /dev/null 2>&1
 
 .PHONY: clean
-clean:
-	-docker stop server > /dev/null 2>&1
-	-docker rm -v server > /dev/null 2>&1
+clean: clean-containers
 	@mkdir -p tmp
 	@touch tmp/image
 	-cat tmp/image | xargs --no-run-if-empty docker rmi

data/README.md

@@ -3,13 +3,11 @@
 Encapsulate bolierplate code and functionality for running Thrift
 servers in Ruby. Bundled functionality:
 
-* Error tracking
-* Metrics on each RPC
-* Logging on each RPC
-* Middleware based approaching making it easy to extend
-* Binary protocol
-* Framed transport
-* Thread pool sever
+* Metrics for server & RPCs
+* Logging for server events & RPCs
+* Middleware & pub-sub based approach making it easy to extend
+* Deep validation on outgoing protocol messages
+* `Thrift::ThreadPoolServer` & `Thrift::ThreadedServer` support
 
 ## Installation
 
@@ -27,31 +25,129 @@ Or install it yourself as:
 
 ## Usage
 
-The libary is defined to wrapping Thrift's processor classes in useful
-functionality for production servers. You must provide objects
-required to implement the behavior. Here's an example from
-[echo\_server.rb](echo_server.rb).
+The library uses delegation to around a provided handler & Thrift
+processor to implement use production server behavior. There are two
+different ways to extend function: pub sub & middleware. Use pub sub
+for events & middleware when you want to modify the request & response
+before/after hitting the handler. Out of the box there is not extra
+behavior. Here's the bare bones useful server.
 
-    server = ThriftServer.build(EchoService::Processor, Handler.new, {
-        logger: Logger.new($stdout),
-        statsd: Statsd.new,
-        error_tracker: ErrorTracker.new
-    })
+	server = ThriftServer.threaded EchoService, Handler.new
 
-    # Now call serve to start it
-    server.serve
+	server.log Logger.new($stdout)
 
-The first arument is a generated `Thrift::Processor` subclass. The second
-is your implementation of the define protocol. The options hash
-defines all the misc objecs and settings. The following options are
-available:
+	server.start
 
-* `logger:` - a `Logger` instance
-* `statsd:` - a `Statsd` instance from the [statsd-ruby gem](https://github.com/reinh/statsd)
-* `error_tracker:` object that implement `#track(rpc, error)`. Use
-  `ThriftServer::HoneybaderErrorTracker` if unsure
-* `threads:` - number of threads to run. Defaults to `4`
-* `port:` - port to run server on. Defaults to `9090`
+The first arument is a module containing a generated
+`Thrift::Processor` subclass or the module itself. `ThriftServer`
+provides factories for building `Thrift::ThreadedServer` and
+`Thrift::ThreadPoolServer` instances.
+
+### Threaded Servers
+
+	server = ThriftServer.threaded EchoService, Handler.new
+
+	server.log Logger.new($stdout)
+
+	server.start
+
+`ThriftServer.threaded` accepts the following options:
+
+* `port:` - port to run server on. Defaults to `9090`.
+
+### Thread Pool Servers
+
+	server = ThriftServer.thread_pool EchoService, Handler.new
+
+	server.log Logger.new($stdout)
+
+	server.start
+
+`ThriftServer.threaded` accepts the following options:
+
+* `threads:` - Pool size. Defaults to `25`.
+* `port:` - port to run server on. Defaults to `9090`.
+
+## Pub Sub
+
+Subscriber objects may be attached. The following events are
+published:
+
+* `rpc_incoming` - published everytime the server receives an RPC
+* `rpc_ok` - Everything when according to plan
+* `rpc_exception` - Handler raised an exception defined in the
+  protocol
+* `rpc_error` - Handler raised an unexpected error (useful for error
+  tracking)
+* `server_start` - Start started
+* `server_connection_opened` - Client TCP connection
+* `server_connection_closed` - Client TCP disconnect
+* `thread_pool_server_pool_change` - Thread pool grow/shinks
+
+The listener should implement a method. A listener will only receive
+notifications if the appropriate method is implemented. Here's an
+example:
+
+	class Counter
+		def initialize
+			@counter = 0
+		end
+
+		def rpc_incoming(rpc)
+			@counter += 1
+		end
+	end
+
+	server = ThriftServer.threaded EchoService, Handler.new
+	server.subscribe Counter.new
+
+### Built-in Subscribers
+
+`ThriftServer` includes three subscribers: two for metrics and one for
+logging. The `ThriftServer::LogSubscriber` uses a standard library
+logger to print useful information when any of the previously
+mentioned events happen. Attaching the subscriber is so important that
+it has its own helper method.
+
+	server.log Logger.new($stdout)
+	# Same thing as above, just much longer
+	server.subscribe ThriftServer::LogSubscriber.new(Logger.new($stdout))
+
+The remaining two middlware handle metrics. Each handles a different
+metric granularity. `ThriftServer::ServerMetricsSubcriber` does stats
+for all RPCs & server things. `ThriftServer::RpcMetricsSubscriber`
+gives metrics for each individual RPC. Naturally there are important
+subscribers and its highly recommend you add them. There is a shortcut
+method for adding them both. They require a [statsd][] instance. You
+can customize statsd prefix & postfix on that instance.
+
+	server.metrics Statsd.new
+	# Same thing as above, just much longer
+	server.subscribe ThriftServer::ServerMetricsSubscriber.new(Statsd.new)
+	server.subscribe ThriftServer::RpcMetricsSubscriber.new(Statsd.new)
+
+`ThriftServer::ServerMetricsSubscriber` instruments the following
+keys:
+
+* `rpc.latency` - (timer)
+* `rpc.incoming` - (counter)
+* `rpc.success` - (counter) - Everything A-OK!
+* `rpc.exception` - (counter) - Result was defined protocol exception
+* `rpc.error` - (counter) - Uncaught errors
+* `server.pool.size` - (guage) - Number of available threads
+* `server.connection.active` - (guage) - Threads with active TCP connections
+
+`ThriftServer::RpcMetricsSubscriber` produces the same metrics, but at
+an individual RPC level. Assume the RPC is named `foo`.
+keys:
+
+* `rpc.foo.latency` (timer)
+* `rpc.foo.incoming` (counter)
+* `rpc.foo.success` (counter)
+* `rpc.foo.exception` (counter)
+* `rpc.foo.exception.xxx` (counter) - where `xxx` is listed in
+  `throws` in the Thrift IDL.
+* `rpc.foo.error` (counter)
 
 ## Middleware
 
@@ -63,25 +159,26 @@ implement your own middleware easily. The middleware must respond to
 `args`. Here's an example that dumps the `args` to stdout.
 
     class ExampleMiddleware
-        include Concord.new(:app)
+		include Concord.new(:app)
 
-        def call(rpc)
-            puts rpc.args.inspect
-            app.call rpc
-        end
+		def call(rpc)
+			puts rpc.args.inspect
+			app.call rpc
+		end
     end
 
 New middleware can be added at build time or afterwards.
 
-    ThriftServer::build processor, handler, options do |stack|
-        stack.use ExampleMiddlware
-    end
+	ThriftServer.threaded processor, handler, options do |stack|
+		stack.use ExampleMiddlware
+	end
 
 Middleware can also be added after the server is built
 
-    server = ThriftServer::build processor, handler, options
-    server.use ExampleMiddleware
-    serve.serve # start it!
+	server = ThriftServer.threaded processor, handler, options
+	server.use ExampleMiddleware
+
+	server.start # start it!
 
 ## Implementation
 
@@ -95,10 +192,10 @@ wrap the handler provided in `initialize` in the delegate class.
 
 ## Development
 
-    $ vagrant up
-    $ vagrant ssh
-    $ cd /vagrant
-    $ make test-ci
+	$ vagrant up
+	$ vagrant ssh
+	$ cd /vagrant
+	$ make test-ci
 
 ## Contributing
 
@@ -106,3 +203,5 @@ wrap the handler provided in `initialize` in the delegate class.
 2. Commit your changes (`git commit -am 'Add some feature'`)
 3. Push to the branch (`git push origin my-new-feature`)
 4. Create a new Pull Request
+
+[statsd]: https://github.com/reinh/statsd

data/circle.yml

@@ -0,0 +1,14 @@
+machine:
+  services:
+    - docker
+dependencies:
+  cache_directories:
+    - "tmp/cache"
+  override:
+    - mkdir -p tmp/cache
+    - script/circleci/cache-image tmp/cache/ruby ruby:2.1
+    - script/circleci/cache-image tmp/cache/thrift thrift:0.9.2
+test:
+  override:
+    - make test-ci
+    - make clean

data/echo_client.rb

@@ -23,13 +23,32 @@ transport.open
 protocol = Thrift::BinaryProtocol.new transport
 client = EchoService::Client.new protocol
 
-result = client.echo "testing"
+response = client.echo "testing"
 
-transport.close
+if response == 'testing'
+  $stdout.puts 'OK'
+else
+  $stderr.puts 'Message not echoed'
+  abort
+end
+
+response = client.structEcho 'testing'
 
-if result == 'testing'
+if response.message == 'testing'
   $stdout.puts 'OK'
 else
   $stderr.puts 'Message not echoed'
   abort
 end
+
+begin
+  client.structEcho 'exception'
+rescue EchoException
+  $stdout.puts 'OK'
+else
+  abort 'Protocol exception lost'
+end
+
+client.ping 'hello'
+
+transport.close

data/echo_server.rb

@@ -9,25 +9,32 @@ $LOAD_PATH << "#{__dir__}/gen-rb"
 require 'echo_service'
 
 class Handler
-  def echo(msg)
-    msg
+  def echo(message)
+    message
   end
-end
 
-class ErrorTracker
-  def track(*)
+  def structEcho(message)
+    case message
+    when /exception/
+      fail EchoException
+    else
+      EchoResponse.new message: message
+    end
+  end
 
+  def ping(message)
+    # async, into the ether!
   end
 end
 
-logger = Logger.new $stdout
-
-server = ThriftServer.build(EchoService::Processor, Handler.new, {
-  logger: logger,
-  statsd: Statsd.new,
-  error_tracker: ErrorTracker.new
-})
-
-logger.info 'Starting server'
-
-server.serve
+if ARGV.include?('--threaded')
+  server = ThriftServer.threaded EchoService, Handler.new
+  server.log Logger.new($stdout)
+  server.start
+elsif ARGV.include?('--thread-pool')
+  server = ThriftServer.thread_pool EchoService, Handler.new
+  server.log Logger.new($stdout)
+  server.start
+else
+  abort 'No server option given'
+end

data/echo_service.thrift

@@ -1,3 +1,14 @@
+exception EchoException { }
+
+struct EchoResponse {
+  1: required string message
+}
+
 service EchoService {
   string echo(1: string message)
+
+  EchoResponse structEcho(1: string message)
+    throws (1: EchoException echo)
+
+  oneway void ping(1: string message)
 }

data/lib/thrift_server.rb

@@ -1,19 +1,43 @@
 require "thrift_server/version"
 
 require 'thrift'
+require 'thrift-validator'
 require 'middleware'
 require 'concord'
 require 'forwardable'
-require 'honeybadger'
 require 'statsd-ruby'
 
-require_relative 'thrift_server/logging_middleware'
-require_relative 'thrift_server/metrics_middleware'
-require_relative 'thrift_server/error_tracking_middleware'
-require_relative 'thrift_server/honeybadger_error_tracker'
+require_relative 'thrift_server/instrumentation_middleware'
+require_relative 'thrift_server/validation_middleware'
 
-class ThriftServer
-  RPC = Struct.new(:name, :args)
+require_relative 'thrift_server/server_metrics_subscriber'
+require_relative 'thrift_server/rpc_metrics_subscriber'
+require_relative 'thrift_server/log_subscriber'
+
+require_relative 'thrift_server/publisher'
+
+require_relative 'thrift_server/thread_pool_server'
+require_relative 'thrift_server/threaded_server'
+
+module ThriftServer
+  RPC = Struct.new(:name, :args, :exceptions) do
+    def initialize(*)
+      super
+      self.exceptions ||= { }
+    end
+
+    def protocol_exception?(ex)
+      exceptions.values.include? ex.class
+    end
+
+    def exception_name(ex)
+      exceptions.invert.fetch ex.class
+    end
+
+    def to_s
+      name.to_s
+    end
+  end
 
   class MiddlewareStack < Middleware::Builder
     def finalize!
@@ -22,7 +46,7 @@ class ThriftServer
     end
   end
 
-  class StackDelegate
+  class HandlerWrapper
     class Dispatcher
       include Concord.new(:app, :handler)
 
@@ -33,15 +57,14 @@ class ThriftServer
 
     extend Forwardable
 
-    include Concord.new(:stack, :handler)
-
-    def_delegator :stack, :use
+    include Concord::Public.new(:stack, :publisher, :handler)
 
     def call(rpc)
       app.call rpc
     end
 
     private
+
     def app
       @app ||= finalize_stack!
     end
@@ -53,54 +76,107 @@ class ThriftServer
   end
 
   class << self
-    def build(processor, handler, options = { }, &block)
-      stack = wrap(processor, options, &block).new handler
-      transport = Thrift::ServerSocket.new options.fetch(:port, 9090)
+    def thread_pool(root, handler, options = { })
+      stack = wrap(root, options).new handler
+
+      threads, port = options.fetch(:threads, 25), options.fetch(:port, 9090)
+
+      transport = Thrift::ServerSocket.new port
       transport_factory = Thrift::FramedTransportFactory.new
 
-      Thrift::ThreadPoolServer.new stack, transport, transport_factory, nil, options.fetch(:threads, 4)
+      ThreadPoolServer.new(stack, transport, transport_factory, nil, threads).tap do |server|
+        # Assign bookkeeping data that is spread across multiple objects
+        server.port = port
+
+        yield server if block_given?
+      end
     end
 
-    def wrap(processor, options = { })
-      rpcs = processor.instance_methods.select { |m| m =~ /^process_(.+)$/ }
+    def threaded(root, handler, options = { })
+      stack = wrap(root, options).new handler
+
+      port = options.fetch :port, 9090
+
+      transport = Thrift::ServerSocket.new port
+      transport_factory = Thrift::FramedTransportFactory.new
+
+      ThreadedServer.new(stack, transport, transport_factory).tap do |server|
+        # Assign bookkeeping data that is spread across multiple objects
+        server.port = port
 
-      logger = options.fetch :logger do
-        fail ArgumentError, ':logger required'
+        yield server if block_given?
       end
+    end
+
+    def wrap(root, options = { })
+      processor = root < ::Thrift::Processor ? root : root.const_get(:Processor)
+
+      processors = processor.ancestors.select do |ancestor|
+        ancestor < ::Thrift::Processor
+      end
+
+      processor_rpcs = processors.each_with_object({ }) do |ancestor, bucket|
+        rpc_methods = ancestor.
+          instance_methods(include_superclass = false).
+          select { |m| m =~ /^process_(.+)$/ }
 
-      statsd = options.fetch :statsd do
-        fail ArgumentError, ':statsd required'
+        rpc_names = rpc_methods.map do |rpc_method|
+          rpc_method.to_s.match(/^process_(.+)$/)[1]
+        end
+
+        bucket[ancestor] = rpc_names.map(&:to_sym)
       end
 
-      error_tracker = options.fetch :error_tracker do
-        fail ArgumentError, ':error_tracker required'
+      rpc_names = processor_rpcs.flat_map do |_, values|
+        values
       end
 
-      stack = MiddlewareStack.new
-      stack.use ErrorTrackingMiddleware, error_tracker
-      stack.use MetricsMiddleware, statsd
-      stack.use LoggingMiddleware, logger
+      rpc_protocol_exceptions = processor_rpcs.each_with_object({ }) do |(processor_klass, rpcs), bucket|
+        rpcs.each do |rpc|
+          result_class = rpc.to_s
+          result_class[0] = result_class[0].upcase
+          result_class_name = "#{result_class}_result"
+
+          service_namespace = processor_klass.name.match(/^(.+)::Processor$/)[1]
+
+          fields = Object.const_get "#{service_namespace}::#{result_class_name}::FIELDS"
 
-      yield stack if block_given?
+          exception_fields = fields.values.select do |meta|
+            meta.key?(:class) && meta.fetch(:class) < ::Thrift::Exception
+          end
+
+          bucket[rpc] = exception_fields.each_with_object({ }) do |meta, exceptions|
+            exceptions[meta.fetch(:name).to_sym] = meta.fetch(:class)
+          end
+        end
+      end
+
+      publisher = Publisher.new
+
+      stack = MiddlewareStack.new
+      stack.use InstrumentationMiddleware, publisher
+      stack.use ValidationMiddleware
 
       wrapped = Class.new processor do
         extend Forwardable
 
-        def_delegator :@handler, :use
+        def_delegators :@handler, :stack
+        def_delegators :@handler, :publisher
+
+        def_delegators :stack, :use
+        def_delegators :publisher, :publish, :subscribe
 
         define_method :initialize do |handler|
-          stack_delegator = Class.new StackDelegate
+          stack_delegator = Class.new HandlerWrapper
           stack_delegator.module_eval do
-            rpcs.each do |method|
-              rpc_name = method.to_s.match(/^process_(.+)$/)[1]
-
-              define_method rpc_name.to_sym do |*args|
-                call RPC.new(rpc_name, args)
+            rpc_names.each do |rpc_name|
+              define_method rpc_name do |*args|
+                call RPC.new(rpc_name, args, rpc_protocol_exceptions.fetch(rpc_name, [ ]))
               end
             end
           end
 
-          super stack_delegator.new(stack, handler)
+          super stack_delegator.new(stack, publisher, handler)
         end
       end