Merge pull request #12 from noisyboiler/0.7.6

0.7.6

README.rst

@@ -36,12 +36,15 @@ For the quickeststart I suggest that you use Crossbar.io and start it up on the
 
     $ pip install --editable .[dev]
 
-    $ crossbar start --config ./test/crossbar.config.json
+    $ crossbar start --config ./wampy/testing/configs/crossbar.config.json
 
 By default a **wampy** ``WebClient`` connects to localhost on port 8080, but this is of course configurable, and is done so on client initialisation.
 
 Now open your preferred text editor and we'll write a few lies of Python constructing a simple WAMP service that takes a decimal number and returns the binary representation of it - fantastic stuff!
 
+Wampy RPC
+~~~~~~~~~
+
 ::
 
     from wampy.peers.clients import Client
@@ -85,13 +88,69 @@ Note that the `Client` here is connecting to `localhost` and `8080`, but you cou
 
     In [2]: from wampy.peers.routers import Crossbar
 
-    In [2]: with Client(router=Crossbar()) as client:
+    In [3]: with Client(router=Crossbar()) as client:
                 result = client.rpc.get_binary_number(number=100)
 
-Please check out the full documentation at ReadTheDocs_ for more patterns.
+Publishing and Subscribing is equally as simple
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To demonstrate, first of all you need a Subscriber. You can either create one yourself in a python module or use the example client in `docs.examples.services`. Here we use the given example service, but all a Subscriber is is a wampy Client with a method decorated by ``subscribe``.
+
+Let's start up that example service.
+
+::
+    
+    $ wampy run docs.examples.services:SubscribingService --router http://localhost:8080
+
+Now we have a service running that subscribes to the topic "foo".
+
+In another terminal, with a wampy virtualenv, you can create a Publihser - which is no different to any other Client.
+
+::
+
+    In [1]: from wampy.peers.clients import Client
+
+    In [2]: from wampy.peers.routers import Crossbar
+
+    In [3]: with Client(router=Crossbar()) as client:
+                client.publish(topic="foo", message="spam")
+
+Hopefully you'll see any message you send printed to the screen where the example service is running. You'll also see the meta data that wampy chooses to send.
+
+TLS Support (alpha)
+~~~~~~~~~~~~~~~~~~
+
+When you instantiate your Client, over-ride the default ``ws`` transport with "wss", e.g.
+
+::
+
+    In [1]: from wampy.peers.clients import Client
+
+    In [2]: from wampy.peers.routers import Crossbar
+
+    In [3]: client = Client(router=Crossbar(), transport="wss")
+
+Your certificates must be configured in your Crossbar.io config. For an example see ``crossbar.config.tls.json`` in the `testing` namespace. Also see ``test.test_transports.py``.
+
 
 Thank you.
 
+
+Testing
+~~~~~~~
+
+wampy provides some ``pytest`` fixtures and helpers for you to run a crossbar server. These are ``router``, ``tls_router`` and ``session_maker``.
+
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+::
+
+    $ pip install --editable .[dev]
+    $ py.test ./test -v
+
+
 Build the docs
 ~~~~~~~~~~~~~~
 

docs/examples/services.py

@@ -1,27 +1,42 @@
 import datetime
 
-from wampy.peers.clients import DefaultClient
-from wampy.roles import register_rpc
+from wampy.peers.clients import Client
+from wampy.roles.callee import register_rpc
+from wampy.roles.subscriber import subscribe
 
 
-class DateService(DefaultClient):
-    """ A web service that returns the current date.
+class DateService(Client):
+    """ A service that returns the current date.
 
     usage ::
 
         $ wampy run docs.examples.services:DateService --router http://example.com:port
 
-    This service can then be called as such ::
+    e.g. ::
 
