Quick Start

In this guide you will learn how to use Vakhshour event passing platform as fast as possible.

Vakhshour Installation

Installing Vakhshour is easy, but before installing Vakhshour you have to install its dependencies. Vakhshour have three dependencies that you can install them using pip or easy_install utilities.

Install dependencies just like this:

# easy_install twisted pyopenssl pycrypto

or:

# pip install twisted pyopenssl pycrypto

Now its time to install Vakhshour itself:

# easy_install vakhshour

or:

# pip install vakhshour

Of course you can install dependecies using your distribution package manager.

Note

Some of Vakhshour dependencies have their own dependencies that you should take care of.

Running Vakhshour daemon

For using Vakhshour you need to run its daemon first (daemon is not a good word for this). Vakhshour daemon is responsible for dispatching events. vakhshourd is the Vakhshour daemon. run it like:

$ /usr/local/bin/vakhshourd

vakhshourd use /etc/vakhshour/vakhshour.json as its default configuration file. you can force vakhshourd to use another configuration file with -c parameter and specify new configuration file path.

Note

For more information about vakhshourd parameters take a look at vakhshourd --help

Note

You should us vakhshourd with some utitlies like Systemd or upstart or etc. if you’re a Debian user, there is a init script.

Sending events

After running the daemon, events can be sent using Node class. it lives in vakhshour.base.Node. Node represent a network node that running the Vakhshour daemon. For example:

from vakhshour.base import Node

node = Node(host="10.1.1.1", port="8888")
result = node.send_event(name="foo", sender="me", first_param="bar", another_param=12)

also you can send events in secure mode (using SSL):

from vakhshour.base import Node

node = Node(ssl_key="/home/lxsameer/src/Vakhshour/keys/test.key",
            ssl_cert="/home/lxsameer/src/Vakhshour/keys/test.crt",
            secure=True)
result = node.send_event(name="foo", sender="me", first_param="bar", another_param=12)

First example will send a foo event with two parameter that called first_param and another_param to a Vakhshour server on 10.1.1.1:8888. Those parameters that send to server will pas to event handler.

Second example is the same as first one but send the event in secure mode using SSL transport. SSL transport use SSLv3 client authentication to authenticate the client. More information on SSLv3 Client Authentication.

Receving events

Vakhshour service publish events by sending them via a TCP socket. Each client can subscribe to publisher port and receive the events. There is a very simple client class in vakhshour/clients.py8.

also Vakhshour can dispatch the received events via HTTP protocol as a request. You have to specifiy a list of event receiver web application in Vakhshour configuration file. for more information read the configuration section.

Vakhshour and Django

Vakhshour provide a Django application for Django webapplications. This application will receive an event from main daemon and run its handler. It will discover all the registered event handlers inside a project and run each event handler that matched with received event.

At first you should add vakhshour.events in your INSTALLED_APPS. Add the following code snippet in your main urls.py so Vakhshour can discover event handlers:

from vakhshour.events.discovery import handler_discovery

handler_discovery()

now Vakhshour will find any events.py module inside your installed app and look for a event handler registeration inside them.

Event handlers

Event handler is a subclass of vakhshour.events.EventHandler class and can handle more than one event. An event handler can define some methods to handle events. each method name should be like on_method_name. below example will show you every thing:

from vakhshour.events import EventHandler, handlers


class AMHandler(EventHandler):

    def on_foo(self, sender, first_param, another_param):
        print "I received a foo event 1: %s 2: %s" % (first_param,
                                                      another_param)


handlers.register(AMHandler())

Do you remember the foo event ? The above code runs when the foo events receive. Bear in mind that you should register any event handler using the handler object. Also you should register an instance of an event handler not the event handler itself.