king_soa 0.0.2 → 0.0.3

data/README.rdoc

@@ -1,55 +1,124 @@
 = KingSoa
 
-Creating a SOA requires a centralized location to define all services within the
-SOA. Furthermore you want to know where those services live.
+KingSoa orchestrates a SOA landscape, by knowing where services live and how to
+call them.
 
-== Tech details
+== Why?
 
-the soa registry is keeping a bunch of service objects which know where a method
-lives. Methods are classes with an self.perform method and can be located local,
-remote(http) or beeing put onto a queue
+While your app is growing you stuff more and more in it, unrelated to its core
+business intelligence. You'll end up with an monolythic clumsy piece, getting
+harder to handle every day. Just think of: scalability, testing, deployment, ..
 
+To keep it clean a division of responsibilities, and with it a separation into
+smaller parts, is needed. But now you've got a communication problem, because
+each part needs to know about the others. This is where KingSoa enters the stage.
 
 
 == Install
 
     gem install king_soa
 
+== Dependencies
+
+Needed gems:
+
+* resque => When a service has a queue set, its enqueued via resque
+* typhoeus => making http requests to remotely located services
+* json => all arguments of a service call are json encoded
+
 == Define services
 
-=== Low Level
+The service registry(KingSoa::Registry) is keeping track of available
+services and behaves more or less like an array. Be aware that KingSoa::Registry
+is a singleton, so that the rack middleware and your app are seeing the same.
+
+A service (KingSoa::Service) has a name and knows how its gonna be called.
+A service call goes out to a class named like the CamelCased service.name with
+an self.perform method. Depending on the service settings it can be located
+local, remote(http) or beeing put onto a queue.
 
 You can define services anywhere in your app and add them to the service
-registry.
-Be aware that the registry is a singleton, so that the rack middleware and your
-app are seeing the same :
-    # create the service
-     service = KingSoa::Service.new(:name=>:increment_usage,
-                                    :url=>'http://localhost:4567',
-                                    :auth_key=>'12345')
-     # register
-     KingSoa::Registry << service
-
-     # somewhere in your app just call your service method
-     KingSoa.increment_usage(12)
-
-A service name is always required. If the service is to be called remotely you
-must add a url and an auth_key.
-The transport is done via http calls, so to make it secure you should either use
-https in public or hide the servers somwhere on your farm.
+registry. This should most likely be done in an initalizer(Rails).
+
+  # A remote service MUST have an url and an auth key set
+  a = KingSoa::Service.new(:name => :increment_usage,
+                        :url  => 'http://localhost:4567',
+                        :auth => '12345')
+
+  # A local service calling CrunchImage.perform
+  b = KingSoa::Service.new(:name => :crunch_image)
+
+  # A queued service MUST have a queue name, and of course you should have a worker looking for it
+  c = KingSoa::Service.new(:name => :delete_user,
+                           :queue => :deletions)
+  # register all of them
+  KingSoa::Registry << a << b << c
+
+  # somewhere in your app just call the services
+  KingSoa.increment_usage(12)
+  KingSoa.crunch_image(image_path)
+  KingSoa.delete_user(user_id)
+
+=== Remote Services
+
+The transport is done via http calls. All http calls have an authentication key 
+to provide some minimal access restriction. To make it secure you should either
+use https in public or hide the endpoints somwhere on your farm.
+
+Service endpoints receiving such calls need to use the provided rack middleware.
+The middleware is doing the authentication, executing the service class and
+returns values or errors.
+
+=== Local Services
+
+A local service calls a class with the CamelCased service name. This class MUST
+have a self.perform method which receives all of the givven arguments.
+
+=== Queued Services
+
+The service is put onto a resque queue and somewhere in you cloud you should
+have a worker looing for it. The service class should also have the resque
+@queue attribute set so the job can be resceduled if it fails.
 
 == Integration
 
+Just think of a buch of small sinatra or specialized rails apps, each having
+some internal services and consuming services from others.
+
 === Rails
 
+Add the middleware(application.rb/environment.rb) if you want to receive calls.
+    require 'king_soa'
+    config.middleware.use KingSoa::Rack::Middleware
+
+Setup services for example in an initializer reading a services.yml file. For 
+now there is no convinience loading method and no proposed yml format.
+    #services.yml
+    sign_document:
+      queue: signings
+    send_sms:
+      url: 'http://messaging.localhost:3000'
+      auth: '12345678'
+
+    # king_soa_init 
+    service_defs = YAML.load_file(File.join(RAILS_ROOT, 'config', 'services.yml'))
+    service_defs.each do |k, v|      
+      opts = { :name => k }     
+      [:url, :auth, :queue].each do |opt|
+        opts[opt] = v[opt.to_s] if v[opt.to_s]
+      end
+      KingSoa::Registry << KingSoa::Service.new(opts)
+    end
 
 === Sinatra
 
 Take a look at spec/server/app where you can see a minimal sinatra implementation
 The base is just:
