saltyrtc.server 5.0.1
A SaltyRTC compliant signalling server.
License: MIT
Keywords: saltyrtc signalling signaling websocket websockets nacl

SaltyRTC Signalling Server
==========================

|CircleCI| |codecov| |PyPI| |Gitter|

This is a SaltyRTC server implementation for Python 3.5+ using
`asyncio`_.

Note
****

On machines where Python 3 is not the default Python runtime, you should
use ``pip3`` instead of ``pip``.

Prerequisites
*************

.. code-block:: bash

    sudo apt-get install python3 python3-pip

We recommend using `venv`_ to create an isolated Python environment:

.. code-block:: bash

    pyvenv venv

You can switch into the created virtual environment *venv* by running
this command:

.. code-block:: bash

    source venv/bin/activate

While the virtual environment is active, all packages installed using
``pip`` will be installed into this environment.

To deactivate the virtual environment, just run:

.. code-block:: bash

    deactivate

If you want easier handling of your virtualenvs, you might also want to
take a look at `virtualenvwrapper`_.

Installation
************

If you are using a virtual environment, activate it first.

Install the module by running:

.. code-block:: bash

    pip install saltyrtc.server

The dependency ``libnacl`` will be installed automatically. However, you
may need to install `libsodium`_ for ``libnacl`` to work.

Command Line Usage
******************

The script ``saltyrtc-server`` will be automatically installed and
provides a command line interface for the server.

Run the following command to see detailed usage information:

.. code-block:: bash

    saltyrtc-server --help

All command line options are also available as environment variables by
prefixing them with `SALTYRTC_SERVER_` and the upper case command name,
followed by the option name in upper case. For example:
`SALTYRTC_SERVER_SERVE_PORT=8765`.

Quick Start
-----------

Generate a new *private permanent key*:

.. code-block:: bash

    saltyrtc-server generate /path/to/permanent-key

Run the following command to start the server on any address with port `8765`:

.. code-block:: bash

    saltyrtc-server serve \
        -p 8765 \
        -tc /path/to/x509-certificate \
        -tk /path/to/key \
        -k /path/to/permanent-key

Alternatively, provide the options via environment variables:

.. code-block:: bash

    export SALTYRTC_SERVER_SERVE_PORT=8765 \
           SALTYRTC_SERVER_SERVE_TLSCERT=/path/to/x509-certificate \
           SALTYRTC_SERVER_SERVE_TLSKEY=/path/to/key \
           SALTYRTC_SERVER_SERVE_KEY=/path/to/permanent-key
    saltyrtc-server serve

Docker
------

You can also use our `official Docker images`_ to run the server:

.. code-block:: bash

    docker run \
        -v /path/to/cert-and-keys:/var/saltyrtc \
        -p 8765:8765
        -it saltyrtc/saltyrtc-server-python:<tag> serve \
        -p 8765 \
        -tc /var/saltyrtc/x509-certificate \
        -tk /var/saltyrtc/key \
        -k /var/saltyrtc/permanent-key

The above command maps port `8765` of the server within the container to port
`8765` on the host machine.

Of course it is also possible to use environment variables to provide the
options, as explained in the previous section.

Contributing
************

If you want to contribute to this project, you should install the
optional ``dev`` requirements of the project in an editable environment:

.. code-block:: bash

    git clone https://github.com/saltyrtc/saltyrtc-server-python.git
    cd saltyrtc-server-python
    pip install -e .[dev]

Before creating a pull request, it is recommended to run the following
commands to check for code style violations (``flake8``), optimise
imports (``isort``), do a static type analysis and run the project's tests:

.. code-block:: bash

    flake8 .
    isort -rc .
    MYPYPATH=${PWD}/stubs mypy saltyrtc examples
    py.test

Reporting Security Issues
*************************

Please report security issues directly to one or both of the following
contacts:

-  Danilo Bargen

   -  Email: mail@dbrgn.ch
   -  Threema: EBEP4UCA
   -  GPG: `EA456E8BAF0109429583EED83578F667F2F3A5FA`_

-  Lennart Grahl

   -  Email: lennart.grahl@gmail.com
   -  Threema: MSFVEW6C
   -  GPG: `3FDB14868A2B36D638F3C495F98FBED10482ABA6`_

.. _asyncio: https://docs.python.org/3/library/asyncio.html
.. _venv: https://docs.python.org/3/library/venv.html
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/
.. _libsodium: https://download.libsodium.org/doc/installation/
.. _official Docker images: https://hub.docker.com/r/saltyrtc/saltyrtc-server-python

.. |CircleCI| image:: https://circleci.com/gh/saltyrtc/saltyrtc-server-python.svg?style=shield
   :target: https://circleci.com/gh/saltyrtc/saltyrtc-server-python
.. |codecov| image:: https://codecov.io/gh/saltyrtc/saltyrtc-server-python/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/saltyrtc/saltyrtc-server-python
.. |PyPI| image:: https://badge.fury.io/py/saltyrtc.server.svg
   :target: https://badge.fury.io/py/saltyrtc.server
.. |Gitter| image:: https://badges.gitter.im/saltyrtc/Lobby.svg
   :target: https://gitter.im/saltyrtc/Lobby
