sk-hoth 0.0.1 → 0.3.0

data/README.rdoc

@@ -1,56 +1,86 @@
-= KingSoa
-
-Creating a SOA requires a centralized location to define all services within the
-SOA. Furthermore you want to know where those services live.
-
-== Tech details
-
-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
+= Hoth
 
+Creating a SOA requires a centralized location to define all services within the SOA. Furthermore you want to know where those services live.
 
+= How to use
 
 == Install
 
-    gem install king_soa
+    gem install hoth
 
-== Define services
+== Define services and modules
 
-=== Low Level
+=== Service-Definition
 
-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
+This is how you define services:
 
-     # somewhere in your app just call your service method
-     KingSoa.increment_usage(12)
+    Hoth::Services.define do
+  
+      service :service_name do |first_param, second_param|
+        returns :descriptive_name
+      end
+        
+    end
 
-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.
-
-== Integration
+This definition describes a service with a name, some parameters and its return value. The naming of the parameters is just for your understanding and will never be used again, so be descriptive. Same goes for the return value. The only exception is, if you want to assure that a service returns nil you can write
+  
+    returns :nothing
+    
+A service whith this return value will always return nil. You can also specify `:nil`, with the same result.
+
+=== Module-Definition
+
+After defining all you services, you need to specify in which modules they live. Each module can be seen as a set of implemented services. Each module can have one or more endpoints. Here is how you define these modules with its endpoints and services:
+
+
+    Hoth::Modules.define do
+
+      service_module :module_name do
+        env :development, :test do
+          endpoint :default do
+            host 'localhost'
+            port 3000
+            transport :http
+          end
+
+          endpoint :bert do
+            host 'localhost'
+            port 9999
+            transport :bert
+          end
+        end
+
+        env :production do
+          endpoint :default do
+            host '192.168.1.12'
+            port 3000
+            transport :http
+          end
+
+          endpoint :bert do
+            host '192.168.1.15'
+            port 9999
+            transport :bert
+          end
+        end
+    
+        add_service :first_service
+        add_service :second_service, :via => :bert
+      end
+      
+    end
 
-=== Rails
 
+As you can see, it is possible to define different endpoints for different environments. Each endpoint has a host, a port and a transport-type. After defining your endpoints you can add your previously defined services to the module and define which endpoint they should use. If you do not specify an endpoint the :default endpoint will be used.
 
-=== Sinatra
+== Integrate in your project
 
-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
+Just execute current code (in rails you can add this line to an initializer):
+    
+    Hoth.init!
+    
+By default, Hoth looks for the files service_definition and module_definition in the config-Directory (`./config`). If you need to load these files from another place, just set `Hoth.config_path` to your needs.
     
- 
 == Note on Patches/Pull Requests
  
 * Fork the project.
@@ -61,4 +91,4 @@ The base is just:
 
 == Copyright
 
-Copyright (c) 2010 Georg Leciejewski. See LICENSE for details.
+Copyright (c) 2009-2010 Dirk Breuer. See LICENSE for details.

data/THANKS.md

@@ -0,0 +1,9 @@
+# Hoth THANKS
+
+A number of people have contributed to Hoth by reporting problems,
+suggesting improvements or submitting changes. Some of these people are:
+
+ * Andreas Bade (<andi.bade@gmail.com>)
+ * Sebastian Cohnen (<sebastian.cohnen@gmail.com>)
+ * Björn Vollmer (<bjoern.vollmer@googlemail.com>)
+ * Andreas Riemer

data/TODO

@@ -0,0 +1,2 @@
+* Make the rack provider independent from one specific transport.
+* Make the bodies of the rack_provider return an object which responds to each in order not break on Ruby 1.9.

data/lib/hoth/encoding/json.rb

@@ -0,0 +1,28 @@
+require 'json'
+
+module Hoth
+  module Encoding
+    class Json
+      
+      class <<self
+        def encode(string)
+          string.to_json
+        end
+
+        def decode(string)
+          begin
+            Hoth::Logger.debug "Original params before decode: #{string.inspect}"
+            JSON.parse(string)
+          rescue JSON::ParserError => jpe
+            raise EncodingError.wrap(jpe)
+          end
+        end
+        
+        def content_type
+          "application/json"
+        end
+      end
+      
+    end
+  end
+end

data/lib/hoth/encoding/no_op.rb

@@ -0,0 +1,19 @@
+module Hoth
+  module Encoding
+    class NoOp
+      
+      class <<self
+        def encode(string)
+          string
+        end
+
+        def decode(string)
+          string
+        end
+        
+        def content_type; end
+      end
+      
+    end
+  end
+end

