Source

araldo / README.rst

Full commit
bb b...@gmx.de 9cca84a 
bb b...@gmx.de c7525c9 
bb b...@gmx.de 9cca84a 
bb b...@gmx.de 885da65 
bb b...@gmx.de 9cca84a 

bb b...@gmx.de c7525c9 
bb b...@gmx.de 9cca84a 

bb b...@gmx.de 885da65 

bb b...@gmx.de c7525c9 




bb b...@gmx.de f20ca3e 
bb b...@gmx.de c7525c9 











bb b...@gmx.de 885da65 

bb b...@gmx.de c7525c9 







































bb b...@gmx.de 885da65 


bb b...@gmx.de c7525c9 







bb b...@gmx.de 885da65 


































bb b...@gmx.de c7525c9 

bb b...@gmx.de f20ca3e 























araldo
######

*araldo* provides a simple, extensible communication relay (based on `gevent <http://www.gevent.org/>`_ and `WebSockets <http://en.wikipedia.org/wiki/WebSocket>`_) between multiple endpoints

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 <http://www.gevent.org/>`_, a corouting-based networking
library. *gevent* uses `green threads <http://en.wikipedia.org/wiki/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 <http://en.wikipedia.org/wiki/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    https://bitbucket.org/ganymed/araldo-redis
                     PubSub
araldo-websocket     Communication with an      https://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
*************

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:

.. code-block:: yaml

  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