Server Configuration File: server.rb
This Ruby file contains the custom application logic writen by the user along with programmable callbacks for OverSIP events.
Check the example server.rb
file that comes with OverSIP.
The server.rb
file is divided in the following sections:
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).
Example code
module MyApp
extend ::OverSIP::Logger
@valid_websocket_origins = ["https://www.myapp.com", "http://www.myapp.com"]
# Get the Array with valid WebSocket Origins.
def self.valid_websocket_origins
@valid_websocket_origins
end
[...]
end
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:
require "/etc/oversip/my_app/file1.rb"
require "/etc/oversip/my_app/file2.rb"
require "/etc/oversip/my_app/file3.rb"
[...]
System Events
This section includes programmable callbacks for system events:
OverSIP::SystemEvents.on_initialize
This method is called by OverSIP when main configuration files have been loaded. This method is NOT executed again when OverSIP is reloaded (HUP
signal or /etc/init.d/oversip reload
).
This is the place for setting i.e. dabatase connections (by using existing OverSIP 3rd party modules such us oversip-mod-mysql or EventMachine based database clients such as ruby-em-pg-client, couchbase-ruby-client-em, EventMachine built-in Memcache client, or some others via em-synchrony).
NOTE: If you need to use Ruby threads within your application logic (via the EventMachine.defer()
method) then this method is a good place to set the EventMachine.threadpool_size
parameter.
Example code
def (OverSIP::SystemEvents).on_initialize
log_info "initializing my OverSIP..."
end
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
def (OverSIP::SystemEvents).on_started
log_info "OverSIP started"
end
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.
Example code
def (OverSIP::SystemEvents).on_user_reload
log_notice "OverSIP user reloaded"
end
OverSIP::SystemEvents.on_terminated
(error)
This method is called after OverSIP has been terminated.
Parameters
error
true
in case OverSIP has died in an unexpected way.
Example code
def (OverSIP::SystemEvents).on_terminated(error)
if error
log_notice "exiting with error: #{error.inspect}"
else
log_info "properly exiting"
end
end
SIP Events
This section includes programmable callbacks for SIP events:
OverSIP::SipEvents.on_request
(request)
This method is called when a SIP request is received.
Parameters
request
- The
OverSIP::SIP::Request
instance.
Example code
For a full example code check the OverSIP::SipEvents.on_request
section in the default server.rb
file.
OverSIP::SipEvents.on_client_tls_handshake
(connection, pems)
This method is called when a SIP client initiates a TLS handshake with OverSIP. It is not called if the SIP callback_on_client_tls_handshake
parameter is not set.
Take a look to the TLS API for using the data provided by this method.
NOTE: When the SIP parameter use_tls_tunnel
is enabled, incoming SIP TLS connections are handled by Stud processes and thus this method is not called.
Parameters
connection
- The
OverSIP::SIP::Connection
instance. pems
- 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.
Take a look to the TLS API for using the data provided by this method.
Parameters
connection
- The
OverSIP::SIP::Connection
instance. pems
- 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 HTTP GET 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
connection
- The associated
OverSIP::WebSocket::Connection
instance. request
- The WebSocket handshake
OverSIP::WebSocket::HttpRequest
instance.
Example code
def (OverSIP::WebSocketEvents).on_connection(connection, http_request)
# Check the Origin header against my allowed list of domains.
if MyApp.valid_websocket_origins.include? http_request.hdr_origin
log_info "allowed WebSocket connection"
else
log_warn "WebSocket connection rejected, invalid Origin: #{http_request.hdr_origin}"
connection.http_reject 403, "Origin not allowed"
end
end
OverSIP::WebSocketEvents.on_disconnection
(connection, client_closed)
This method is called when a WebSocket connection is closed.
Parameters
connection
- The associated
OverSIP::WebSocket::Connection
instance. client_closed
true
if the client caused the disconnection,false
otherwise (OverSIP closed it).
Example code
def (OverSIP::WebSocketEvents).on_disconnection(connection, client_closed)
if client_closed
log_info "WebSocket connection closed by the client"
else
log_info "WebSocket connection closed by OverSIP"
end
end
OverSIP::WebSocketEvents.on_client_tls_handshake
(connection, pems)
This method is called when a WebSocket client initiates a TLS handshake with OverSIP. It is not called if the WebSocket callback_on_client_tls_handshake
parameter is not set.
Take a look to the TLS API for using the data provided by this method.
NOTE: When the WebSocket parameter use_tls_tunnel
is enabled, incoming WebSocket TLS connections are handled by Stud processes and thus this method is not called.
Parameters
connection
- The
OverSIP::WebSocket::Connection
instance. pems
- 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.