Metadata-Version: 2.1
Name: redis-websocket-api
Version: 0.4.3
Summary: Redis-over-WebSocket API on top of websockets and aioredis
Home-page: https://github.com/geops/redis-websocket-api
Author: Milan Oberkirch | geOps
Author-email: milan.oberkirch@geops.de
License: MIT
Keywords: tralis websocket websockets aioredis redis
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: aioredis
Requires-Dist: hiredis
Requires-Dist: websockets
Provides-Extra: geo
Requires-Dist: pyproj (<2) ; extra == 'geo'
Provides-Extra: testing
Requires-Dist: pytest ; extra == 'testing'

An extensible Redis-over-WebSocket API on top of websockets and aioredis.


Installation
------------

For basic functionality:

    pip install redis_websocket_api

With geo extension (filtering messages by extent, projection transformation):

    pip install redis_websocket_api[geo]


Server-Side Usage
-----------------

For a quick test you can run

```bash
python -m redis_websocket_api
```

to start a simple redis websocket api on `ws://localhost:8765`.

This does [roughly](./redis_websocket_api/__main__.py) the equivalant of:

```python
from aioredis import from_url
from redis_websocket_api import WebsocketServer, WebsocketHandler


class PublishEverythingHandler(WebsocketHandler):

    def channel_is_allowed(self, channel_name):
        return True


WebsocketServer(
    redis=from_url("redis:///", encoding="utf-8", decode_responses=True),
    read_timeout=30,
    keep_alive_timeout=120,
    handler_class=PublishEverythingHandler,
).listen(
    host='localhost',
    port=8000,
    channel_patterns=["[a-z]*"],
)
```

Have a look at `examples/demo.py` for an example with the `GeoCommandsMixin`
added.


Client-Side Usage
-----------------

#### `WebsocketHandler`

The default functionality provides the following interface to the web client
(expecting the requests over a websocket connection):
- `GET key` translates to `hvals key`
- `GET key hkey` translates to `hget key hkey`
- `SUB key` subscribes the websocket to a redis channel (using a single redis
  connection pool for all clients)
- `DEL key` unsubscribes the client from the channel
- `PING` causes a `PONG` response (to avoid timeouts)

#### Subclass of `WebsocketHandler` with `GeoCommandsMixin` added

By adding the `GeoCommandsMixin` the web client can use
- `BBOX left bottom right top` to only receive GeoJSON features within this box
  plus all messages which are not valid GeoJSON
- `PROJECTION epsg:number` causes all future GeoJSON features to be transformed
  to the given projection

See `examples/demo.py` for how to use an extended `WebsocketHandler` subclass.

Geo commands are currently limited to `LineString`, `Polygon`, and `Point`
geometries.

#### Build your own protocol

Using the commands listed above for communicating from client to server is
completly optional and determinded by the Mixin classes added to the
`WebsocketHandlerBase`.