.. _EA456E8BAF0109429583EED83578F667F2F3A5FA: https://keybase.io/dbrgn
.. _3FDB14868A2B36D638F3C495F98FBED10482ABA6: https://keybase.io/lgrahl

Changelog
*********

`5.0.1`_ (2019-09-09)
---------------------

- Fix an exception when disconnected by another client

`5.0.0`_ (2019-08-29)
---------------------

- Bump the Python version requirement to 3.6.1
- Upgrade dependencies
- Fix a race condition that leads to path duplication

`4.2.0`_ (2019-04-25)
---------------------

- Internal refactoring of task and job handling

`4.1.1`_ (2019-04-09)
---------------------

- Fix accidental cancellation of the task loop

`4.1.0`_ (2019-04-04)
---------------------

- Allow the use of environment variables as CLI parameter substitution
    - Instead of ``saltyrtc-server serve --tlskey=foo`` you can now write
      ``SALTYRTC_SERVER_TLSKEY=foo saltyrtc-server serve``
- Fix import order in pyi files

`4.0.1`_ (2019-01-24)
---------------------

- Bump the Python version requirement to 3.5.3
- Remove workarounds for Python 3.5.2

`4.0.0`_ (2018-01-24)
---------------------

**Important:** Make sure you're using Python >= 3.5.3 before upgrading.

- Drop Python 3.4 support (major)
- Deprecate the CLI options `-sc`, `--sslcert` and `-sk`, `--sslkey`. Use
  `-tc`, `--tlscert` and `-tk`, `--tlskey` instead.
- Add type hints
- Fix discard string messages
- Fix validate received client ID types correctly
- Fix validate received sub-protocols correctly
- Fix a race condition during the handshake when one client drops another
- Cleanup of the code base

`3.1.2`_ (2019-01-08)
---------------------

- Fix imports for earlier Python 3.5 versions

`3.1.1`_ (2019-01-08)
---------------------

- Disable deprecation warning in py.test for now (see `#90`_)

`3.1.0`_ (2019-01-07)
---------------------

- Event callback arguments now always need to provide a `data` argument

`3.0.1`_ (2019-01-02)
---------------------

- Fix forward the `timeout` close code as an `int` to event callbacks

`3.0.0`_ (2018-12-18)
---------------------

- Use the `timeout` close code (`3008`) when a client does not respond to a
  *ping* message (major)
- Add support for Python 3.7
- Various task queue improvements resulting in more robust client handling
- Fix to not send a 'disconnected' message when a responder has been dropped
  via 'drop-responder'
- Fix to prevent the initiator from relaying messages to a responder client
  which is in the process of being dropped
- Fix to not accept new incoming connections when closing the server

`2.0.1`_ (2018-08-20)
---------------------

- Fix to prevent creating two path instances with the same path string
- Various improvements to logging messages

`2.0.0`_ (2018-07-16)
---------------------

**Important:** Make sure you're using Python >= 3.4.4 and that your clients
support the `disconnected` message before upgrading.

- Add support for the `disconnected` message (major)
- Fix potential invalid order of messages when dispatching a `send-error`
- Fix the *id* field's value in the `send-error` message
- Fix a few potential race conditions

`1.0.2`_ (2017-11-15)
---------------------

- Fix do not accept unencrypted 'client-auth' messages from the initiator

`1.0.1`_ (2017-07-25)
---------------------

- Fix to handle new `libnacl <https://github.com/saltstack/libnacl/pull/91>`_
  exceptions

`1.0.0`_ (2017-03-24)
---------------------

- Add server implementation of the `SaltyRTC 1.0 Protocol`_
- Initial publication on PyPI

.. _#90: https://github.com/saltyrtc/saltyrtc-server-python/issues/90
.. _SaltyRTC 1.0 Protocol: https://github.com/saltyrtc/saltyrtc-meta/blob/protocol-1.0/Protocol.md

.. _5.0.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v5.0.0...v5.0.1
.. _5.0.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v4.2.0...v5.0.0
.. _4.2.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v4.1.1...v4.2.0
.. _4.1.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v4.1.0...v4.1.1
.. _4.1.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v4.0.1...v4.1.0
.. _4.0.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v4.0.0...v4.0.1
.. _4.0.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v3.1.2...v4.0.0
.. _3.1.2: https://github.com/saltyrtc/saltyrtc-server-python/compare/v3.1.1...v3.1.2
.. _3.1.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v3.1.0...v3.1.1
.. _3.1.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v3.0.1...v3.1.0
.. _3.0.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v3.0.0...v3.0.1
.. _3.0.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v2.0.1...v3.0.0
.. _2.0.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v2.0.0...v2.0.1
.. _2.0.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/v1.0.2...v2.0.0
.. _1.0.2: https://github.com/saltyrtc/saltyrtc-server-python/compare/v1.0.1...v1.0.2
.. _1.0.1: https://github.com/saltyrtc/saltyrtc-server-python/compare/v1.0.0...v1.0.1
.. _1.0.0: https://github.com/saltyrtc/saltyrtc-server-python/compare/aa3aceba46cc8683e640499936a6eaa406819ef8...v1.0.0