Merge pull request #536 from meetecho/event-handlers

Event handler plugins

.gitignore

@@ -6,6 +6,7 @@ docs/html/
 /janus-pp-rec
 /plugins/*.so
 /transports/*.so
+/events/*.so
 
 Makefile
 Makefile.in
@@ -35,6 +36,10 @@ Makefile.in
 /transports/*.lo
 /transports/*.la
 /transports/.libs
+/events/*.o
+/events/*.lo
+/events/*.la
+/events/.libs
 /postprocessing/*.o
 
 /conf/janus.cfg.sample

Makefile.am

@@ -12,7 +12,7 @@ AM_CFLAGS = \
 	-Warray-bounds -Wold-style-definition -Wsign-compare -Wlarger-than=65537
 AM_CFLAGS += -Wno-undef  # sofiasip is not -Wundef--safe
 AM_CFLAGS += -Wno-redundant-decls  # sofiasip also contains redundant declarations
-AM_CFLAGS += -Wno-override-init  # we need this for JANUS_PLUGIN_INIT and JANUS_TRANSPORT_INIT
+AM_CFLAGS += -Wno-override-init  # we need this for JANUS_PLUGIN_INIT and JANUS_TRANSPORT_INIT and JANUS_EVENTHANDLER_INIT
 # FIXME: These should be enabled once the code is safe for them. That requires
 # some fairly big refactoring though, which can wait.
 # AM_CFLAGS += -Wshadow -Wstrict-aliasing=2
@@ -29,8 +29,9 @@ bin_PROGRAMS = janus
 
 headerdir = $(includedir)/janus
 header_HEADERS = \
-	plugins/plugin.h transports/transport.h apierror.h config.h debug.h dtls.h \
-	janus.h ice.h mutex.h record.h rtcp.h rtp.h sctp.h sdp.h sdp-utils.h turnrest.h utils.h log.h
+	plugins/plugin.h transports/transport.h events/eventhandler.h \
+	apierror.h config.h debug.h dtls.h events.h janus.h ice.h mutex.h \
+	record.h rtcp.h rtp.h sctp.h sdp.h sdp-utils.h turnrest.h utils.h log.h
 
 confdir = $(sysconfdir)/janus
 conf_DATA = conf/janus.cfg.sample
@@ -44,6 +45,9 @@ plugin_LTLIBRARIES = $(NULL)
 transportdir = $(libdir)/janus/transports
 transport_LTLIBRARIES = $(NULL)
 
+eventdir = $(libdir)/janus/events
+event_LTLIBRARIES = $(NULL)
+
 SUBDIRS = html
 html_DATA = README.md
 
@@ -60,6 +64,7 @@ recordings_DATA = $(NULL)
 	    s|[@]certdir[@]|$(certdir)|;\
 	    s|[@]plugindir[@]|$(plugindir)|;\
 	    s|[@]transportdir[@]|$(transportdir)|;\
+	    s|[@]eventdir[@]|$(eventdir)|;\
 	    s|[@]recordingsdir[@]|$(recordingsdir)|;\
 	    s|[@]streamdir[@]|$(streamdir)|" \
 	$< > $@ || rm $@
@@ -85,6 +90,8 @@ janus_SOURCES = \
 	dtls.h \
 	dtls-bio.c \
 	dtls-bio.h \
+	events.c \
+	events.h \
 	ice.c \
 	ice.h \
 	janus.c \
@@ -111,13 +118,15 @@ janus_SOURCES = \
 	plugins/plugin.c \
 	plugins/plugin.h \
 	transports/transport.h \
+	events/eventhandler.h \
 	$(NULL)
 
 janus_CFLAGS = \
 	$(AM_CFLAGS) \
 	$(JANUS_CFLAGS) \
 	-DPLUGINDIR=\"$(plugindir)\" \
 	-DTRANSPORTDIR=\"$(transportdir)\" \
+	-DEVENTDIR=\"$(eventdir)\" \
 	-DCONFDIR=\"$(confdir)\" \
 	$(BORINGSSL_CFLAGS) \
 	$(NULL)
@@ -202,6 +211,29 @@ conf_DATA += conf/janus.transport.pfunix.cfg.sample
 EXTRA_DIST += conf/janus.transport.pfunix.cfg.sample
 endif
 
+##
+# Event handlers
+##
+
+events_cflags = \
+	$(AM_CFLAGS) \
+	$(EVENTS_CFLAGS) \
+	$(NULL)
+
+events_libadd = \
+	$(EVENTS_LIBS) \
+	$(NULL)
+
+if ENABLE_SAMPLEEVH
+event_LTLIBRARIES += events/libjanus_sampleevh.la
+events_libjanus_sampleevh_la_SOURCES = events/janus_sampleevh.c
+events_libjanus_sampleevh_la_CFLAGS = $(events_cflags)
+events_libjanus_sampleevh_la_LDFLAGS = $(events_ldflags) -lcurl
+events_libjanus_sampleevh_la_LIBADD = $(events_libadd)
+conf_DATA += conf/janus.eventhandler.sampleevh.cfg.sample
+EXTRA_DIST += conf/janus.eventhandler.sampleevh.cfg.sample
+endif
+
 ##
 # Plugins
 ##

README.md

@@ -43,7 +43,8 @@ A couple of plugins depend on a few more libraries:
 * [libopus](http://opus-codec.org/) (only needed for the bridge plugin)
 * [libogg](http://xiph.org/ogg/) (only needed for the voicemail plugin)
 * [libcurl](https://curl.haxx.se/libcurl/) (only needed if you are
-interested in RTSP support in the Streaming plugin)
+interested in RTSP support in the Streaming plugin or in the sample
+Event Handler plugin)
 
 Additionally, you'll need the following libraries and tools:
 
@@ -74,6 +75,10 @@ On Ubuntu or Debian, it would require something like this:
 on Ubuntu or Debian, unless you're using a recent version (e.g., Ubuntu
 14.04 LTS). In that case, you'll have to [install it manually](http://www.opus-codec.org).
 
+In case you're interested in compiling the sample Event Handler plugin,
+you'll need to install the development version of libcurl as well (usually
+`libcurl-devel` on Fedora/CentOS, `libcurl4-openssl-dev` on Ubuntu/Debian).
+
 If your distro ships a pre-1.5 version of libsrtp, it may be better to
 uninstall that version and [install 1.5 or 2.0.0 manually](https://github.com/cisco/libsrtp/releases).
 In fact, 1.4.x is known to cause several issues with WebRTC. Installation
@@ -293,7 +298,7 @@ or on the command line:
 
 	<installdir>/bin/janus --help
 
-	janus 0.2.1
+	janus 0.2.2
 
 	Usage: janus [OPTIONS]...
 
@@ -351,6 +356,7 @@ or on the command line:
                                   default)
 	-A, --token-auth              Enable token-based authentication for all
                                   requests  (default=off)
+	-e, --event-handlers          Enable event handlers  (default=off)
 
 Options passed through the command line have the precedence on those
 specified in the configuration file. To start the gateway, simply run:

conf/janus.cfg.sample.in

@@ -160,3 +160,16 @@ ice_ignore_list = vmnet
 ; transports are enabled and loaded at startup.
 [transports]
 ; disable = libjanus_rabbitmq.so
+
+; Event handlers allow you to receive live events from Janus happening
+; in core and/or plugins. Since this can require some more resources,
+; the feature is disabled by default. Setting broadcast to yes will
+; enable them. You can then choose which of the available event handlers
+; should be loaded or not. Use the 'disable' directive to prevent Janus
+; from loading one or more event handlers: use a comma separated list of
+; file names to identify the event handlers to disable. By default, if
+; broadcast is set to yes all available event handlers are enabled and
+; loaded at startup.
+[events]
+; broadcast = yes
+; disable = libjanus_sampleevh.so

conf/janus.eventhandler.sampleevh.cfg.sample

@@ -0,0 +1,34 @@
+; This configures the sample event handler. Since this plugin simply
+; forwards each event it receives via HTTP POST, you simply need to
+; configure (i) which events to subscribe to, and (ii) the address of
+; the web server which will receive the requests.
+
+[general]
+enabled = no	; By default the module is not enabled
+events = all	; Comma separated list of the events mask you're interested
+				; in. Valid values are none, sessions, handles, jsep, webrtc,
+				; media, plugins, transports, core and all. By default we
+				; subscribe to everything (all)
+grouping = no	; Whether events should be sent individually (one per
+				; HTTP POST, JSON object), or if it's ok to group them
+				; (one or more per HTTP POST, JSON array with objects)
+backend = http://your.webserver.here/and/a/path
+				; Address the plugin will send all events to as HTTP POST
+				; requests with an application/json payload. In case
+				; authentication is required to contact the backend, set
+				; the credentials as well (basic authentication only).
+;backend_user = myuser
+;backend_pwd = mypwd
+				; You can also configure how retransmissions should
+				; happen, after a failed attempt to deliver an event.
+				; Specifically, you can specify how many times a
+				; retransmission should be attempted (default=5) and
+				; which step is used, in milliseconds, for the exponential
+				; backoff before retrying (e.g, if step=100ms, then the
+				; the first retry will happen after 100ms, the second
+				; after 200ms, then 400ms, and so on). If the event cannot
+				; be retransmitted after the maximum number of attemps
+				; is reached, then it's lost. Beware that retransmissions
+				; will also delay pending events and increase the queue.
+;max_retransmisson = 5
+;retransmissions_backoff = 100

conf/janus.plugin.audiobridge.cfg.sample

@@ -12,6 +12,8 @@
 [general]
 ;admin_key = supersecret		; If set, rooms can be created via API only
 								; if this key is provided in the request
+;events = no					; Whether events should be sent to event
+								; handlers (default is yes)
 
 [1234]
 description = Demo Room

conf/janus.plugin.echotest.cfg.sample

@@ -1 +1,4 @@
-; The Echo Test plugin doesn't need any configuration
+; events = yes|no, whether events should be sent to event handlers
+
+[general]
+;events = no

conf/janus.plugin.recordplay.cfg.sample.in

@@ -1,4 +1,6 @@
 ; path = where to place recordings in the file system
+; events = yes|no, whether events should be sent to event handlers
 
 [general]
 path = @recordingsdir@
+;events = no

conf/janus.plugin.sip.cfg.sample

@@ -1,7 +1,7 @@
 [general]
 ; Specify which local IP address to use. If not set it will be automatically
 ; guessed from the system
-; local_ip = 1.2.3.4
+;local_ip = 1.2.3.4
 
 ; Enable local keep-alives to keep the registration open. Keep-alives are
 ; sent in the form of OPTIONS requests, at the given interval inseconds.
@@ -17,3 +17,6 @@ behind_nat = no
 ; user_agent = Cool WebRTC Gateway
 ; Expiration time for registrations
 register_ttl = 3600
+
+; Whether events should be sent to event handlers (default is yes)
+;events = no

conf/janus.plugin.streaming.cfg.sample.in

@@ -40,6 +40,8 @@
 [general]
 ;admin_key = supersecret		; If set, mountpoints can be created via API
 								; only if this key is provided in the request
+;events = no					; Whether events should be sent to event
+								; handlers (default is yes)
 
 [gstreamer-sample]
 type = rtp

conf/janus.plugin.textroom.cfg.sample

@@ -10,6 +10,8 @@
 								; if this key is provided in the request
 json = indented					; Whether the data channel JSON messages should be indented (default),
 								; plain (no indentation) or compact (no indentation and no spaces)
+;events = no					; Whether events should be sent to event
+								; handlers (default is yes)
 
 [1234]
 description = Demo Room

conf/janus.plugin.videocall.cfg.sample

@@ -1 +1,4 @@
-; The Video Call plugin doesn't need any configuration
+; events = yes|no, whether events should be sent to event handlers
+
+[general]
+;events = no

conf/janus.plugin.videoroom.cfg.sample

@@ -21,6 +21,8 @@
 [general]
 ;admin_key = supersecret		; If set, rooms can be created via API only
 								; if this key is provided in the request
+;events = no					; Whether events should be sent to event
+								; handlers (default is yes)
 
 [1234]
 description = Demo Room

conf/janus.plugin.voicemail.cfg.sample

@@ -2,7 +2,9 @@
 ;	properly configured web server, if you want the demo to work)
 ; base = base path to use when returning the recording URI (use this
 ;	to make sure the file in the path you chose is reachable via HTTP)
+; events = yes|no, whether events should be sent to event handlers
 
 [general]
 path = /tmp/voicemail/
 base = /voicemail/
+events = yes

configure.ac

@@ -1,4 +1,4 @@
-AC_INIT([Janus Gateway],[0.2.1],[https://github.com/meetecho/janus-gateway],[janus-gateway],[https://janus.conf.meetecho.com])
+AC_INIT([Janus Gateway],[0.2.2],[https://github.com/meetecho/janus-gateway],[janus-gateway],[https://janus.conf.meetecho.com])
 AC_CONFIG_AUX_DIR([.])
 AC_CONFIG_MACRO_DIR([m4])
 
@@ -76,6 +76,12 @@ AC_ARG_ENABLE([unix-sockets],
               [],
               [enable_unix_sockets=maybe])
 
+AC_ARG_ENABLE([sample-event-handler],
+              [AS_HELP_STRING([--disable-sample-event-handler],
+                              [Disable sample event handler (HTTP POST) ])],
+              [],
+              [enable_sample_event_handler=maybe])
+
 AC_ARG_ENABLE([boringssl],
               [AS_HELP_STRING([--enable-boringssl],
                               [Use BoringSSL instead of OpenSSL])],
@@ -210,12 +216,21 @@ PKG_CHECK_MODULES([LIBCURL],
                         JANUS_MANUAL_LIBS+=" -lcurl"
                         enable_turn_rest_api=yes
                       ])
+                    AS_IF([test "x$enable_sample_event_handler" != "xno"],
+                      [
+                        AC_DEFINE(HAVE_SAMPLEEVH)
+                        JANUS_MANUAL_LIBS+=" -lcurl"
+                        enable_sample_event_handler=yes
+                      ])
                   ],
                   [
                     AS_IF([test "x$enable_turn_rest_api" = "xyes"],
                           [AC_MSG_ERROR([libcurl not found not found. See README.md for installation instructions or use --disable-turn-rest-api])])
+                    AS_IF([test "x$enable_sample_event_handler" = "xyes"],
+                          [AC_MSG_ERROR([libcurl not found not found. See README.md for installation instructions or use --disable-sample-event-handler])])
                   ])
 AM_CONDITIONAL([ENABLE_TURN_REST_API], [test "x$enable_turn_rest_api" = "xyes"])
+AM_CONDITIONAL([ENABLE_SAMPLEEVH], [test "x$enable_sample_event_handler" = "xyes"])
 
 AC_CHECK_PROG([DOXYGEN],
               [doxygen],
@@ -460,6 +475,18 @@ AM_CONDITIONAL([ENABLE_PLUGIN_VIDEOROOM], [test "x$enable_plugin_videoroom" = "x
 AM_CONDITIONAL([ENABLE_PLUGIN_VOICEMAIL], [test "x$enable_plugin_voicemail" = "xyes"])
 AM_CONDITIONAL([ENABLE_PLUGIN_TEXTROOM], [test "x$enable_plugin_textroom" = "xyes"])
 
+
+##
+# Event handlers
+##
+
+PKG_CHECK_MODULES([EVENTS],
+                  [
+                    glib-2.0 >= $glib_version
+                    jansson
+                  ])
+
+
 ##
 # Post-processing
 ##
@@ -565,6 +592,10 @@ AM_COND_IF([ENABLE_PLUGIN_RECORDPLAY],
 AM_COND_IF([ENABLE_PLUGIN_TEXTROOM],
 	[echo "    Text Room:             yes"],
 	[echo "    Text Room:             no"])
+echo "Event handlers:"
+AM_COND_IF([ENABLE_SAMPLEEVH],
+	[echo "    Sample event handler:  yes"],
+	[echo "    Sample event handler:  no"])
 
 echo
 echo "If this configuration is ok for you, do a 'make' to start building Janus. A 'make install' will install Janus and its plugins to the specified prefix. Finally, a 'make configs' will install some sample configuration files too (something you'll only want to do the first time, though)."

docs/janus-doxygen.cfg

@@ -32,7 +32,7 @@ PROJECT_NAME           = "Janus"
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.2.1
+PROJECT_NUMBER         = 0.2.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer
@@ -668,7 +668,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = .. ../plugins ../transports ../postprocessing
+INPUT                  = .. ../plugins ../transports ../events ../postprocessing
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is