-        In [1]: from wampy.peers import WebClient
-
-        In [2]: with WebClient(name="wampy", host="examaple.com", port=port) as client:
-           ...:     date = client.rpc.get_todays_date()
-
-        In [3]: date
-        Out[3]: u'2016-11-26'
+        $ crossbar start --config ./wampy/testing/configs/crossbar.config.json
+        $ wampy run docs.examples.services:SubscribingService --router http://localhost:8080
 
     """
     @register_rpc
     def get_todays_date(self):
         return datetime.date.today().isoformat()
+
+
+class SubscribingService(Client):
+    """ A service that prints out "foo" topic messages
+
+    usage ::
+
+        $ wampy run docs.examples.services:SubscribingService --router http://example.com:port
+
+    e.g. ::
+
+        $ crossbar start --config ./wampy/testing/configs/crossbar.config.json
+        $ wampy run docs.examples.services:SubscribingService --router http://localhost:8080
+
+    """
+
+    @subscribe(topic="foo")
+    def foo_handler(self, **kwargs):
+        print("foo message received: {}".format(kwargs))

setup.py

@@ -12,7 +12,7 @@
 
 setup(
     name='wampy',
-    version='0.7.5',
+    version='0.7.6',
     description='WAMP RPC and Pub/Sub for python apps and microservices',
     long_description=long_description,
     url='https://github.com/noisyboiler/wampy',

test/test_publishing.py

@@ -1,3 +1,4 @@
+import logging
 import pytest
 from mock import ANY
 
@@ -8,6 +9,9 @@
 from test.helpers import assert_stops_raising
 
 
+logger = logging.getLogger('wampy.testing')
+
+
 class SubscribingClient(Client):
 
     call_count = 0

test/test_transports.py

@@ -0,0 +1,40 @@
+import datetime
+from datetime import date
+
+from wampy.peers.clients import Client
+from wampy.roles.callee import rpc
+
+
+class DateService(Client):
+
+    @rpc
+    def get_todays_date(self):
+        return datetime.date.today().isoformat()
+
+
+def test_connection(router):
+    service = DateService(router=router, transport="ws")
+    with service:
+
+        client = Client(router=router, transport="ws")
+
+        with client:
+            result = client.rpc.get_todays_date()
+
+    today = date.today()
+
+    assert result == today.isoformat()
+
+
+def test_secure_connection(tls_router):
+    service = DateService(router=tls_router, transport="wss")
+    with service:
+
+        client = Client(router=tls_router, transport="wss")
+
+        with client:
+            result = client.rpc.get_todays_date()
+
+    today = date.today()
+
+    assert result == today.isoformat()

wampy/peers/clients.py

@@ -21,7 +21,7 @@ class Client(object):
 
     def __init__(
             self, roles=DEFAULT_ROLES, realm=DEFAULT_REALM, router=Router(),
-            transport="websocket", id=None
+            transport="ws", id=None
     ):
         self.roles = roles
         self.realm = realm

wampy/roles/subscriber.py

@@ -63,7 +63,7 @@ class TopicSubscriber(object):
 
     def __init__(
             self, router, realm, topics, message_handler,
-            roles=None, transport="websocket",
+            roles=None, transport="ws",
     ):
         """ Subscribe to a single topic.
 

wampy/session.py

@@ -7,21 +7,27 @@
 from wampy.messages.handlers.default import DefaultMessageHandler
 from wampy.messages.hello import Hello
 from wampy.messages.goodbye import Goodbye
-from wampy.transports.websocket.connection import WebSocket
+from wampy.transports.websocket.connection import WebSocket, TLSWebSocket
 
 from wampy.messages import MESSAGE_TYPE_MAP
 
 
 logger = logging.getLogger('wampy.session')
 
 
-def session_builder(client, router, realm, transport="websocket"):
-    if transport == "websocket":
-        transport = WebSocket(host=router.host, port=router.port)
-        return Session(
-            client=client, router=router, realm=realm, transport=transport
-        )
-    raise WampError("transport not supported: {}".format(transport))
+def session_builder(client, router, realm, transport="ws"):
+    if transport == "ws":
+        transport = WebSocket(
+            host=router.host, port=router.port, websocket_location="ws")
+    elif transport == "wss":
+        transport = TLSWebSocket(
+            host=router.host, port=router.port, websocket_location="ws")
+    else:
+        raise WampError("transport not supported: {}".format(transport))
+
+    return Session(
+        client=client, router=router, realm=realm, transport=transport
+    )
 
 
 class Session(object):

wampy/testing/configs/crossbar.config.tls.json

