Merge branch 'development'

Author: Pithikos

README.md

@@ -1,7 +1,7 @@
 Websocket Server
 =======================
 
-[![CircleCI](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master.svg?style=svg)](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master)
+[![CircleCI](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master.svg?style=svg)](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master) [![PyPI version](https://badge.fury.io/py/websocket-server.svg)](https://badge.fury.io/py/websocket-server)
 
 A minimal Websockets Server in Python with no external dependencies.
 
@@ -18,11 +18,9 @@ websocket server for prototyping, testing or for making a GUI for your applicati
 Installation
 =======================
 
-You can use the project in three ways.
+Install with pip
 
-  1. Copy/paste the *websocket_server.py* file in your project and use it directly
-  2. `pip install git+https://github.com/Pithikos/python-websocket-server` (latest code)
-  3. `pip install websocket-server` (might not be up-to-date)
+    pip install websocket-server
 
 For coding details have a look at the [*server.py*](https://github.com/Pithikos/python-websocket-server/blob/master/server.py) example and the [API](https://github.com/Pithikos/python-websocket-server#api).
 
@@ -61,7 +59,7 @@ The WebsocketServer can be initialized with the below parameters.
 
 *`key`* - If using SSL, this is the path to the key.  
 
-*`cert`* - If using SSL, this is the path to the certificate. 
+*`cert`* - If using SSL, this is the path to the certificate.
 
 
 ### Properties
@@ -80,6 +78,9 @@ The WebsocketServer can be initialized with the below parameters.
 | `set_fn_message_received()` | Sets a callback function that will be called when a `client` sends a message          | function        | None  |
 | `send_message()`            | Sends a `message` to a specific `client`. The message is a simple string.             | client, message | None  |
 | `send_message_to_all()`     | Sends a `message` to **all** connected clients. The message is a simple string.       | message         | None  |
+| `shutdown_gracefully()`     | Shutdown server by sending a websocket CLOSE handshake to all connected clients.      | None            | None  |
+| `shutdown_abruptly()`       | Shutdown server without sending any websocket CLOSE handshake.                        | None            | None  |
+
 
 
 ### Callback functions

docs/release-workflow.md

@@ -0,0 +1,14 @@
+Release notes
+-------------
+
+Releases are marked on master branch with tags. The upload to pypi is automated as long as a merge
+from development comes with a tag.
+
+General flow
+
+  1. Get in dev branch
+  2. Update VERSION in setup.py and releases.txt file
+  3. Make a commit
+  4. Merge development into master (`git merge --no-ff development`)
+  4. Add corresponding version as a new tag (`git tag <new_version>`) e.g. git tag v0.3.0
+  5. Push everything (`git push --tags && git push`)

docs/release.md

@@ -0,0 +1,9 @@
+0.4
+- Python 2 and 3 support
+
+0.5.1
+- SSL support
+- Drop Python 2 support
+
+0.5.4
+- Add API for shutting down server (abruptly & gracefully)

releases.txt

@@ -2,5 +2,5 @@
 tox>=3.24.0
 IPython
 pytest
-websocket-client
+websocket-client>=1.1.1
 twine

requirements.txt

@@ -12,7 +12,7 @@
     from distutils.command.install import install
 
 
-VERSION = '0.5.1'
+VERSION = '0.5.4'
 
 
 def get_tag_version():

setup.py

@@ -0,0 +1,84 @@
+from utils import session, client_session, server
+from time import sleep
+
+import websocket
+import pytest
+
+
+def test_send_close(client_session):
+    """
+    Ensure client stops receiving data once we send_close (socket is still open)
+    """
+    client, server = client_session
+    assert client.received_messages == []
+
+    server.send_message_to_all("test1")
+    sleep(0.5)
+    assert client.received_messages == ["test1"]
+
+    # After CLOSE, client should not be receiving any messages
+    server.clients[-1]["handler"].send_close()
+    sleep(0.5)
+    server.send_message_to_all("test2")
+    sleep(0.5)
+    assert client.received_messages == ["test1"]
+
+
+def test_shutdown_gracefully(client_session):
+    client, server = client_session
+    assert client.ws.sock and client.ws.sock.connected
+    assert server.socket.fileno() > 0
+
+    server.shutdown_gracefully()
+    sleep(0.5)
+
+    # Ensure all parties disconnected
+    assert not client.ws.sock
+    assert server.socket.fileno() == -1
+    assert not server.clients
+
+
+def test_shutdown_abruptly(client_session):
+    client, server = client_session
+    assert client.ws.sock and client.ws.sock.connected
+    assert server.socket.fileno() > 0
+
+    server.shutdown_abruptly()
+    sleep(0.5)
+
+    # Ensure server socket died
+    assert server.socket.fileno() == -1
+
+    # Ensure client handler terminated
+    assert server.received_messages == []
+    assert client.errors == []
+    client.ws.send("1st msg after server shutdown")
+    sleep(0.5)
+
+    # Note the message is received since the client handler
+    # will terminate only once it has received the last message
+    # and break out of the keep_alive loop. Any consecutive messages
+    # will not be received though.
+    assert server.received_messages == ["1st msg after server shutdown"]
+    assert len(client.errors) == 1
+    assert isinstance(client.errors[0], websocket._exceptions.WebSocketConnectionClosedException)
+
+    # Try to send 2nd message
+    with pytest.raises(websocket._exceptions.WebSocketConnectionClosedException):
+        client.ws.send("2nd msg after server shutdown")
+
+
+def test_client_closes_gracefully(session):
+    client, server = session
+    assert client.connected
+    assert server.clients
+    old_client_handler = server.clients[0]["handler"]
+    client.close()
+    assert not client.connected
+
+    # Ensure server closed connection.
+    # We test this by having the server trying to send
+    # data to the client
+    assert not server.clients
+    with pytest.raises(BrokenPipeError):
+        old_client_handler.connection.send(b"test")

tests/test_server.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 from utils import session, server
 
 

tests/test_text_messages.py

@@ -1,17 +1,65 @@
 import logging
+from time import sleep
 from threading import Thread
 
 import pytest
-from websocket import create_connection  # websocket-client
+import websocket # websocket-client
 
 import _bootstrap_
 from websocket_server import WebsocketServer
 
 
+class TestClient():
+    def __init__(self, port, threaded=True):
+        self.received_messages = []
+        self.closes = []
+        self.opens = []
+        self.errors = []
+
+        websocket.enableTrace(True)
+        self.ws = websocket.WebSocketApp(f"ws://localhost:{port}/",
+                                  on_open=self.on_open,
+                                  on_message=self.on_message,
+                                  on_error=self.on_error,
+                                  on_close=self.on_close)
+        if threaded:
+            self.thread = Thread(target=self.ws.run_forever)
+            self.thread.daemon = True
+            self.thread.start()
+        else:
+            self.ws.run_forever()
+
+    def on_message(self, ws, message):
+        self.received_messages.append(message)
+        print(f"TestClient: on_message: {message}")
+
+    def on_error(self, ws, error):
+        self.errors.append(error)
+        print(f"TestClient: on_error: {error}")
+
+    def on_close(self, ws, close_status_code, close_msg):
+        self.closes.append((close_status_code, close_msg))
+        print(f"TestClient: on_close: {close_status_code} - {close_msg}")
+
+    def on_open(self, ws):
+        self.opens.append(ws)
+        print("TestClient: on_open")
+
+
+class TestServer(WebsocketServer):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.received_messages = []
+        self.set_fn_message_received(self.handle_received_message)
+
+    def handle_received_message(self, client, server, message):
+        self.received_messages.append(message)
+
+
 @pytest.fixture(scope='function')
 def server():
     """ Returns the response of a server after"""
-    s = WebsocketServer(0, loglevel=logging.DEBUG)
+    s = TestServer(0, loglevel=logging.DEBUG)
     server_thread = Thread(target=s.run_forever)
     server_thread.daemon = True
     server_thread.start()
@@ -21,6 +69,21 @@ def server():
 
 @pytest.fixture
 def session(server):
-    ws = create_connection("ws://{}:{}".format(*server.server_address))
-    yield ws, server
-    ws.close()
+    """
+    Gives a simple connection to a server
+    """
+    conn = websocket.create_connection("ws://{}:{}".format(*server.server_address))
+    yield conn, server
+    conn.close()
+
+
+@pytest.fixture
+def client_session(server):
+    """
+    Gives a TestClient instance connected to a server
+    """
+    client = TestClient(port=server.port)
+    sleep(1)
+    assert client.ws.sock and client.ws.sock.connected
+    yield client, server
+    client.ws.close()