.. warning:: This is alpha-stage software. Use with caution.
araldo
######
*araldo* provides a simple, extensible communication relay (based on `gevent `_ and `WebSockets `_) between multiple endpoints
Resources:
- `Repository and issue tracker: `_
- `Documentation of in-development version `_
Use cases
*********
- Push notification from server to Browser
- Bidirectional communication between browsers
- Bidirectional communication between browsers and a backend
- Interoperability between different message-oriented middleware products
Architecture
************
*araldo* is a central server component that provides an arbitrary amount of
endpoints to which clients may connect, or which connect to other servers.
Routes
======
*araldo* uses the concept of *routes* for setting up communication. Rather than
relying on clients subscribing/publishing to/from particular channels, the channel
setup and routing between endpoints is done inside *araldo*.
Implementation
==============
*araldo* uses `gevent `_, a corouting-based networking
library. *gevent* uses `green threads `_ (greenlets) and asynchronous IO. Therefore,
the *araldo* server is single-threaded with respect to native threads, but highly
concurrent with respect to green threads.
Plugins
=======
Available Plugins
-----------------
*araldo* consists of a core that is run as a server process, and several plugins.
Available plugins are loaded automatically. Out of the box, *araldo* provides a
`WebSocket `_ server that allows multiple clients
to communicate with each other via routes.
Currently the following plugins are available:
=================== ========================== ==============================================
Name Description Link
=================== ========================== ==============================================
araldo-redis Communication via Redis http://bitbucket.org/ganymed/araldo-redis
PubSub
araldo-websocket Communication with an http://bitbucket.org/ganymed/araldo-websocket
HTML5 WebSocket server
=================== ========================== ==============================================
Extensibility
-------------
*araldo* uses the Python entry-point mechanism for plugin discovery.
Installation
************
To install *araldo* along with some plugins, type::
pip install araldo
Configuration
*************
Command line parameters::
Usage: server.py [options]
Options:
-h, --help show this help message and exit
-c CONFIG, --config=CONFIG
Configuration path
Configuration File
==================
The configuration file in *YAML* format mainly contains
- global settings
- plugin instances, with plugin-specific settings
- routes (connections between endpoints)
The standard configuration file is ``araldo.yaml`` in the current directory.
Global parameters
=================
============== ========= ============================================
Parameter Type Description
============== ========= ============================================
server-port int TCP port of web (WebSocket) server
log-level str One of ``debug``, ``info``, ``warning``,
``error``, ``fatal``.
Verbosity of logging
============== ========= ============================================
Plugin-Specific parameters
==========================
Plugins are configured under the toplevel configuration key ``plugins``.
All plugins
----------------------
============== ========= ============================================
Parameter Type Description
============== ========= ============================================
name str Unique name for the plugin instance
id str Identifier for the plugin type
============== ========= ============================================
Routing
=======
Routes map messages from an inbound source to multiple outbound endpoints.
Routing is configured under the toplevel configuration key ``routes``. Each
route consists of a key that references a name of an endpoint. The value is
a list of names referencing other endpoints.
Sample configuration::
global:
server-port: 54321
log-level: debug
plugins:
araldo.marshalling:
- name: marshal-json
id: marshal-json
araldo.endpoints.endpoint:
- name: mock_1
id: endpoint-mock
channel: channel_1
- name: redis_2
id: endpoint-mock
channel: channel_2
- name: redis_3
id: endpoint-mock
channel: channel_3
routes:
redis_1:
- redis_2
- redis_3
Platform & System Requirements
******************************
- *araldo* has been tested under Python 2.6 and 2.7. Python 3.x is not
supported because not all libraries it depends on currently support 3.x.
- *araldo* was tested exclusively under Linux.