@@ -0,0 +1,59 @@
+{
+   "version":2,
+   "workers":[
+      {
+         "type":"router",
+         "realms":[
+            {
+               "name":"realm1",
+               "roles":[
+                  {
+                     "name":"anonymous",
+                     "permissions":[
+                        {
+                           "uri":"",
+                           "match":"prefix",
+                           "allow":{
+                              "call":true,
+                              "register":true,
+                              "publish":true,
+                              "subscribe":true
+                           },
+                           "disclose":{
+                              "caller":false,
+                              "publisher":false
+                           },
+                           "cache":true
+                        }
+                     ]
+                  }
+               ]
+            }
+         ],
+         "transports":[
+            {
+               "type":"web",
+               "endpoint":{
+                  "type":"tcp",
+                  "port":8080,
+                  "tls":{
+                     "key":"./wampy/testing/keys/server_key.pem",
+                     "certificate":"./wampy/testing/keys/server_cert.pem",
+                     "dhparam":"./wampy/testing/keys/dhparam.pem",
+                     "ciphers":"ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AES:RSA+3DES:!ADH:!AECDH:!MD5:!DSS"
+                  }
+               },
+               "paths":{
+                  "/":{
+                     "type":"static",
+                     "directory":"./wampy/testing/"
+                  },
+                  "ws":{
+                     "type":"websocket"
+                  }
+               }
+            }
+         ]
+      }
+   ]
+}

wampy/testing/keys/dhparam.pem

@@ -0,0 +1,5 @@
+-----BEGIN DH PARAMETERS-----
+MIGHAoGBALOSAAEXXAZLxNbZOw92qfwJtToq1eiVr8vF7jhVESvZXviE/nwHVYw3
+IkbjFJDK+6kwH+KGpMGf4DYDraRpiArLOoveL8swh3WouKAEl0o5yoLwUi072W8j
+SSPEGqRh+19r2HNo25/mgxF9ddMKFalGzURM2oTl4y+ZXaIt6GsTAgEC
+-----END DH PARAMETERS-----

wampy/testing/keys/server_cert.pem

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDNjCCAh4CCQCP5LnGD/PkTDANBgkqhkiG9w0BAQUFADBdMQswCQYDVQQGEwJE
+RTEQMA4GA1UECAwHQmF2YXJpYTERMA8GA1UEBwwIRXJsYW5nZW4xFTATBgNVBAoM
+DFRhdmVuZG8gR21iSDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTE0MTEwNjIxMjIx
+MloXDTI0MTEwMzIxMjIxMlowXTELMAkGA1UEBhMCREUxEDAOBgNVBAgMB0JhdmFy
+aWExETAPBgNVBAcMCEVybGFuZ2VuMRUwEwYDVQQKDAxUYXZlbmRvIEdtYkgxEjAQ
+BgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+AK54iBXPWPyCGlsrGhBV1xkrfubttugoqADvfYP9eptzqOCzcAqtlWLFYf1tDGbT
+mkwNsgV/lJKVzGMyosSAuRBmolRTQeyBcypsX9QJt6s/PJ2vh3v2QQ7DWlokZGhx
+sCX6p6GEUbcBo61Yc+AvhAmJ+olYyLqp8nCIJFy0F+P7qvxx1B6pg08J/d75/m9A
+BiGgZ0WjYLrDj0yERWX3WljuYIT4e34WMPofaBeiMTQEpqdgTbuSgpXdNdlzuWaq
+gn8ITIHMnf5mlnCeU1rsHMJwJAUzRR9S40Km4WNxIP4/j+uVwMQLcJg73ni43n5V
+xza6fgCQGfe8HQLxItwoU0MCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEAEsiNnmRU
+O4UW2AjI5EIr1Na7Xae8NZyIGrH+ONJUxaQxrpj1Q/bHmN7ZPFIDkZ2NX0rZBWwC
+gbLSG0HIK2CdA+ghW0RaOnQgzLoJKJCERMSYDL26AXBJ4L0h5U43rsgXTD/zaWid
+9B90pxSCXvSnA+yw1U67Lgm1x9LEkgpGWpqPlHQBMvwi4gkkdUsPxBLCie4TfX+p
+gB51+Rjh8HaLl9tc0Z1JcjhK7ih1kz6A6XF7GaMvW0ipZYX/xIkUQNMTKhfdrrms
+qr2GdKmJpFKJhrvYpbx560R0ZT2Sxic8EOLjfWfvxD56xTU6ssosw1oYdRB2W9i7
+hsK8dBzPGj1ZcQ==
+-----END CERTIFICATE-----

