crossbarhttp3 1.1
Library for connecting to Crossbar.io HTTP Bridge Services.
License: MIT
Keywords: wamp,crossbar.io,websockets,http-bridge

===============
Crossbar HTTP 3
===============

.. image:: https://travis-ci.org/jose-lpa/crossbarhttp3.svg?branch=master
    :target: https://travis-ci.org/jose-lpa/crossbarhttp3

.. image:: https://codecov.io/gh/jose-lpa/crossbarhttp3/branch/master/graph/badge.svg
    :target: https://codecov.io/github/jose-lpa/crossbarhttp3

.. image:: https://img.shields.io/pypi/v/crossbarhttp3.svg
    :target: https://pypi.python.org/pypi/crossbarhttp3

.. image:: https://img.shields.io/pypi/l/crossbarhttp3.svg
    :target: https://pypi.python.org/pypi/crossbarhttp3

Module that provides methods for accessing Crossbar.io HTTP Bridge Services

Fork of the original package by `Eric Chapman at The HQ`_, now supporting 
Python 2.6, 2.7 and 3+ versions.


Installation
============

Install Crossbar HTTP 3 with pip::

    pip install crossbarhttp3


Basic usage
===========

Call
----

To call a Crossbar HTTP bridge, do the following:

.. code-block:: python

    client = Client('http://127.0.0.1/call')
    result = client.call('com.example.add', 2, 3, offset=10)
    
This will call the following ``add_something`` method of an `ApplicationSession object`_:

.. code-block:: python

    from autobahn.twisted.wamp import ApplicationSession
    from twisted.internet.defer import inlineCallbacks


    class MyComponent(ApplicationSession):
        @inlineCallbacks
        def onJoin(self, details):

            def add_something(x, y, offset=0):
                print('Add was called')
                return x + y + offset

            yield self.register(add_something, 'com.example.add')
        
Publish
-------

To publish to a Crossbar HTTP bridge, do the following:

.. code-block:: python

    client = Client('http://127.0.0.1/publish')
    result = client.publish('com.example.event', event='new event')
    
The receiving subscription implemented in an ``ApplicationSession`` class would
look like this:

.. code-block:: python

    from autobahn.twisted.wamp import ApplicationSession
    from twisted.internet.defer import inlineCallbacks


    class MyComponent(ApplicationSession):
        @inlineCallbacks
        def onJoin(self, details):

            def subscribe_something(event=None, **kwargs):
                print('Publish was called with event %s' % event)

            yield self.subscribe(subscribe_something, 'com.example.event')

Key/Secret
----------

For bridge services that have a key and secret defined, simply include the key
and secret in the instantiation of the client.

.. code-block:: python

    client = Client('http://127.0.0.1/publish', key='key', secret='secret')

Additional options
------------------

There are two more options available in the client instantiation:

- ``timeout``: Lets you specify a number of seconds from which an idle request to the Crossbar.io node will be dismissed (timed out). Defaults to ``None``, meaning that the global default timeout setting will be used.
- ``silently``: If set to ``True``, any failed request to the Crossbar.io node will be returned by the client as ``None``, **without raising any exception**. Defaults to ``False``, meaning that all failures will raise their correspondent exceptions.

Exceptions
----------

The library will throw the following exceptions.  Note that all exceptions
subclass from ``ClientBaseException`` so you can just catch that if you don't
want the granularity.

- ``ClientBadUrl`` - The specified URL is not a HTTP bridge service
- ``ClientBadHost`` - The specified host name is rejecting the connection
- ``ClientMissingParams`` - The call was missing parameters
- ``ClientSignatureError`` - The signature did not match
- ``ClientNoCalleeRegistered`` - Callee was not registered on the router for the specified procedure
- ``ClientCallRuntimeError`` - Procedure triggered an exception

Contributing
============

All bug-fixes or improvements to the library are welcome.

To contribute, fork the repo and submit a pull request to the ``develop``
branch. Please, try to follow this basic coding rules:

- Always include some unit tests for the new code you write or the bugs you fix. Or, update the existent unit tests if necessary.
- Stick to `PEP-8`_ styling.

Testing
-------

In order to test Crossbar HTTP 3 properly you must have a Crossbar.io node in
HTTP Bridge mode running in localhost port 8001. You can do that by yourself if
you need it, but otherwise there is a `Docker image`_ already prepared, so you
don't have to bother with this.

To use that image and raise a Docker container with everything working, make
sure you have `Docker installed`_ and execute this command::

    docker run -t -p 8001:8001 --name crossbar-bridge joselpa/crossbar-http-bridge:0.2

Then you can run the unit tests in the regular way::

    python setup.py test

License
=======

Released under `MIT License`_.

.. _Eric Chapman at The HQ: https://github.com/thehq/python-crossbarhttp
.. _ApplicationSession object: http://autobahn.ws/python/wamp/programming.html#creating-components
.. _PEP-8: https://www.python.org/dev/peps/pep-0008/
.. _Docker image: https://hub.docker.com/r/joselpa/crossbar-http-bridge/
.. _Docker installed: https://docs.docker.com/
.. _MIT License: https://opensource.org/licenses/MIT