data/lib/hoth/endpoint.rb

@@ -0,0 +1,28 @@
+module Hoth
+  class Endpoint
+    attr_accessor :host, :port, :module_name, :transport
+    
+    class ConfigEvaluator
+      attr_reader :endpoint
+      def initialize(endpoint, &block)
+        @endpoint = endpoint
+        instance_eval(&block)
+      end
+      
+      [:host, :port, :module_name, :transport].each do |endpoint_attribute|
+        define_method endpoint_attribute do |value|
+          endpoint.send("#{endpoint_attribute}=", value)
+        end
+      end
+    end
+    
+    def initialize(&block)
+      ConfigEvaluator.new(self, &block)
+    end
+    
+    def to_url
+      "http://#{@host}:#{@port}/execute"
+    end
+    
+  end
+end

data/lib/hoth/exceptions.rb

@@ -0,0 +1,14 @@
+module Hoth
+  class HothException < StandardError
+    attr_reader :original
+    def self.wrap(original)
+      wrapped = new("#{original.class} says: #{original.message}")
+      wrapped.set_backtrace original.backtrace
+      wrapped.instance_variable_set :@original, original
+      wrapped
+    end
+  end
+
+  class TransportError < HothException; end
+  class TransportException < HothException; end
+end

data/lib/hoth/extension/core/exception.rb

@@ -0,0 +1,15 @@
+class Exception
+  def to_json(*params)
+    {
+      'json_class'   => self.class.name,
+      'message'      => self.message,
+      'backtrace'    => self.backtrace
+    }.to_json(*params)
+  end
+  
+  def self.json_create(hash)
+    exception = new(hash["message"])
+    exception.set_backtrace hash['backtrace']
+    exception
+  end
+end

data/lib/hoth/modules.rb

@@ -0,0 +1,27 @@
+module Hoth
+  class Modules
+    include Singleton
+
+    attr_reader :service_modules
+
+    def self.define(&block)
+      instance.instance_eval(&block)
+    end
+
+    def self.module(module_name)
+      instance.service_modules[module_name]
+    end
+    
+    def service_module(module_name, &block)
+      service_module = ServiceModule.new(:name => module_name)
+      service_module.instance_eval(&block)
+      @service_modules[module_name] = service_module
+    end
+    
+    private
+
+      def initialize
+        @service_modules = {}
+      end
+  end
+end

data/lib/hoth/providers/bertrpc_provider.rb