+
     require 'king_soa'
     use KingSoa::Rack::Middleware
-    
+
+The service definition should of course also be done, see rails example.
  
 == Note on Patches/Pull Requests
  

data/lib/king_soa.rb

@@ -8,43 +8,21 @@ require 'king_soa/registry'
 require 'king_soa/service'
 require 'king_soa/rack/middleware'
 
-# Define available services.
-#
-# service:
-#   name: sign_document
-#   url: "https://msg.salesking.eu"
-#   auth: 'a-long-random-string'
-#   queue: a-queue-name
-#
-#
-# method: save_signed_document
-# url: "https://www.salesking.eu/soa"
-#
-#
-# after defining your services you can call each of them with
-#
-# <tt>KingSoa.service_name(args)</tt>
-#
-#     KingSoa.sign_document(counter)
-#     current_number = Hoth::Services.value_of_counter(counter)
-#     created_account = Hoth::Services.create_account(account)
-#
 module KingSoa
   
   class << self
-
-    def init_from_hash(services)
-      # create service      
-    end
     
-    # Locate service by a given name
+    # Locate service by a given name:
+    #   KingSoa.find(:my_service_name)
     # ==== Parameter
     # service<String|Symbol>:: the name to lookup
     def find(service)
       Registry[service]
     end
 
-    # this is where the services get called
+    # This is where the services get called.
+    # Tries to locate the service in the registry and if found call its perform
+    # method
     def method_missing(meth, *args, &blk) # :nodoc:
       if service = Registry[meth]
         service.perform(*args)

data/lib/king_soa/registry.rb

@@ -33,17 +33,24 @@ module KingSoa
       @services ||= []
     end
 
-    # Add a new method onto the stack
+    # Add a new service onto the stack
+    # === Parameter
+    # service<KingSoa::Service>:: the service to add
     def <<(service)
       (services || []) << service
     end
 
     # Get a method by a given name
+    # === Parameter
+    # service_name<String|Symbol>:: the service to find
+    # === Returns
+    # <KingSoa::Service> or <nil>
     def [](service_name)
       name = service_name.to_sym
       services.detect {|s| s.name == name }
     end
 
+    # untested
     def group(service_name)
       name = service_name.to_sym
 #      srvs = []

data/lib/king_soa/service.rb

@@ -31,7 +31,10 @@ module KingSoa
       Resque::Job.create(queue, local_class_name, *args)
     end
 
-    # Call a method: remote over http, local or put a job onto a queue
+    # Call a method:
+    #  * remote over http
+    #  * local by calling perform method on a class
+    #  * put a job onto a queue
     # === Parameter
     # args:: whatever arguments the service methods recieves. Those are later json
     # encoded for remote or queued methods
@@ -45,6 +48,7 @@ module KingSoa
       end
     end    
 
+    # The local class, if found
     def local_class
       @local_class ||= begin
                         local_class_name.constantize
@@ -53,7 +57,8 @@ module KingSoa
                       end
     end
 
-    # Return the classname infered from service name
+    # Return the classname infered from the camelized service name.
+    # A service named: save_attachment => class SaveAttachment
     def local_class_name
       self.name.to_s.camelize
     end

data/spec/king_soa/rack/middleware_spec.rb

@@ -16,7 +16,7 @@ describe KingSoa::Rack::Middleware do
     rack_response = middleware.call env
     rack_response.first.should == 500 #status code
     rack_response.last.should be_a_kind_of(Array)
-    rack_response.last.first.should == "{\"error\":\"An error occurred! (Missing rack.input)\"}"
+    rack_response.last.first.should == "{\"error\":\"An error occurred => Missing rack.input\"}"
   end
 
   xit "should handle result" do

data/spec/king_soa/service_spec.rb

@@ -10,7 +10,6 @@ describe KingSoa::Service do
 end
 
 describe KingSoa::Service, 'local request' do
-
   it "should call service" do
     s = KingSoa::Service.new(:name=>:local_soa_class)
     s.perform(1,2,3).should == [1,2,3]
@@ -26,7 +25,6 @@ describe KingSoa::Service, 'queued' do
 end
 
 describe KingSoa::Service, 'remote request' do
-
   before :all do
     start_test_server
   end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Georg Leciejewski
@@ -42,7 +42,7 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: resque
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
@@ -51,8 +51,32 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
+  type: :runtime
   version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rack
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
 description: |
   Creating a SOA requires a centralized location to define all services within the
   SOA. KingSoa takes care of keeping services in a service registry and knows how to call them.