3rd Party Modules Development

Starting with version 1.2.0 OverSIP provides a simple framework for 3rd party modules development.

Module OverSIP::SystemCallbacks class methods

NEW in 1.2.x

A new module OverSIP::SystemCallbacks provides access to OverSIP system callbacks in which 3rd party modules can add their desired code to be executed.

NOTE: log_xxxx() methods of Logger API cannot be used within these callbacks. Instead use the log_system_xxxx() syntax.

on_started(&block)

This method adds the given block or Proc instance to the list of callbacks to be executed once the core reactor has been started. Module developers can add their custom code here.

Example

OverSIP::SystemCallbacks.on_started do
  [...]
end

on_reload(&block)

This method adds the given block or Proc instance to the list of callbacks to be executed when OverSIP is reloaded (the master process receives a HUP signal).

Example

OverSIP::SystemCallbacks.on_reload do
  [...]
end

on_terminated(&block)

This method adds the given block or Proc instance to the list of callbacks to be executed when OverSIP terminates.

Block parameters

error

true in case OverSIP has died in an unexpected way.

Example

OverSIP::SystemCallbacks.on_terminated do |error|
  [...]
end

Module OverSIP::Launcher class methods

fatal(msg)

This method logs the given message or error with “critical” severity and terminates OverSIP. It is useful for 3rd party modules within the OverSIP::SystemCallbacks callbacks above (i.e. for exiting if the module given configuration is wrong).

Parameters

msg

A String or a Exception to be logged.

Example

OverSIP::SystemCallbacks.on_started do
  unless OverSIP::Modules::MyModule.validate_settings
    OverSIP::Launcher.fatal "invalid module settings, exiting"
  end
end

Building a module

The typical approach is to create a new Ruby Gem called oversip-mod-xxxxxx.

If the module must log something (by using log_system_xxxx() methods) include/extend the OverSIP::Logger module in the library. Also set a class attribute @log_id = "Xxxxxx module" (if your module provide class methods) or an instance method log_id (if your module provide class instances):

module OverSIP::Modules::Xxxxxx

  extend OverSIP::Logger

  @log_id = "Xxxxxx module"

  def self.do_something
    log_system_info "doing something..."
    [...]
  end


  # A class within the module.
  class Yyyyyy
    include OverSIP::Logger

    LOG_ID = "Xxxxxx::Yyyyyy class"

    def log_id
      LOG_ID
    end

    def do_something
      log_system_info "doing something..."
      [...]
    end
  end

end

Tips

• Build your Gem under the OverSIP::Modules namespace (note that OverSIP::M is an alias for OverSIP::Modules).
• Tell the user to load the module on top of server.rb:
  

  require "oversip-mod-xxxxxx"
  

• Provide a simple API for the user so he can configure the module parameters within the OverSIP::SystemEvents.on_initialize method.
• If the module needs to establish network/database connections then do that within a SystemCallbacks.on_started callback (the module must do it internally without asking the user for setting such a callback).

Examples

For a full example of a real 3rd party module check oversip-mod-mysql.