event_stream Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Stream socket syntax
1.3. Dependencies
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications
1.4. Exported Parameters
1.4.1. reliable_mode (integer)
1.4.2. timeout (integer)
1.4.3. event_param (string)
1.5. Exported Functions
1.6. Examples
1.6.1.
1.6.2. JSON-RPC notification
1.6.3. JSON-RPC Request
1.6.4. JSON-RPC Notification with Event's name
1.6.5. Custom JSON-RPC Notification from script
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set reliable_mode parameter
1.2. Set timeout parameter
1.3. Set event_param parameter
1.4. Stream socket
1.5. E_PIKE_BLOCKED JSON-RPC notification
1.6. E_PIKE_BLOCKED JSON-RPC request (reliable_mode)
1.7. E_PIKE_BLOCKED notification with event name
1.8. E_PIKE_BLOCKED event

Chapter 1. Admin Guide

1.1. Overview

This module provides a TCP transport layer implementation for the Event Interface. The module can either send a JSON-RPC notification or a standard request and wait for the response (when used in reliable_mode).

As the JSON-RPC is sent directly over TCP, avoiding any application transport layer (such as HTTP), this module offers a very lightweight and reliable way of delivering events to an application server.

In order to be notified, a JSON-RPC server has to subscribe for a certain event provided by OpenSIPS. This can be done using the generic MI Interface (event_subscribe function) or from OpenSIPS script (subscribe_event core function).

1.2. Stream socket syntax

'tcp:' host ':' port ['/' method]

Meaning:

  • 'tcp:' - specifies the transport protocol used by the Event Interface to send the command. the tcp token indicates that the subscriber's events should be notified using the event_strea, module.

  • host - host name of the JSON-RPC server.

  • port - port of the JSON-RPC server.

  • method - method called remotely by the JSON-RPC client.

    NOTE: this parameter is optional - if it is missing, the method used is the actual event subscribed to (i.e. if localhost:8080 subscribes to the E_PIKE_BLOCKED event, the RPC call will use the E_PIKE_BLOCKED method.

The JSON-RPC command is built as it follows:

  • id - uniquly generated if reliable_mode is used, otherwise (for notifications) null.

  • method - if no method is specified in the socket, the name of the event is set as method, otherwise the token specified is used.

  • params - if the event sent contains named parameters, then this parameter contains a JSON object with an object for each parameter. If the event sent only contains values, the parameters will be sent as an array.

1.3. Dependencies

1.3.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • none.

1.3.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • none

1.4. Exported Parameters

1.4.1. reliable_mode (integer)

This parameter controls the way the event_stream module communicates with the JSON-RPC server. If enabled, (set to 1), each event is translated to a JSON-RPC request. If disabled, each event will be sent as a JSON-RPC notification - there will be no reply expected by our client.

Note that if you need a reliable communication with the JSON-RPC server, where each event sent needs to be confirmed (by a JSON-RPC response), you must set this parameter to 1/yes. If you are using this module in a failover setup (using the event_virtual module), it is recommended to set this parameter to 1/yes.

Default value is 0 (disabled).

Example 1.1. Set reliable_mode parameter

...
modparam("event_stream", "reliable_mode", yes)
...

1.4.2. timeout (integer)

Specified the amount of milliseconds the module waits for a command to complete. In reliable_mode, it specifies the time module waits the request to be sent and a reply received. In non-reliable_mode, it represents only the time opensips takes to send the JSON-RPC notification.

NOTE that if the event is not using names for its parameters, the event will be the first parameter in the JSON-RPC command.

Default value is 1000 milliseconds = 1 second.

Example 1.2. Set timeout parameter

...
# only wait for 200 milliseonds for a reply
modparam("event_stream", "timeout", 200)
...

1.4.3. event_param (string)

By default, the name of the event subscribed to is not send in the JSON-RPC command. If one needs to send the name of the event as well, you can use this parameter to specify the name of JSON object within the params that will contain the name of the event.

Default value is disabled - event is not added.

Example 1.3. Set event_param parameter

...
modparam("event_stream", "event_param", "opensips_event")
# json resulted will contain the "opensips_event": EVENT token
...

1.5. Exported Functions

No function exported to be used from configuration file.

1.6. Examples

Example 1.4. Stream socket


	# calls the 'block_ip' method
	tcp:127.0.0.1:8080/block_ip

	# calls the 'E_PIKE_BLOCKED' method, if subscribed to the E_PIKE_BLOCKED event
	tcp:127.0.0.1:8080


1.6.2. JSON-RPC notification

This is an example of an event raised when reliable_mode is disabled by the pike module when it decides an ip should be blocked:

Example 1.5. E_PIKE_BLOCKED JSON-RPC notification


{
	"jsonrpc": "2.0",
	"method": "E_PIKE_BLOCKED",
	"params": {
		"ip": "192.168.2.11"
	}
}


1.6.3. JSON-RPC Request

This is an example of an event raised in reliable_mode by the pike module when it decides an ip should be blocked:

Example 1.6. E_PIKE_BLOCKED JSON-RPC request (reliable_mode)


# request
{
	"id": 915243442,
	"jsonrpc": "2.0",
	"method": "E_PIKE_BLOCKED",
	"params": {
		"ip": "192.168.2.11"
	}
}

# reply
{
	"jsonrpc": "2.0",
	"result": 8,
	"id": 915243442
}


1.6.4. JSON-RPC Notification with Event's name

when having the event_param set to opensips_event, the event raised by the pike module will look like the following:

Example 1.7. E_PIKE_BLOCKED notification with event name


# module configuration
modparam("event_stream", "event_param", "opensips_event")

# Stream socket: tcp:HOST:PORT/handle_cmd

# JSON-RPC command sent
{
	"jsonrpc": "2.0",
	"method": "handle_cmd",
	"params": {
		"opensips_event": "E_PIKE_BLOCKED"
		"ip": "192.168.2.11"
	}
}


1.6.5. Custom JSON-RPC Notification from script

This example contains a snippet to send a custom event from the script using the event_stream module.

Note that we are only populating values for the event, we are not assinging names to those values. Therefore, the parameters will be sent as an array.

Example 1.8. E_PIKE_BLOCKED event


startup_route {
	subscribe_event("E_MY_EVENT", "tcp:127.0.0.1:8080");
}

route {
	...
	$avp(attr-val) = 3;
	$avp(attr-val) = 5;
	raise_event("E_MY_EVENT", $avp(attr-val));
	...
}

# JSON-RPC command sent
{
	"jsonrpc": "2.0",
	"method": "E_MY_EVENT",
	"params": [3, 5]
}


Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Razvan Crainea (@razvancrainea)31141802100
2. Vlad Patrascu (@rvlad-patrascu)106105145
3. Liviu Chircu (@liviuchircu)751341
4. Bogdan-Andrei Iancu (@bogdan-iancu)4279
5. Maksym Sobolyev (@sobomax)4234
6. Peter Lemenkov (@lemenkov)4222

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Liviu Chircu (@liviuchircu)Apr 2018 - Jun 2023
2. Vlad Patrascu (@rvlad-patrascu)May 2020 - Jun 2023
3. Maksym Sobolyev (@sobomax)Feb 2023 - Feb 2023
4. Peter Lemenkov (@lemenkov)Jun 2018 - Aug 2020
5. Razvan Crainea (@razvancrainea)Mar 2018 - Jan 2020
6. Bogdan-Andrei Iancu (@bogdan-iancu)Feb 2019 - Apr 2019

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea).

Documentation Copyrights:

Copyright © 2018 www.opensips-solutions.com