marilyn-rpc 0.0.2 → 0.0.3

data/README.md

@@ -9,10 +9,7 @@ The services are unique per connection, so if you have 50 connections, 50
 service objects will be used, if (and only if) they are requested by the client.
 
 Since this is a session dedicated to one connection, marilyn has support for per 
-connection caching by using instance variables. Further on, it is planned to 
-enhance the capabilities of marilyn to allow connection based authentication.
-Like in other protocols (e.g. IMAP) where some methods can be called
-unauthenticated and some not.
+connection caching by simply using instance variables.
 
 Like in IMAP marilyn supports sending of multiple requests to a server over one
 connection. This feature is called multiplexing supported by the current
@@ -122,6 +119,44 @@ The client also simply has to enable a secure connection:
 
     client = MarilynRPC::NativeClient.connect_tcp('localhost', 8008, :secure => true)
 
+## Authentication
+
+If some remote service methods only should be called using a username/password
+protection, one simply has to define which method and what mechanism:
+
+    MarilynRPC::Service.authenticate_with do |username, password|
+      username == "testuserid" && password == "secret"
+    end
+
+    class TestService < MarilynRPC::Service
+      register :test
+      authentication_required :add
+  
+      def time # unauthenticated
+        puts session_username
+        puts session_authenticated?
+        Time.now
+      end
+  
+      def add(a, b) # authenticated
+        puts session_username
+        puts session_authenticated?
+        a + b
+      end
+    end
+    
+The client simple has to do the authentication before start marking calls:
+
+    client = MarilynRPC::NativeClient.connect_tcp('localhost', 8000)
+    TestService = client.for(:test)
+
+    p TestService.time.to_f
+    client.authenticate "testuserid", "secret"
+    p TestService.add(1, 2)
+
+    client.disconnect
+
+
 ## Async Server Example & NativeClient
 
 As previously said, the server can use the `Gentleman` to issue asynchronous

data/examples/async/client.rb

@@ -19,7 +19,6 @@ done = false
 t3 = Thread.new do
   while !done
     sleep 1
-    p client
     STDOUT.print "."
     STDOUT.flush
   end
@@ -29,10 +28,6 @@ t1.join
 t2.join
 
 done = true
-t3.join
-
-p client
-
 end_time = Time.now
 
 puts "#{start_time - end_time}"

data/examples/authentication/client.rb

@@ -0,0 +1,18 @@
+$:.push(File.join(File.dirname(__FILE__), "..", "..", "lib"))
+require "marilyn-rpc"
+client = MarilynRPC::NativeClient.connect_tcp('localhost', 8000)
+TestService = client.for(:test)
+
+begin
+  p TestService.add(1, 2)
+rescue MarilynRPC::MarilynError => ex
+  puts "PermissionDenied: #{ex.message}"
+end
+
+p TestService.time.to_f
+
+client.authenticate "testuserid", "secret"
+
+p TestService.add(1, 2)
+
+client.disconnect

data/examples/authentication/server.rb

@@ -0,0 +1,30 @@
+$:.push(File.join(File.dirname(__FILE__), "..", "..", "lib"))
+require "marilyn-rpc"
+require "rubygems"
+require "eventmachine"
+
+MarilynRPC::Service.authenticate_with do |username, password|
+  username == "testuserid" && password == "secret"
+end
+
+class TestService < MarilynRPC::Service
+  register :test
+  authentication_required :add
+  
+  def time
+    puts session_username
+    puts session_authenticated?
+    Time.now
+  end
+  
+  def add(a, b)
+    puts session_username
+    puts session_authenticated?
+    a + b
+  end
+end
+
+
+EM.run {
+  EM.start_server "localhost", 8000, MarilynRPC::Server
+}

data/lib/marilyn-rpc.rb

