Merge pull request #161 from lendingblock/master

1.2.4

openapi/__init__.py

@@ -1,4 +1,3 @@
-"""Minimal OpenAPI asynchronous server application
-"""
+"""Minimal OpenAPI asynchronous server application"""
 
-__version__ = '1.2.3'
+__version__ = '1.2.4'

readme.md

@@ -36,3 +36,63 @@ pytest --cov
 * Asynchronous DB interaction with [asyncpg](https://github.com/MagicStack/asyncpg)
 * Migrations with [alembic](http://alembic.zzzcomputing.com/en/latest/)
 * SqlAlchemy tables as python dataclasses
+
+## Websockets
+
+This library provides a simple distributed websocket utility for creating
+websocket remote procedure calls (RPC) and pub/sub.
+```python
+from aiohttp import web
+
+from openapi.ws import Sockets
+
+app = web.Application()
+...
+app['web_sockets'] = Sockets(app)
+```
+### RPC protocol
+
+The RPC protocol has the following structure for incoming messages
+```javascript
+{
+    "id": "abc",
+    "method": "rpc_method_name",
+    "payload": {
+        ...
+    }
+}
+```
+The ``id`` is used by clients to link the request with the corresponding response.
+The response for an RPC call is eitrher a success
+```javascript
+{
+    "id": "abc",
+    "method": "rpc_method_name",
+    "result": {
+        ...
+    }
+}
+```
+or error
+```
+{
+    "id": "abc",
+    "method": "rpc_method_name":
+    "error": {
+        ...
+    }
+}
+```
+### Publish/Subscribe
+
+To subscribe to messages, one need to use the ``Subscribe`` mixin with the subscribe RPC handler.
+Messages take the form:
+```javascript
+{
+    "channel": "channel_name",
+    "event": "event_name",
+    "data": {
+        ...
+    }
+}
+```