@@ -0,0 +1,35 @@
+require 'ernie'
+
+module Hoth
+  module Providers
+    class BertRPCProvider
+      
+      def self.create_ernie_definition
+        Ernie.log "Possible Service implementations: #{Object.constants.grep(/.*Impl$/).inspect}"
+        Object.constants.grep(/.*Impl$/).each do |impl_class_name|
+          if impl_class = Object.const_get(impl_class_name) #&& impl_class.respond_to?(:execute)
+            Ernie.log "Service implementation was loaded! (#{impl_class.inspect})"
+            if impl_class.respond_to?(:execute)
+              service_name = impl_class_name.gsub("Impl", "").underscore.to_sym
+              mod(service_name) do
+                fun(:execute) do |*args|
+                  return_value = begin
+                    Hoth::Transport::Bert::TuplePreparer.prepare(Hoth::Services.send(service_name, *args))
+                  rescue Exception => e
+                    Ernie.log %Q{An Exception occured: #{e.message} -- #{e.backtrace.join("\n\t")}}
+                    false
+                  end
+                end
+              end
+            else
+              Ernie.log "Implementation wasn't applicatable. :execute method is missing!"
+            end
+          else
+            Ernie.log "Service implementation was not loaded! (#{impl_class_name.inspect})"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/hoth/providers/rack_provider.rb

@@ -0,0 +1,45 @@
+require 'rack/request'
+
+module Hoth
+  module Providers
+    class RackProvider
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Hoth::Logger.debug "env: #{env.inspect}"
+        if env["PATH_INFO"] =~ /^\/execute/
+          begin
+            req = Rack::Request.new(env)
+
+            service_name   = req.params["name"]
+            service_params = req.params["params"]
+            
+            responsible_service = ServiceRegistry.locate_service(service_name)
+            
+            decoded_params = responsible_service.transport.encoder.decode(service_params)
+            result = Hoth::Services.send(service_name, *decoded_params)
+            
+            encoded_result = responsible_service.transport.encoder.encode({"result" => result})
+          
+            [200, {'Content-Type' => responsible_service.transport.encoder.content_type, 'Content-Length' => "#{encoded_result.length}"}, [encoded_result]]
+          rescue Exception => e
+            Hoth::Logger.debug "e: #{e.message}"
+            if responsible_service
+              encoded_error = responsible_service.transport.encoder.encode({"error" => e})
+              [500, {'Content-Type' => service.transport.encoder.content_type, 'Content-Length' => "#{encoded_error.length}"}, [encoded_error]]
+            else
+              plain_error = "An error occuered! (#{e.message})"
+              [500, {'Content-Type' => "text/plain", 'Content-Length' => "#{plain_error.length}"}, [plain_error]]
+            end
+          end
+        else
+          @app.call(env)
+        end
+      end
+      
+    end
+  end
+end

data/lib/hoth/service.rb

@@ -0,0 +1,50 @@
+module Hoth
+  class Service
+    attr_accessor :name, :params_arity, :module
+    
+    def initialize(name, &block)
+      @name         = name
+      @params_arity = block.arity
+      instance_eval(&block)
+    end
+    
+    def returns(return_value)
+      @return_value = return_value
+    end
+    
+    def transport
+      @transport ||= Transport.create(endpoint.transport, self)
+    end
+    
+    def impl_class
+      @impl_class_name ||= "#{self.name.to_s.camelize}Impl"
+      begin
+        @impl_class_name.constantize
+      rescue NameError => e
+        # no local implementation
+        false
+      end
+    end
+    
+    def is_local?
+      !!impl_class
+    end
+    
+    def execute(*args)
+      result = self.is_local? ? impl_class.send(:execute, *args) : transport.call_remote_with(*args)
+      return return_nothing? ? nil : result
+    end
+    
+    def return_nothing?
+      [:nothing, :nil, nil].include? @return_value
+    end
+    
+    def via_endpoint(via = nil)
+      @via_endpoint = via || :default
+    end
+    
+    def endpoint
+      @endpoint ||= self.module[Hoth.env][@via_endpoint]
+    end
+  end
+end

data/lib/hoth/service_definition.rb

@@ -0,0 +1,18 @@
+module Hoth
+  class ServiceDefinition
+    
+    # create a new service with service_name and register it at the
+    # ServiceRegistry. The paramters of the block define the parameters of the
+    # defined service. Within the block you can describe the return value.
+    #
+    # Example:
+    #
+    #     service :create_account do |account|
+    #       returns :account_id
+    #     end
+    #
+    def service(service_name, &block)
+      ServiceRegistry.add_service(Service.new(service_name, &block))
+    end
+  end
+end

data/lib/hoth/service_module.rb

@@ -0,0 +1,49 @@
+module Hoth
+  class ServiceModule
+    attr_accessor :name, :environments
+
+    class Environment
+      attr_accessor :endpoints
+      
+      def initialize(&block)
+        @endpoints = {}
+        instance_eval(&block)
+      end
+      
+      def endpoint(endpoint_name, &block)
+        @endpoints[endpoint_name.to_sym] = Endpoint.new(&block)
+      end
+      
+      def [](endpoint_name)
+        @endpoints[endpoint_name.to_sym]
+      end
+    end
+    
+    def initialize(attributes = {})
+      @environments = {}
+      @name = attributes[:name]
+    end
+    
+    def env(*env_names, &block)
+      env_names.each do |env_name|
+        @environments[env_name.to_sym] = Environment.new(&block)
+      end
+    end
+    
+    def add_service(service_name, options = {})
+      raise HothException.new("no endpoint-definition for environment '#{Hoth.env}' and service '#{service_name}'") unless self.environments[Hoth.env]
+
+      service = ServiceRegistry.locate_service(service_name.to_sym)
+
+      raise HothException.new("tried to add service '#{service_name}' but was not defined by service-definition") unless service
+      
+      service.module = self
+      service.via_endpoint(options[:via])
+    end
+    
+    def [](env_name)
+      @environments[env_name.to_sym]
+    end
+
+  end
+end

data/lib/hoth/service_registry.rb

@@ -0,0 +1,34 @@
+module Hoth
+  
+  # The ServiceRegistry knows all registered services. You can register new
+  # services and locate existing services.
+  
+  class ServiceRegistry
+    include Singleton
+    
+    # add a service to the registry
+    def self.add_service(service)
+      instance.add_service(service)
+    end
+    # alias_method :register_service, :add_service
+    
+    # find a service with a given name
+    def self.locate_service(service_name)
+      instance.locate_service(service_name)
+    end
+    
+    def add_service(service) # :nodoc:
+      @registry[service.name.to_sym] = service
+    end
+    
+    def locate_service(service_name) # :nodoc:
+      @registry[service_name.to_sym]
+    end
+    
+    private
+      
+      def initialize # :nodoc:
+        @registry = {}
+      end
+  end
+end

data/lib/hoth/services.rb

@@ -0,0 +1,51 @@
+module Hoth
+  class Services
+    
+    # With Hoth::Services.define followed by a block you define all your
+    # available services.
+    #
+    # Example:
+    #
+    #     Hoth::Services.define do
+    #       
+    #       service :increment_counter do |counter|
+    #         returns :nothing
+    #       end
+    #       
+    #       service :value_of_counter do |counter|
+    #         returns :fixnum
+    #       end
+    #       
+    #       service :create_account do |account|
+    #         returns :account_id
+    #       end
+    #       
+    #     end
+    #   
+    # after defining your services you can call each of them with
+    # <tt>Hoth::Services.service_name(params)</tt>
+    #       
+    #     Hoth::Services.increment_counter(counter)
+    #     current_number = Hoth::Services.value_of_counter(counter)
+    #     created_account = Hoth::Services.create_account(account)
+    #
+    # see Hoth::ServiceDefinition for further informations of the block
+    # content.
+    
+    def self.define(&block)
+      ServiceDefinition.new.instance_eval(&block)
+    end
+    
+    class <<self
+
+      # this is where the services get called
+      def method_missing(meth, *args, &blk) # :nodoc:
+        if _service = ServiceRegistry.locate_service(meth)
+          _service.execute(*args)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/hoth/transport/base.rb

@@ -0,0 +1,19 @@
+require 'forwardable'
+ 
+module Hoth
+  module Transport
+    class Base
+      extend Forwardable
+      
+      attr_reader :encoder
+      
+      def_delegators :@service_delegate, :name, :module, :endpoint, :params, :return_nothing?
+      
+      def initialize(service_delegate, options = {})
+        @service_delegate = service_delegate
+        @encoder = options[:encoder] || Encoding::NoOp
+      end
+      
+    end
+  end
+end

data/lib/hoth/transport/bert.rb

@@ -0,0 +1,87 @@
+require 'bert'
+require 'bertrpc'
+
+module Hoth
+  module Transport
+    class Bert < Base
+      
+      class TuplePreparer
+        def self.prepare(obj)
+          case obj
+          when Array
+            obj.collect { |o| prepare o }
+          when Hash
+            obj.each { |k,v| obj[k] = prepare(v) }
+          else
+            ruby2tuple obj
+          end
+        end
+        
+        def self.ruby2tuple(ruby)
+          if ruby.respond_to? :to_serialize
+            tuple = t[ruby.class.name.underscore, {}]
+            ruby.to_serialize.each do |field|
+              tuple.last[field] = prepare(ruby.send(field))
+            end
+            tuple
+          else
+            ruby
+          end
+        end
+      end
+      
+      class Deserializer
+        def self.deserialize(data)
+          case data
+          when BERT::Tuple
+            tuple2ruby data
+          when Array
+            data.collect { |o| deserialize o }
+          when Hash
+            data.each { |k,v| data[k] = deserialize(v) }
+          else
+            data
+          end
+        end
+        
+        def self.tuple2ruby(tuple)
+          case tuple
+          when BERT::Tuple
+            begin
+              ruby_class = tuple.first.camelize.constantize
+              ruby_obj = ruby_class.new({})
+              ruby_obj.to_serialize.each do |field|
+                ruby_obj.send("#{field}=", deserialize(tuple.last[field]))
+              end
+              
+              ruby_obj
+            rescue NameError => e
+              puts %Q{An Exception occured: #{e.message} -- #{e.backtrace.join("\n\t")}}
+              tuple
+            end
+          else
+            puts "Was not anything we could decode!"
+            tuple
+          end
+        end
+      end
+      
+      def call_remote_with(*args)
+        bert_service = BERTRPC::Service.new(self.endpoint.host, self.endpoint.port)
+        
+        response = bert_service.call.send(self.name).execute(*TuplePreparer.prepare(args))
+        
+        if self.return_value
+          return Deserializer.deserialize(response)
+        else
+          return true
+        end
+      end
+      
+      def decode_params(params)
+        Deserializer.deserialize(params)
+      end
+      
+    end
+  end
+end