@@ -1,4 +1,4 @@
-%w(version gentleman envelope mails service 
+%w(error version gentleman envelope mails service 
    server service_cache client).each do |file|
   require File.join(File.dirname(__FILE__), "marilyn-rpc", file)
 end

data/lib/marilyn-rpc/client.rb

@@ -2,11 +2,12 @@ require 'socket'
 require 'thread'
 
 module MarilynRPC
-  class BlankSlate
+  # A class with nothing but `__send__` and `__id__`
+  class ClientBlankSlate
     instance_methods.each { |m| undef_method m unless m =~ /^__/ }
   end
   
-  class NativeClientProxy < BlankSlate
+  class NativeClientProxy < ClientBlankSlate
     # Creates a new Native client proxy, were the calls get send to the remote
     # side.
     # @param [Object] path the path that is used to identify the service
@@ -62,6 +63,16 @@ module MarilynRPC
     def disconnect
       @socket.close
     end
+    
+    # authenicate the client to call methods that require authentication
+    # @param [String] username the username of the client
+    # @param [String] password the password of the client
+    # @param [Symbol] method the method to use for authentication, currently
+    #   only plain is supported. So make sure you are using a secure socket.
+    def authenticate(username, password, method = :plain)
+      execute(MarilynRPC::Service::AUTHENTICATION_PATH,
+              "authenticate_#{method}".to_sym, [username, password])
+    end
 
     # Creates a new Proxy Object for the connection.
     # @param [Object] path the path were the service is registered on the remote
@@ -139,8 +150,15 @@ module MarilynRPC
       if mail.is_a? MarilynRPC::CallResponseMail
         mail.result
       else
-        raise mail.exception
+        raise MarilynError.new # raise exception to capture the client backtrace
       end
+    rescue MarilynError => exception
+      # add local and remote trace together and reraise the original exception
+      backtrace = []
+      backtrace += exception.backtrace
+      backtrace += mail.exception.backtrace
+      mail.exception.set_backtrace(backtrace)
+      raise mail.exception
     end
   end
 end

data/lib/marilyn-rpc/error.rb

@@ -0,0 +1,13 @@
+module MarilynRPC
+  class MarilynError < StandardError; end
+  
+  # Error that occurs, when we recieve an broken envelope
+  class BrokenEnvelopeError < MarilynError; end
+  
+  # Error that occurs, when the client tries to call an unknown service
+  class UnknownServiceError < MarilynError; end
+
+  # Error that occurs, when the client tries to call an service, that requires
+  # authentication. The client must be authenticated before that call.
+  class PermissionDeniedError < MarilynError; end
+end

data/lib/marilyn-rpc/mails.rb

@@ -61,11 +61,11 @@ module MarilynRPC
     TYPE = MarilynRPC::MailHelper.type(3)
     
     def encode
-      TYPE + serialize(self.exception)
+      TYPE + serialize([self.tag, self.exception])
     end
     
     def decode(data)
-      self.exception = deserialize(only_data(data))
+      self.tag, self.exception = deserialize(only_data(data))
     end
   end
   
@@ -86,7 +86,7 @@ module MarilynRPC
         when MarilynRPC::ExceptionMail::TYPE
           mail = MarilynRPC::ExceptionMail.new
         else
-          raise ArgumentError.new("The passed type #{type.inspect} is unknown!")
+          raise MarilynRPC::BrokenEnvelopeError.new("The passed envelope is broken!")
       end  
       mail.decode(data)
       mail

data/lib/marilyn-rpc/server.rb

@@ -34,17 +34,12 @@ module MarilynRPC::Server
     
     # was massage parsed successfully?
     if @envelope.finished?
-      begin
-        # grep the request
-        mail = MarilynRPC::MailFactory.unpack(@envelope)
-        answer = @cache.call(mail)
-        if answer.is_a? MarilynRPC::CallResponseMail
-          send_mail(answer)
-        else
-          answer.connection = self # pass connection for async responses
-        end
-      rescue => exception
-        send_mail(MarilynRPC::ExceptionMail.new(mail.tag, exception))
+      # grep the request
+      answer = @cache.call(@envelope)
+      if answer.is_a? MarilynRPC::Gentleman
+        answer.connection = self # pass connection for async responses
+      else  
+        send_mail(answer)
       end
       
       # initialize the next envelope

data/lib/marilyn-rpc/service.rb

@@ -1,10 +1,19 @@
+# A class with nothing but `__send__`, `__id__`, `class` and `public_methods`.
+class ServiceBlankSlate
+  instance_methods.each { |m| undef_method m unless m =~ /^__|public_methods|class/ }
+end 
+
 # This class represents the base for all events, it is used for registering
-# services and defining callbacks for certain service events.
+# services and defining callbacks for certain service events. It is also
+# possible to enable an authentication check for methods of the service.
+# @attr [MarilynRPC::ServiceCache] service_cache the service cache where an 
+#   instance lives in
 # @example a service that makes use of the available helpers
 #   class EventsService < MarilynRPC::Service
 #     register :events
 #     after_connect :connected
 #     after_disconnect :disconnected
+#     authentication_required :notify
 #   
 #     def connected
 #       puts "client connected"
@@ -19,7 +28,9 @@
 #     end
 #   end
 #
-class MarilynRPC::Service
+class MarilynRPC::Service < ServiceBlankSlate
+  attr_accessor :service_cache
+  
   # registers the class where is was called as a service
   # @param [String] path the path of the service
   def self.register(path)
@@ -31,7 +42,7 @@ class MarilynRPC::Service
   # @api private
   # @return [Hash<String, Object>] all registered services with path as key and
   #   the registered service as object
-  def self.registry
+  def self.__registry__
     @@registry || {}
   end
   
@@ -39,21 +50,21 @@ class MarilynRPC::Service
   # defined in the class
   # @param [Array<Symbol>, Array<String>] callbacks the method names
   def self.after_connect(*callbacks)
-    register_callbacks :after_connect, callbacks
+    __register_callbacks__ :after_connect, callbacks
   end
   
   # register one or more disconnect callbacks, a callback is simply a method
   # defined in the class
   # @param [Array<Symbol>, Array<String>] callbacks the method names
   def self.after_disconnect(*callbacks)
-    register_callbacks :after_disconnect, callbacks
+    __register_callbacks__ :after_disconnect, callbacks
   end
   
   # registers a callbacks for the service class
   # @param [Symbol] name the name under which the callbacks should be saved
   # @param [Array<Symbol>, Array<String>] callbacks the method names
   # @api private
-  def self.register_callbacks(name, callbacks)
+  def self.__register_callbacks__(name, callbacks)
     @_callbacks ||= {}         # initialize callbacks
     @_callbacks[name] ||= []   # initialize specific set
     @_callbacks[name] += callbacks
@@ -64,16 +75,80 @@ class MarilynRPC::Service
   # @return [Array<String>, Array<Symbol>] an array of callback names, or an
   #   empty array
   # @api private
-  def self.registered_callbacks(name)
-    (@_callbacks || {})[name] || []
+  def self.__registered_callbacks__(name)
+    @_callbacks ||= {}
+    @_callbacks[name] || []
+  end
+  
+  # this generator marks the passed method names to require authentication.
+  # A Method that requires authentication is only callable if the client was
+  # successfully authenticated.
+  # @param [Array<String>, Array<Symbol>] methods the methods names
+  def self.authentication_required(*methods)
+    @_authenticated ||= {} # initalize hash of authenticated methods
+    methods.each { |m| @_authenticated[m.to_sym] = true }
+  end
+  
+  # returns all methods of the service that require authentication
+  # @return [Array<Symbol>] methods that require authentication
+  # @api private
+  def self.__methods_with_authentication__
+    @_authenticated ||= {}
   end
   
   # calls the defined connect callbacks
   # @param [Symbol] the name of the callbacks to run
   # @api private
-  def run_callbacks!(name)
-    self.class.registered_callbacks(name).each do |callback|
-      self.send(callback)
+  def __run_callbacks__(name)
+    self.class.__registered_callbacks__(name).each do |callback|
+      self.__send__(callback)
+    end
+  end
+  
+  # returns the username if a user is authenticated
+  # @return [String, nil] the username or nil, if no user is authenticated
+  def session_username
+    @service_cache.username
+  end
+  
+  # checks if a user is authenticated
+  # @return [Boolean] `true` if a user is authenticated, `false` otherwise
+  def session_authenticated?
+    !@service_cache.username.nil?
+  end
+  
+  # the name for the service which will be used to do the authentication
+  AUTHENTICATION_PATH = :__marilyn_rpc_service_authentication
+  
+  # define an authentication mechanism using a `lambda` or `Proc` object, or
+  # something else that respond to `call`. The authentication is available for
+  # all serivces of that connection.
+  # @param [Proc] &authenticator the authentication mechanism
+  # @yieldparam [String] username the username of the client
+  # @yieldparam [String] password the password of the client
+  # @yieldreturn [Boolean] To authenticate a user, the passed
+  #   block must return `true` otherwise `false`
+  # @example Create a new authentication mechanism for clients using callable
+  #   MarilynRPC::Service.authenticate_with do |username, password|
+  #     username == "testuserid" && password == "secret"
+  #   end
+  # 
+  def self.authenticate_with(&authenticator)
+    Class.new(self) do # anonymous class
+      @@authenticator = authenticator
+      register(AUTHENTICATION_PATH)
+      
+      # authenticate the user using a plain password method
+      # @param [String] username the username of the client
+      # @param [String] password the password of the client
+      def authenticate_plain(username, password)
+        if @@authenticator.call(username, password)
+          @service_cache.username = username
+        else
+          raise MarilynRPC::PermissionDeniedError.new \
+            "Wrong username or password!"
+        end
+      end
     end
   end
 end

data/lib/marilyn-rpc/service_cache.rb

@@ -1,33 +1,53 @@
-class MarilynRPC::ServiceCache  
+# # This class represents a per connection cache of the service instances.
+# @attr [String, nil] username the username of a authenticated user oder `nil`
+class MarilynRPC::ServiceCache
+  attr_accessor :username
+  
   # creates the service cache
   def initialize
     @services = {}
   end
   
   # call a service in the service cache
-  # @param [MarilynRPC::CallRequestMail] mail the mail request object, that
-  #   should be handled
+  # @param [MarilynRPC::Envelope] envelope the envelope that contains the
+  #   request subject (mail), that should be handled
   # @return [MarilynRPC::CallResponseMail, MarilynRPC::Gentleman] either a 
   #   Gentleman if the response is async or an direct response.
-  def call(mail)
-    # check if the correct mail object was send
-    unless mail.is_a?(MarilynRPC::CallRequestMail)
-      raise ArgumentError.new("Expected CallRequestMail Object!")
-    end
-    
-    # call the service instance using the argument of the mail
-    # puts "call #{mail.method}@#{mail.path} with #{mail.args.inspect}"
-    result = lookup(mail.path).send(mail.method, *mail.args)
-    # puts "result => #{result.inspect}"
+  def call(envelope)
+    mail = MarilynRPC::MailFactory.unpack(envelope)
+    tag = mail.tag
     
-    # no direct result, register callback
-    if result.is_a? MarilynRPC::Gentleman
-      result.tag = mail.tag # set the correct mail tag for the answer
-      result
+    if mail.is_a?(MarilynRPC::CallRequestMail) # handle a call request
+      # fetch the service and check if the user has the permission to access the
+      # service
+      service = lookup(mail.path)
+      method = mail.method.to_sym
+      if service.class.__methods_with_authentication__[method] && !@username 
+        raise MarilynRPC::PermissionDeniedError.new("No permission to access" \
+              " the #{service.class.name}##{method}")
+      end
+  
+      # call the service instance using the argument of the mail
+      #puts "call #{mail.method}@#{mail.path} with #{mail.args.inspect}"
+      result = service.__send__(method, *mail.args)
+      #puts "result => #{result.inspect}"
+  
+      # no direct result, register callback
+      if result.is_a? MarilynRPC::Gentleman
+        result.tag = tag # set the correct mail tag for the answer
+        result
+      else
+        MarilynRPC::CallResponseMail.new(tag, result) # direct response
+      end
     else
-      # make response
-      MarilynRPC::CallResponseMail.new(mail.tag, result)
+      raise MarilynRPC::BrokenEnvelopeError.new("Expected CallRequestMail Object!")
     end
+  rescue MarilynRPC::BrokenEnvelopeError => exception
+    MarilynRPC::ExceptionMail.new(nil, exception)
+  rescue => exception
+    #puts exception
+    #puts exception.backtrace.join("\n   ")
+    MarilynRPC::ExceptionMail.new(tag, exception)
   end
   
   # get the service from the cache or the service registry
@@ -38,12 +58,13 @@ class MarilynRPC::ServiceCache
     if service = @services[path]
       return service
     # it's not in the cache, so try lookup in the service registry
-    elsif service = MarilynRPC::Service.registry[path]
+    elsif service = MarilynRPC::Service.__registry__[path]
       @services[path] = service.new
-      @services[path].run_callbacks! :after_connect
+      @services[path].service_cache = self
+      @services[path].__run_callbacks__(:after_connect)
       return @services[path]
     else
-      raise ArgumentError.new("Service #{path} unknown!")
+      raise MarilynRPC::UnknownServiceError.new("Service #{path} unknown!")
     end
   end
   
@@ -52,7 +73,7 @@ class MarilynRPC::ServiceCache
   # @api private
   def disconnect!
     @services.each do |path, service|
-      service.run_callbacks! :after_disconnect
+      service.__run_callbacks__(:after_disconnect)
     end
   end
 end