.. 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.