zss 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b3b8da3123f3885cb835b2c0800da180274aa68c
-  data.tar.gz: d41d309e3e9f883d7bd51a0786e690cef388efcb
+  metadata.gz: c3cc50db4db8b982f79b85954265a191f92994b8
+  data.tar.gz: 3a140a07037992c73f53872a4684604b0500645c
 SHA512:
-  metadata.gz: 19d8756d422e2b31e299c8afd6971d381af12788623997f789bea25d32b654ced753a3968195e7e38f76cb3d45766842931d1325dae926345c67f6ef29ea8fae
-  data.tar.gz: 1ab9c2291366feec26837e91b34fd7ef07a2283331327200ad71cf01a379ad1430c7970ad020e823339603aa2b8a75b1a740f879d85a12757f49559265ac694b
+  metadata.gz: 433fe48debfcf3991d99d49e195de568b30f4a404b74aa6ea3a7ee6261ee2505d1d33bb713a1570eea0a526e406872a5f1588a4c2358c85e1df65ff77340419a
+  data.tar.gz: 73f90c97b364059f96a2bc44f84ea28d421638fe389b6547d58bcb7d8c39d4d050407ab6e810a442adfbacac5e6eb0ca54de37a77d045af396dbaf61db2612aa

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zss (0.1.0)
+    zss (0.2.0)
       activesupport (~> 4.1)
       daemons (~> 1.1)
       em-zeromq (~> 0.5)

data/README.md