wampy/testing/keys/server_key.pem

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEArniIFc9Y/IIaWysaEFXXGSt+5u226CioAO99g/16m3Oo4LNw
+Cq2VYsVh/W0MZtOaTA2yBX+UkpXMYzKixIC5EGaiVFNB7IFzKmxf1Am3qz88na+H
+e/ZBDsNaWiRkaHGwJfqnoYRRtwGjrVhz4C+ECYn6iVjIuqnycIgkXLQX4/uq/HHU
+HqmDTwn93vn+b0AGIaBnRaNgusOPTIRFZfdaWO5ghPh7fhYw+h9oF6IxNASmp2BN
+u5KCld012XO5ZqqCfwhMgcyd/maWcJ5TWuwcwnAkBTNFH1LjQqbhY3Eg/j+P65XA
+xAtwmDveeLjeflXHNrp+AJAZ97wdAvEi3ChTQwIDAQABAoIBAD0R+7CGr8NTVx5q
+a+kj4vLwgq8arld9Q7FwIyM8atpXFdnxdVqHgC7eoHow3ZJwpyXP9WxvR/Y3cR+X
+7dmSpTTUeCXELuM2PLWw0apK7HuI2xLnCimd/Q/J2aqL6omUoe/pWRv0URYaAM0A
+lS738uPT5FqHNVwBeNdjEDdS4rnuHei1wYwWKlZ5aTRaO21g0Ya67fY7AKRFuKEn
+TxGmgA/cKT+RCoztBSys1vY4vuBBhsZXBzSWjkQE/nh5FiZ/rDvmtPeBn2hjqKK2
+IE3k6LOvkpwSRfzbR26lQv3PdEL0SFbGiqwfCm2Et77scL73uXS5Ov8cnsKtlBXs
+xEWfrWECgYEA1gwOqsx3FAU+gwC/2fS9oA2niq2wCPkfQzeiqiExeUCbOnHG6pdH
+gv6GD7HPmu9KfY7gqsyku/x0+hMZszCg/98+s0lNL4+N5Khmg+ORso6FpOqLk0du
+5f1E+f/WDEjh0vKHXOLoaJ8tzj3JpZxwKL8/E2wG1dO5dWwAkUvEyq8CgYEA0Kq1
+/BUAUti6p6pGSVqijOsUFVDUxzne5aZEvtWmqHerYtShRZM0bmYsKhLjW9NuVMDa
+jBU1bs/UUcPbW0Bfc/Fl3fvCzXH7RxIEzMmnB5ckxLLzYMpDBVQ9PNZBBcW+B9d0
+xiScVExFIgAN+0nPNLa/wrEyvIml0i4TOlvlFa0CgYEA0F4QcSh1yyGHxxOVr+FW
+L1bbgF6wfSu2yUKBsUh61uSTuANGdtwpm1WWv/SCevry8uOBxgNNYkrSvRaW8B8o
+u61hZjq3TtNad/uPQFjqXn3rj61bjlX9mRpCaXQptO/GFgpOx5eEU0SR3LG9eOCf
+NqtmBcwlo0Zmxe4LZ2Xw/rUCgYAI6+OP/Y3f/OguFveeV0Ov5rUbHDOcuPqwsuUp
+i5Tuiv9G4HRstxh8x92Hhvs1h9qlwQEXECkSrcwUGt2cDyqFmIKUdRklE4R8y2Zt
+IwoDJxEpX8VMFBm9dpaPrVFmX8f6KdoSRqpwaDpkc8AlSEiVpmKYfl7+9JukWtfz
+nM40mQKBgQCIhntxpd46R3B4yn2nRm6VIduEIxkxYwJahKIiGi51GM4n3flJAoEV
+jTfzy5UEGz8WMhgr5PpvIyxaABIgU+ijbnQcHNN9WfcVULlM6WOyuRYRbqmaQOh7
+ohnuqq4w8Y0tK2UKK/Vf3ku16SCck2t/LpURwAZp/hKmxvZ46Th5wQ==
+-----END RSA PRIVATE KEY-----