Add tests and docs

docs/api.rst

@@ -114,3 +114,9 @@ API Reference
 
 .. autoclass:: AsyncRedisManager
    :members:
+
+``ConnectionRefusedError`` class
+--------------------------------
+
+.. autoclass:: ConnectionRefusedError
+   :members:

docs/server.rst

@@ -111,6 +111,18 @@ standard WSGI format containing the request information, including HTTP
 headers. After inspecting the request, the connect event handler can return
 ``False`` to reject the connection with the client.
 
+If any additional data has to be passed on connection reject, than instead of
+returning ``False`` :class:`socketio.exceptions.ConnectionRefusedError` could
+be raised:
+
+    @sio.on('connect')
+    def connect(sid, environ):
+        message = 'Incorrect user data'
+        raise ConnectionRefusedError(message)
+
+In this case message will be returned directly to the client with rejected
+connection.
+
 Emitting Events
 ---------------
 

tests/asyncio/test_asyncio_server.py

@@ -10,7 +10,7 @@ if six.PY3:
 else:
     import mock
 
-from socketio import asyncio_server
+from socketio import asyncio_server, exceptions
 from socketio import asyncio_namespace
 from socketio import packet
 from socketio import namespace
@@ -276,6 +276,36 @@ class TestAsyncServer(unittest.TestCase):
         self.assertEqual(s.environ, {})
         s.eio.send.mock.assert_any_call('123', '4/foo', binary=False)
 
+    def test_handle_connect_namespace_rejected_with_exception(self, eio):
+        eio.return_value.send = AsyncMock()
+        mgr = self._get_mock_manager()
+        s = asyncio_server.AsyncServer(client_manager=mgr)
+        handler = mock.MagicMock(side_effect=exceptions.ConnectionRefusedError('fail_reason'))
+        s.on('connect', handler, namespace='/foo')
+        _run(s._handle_eio_connect('123', 'environ'))
+        _run(s._handle_eio_message('123', '0/foo'))
+        self.assertEqual(s.manager.connect.call_count, 2)
+        self.assertEqual(s.manager.disconnect.call_count, 1)
+        self.assertEqual(s.environ, {})
+        s.eio.send.mock.assert_any_call('123', '4/foo,"fail_reason"', binary=False)
+
+    def test_handle_connect_namespace_rejected_with_custom_exception(self, eio):
+        class CustomizedConnRefused(exceptions.ConnectionRefusedError):
+            def get_info(self):
+                return 'customized: {}'.format(self._info)
+
+        eio.return_value.send = AsyncMock()
+        mgr = self._get_mock_manager()
+        s = asyncio_server.AsyncServer(client_manager=mgr)
+        handler = mock.MagicMock(side_effect=CustomizedConnRefused('fail_reason'))
+        s.on('connect', handler, namespace='/foo')
+        _run(s._handle_eio_connect('123', 'environ'))
+        _run(s._handle_eio_message('123', '0/foo'))
+        self.assertEqual(s.manager.connect.call_count, 2)
+        self.assertEqual(s.manager.disconnect.call_count, 1)
+        self.assertEqual(s.environ, {})
+        s.eio.send.mock.assert_any_call('123', '4/foo,"customized: fail_reason"', binary=False)
+
     def test_handle_disconnect(self, eio):
         eio.return_value.send = AsyncMock()
         mgr = self._get_mock_manager()

tests/common/test_server.py

@@ -8,6 +8,7 @@ if six.PY3:
 else:
     import mock
 
+from socketio import exceptions
 from socketio import packet
 from socketio import server
 from socketio import namespace
@@ -218,6 +219,32 @@ class TestServer(unittest.TestCase):
         self.assertEqual(s.manager.disconnect.call_count, 1)
         s.eio.send.assert_any_call('123', '4/foo', binary=False)
 
+    def test_handle_connect_namespace_rejected_with_exception(self, eio):
+        mgr = mock.MagicMock()
+        s = server.Server(client_manager=mgr)
+        handler = mock.MagicMock(side_effect=exceptions.ConnectionRefusedError('fail_reason'))
+        s.on('connect', handler, namespace='/foo')
+        s._handle_eio_connect('123', 'environ')
+        s._handle_eio_message('123', '0/foo')
+        self.assertEqual(s.manager.connect.call_count, 2)
+        self.assertEqual(s.manager.disconnect.call_count, 1)
+        s.eio.send.assert_any_call('123', '4/foo,"fail_reason"', binary=False)
+
+    def test_handle_connect_namespace_rejected_with_custom_exception(self, eio):
+        class CustomizedConnRefused(exceptions.ConnectionRefusedError):
+            def get_info(self):
+                return 'customized: {}'.format(self._info)
+
+        mgr = mock.MagicMock()
+        s = server.Server(client_manager=mgr)
+        handler = mock.MagicMock(side_effect=CustomizedConnRefused('fail_reason'))
+        s.on('connect', handler, namespace='/foo')
+        s._handle_eio_connect('123', 'environ')
+        s._handle_eio_message('123', '0/foo')
+        self.assertEqual(s.manager.connect.call_count, 2)
+        self.assertEqual(s.manager.disconnect.call_count, 1)
+        s.eio.send.assert_any_call('123', '4/foo,"customized: fail_reason"', binary=False)
+
     def test_handle_disconnect(self, eio):
         mgr = mock.MagicMock()
         s = server.Server(client_manager=mgr)