Class: MarilynRPC::Service

Inherits:
ServiceBlankSlate show all
Defined in:
lib/marilyn-rpc/service.rb

Overview

This class represents the base for all events, it is used for registering services and defining callbacks for certain service events. It is also possible to enable an authentication check for methods of the service.

Examples:

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"
  end

  def notify(msg)
    puts msg
  end

  def disconnected
    puts "client disconnected"
  end
end

Constant Summary collapse

AUTHENTICATION_PATH =

the name for the service which will be used to do the authentication

:__marilyn_rpc_service_authentication

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#service_cache ⇒ MarilynRPC::ServiceCache

the service cache where an instance lives in

Returns:



31
32
33
 
# File 'lib/marilyn-rpc/service.rb', line 31

def service_cache
  @service_cache
end

Class Method Details

.__methods_with_authentication__ ⇒ Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

returns all methods of the service that require authentication

Returns:

  • (Array<Symbol>) —

    methods that require authentication



95
96
97
 
# File 'lib/marilyn-rpc/service.rb', line 95

def self.__methods_with_authentication__
  @_authenticated ||= {}
end

.__register_callbacks__(name, callbacks) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

registers a callbacks for the service class

Parameters:

  • name (Symbol) —

    the name under which the callbacks should be saved

  • callbacks (Array<Symbol>, Array<String>) —

    the method names



67
68
69
70
71
 
# File 'lib/marilyn-rpc/service.rb', line 67

def self.__register_callbacks__(name, callbacks)
  @_callbacks ||= {}         # initialize callbacks
  @_callbacks[name] ||= []   # initialize specific set
  @_callbacks[name] += callbacks
end

.__registered_callbacks__(name) ⇒ Array<String>, Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

returns the registered callbacks for name

Parameters:

  • name (Symbol) —

    the name to lookup callbacks for

Returns:

  • (Array<String>, Array<Symbol>) —

    an array of callback names, or an empty array



78
79
80
81
 
# File 'lib/marilyn-rpc/service.rb', line 78

def self.__registered_callbacks__(name)
  @_callbacks ||= {}
  @_callbacks[name] || []
end

.__registry__ ⇒ Hash<String, Object>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

returns all services, that where registered

Returns:

  • (Hash<String, Object>) —

    all registered services with path as key and the registered service as object



45
46
47
 
# File 'lib/marilyn-rpc/service.rb', line 45

def self.__registry__
  @@registry || {}
end

.after_connect(*callbacks) ⇒ Object

register one or more connect callbacks, a callback is simply a method defined in the class

Parameters:

  • callbacks (Array<Symbol>, Array<String>) —

    the method names



52
53
54
 
# File 'lib/marilyn-rpc/service.rb', line 52

def self.after_connect(*callbacks)
  __register_callbacks__ :after_connect, callbacks
end

.after_disconnect(*callbacks) ⇒ Object

register one or more disconnect callbacks, a callback is simply a method defined in the class

Parameters:

  • callbacks (Array<Symbol>, Array<String>) —

    the method names



59
60
61
 
# File 'lib/marilyn-rpc/service.rb', line 59

def self.after_disconnect(*callbacks)
  __register_callbacks__ :after_disconnect, callbacks
end

.authenticate_with {|username, password| ... } ⇒ Object

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.

Examples:

Create a new authentication mechanism for clients using callable

MarilynRPC::Service.authenticate_with do |username, password|
  username == "testuserid" && password == "secret"
end

Parameters:

  • &authenticator (Proc) —

    the authentication mechanism

Yield Parameters:

  • username (String) —

    the username of the client

  • password (String) —

    the password of the client

Yield Returns:

  • (Boolean) —

    To authenticate a user, the passed block must return ‘true` otherwise `false`



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/marilyn-rpc/service.rb', line 136

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

.authentication_required(*methods) ⇒ Object

this generator marks the passed method names to require authentication. A Method that requires authentication is only callable if the client was successfully authenticated.

Parameters:

  • methods (Array<String>, Array<Symbol>) —

    the methods names



87
88
89
90
 
# File 'lib/marilyn-rpc/service.rb', line 87

def self.authentication_required(*methods)
  @_authenticated ||= {} # initalize hash of authenticated methods
  methods.each { |m| @_authenticated[m.to_sym] = true }
end

.register(path) ⇒ Object

registers the class where is was called as a service

Parameters:

  • path (String) —

    the path of the service



36
37
38
39
 
# File 'lib/marilyn-rpc/service.rb', line 36

def self.register(path)
  @@registry ||= {}
  @@registry[path] = self
end

Instance Method Details

#__run_callbacks__(name) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

calls the defined connect callbacks

Parameters:

  • the (Symbol) —

    name of the callbacks to run



102
103
104
105
106
 
# File 'lib/marilyn-rpc/service.rb', line 102

def __run_callbacks__(name)
  self.class.__registered_callbacks__(name).each do |callback|
    self.__send__(callback)
  end
end

#session_authenticated? ⇒ Boolean

checks if a user is authenticated

Returns:

  • (Boolean) —

    ‘true` if a user is authenticated, `false` otherwise



116
117
118
 
# File 'lib/marilyn-rpc/service.rb', line 116

def session_authenticated?
  !@service_cache.username.nil?
end

#session_username ⇒ String?

returns the username if a user is authenticated

Returns:

  • (String, nil) —

    the username or nil, if no user is authenticated



110
111
112
 
# File 'lib/marilyn-rpc/service.rb', line 110

def session_username
  @service_cache.username
end