@@ -67,6 +67,197 @@ PongClient.call("ping/pong", "payload")
 
 ```
 
+### Client errors
+
+The client raises services errors using ZSS::Error class, with code, developer message and user message.
+
+```ruby
+require 'zss'
+
+PongClient = ZSS::Client.new(:pong)
+
+begin
+  PongClient.ping("payload")
+rescue ZSS::Error => error
+  puts "Status code: #{error.code}"
+  puts "User Message: #{error.user_message}"
+  puts "Developer Message: #{error.developer_message}"
+end
+
+```
+
+## ZSS Service
+
+The ZSS Service is responsible for receiving ZSS Request and execute configured service handlers.
+
+**The main components are:**
+* ZSS::Service.new(:sid, config)
+
+  This component responsible for receiving and routing ZSS requests.
+  The first parameter is service identifier (sid), you can use either symbol or string.
+  The configuration parameter will be used to pass heartbeat interval and broker backend address.
+
+```ruby
+  config = {
+    backend: 'tcp://127.0.0.1:7776',  # default: tcp://127.0.0.1:7776
+    heartbeat: 1000                   # ms, default: 1s
+  }
+  service = ZSS::Service.new(:pong, config)
+```
+
+* ZSS::Runner.run(:sid)
+
+  This component is responsible to execute a ZSS::Service as daemon, when in background it redirects stdout to file and manages pid files. It uses [daemon gem](https://rubygems.org/gems/daemon).
+
+      $ bin/pong run
+
+  or in background, where pidfile and logs are under /log
+
+      $ bin/pong start/stop
+
+* ZSS::ServiceRegister
+
+  This component is the glue entry point between Runner & Service.
+
+
+**NOTE:** You can run services without using the runner and service register, they are just one way to run services, you can use your own. Using Runner and service registry all services are done on the same way and using shared infra.
+
+### Creating a new service step by step
+
+Let's create our first service sample, Ping-Pong, step by step.
+Note: For your next services you will be able to use [Service Generation rake](#zss-service-generation-rake), but for now you learn what the rake does and why!
+
+* Create you service logic class, adding a pong_service.rb under /lib folder.
+
+```ruby
+class PongService
+
+  # it print's payload and headers on the console
+  def ping(payload, headers)
+    puts "Payload => #{payload}"
+    puts "Headers => #{headers}"
+
+    return "PONG"
+  end
+
+end
+
+```
+**NOTE:** Headers parameter is optional!
+
+* Create the service registration, adding a service_register.rb under /lib folder.
+
+```ruby
+module ZSS
+  class ServiceRegister
+
+    def self.get_service
+      config = Hashie::Mash.new(
+        # this data should be received from a config file instead!
+        backend: 'tcp://127.0.0.1:7776'
+      )
+
+      # create a service instance for sid :pong
+      service = ZSS::Service.new(:pong, config)
+
+      instance = PongService.new
+      # register route ping for the service
+      service.add_route(instance, :ping)
+
+      service
+    end
+  end
+end
+
+```
+
+* Hook your files by creating start.rb under /lib folder.
+
+```ruby
+require 'zss/service'
+
+require_relative 'service_register'
+require_relative 'pong_service'
+```
+
+* Register LoggerFacade plugin/s
+
+The ZSS library uses the [LoggerFacade](https://github.com/pjanuario/logger-facade-ruby) library to abstract logging info, so you should hook your plugins on start.rb.
+
+
+```ruby
+# log level should be retrieved from a configuration file
+plugin = LoggerFacade::Plugins::Console.new({ level: :debug })
+LoggerFacade::Manager.use(plugin)
+```
+
+* Create a binary file to run the service as daemon, such as bin/pong
+
+```ruby
+#!/usr/bin/env ruby
+require 'rubygems' unless defined?(Gem)
+
+require 'bundler/setup'
+Bundler.require
+
+$env     = ENV['ZSS_ENV'] || 'development'
+
+require 'zss/runner'
+require_relative '../lib/start'
+
+# Runner receives the identifier used for pid and log filename
+ZSS::Runner.run(:pong)
+```
+
+**NOTES:**
+* ZSS_ENV: is used to identify the running environment
+
+
+You running service example [here](https://github.com/pjanuario/zss-service-sample)
+
+### Returning errors
+
+Every exception that is raised by the service is shield and result on a response with status code 500 with default user and developer messages.
+
+The available errors dictionary is defined in [error.json](https://github.com/pjanuario/zmq-service-suite-ruby/blob/master/lib/zss/errors.json).
+
+**Raising different errors**
+
+```ruby
+raise Error[500]
+# or
+raise Error.new
+# or
+raise Error.new(500)
+# or with developer message override
+raise Error.new(500, "this message should helpfull for developer!")
+```
+When relevant errors should be raised be with developer messages!
+
+**New Error Types**
+
+New error types should be added to [error.json](https://github.com/pjanuario/zmq-service-suite-ruby/blob/master/lib/zss/errors.json) using pull request.
+
+
+### ZSS Service Generation Rake
+
+[**#TODO**](https://github.com/pjanuario/zmq-service-suite-ruby/issues/11)
+
+rake zss:service sid (--airbrake)
+
+It generates the service skeleton, adding several files into root directory:
+* sid - binary file named with sid
+* start.rb with console plugin attached (--airbrake will add Airbrake plugin also)
+* sid_service.rb
+* service_register.rb
+* config/application.yml
+* travis.yml
+* .rvmrc.sample
+* .rvmrc
+* .rspec
+* Gemfile
+* .gitignore
+
 ## Contributing
 
 1. Fork it

data/lib/zss/client.rb

@@ -1,3 +1,4 @@
+require_relative '../zss'
 require_relative 'socket'
 
 module ZSS
@@ -29,7 +30,7 @@ module ZSS
 
       log.info("Received response to #{request.rid} with status #{response.status}")
 
-      fail ZSS::Error.new(response.status, response.payload) if response.is_error?
+      fail ZSS::Error.new(response.status, payload: response.payload) if response.is_error?
 
       response.payload
     end

data/lib/zss/error.rb

@@ -6,9 +6,19 @@ module ZSS
     attr_reader :code, :user_message
     attr_accessor :developer_message
 
-    def initialize(code, payload)
+    def initialize(code = 500, developer_message = nil, payload: nil)
+
+      if payload
+        fail "Invalid error code: #{code}" if code.blank?
+      else
+        data = self.class.get_errors[code.to_s]
+        payload = data.body if data
+      end
+
+      fail "Invalid error with code: #{code}" unless payload
+
       @code = code.to_i
-      @developer_message = payload.developerMessage
+      @developer_message = developer_message || payload.developerMessage
       @user_message = payload.userMessage
       super @developer_message
       set_backtrace caller

data/lib/zss/service.rb

@@ -1,4 +1,5 @@
 require 'em-zeromq'
+require_relative '../zss'
 require_relative 'router'
 require_relative 'message/smi'
 

data/lib/zss/version.rb

@@ -1,3 +1,3 @@
 module ZSS
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/spec/unit/client_spec.rb

@@ -139,12 +139,12 @@ describe ZSS::Client do
             userMessage: "user info",
             developerMessage: "dev info"
           )
-          msg.status = 500
+          msg.status = 999
           msg
         end
 
         expect { subject.call(:ping, "ping") }.to raise_exception(ZSS::Error) do |error|
-            expect(error.code).to eq(500)
+            expect(error.code).to eq(999)
         end
       end
 

data/spec/unit/error_spec.rb

@@ -8,22 +8,74 @@ describe ZSS::Error do
 
   describe('#ctor') do
 
-    subject do
-      described_class.new(500, response)
+    context('on invalid code') do
+
+      it('raises an exception when code is nil') do
+        expect{ described_class.new(nil, payload: response) }.to raise_exception(RuntimeError)
+      end
+
+      it('raises an exception when code does not exist on errors.json') do
+        expect{ described_class.new(0) }.to raise_exception(RuntimeError)
+      end
+
     end
 
-    it('returns a fullfilled error.message') do
-      expect(subject.code).to eq(500)
-      expect(subject.developer_message).to eq("dev info")
-      expect(subject.user_message).to eq("user info")
+    context('with payload') do
+
+      subject do
+        described_class.new(500, payload: response)
+      end
+
+      it('returns a fullfilled error.message') do
+        expect(subject.code).to eq(500)
+        expect(subject.developer_message).to eq("dev info")
+        expect(subject.user_message).to eq("user info")
+      end
+
+      it('returns error with dev info as error.message') do
+        expect(subject.message).to eq("dev info")
+      end
+
+      it('returns error with stacktrace') do
+        expect(subject.backtrace).not_to be_nil
+      end
+
     end
 
-    it('returns error with dev info as error.message') do
-      expect(subject.message).to eq("dev info")
+    context('with default error') do
+
+      subject { described_class.new }
+
+      it('returns an error') do
+        expect(subject.code).to eq(500)
+        expect(subject.developer_message).not_to be_nil
+        expect(subject.user_message).not_to be_nil
+      end
+
     end
 
-    it('returns error with stacktrace') do
-      expect(subject.backtrace).not_to be_nil
+
+    context('with default error') do
+
+      subject { described_class.new(500) }
+
+      it('returns an error') do
+        expect(subject.code).to eq(500)
+        expect(subject.developer_message).not_to be_nil
+        expect(subject.user_message).not_to be_nil
+      end
+
+
+      context('with override on developer message') do
+
+        subject { described_class.new(500, "dev info") }
+
+        it('returns an error') do
+          expect(subject.code).to eq(500)
+          expect(subject.developer_message).to eq('dev info')
+        end
+
+      end
     end
 
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zss
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pedro Januário
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-31 00:00:00.000000000 Z
+date: 2014-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler