Metadata-Version: 2.1
Name: channelstream
Version: 0.6.9
Summary: Websocket server supporting channels/users communication
Home-page: https://github.com/Channelstream/channelstream
Author: Marcin Lulek
Author-email: info@webreactor.eu
License: BSD
Keywords: websockets async communication chat notification django flask pyramid
Platform: UNKNOWN
Classifier: Framework :: Django
Classifier: Framework :: Flask
Classifier: Framework :: Pyramid
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Communications :: Conferencing
Requires-Python: >=2.7
Description-Content-Type: text/markdown
Requires-Dist: gevent (>=1.3.7)
Requires-Dist: ws4py (>=0.5.1)
Requires-Dist: marshmallow (>=2.16.1)
Requires-Dist: python-dateutil (>=2.7.5)
Requires-Dist: pyramid (>=1.9.2)
Requires-Dist: pyramid-jinja2 (>=2.7)
Requires-Dist: pyramid-apispec (>=0.2.1)
Requires-Dist: itsdangerous (>=1.1.0)
Requires-Dist: requests (>=2.20.0)
Requires-Dist: six (>=1.11.0)
Provides-Extra: dev
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pyramid; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: mock; extra == 'dev'
Provides-Extra: lint
Requires-Dist: black; extra == 'lint'

# Channelstream

[![Build Status]](https://travis-ci.org/Channelstream/channelstream)

This is a websocket-based communication server for python applications,
your applications communicate with it via simple JSON REST API.

Visit http://channelstream.org for more information.

## Installation and Setup

Obtain source from github and do:

    python setup.py develop

Basic usage:

    YOUR_PYTHON_ENV/bin/channelstream

The server can (and should be) also be configured via ini files (channelstream -i filename), example:

    [channelstream]
    debug = 0
    port = 8000
    secret = YOURSECRET
    admin_secret = YOURADMINSECRET
    allow_posting_from = 127.0.0.1,
                         x.x.x.x,
                         y.y.y.y,

To build frontend files:

    cd frontend
    yarn
    yarn build # build minified bundles
    yarn dev   # run watcher process and rebuild on the fly

## Demos

This repository provides demonstrative applications on how to connect with the server
and send information to clients.

You have a simple notification demo built on flask:

    cd demo/notification/
    YOUR_PYTHON_ENV/bin/pip install flask
    YOUR_PYTHON_ENV/bin/flask run

Now you can open multiple browser windows to http://127.0.0.1:5000/ and test notifications.

There is also more complex chat application demo included, it showcases
multiple channel subscriptions, message edits and user state changing.

    YOUR_PYTHON_ENV/bin/python demo/chat/app.py

Open your browser and point it to following url:

    http://127.0.0.1:6543

To run the demo you will need to have the `requests` package installed in your environment.

### Security and communication model

Channelstream provides API explorer that you can use to interact with various
endpoints, it is available by default under http://127.0.0.1:8000/api-explorer.

To send information client interacts only with your normal www application.
Your app handled authentication and processing messages from client, then passed
them as signed message to channelstream server for broadcast.

websocket client -> webapp (security and transformation happens here) -> REST call to socket server -> broadcast to other clients

This model is easy to implement, secure, easy to scale and allows all kind of
languages/apps/work queues to interact with socket server.

All messages need to be signed with a HMAC of destination endpoint ::

    import requests
    from itsdangerous import TimestampSigner
    signer = TimestampSigner(SERVER_SECRET)
    sig_for_server = signer.sign('/connect')
    secret_headers = {'x-channelstream-secret': sig_for_server,
                      'Content-Type': 'application/json'}
    response = requests.post(url, data=json.dumps(payload),
                             headers=secret_headers).json()

## Data format and endpoints

Please consult API Explorer (http://127.0.0.1:8000/api-explorer) for in depth information
about endpoints.

Some examples:

* /connect **POST** connects users to the server
* /subscribe **POST** Subscribes connection to new channels
* /unsubscribe **POST** Removes connection from channels
* /user_state **POST** set the state of specific user
* /message **POST** Send message to channels and/or users
* /message **DELETE** Delete message from history and emit changes
* /message **PATCH** Edit existing message in history and emit changes
* /channel_config **POST** Set channel configuration
* /info **POST** Returns channel information

Client API

* /ws **GET** Handles websocket connections
* /listen **GET** Handles long polling connections
* /disconnect **GET** Permanently remove connection from server
* /disconnect **POST** Permanently remove connection from server


Admin API

* /admin/admin.json **GET** Return server information in json format for admin panel purposes
* /admin/admin.json **POST** Return server information in json format for admin panel purposes

### Responses to js client

Responses to client are in form of **list** containing **objects**:

examples:

**new message** ::

    {
    "date": "2011-09-15T11:36:18.471862",
    "message": MSG_PAYLOAD,
    "type": "message",
    "user": "NAME_OF_POSTER",
    "channel": "CHAN_NAME"
    }

**presence info** ::

    {
    "date": "2011-09-15T11:43:47.434905",
    "message": {"action":"joined/parted"},
    "type": "presence",
    "user": "NAME_OF_POSTER",
    "channel": "CHAN_NAME"
    }

Currently following message types are emited: `message`, `message:edit`,
`message:delete`, `presence`, `user_state_change`.

[Build Status]: https://travis-ci.org/Channelstream/channelstream.svg?branch=master


