OverSIP

the SIP framework you dreamed about

Server Configuration File: server.rb

This Ruby file contains the custom application logic writen by the user along with programmable callbacks for OverSIP events. All those callbacks are executed within a new Ruby Fiber, allowing synchronous style coding by using em-synchrony libraries.

Example code in this page makes use of the oversip-mod-mysql MySQL driver with synchronous style coding (no callbacks for retrieving the SQL queries result).

Custom Application Logic

The top of the file is reserved for custom code writen by the user. Typicaly the user loads here external required Gems or libraries (via require "gem-name") and adds modules, classes and methods for building a custom application logic on top of OverSIP.

If the user adds a module or class here it’s useful it to include/extend the OverSIP::Logger module so the user can make use of the methods provided by OverSIP for logging into Syslog (log_debug, log_info, log_warn, etc).

When the user’s custom code is too long it can be split into different files. For example, the user could create a directory /etc/oversip/my_app/ containing custom files and load them at the top of server.rb as follows:

OverSIP::SystemEvents.on_started

This method is called by OverSIP once the core reactor has been started. Place here code to retrieve information from i.e. a database and fill some custom variable that will be later inspected in runtime.

Example code

OverSIP::SystemEvents.on_user_reload

This method is called by OverSIP when a USR1 signal is received by the OverSIP main process (or /etc/init.d/oversip user-reload is executed) and allows the user to set custom code to be executed or reloaded.

For example, this method could be used to reload a Ruby object (i.e. a Hash) with data retrieved from a database when such an information has been modified in the database.

Parameters

An Array with the chain of X509 certificates in PEM format (String) presented by the client during the TLS handshake. The first element is the most-resolved certificate, followed by the successive intermediate certificates and the root (or CA) certificate at the end. It could be empty if the client does not present a TLS certificate.

OverSIP::SipEvents.on_server_tls_handshake(connection, pems)

This method is called when OverSIP initiates a TLS handshake with a SIP server. It is not called if the callback_on_server_tls_handshake is not set for the “Proxy” instance being used for routing the SIP request.

In case the connection is not desired (after TLS certificate validation) it can be closed (and thus the SIP request not sent) by calling the close() method in the given OverSIP::SIP::Connection instance. It would generate an internal 500 “TLS Validation Failed” SIP response.

Parameters

An Array with the chain of X509 certificates in PEM format (String) presented by the server during the TLS handshake. The first element is the most-resolved certificate, followed by the successive intermediate certificates and the root (or CA) certificate at the end.

WebSocket Events

This section includes programmable callbacks for WebSocket events:

OverSIP::WebSocketEvents.on_connection(connection, http_request)

This method is called when a client attempts to establish a WebSocket connection and once OverSIP has validated that the HTTPGET request is a valid WebSocket handshake request but before OverSIP replies the HTTP 101 “Switching Protocols”.

Based on the HTTP request parameters and local policy the user can decide here whether to allow or reject the WebSocket connection attempt. This can be done by inspecting specific fields of the request (i.e. Origin header, Cookie header, request URI value and parameters, etc) and data from the connection (source address, plain or secure WebSocket connection, etc). The user can reject the WebSocket connection by calling connection.http_reject (so the HTTP 101 response required for completing the WebSocket handshake wont take place).

Parameters

An Array with the chain of X509 certificates in PEM format (String) presented by the client during the TLS handshake. The first element is the most-resolved certificate, followed by the successive intermediate certificates and the root (or CA) certificate at the end. It could be empty if the client does not present a TLS certificate.