simple-socket-server 2.0__py3-none-any.whl → 2.1__py3-none-any.whl

simple_socket_server/__init__.py

@@ -11,15 +11,17 @@ Distributed under the BSD 3-Clause license. See LICENSE.md for more info.
 
 import select
 import socket
+import sys
 import threading
+import time
 
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Set, Tuple
 
 from event_bus import EventBus
 
 __all__ = ["SimpleSocketServer", "SimpleSocketServerException"]
 
-__version__ = "2.0"
+__version__ = "2.1"
 
 #: Peer address as returned by accept(): (host, port).
 Address = Tuple[str, int]
@@ -30,6 +32,11 @@ _RECV_SIZE = 1024
 #: How long select() waits for socket activity, in seconds.
 _POLL_INTERVAL = 0.1
 
+#: Default client limit. select() refuses a descriptor set larger than
+#: FD_SETSIZE by raising ValueError, and that limit is 512 on Windows and
+#: 1024 elsewhere, so the default stays below both.
+_DEFAULT_MAX_CLIENTS = 500
+
 
 class SimpleSocketServerException(socket.error):
     """Raised when the listening socket cannot be created, bound or enabled."""
@@ -47,14 +54,18 @@ class SimpleSocketServer(EventBus):
     ``message(sock, peer, data)``
         A chunk of bytes has been received.
     ``disconnect(sock, peer)``
-        The connection is gone: the peer closed it, reset it or a send failed.
+        The connection is closed: the peer closed it, reset it, a send failed
+        or disconnect() was called. Queued replies are delivered before it.
     ``error(sock, peer, error)``
-        A socket error occurred; the connection is closed right after.
+        A socket error occurred; the connection is closed right after, or the
+        server itself stops when the listening socket or select() fails.
     ``stop(host, port)``
         run() has returned and every socket is closed.
 
     Handlers are called from the thread that runs run(), one at a time, so a
-    slow handler delays every other connection.
+    slow handler delays every other connection. **Handlers must not raise**: an
+    exception propagates out of run() and stops the server for every client.
+    The sockets are still closed before run() returns.
     """
 
     def __init__(self) -> None:
@@ -62,11 +73,14 @@ class SimpleSocketServer(EventBus):
         self.__host = "0.0.0.0"
         self.__port = 6666
         self.__max_conn = 5
+        self.__max_clients = _DEFAULT_MAX_CLIENTS
         self.__server_socket: Optional[socket.socket] = None
         self.__inputs: List[socket.socket] = []
         self.__outputs: List[socket.socket] = []
         self.__pending: Dict[socket.socket, bytearray] = {}
         self.__clients: Dict[socket.socket, Address] = {}
+        self.__closing: Set[socket.socket] = set()
+        self.__lock = threading.Lock()
         self.__stop = threading.Event()
 
     @property
@@ -84,19 +98,31 @@ class SimpleSocketServer(EventBus):
         """Port the listening socket is bound to."""
         return self.__port
 
-    def run(self, host: str = "0.0.0.0", port: int = 6666, max_conn: int = 5) -> None:
+    def run(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 6666,
+        max_conn: int = 5,
+        max_clients: int = _DEFAULT_MAX_CLIENTS,
+    ) -> None:
         """Serve connections until stop() is called.
 
         The call blocks the calling thread. Once it returns, every client socket
         and the listening socket are closed. A port of 0 makes the operating
         system pick a free port; the actual address is reported by the start
         event and by the host and port properties.
+
+        max_conn is the backlog of the listening socket: how many connections the
+        system may queue before accept(). max_clients is the number of clients
+        the server keeps at once; a connection above it is accepted and closed
+        immediately with an error event.
         """
         if self.is_running:
             raise RuntimeError("the server is already running")
         self.__host = host
         self.__port = port
         self.__max_conn = max_conn
+        self.__max_clients = max_clients
         self.__stop.clear()
         self.__initialize()
         try:
@@ -120,14 +146,32 @@ class SimpleSocketServer(EventBus):
         The socket is non-blocking, so the bytes are buffered and the unwritten
         tail is retried on the next poll; a message larger than the socket
         buffer is delivered in full. Empty messages are ignored.
+
+        Safe to call from another thread: delivery happens during the next poll,
+        so it may take up to the poll interval. The queue has no size limit, so
+        a slow reader grows the buffer until it is disconnected.
         """
-        if sock not in self.__pending:
-            raise ValueError("the socket is not a client of this server")
         if not message:
             return
-        self.__pending[sock].extend(message)
-        if sock not in self.__outputs:
-            self.__outputs.append(sock)
+        with self.__lock:
+            pending = self.__pending.get(sock)
+            if pending is None:
+                raise ValueError("the socket is not a client of this server")
+            pending.extend(message)
+            if sock not in self.__outputs:
+                self.__outputs.append(sock)
+
+    def disconnect(self, sock: socket.socket) -> None:
+        """Close a client connection gracefully.
+
+        The socket stops being read, the replies already queued for it are
+        delivered first, and only then it is closed and the disconnect event is
+        emitted. Safe to call from an event handler or from another thread.
+
+        Use it instead of sock.close(): closing a socket behind the server's
+        back leaves the select() set with a dead descriptor.
+        """
+        self.__start_closing(sock, strict=True)
 
     def __initialize(self) -> None:
         server_socket = socket.socket(
@@ -156,41 +200,74 @@ class SimpleSocketServer(EventBus):
         self.emit("start", self.__host, self.__port)
 
     def __select(self) -> None:
+        self.__prune()
+        # Handlers may call disconnect() and send() from another thread, so the
+        # sequences handed to select() are snapshots taken under the lock.
+        with self.__lock:
+            sock_to_read = list(self.__inputs)
+            sock_to_write = list(self.__outputs)
+        server_socket = self.__server_socket
+        sock_to_check = [server_socket] if server_socket is not None else []
         try:
             sock_to_read, sock_to_write, sock_errors = select.select(
-                self.__inputs,
-                self.__outputs,
-                self.__inputs,
+                sock_to_read,
+                sock_to_write,
+                sock_to_check,
                 _POLL_INTERVAL,
             )
-        except OSError as error:
-            # select() itself failed, so the listening socket is unusable.
-            self.emit("error", None, None, error)
+        except (OSError, ValueError) as error:
+            # select() broke: an unusable listening socket, or a descriptor set
+            # larger than the platform allows. The poll set cannot be trusted.
+            self.emit("error", server_socket, None, error)
             self.stop()
             return
         for sock in sock_errors:
-            if sock is self.__server_socket:
+            # Only the listening socket is polled here: urgent (out of band)
+            # data on a client connection is not a connection error.
+            if sock is server_socket:
                 self.stop()
-            else:
-                self.__close(sock)
         for sock in sock_to_read:
-            if sock is self.__server_socket:
+            if sock is server_socket:
                 self.__accept()
             else:
                 self.__receive(sock)
         for sock in sock_to_write:
             self.__flush(sock)
 
+    def __prune(self) -> None:
+        """Drop sockets that the application closed behind the server's back."""
+        for sock in list(self.__clients):
+            if sock.fileno() < 0:
+                self.__close(sock)
+
     def __accept(self) -> None:
+        server_socket = self.__server_socket
+        if server_socket is None:
+            return
         try:
-            client_socket, client_address = self.__server_socket.accept()
+            client_socket, client_address = server_socket.accept()
+        except BlockingIOError:
+            # The connection died in the backlog before accept() reached it.
+            return
         except OSError as error:
-            self.emit("error", self.__server_socket, None, error)
+            self.emit("error", server_socket, None, error)
+            # Out of descriptors (EMFILE) would spin the loop without a pause.
+            time.sleep(_POLL_INTERVAL)
             return
         client_socket.setblocking(False)
-        self.__clients[client_socket] = client_address
-        self.__pending[client_socket] = bytearray()
-        self.__inputs.append(client_socket)
+        if len(self.__clients) >= self.__max_clients:
+            client_socket.close()
+            self.emit(
+                "error",
+                client_socket,
+                client_address,
+                ConnectionAbortedError("the client limit is reached"),
+            )
+            return
+        with self.__lock:
+            self.__clients[client_socket] = client_address
+            self.__pending[client_socket] = bytearray()
+            self.__inputs.append(client_socket)
         self.emit("connect", client_socket, client_address)
 
     def __receive(self, sock: socket.socket) -> None:
@@ -212,37 +289,68 @@ class SimpleSocketServer(EventBus):
             return
         if not data:
             # An empty chunk means the peer closed its end of the connection.
-            self.__close(sock)
+            # Replies queued for it are still delivered before the socket goes.
+            self.__start_closing(sock)
             return
         self.emit("message", sock, peer, data)
 
+    def __start_closing(self, sock: socket.socket, strict: bool = False) -> None:
+        """Stop reading a connection and close it once its queue is drained."""
+        with self.__lock:
+            if sock not in self.__clients:
+                if strict:
+                    raise ValueError("the socket is not a client of this server")
+                return
+            self.__closing.add(sock)
+            if sock in self.__inputs:
+                self.__inputs.remove(sock)
+            drained = not self.__pending.get(sock)
+            if not drained and sock not in self.__outputs:
+                self.__outputs.append(sock)
+        if drained:
+            self.__close(sock)
+
     def __flush(self, sock: socket.socket) -> None:
-        pending = self.__pending.get(sock)
-        if pending is None:
-            if sock in self.__outputs:
-                self.__outputs.remove(sock)
-            return
-        try:
-            sent = sock.send(pending)
-        except BlockingIOError:
-            # The kernel buffer is full again; the tail stays queued.
-            return
-        except OSError as error:
-            self.emit("error", sock, self.__clients.get(sock), error)
+        failure: Optional[OSError] = None
+        drained = False
+        closing = False
+        with self.__lock:
+            pending = self.__pending.get(sock)
+            if pending is None:
+                if sock in self.__outputs:
+                    self.__outputs.remove(sock)
+                return
+            try:
+                with memoryview(pending) as view:
+                    sent = sock.send(view)
+            except BlockingIOError:
+                # The kernel buffer is full again; the tail stays queued.
+                return
+            except OSError as error:
+                failure = error
+            else:
+                del pending[:sent]
+                drained = not pending
+                if drained and sock in self.__outputs:
+                    self.__outputs.remove(sock)
+            closing = drained and sock in self.__closing
+        if failure is not None:
+            self.emit("error", sock, self.__clients.get(sock), failure)
             self.__close(sock)
             return
-        del pending[:sent]
-        if not pending and sock in self.__outputs:
-            self.__outputs.remove(sock)
+        if closing:
+            self.__close(sock)
 
     def __close(self, sock: socket.socket) -> None:
-        """Close a client connection and forget it. Safe to call twice."""
-        peer = self.__clients.pop(sock, None)
-        if sock in self.__inputs:
-            self.__inputs.remove(sock)
-        if sock in self.__outputs:
-            self.__outputs.remove(sock)
-        self.__pending.pop(sock, None)
+        """Drop a client connection and close it. Safe to call twice."""
+        with self.__lock:
+            peer = self.__clients.pop(sock, None)
+            if sock in self.__inputs:
+                self.__inputs.remove(sock)
+            if sock in self.__outputs:
+                self.__outputs.remove(sock)
+            self.__pending.pop(sock, None)
+            self.__closing.discard(sock)
         if peer is None:
             sock.close()
             return
@@ -252,11 +360,33 @@ class SimpleSocketServer(EventBus):
             sock.close()
 
     def __shutdown(self) -> None:
-        for sock in list(self.__clients):
-            self.__close(sock)
+        """Close everything, no matter what the handlers do.
+
+        The listening socket goes first, so the port stops accepting; then every
+        client is closed even if a disconnect handler raises, and stop is
+        emitted in any case. The first handler failure is re-raised afterwards
+        unless run() is already unwinding because of another error.
+        """
+        failure: Optional[BaseException] = None
         server_socket, self.__server_socket = self.__server_socket, None
         if server_socket is not None:
-            if server_socket in self.__inputs:
-                self.__inputs.remove(server_socket)
+            with self.__lock:
+                if server_socket in self.__inputs:
+                    self.__inputs.remove(server_socket)
             server_socket.close()
-        self.emit("stop", self.__host, self.__port)
+        for sock in list(self.__clients):
+            try:
+                self.__close(sock)
+            except Exception as error:  # noqa: BLE001 - cleanup must finish
+                if failure is None:
+                    failure = error
+        for sock in list(self.__outputs):
+            sock.close()
+        self.__outputs.clear()
+        try:
+            self.emit("stop", self.__host, self.__port)
+        except Exception as error:  # noqa: BLE001 - cleanup must finish
+            if failure is None:
+                failure = error
+        if failure is not None and sys.exc_info()[0] is None:
+            raise failure

{simple_socket_server-2.0.dist-info → simple_socket_server-2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple-socket-server
-Version: 2.0
+Version: 2.1
 Summary: Simple TCP socket server with select
 Author-email: webtoucher <webtoucher@ya.ru>
 License-Expression: BSD-3-Clause
@@ -59,7 +59,7 @@ $ pip install simple-socket-server
 Or you can add it as dependency in requirements.txt file of your python application:
 
 ```
-simple-socket-server~=2.0
+simple-socket-server~=2.1
 ```
 
 ## Usage
@@ -127,40 +127,57 @@ print(socket_server.host, socket_server.port)
 
 Handlers are called from the thread that runs `run()`, one at a time.
 
-| Event        | Arguments               | When it fires                                                    |
-|--------------|-------------------------|------------------------------------------------------------------|
-| `start`      | `host, port`            | the listening socket is ready                                    |
-| `connect`    | `sock, peer`            | a client has been accepted                                       |
-| `message`    | `sock, peer, data`      | a chunk of bytes has been received                               |
-| `disconnect` | `sock, peer`            | the connection is gone; the socket is closed right after         |
-| `error`      | `sock, peer, error`     | a socket error occurred; `disconnect` follows                    |
-| `stop`       | `host, port`            | `run()` has returned and every socket is closed                  |
+| Event        | Arguments               | When it fires                                                             |
+|--------------|-------------------------|---------------------------------------------------------------------------|
+| `start`      | `host, port`            | the listening socket is ready                                             |
+| `connect`    | `sock, peer`            | a client has been accepted                                                |
+| `message`    | `sock, peer, data`      | a chunk of bytes has been received                                        |
+| `disconnect` | `sock, peer`            | the connection is closed; the replies queued for it were delivered first   |
+| `error`      | `sock, peer, error`     | a socket error occurred; the connection is closed and `disconnect` follows |
+| `stop`       | `host, port`            | `run()` has returned and every socket is closed                            |
 
-`peer` is an `(host, port)` tuple, `data` is `bytes`, `error` is an `OSError`.
+`peer` is an `(host, port)` tuple, `data` is `bytes`, `error` is an `OSError`. When
+`error` reports a failure of the listening socket or of `select()` itself, `peer` is
+`None` and the server stops.
 
 ## API
 
-| Member                                | Description                                                          |
-|---------------------------------------|----------------------------------------------------------------------|
-| `run(host='0.0.0.0', port=6666, max_conn=5)` | serve connections until `stop()` is called                    |
-| `stop()`                              | ask `run()` to return; safe from a handler or another thread          |
-| `send(sock, message)`                 | queue `bytes` for a client; `ValueError` if it is not a client        |
-| `is_running`                          | `True` while `run()` is serving connections                           |
-| `host`, `port`                        | the address the listening socket is bound to                          |
-| `on(event)`, `emit(...)`              | inherited from `event_bus.EventBus`                                   |
+| Member                                   | Description                                                          |
+|------------------------------------------|----------------------------------------------------------------------|
+| `run(host='0.0.0.0', port=6666, max_conn=5, max_clients=500)` | serve connections until `stop()` is called      |
+| `stop()`                                 | ask `run()` to return; safe from a handler or another thread          |
+| `send(sock, message)`                    | queue `bytes` for a client; `ValueError` if it is not a client        |
+| `disconnect(sock)`                       | stop reading a client, deliver its queue, then close it               |
+| `is_running`                             | `True` while `run()` is serving connections                           |
+| `host`, `port`                           | the address the listening socket is bound to                          |
+| `on(event)`, `emit(...)`                 | inherited from `event_bus.EventBus`                                   |
 
 Notes:
 
 - The server is single-threaded and handlers are called synchronously, so a slow
   handler delays every other connection. Hand off long work to your own thread.
+- **A handler must not raise.** The exception propagates out of `run()` and stops
+  the server for every client; the sockets are still closed before the call returns.
+  If one connection misbehaves, handle it in the handler and call `disconnect()`.
 - `message` carries one raw `recv()` chunk of up to 1024 bytes. There is no
   framing: the protocol you put on top has to delimit its own messages.
 - `send()` never blocks and never truncates: because client sockets are
   non-blocking, the bytes are buffered and the unwritten tail is retried on the
   next poll, so a message larger than the socket buffer arrives in full.
-- Do not use the socket after `disconnect` or `error`: it is closed.
-- An exception raised by a handler propagates out of `run()`. The socket state is
-  still cleaned up before the call returns.
+- The outbound queue has no size limit: a client that stops reading grows the
+  buffer of the server until you disconnect it.
+- `send()` and `disconnect()` are safe to call from another thread. Delivery
+  happens during the next poll, so it can take up to the poll interval (0.1 s).
+- `max_conn` is the `listen()` backlog: how many connections the system queues
+  before `accept()`. It is not a limit of served clients. `max_clients` is that
+  limit: a connection above it is accepted, closed at once and reported through
+  `error`.
+- Do not call `sock.close()` yourself and do not use the socket after
+  `disconnect` or `error`. Use `disconnect(sock)` instead: it stops reading the
+  client and closes the socket after the queued replies are delivered. A socket
+  closed behind the server's back is dropped on the next poll, without delivery.
+- Urgent (out of band) data is not supported, and such data is not treated as an
+  error: the bytes stay in the stream and arrive through `message`.
 
 ## Compatibility
 
@@ -171,6 +188,10 @@ Notes:
   pyright see real signatures instead of `Any`.
 - Any server instance is independent: several servers may run in one process, each
   in its own thread.
+- The poll set of `select()` is limited by the platform: 512 descriptors on Windows
+  and 1024 elsewhere, the listening socket included. That is why concurrent clients
+  are capped by `max_clients`, 500 by default; a larger value makes `select()` fail,
+  and the server stops with an `error` event.
 
 ## Development
 
@@ -187,7 +208,16 @@ The test suite covers:
 - the message flow: `connect`, echo round trips, ordering and large payloads,
 - disconnects: graceful close by the peer, an abrupt reset and a send to a
   connection that is already gone,
-- error handling: an unknown socket for `send()` and a port that is already taken,
+- error handling: `send()` and `disconnect()` for an unknown socket, a client limit
+  that is reached, and a port that is already taken (POSIX only: on Windows
+  `SO_REUSEADDR` allows rebinding a listening port),
+- a half-close: the peer sends, shuts down its writing side and still receives the
+  whole reply, a 256 KiB one included,
+- server-driven disconnects: a queued reply reaches the client before the socket is
+  closed,
+- resilience: a handler that closes its socket does not stop the server, and
+  `stop()` closes every client and emits `stop` even if a `disconnect` handler
+  raises,
 - independence of two servers running in one process.
 
 Project layout:

simple_socket_server-2.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+simple_socket_server/__init__.py,sha256=9vi_e0QnPDT9WZb2rVmkzcs-hqzIUmQfSQ86DukSM04,14926
+simple_socket_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simple_socket_server-2.1.dist-info/licenses/LICENSE.md,sha256=viUOCJf97qThnFWXx3lGwpWwhWfuo8ug8QQAHtAFh8c,1496
+simple_socket_server-2.1.dist-info/METADATA,sha256=cVqpCqfCBck5bLq0UXWSkDSPr438fQzBmxl08bZEiNs,10962
+simple_socket_server-2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+simple_socket_server-2.1.dist-info/top_level.txt,sha256=U3g9Q_CXbmmzcFW0pQ4cEZgmkbi0TORT9q3EA_C7I04,21
+simple_socket_server-2.1.dist-info/RECORD,,

simple_socket_server-2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-simple_socket_server/__init__.py,sha256=NG1iCg4yUKkq6G77v7ffvkGdrkMivnqu_vcFq9wwYQk,9173
-simple_socket_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-simple_socket_server-2.0.dist-info/licenses/LICENSE.md,sha256=viUOCJf97qThnFWXx3lGwpWwhWfuo8ug8QQAHtAFh8c,1496
-simple_socket_server-2.0.dist-info/METADATA,sha256=pehdXAJEjZO1_hgYGB3BGO49nrqExDJVQRgbwEsOUKc,8769
-simple_socket_server-2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-simple_socket_server-2.0.dist-info/top_level.txt,sha256=U3g9Q_CXbmmzcFW0pQ4cEZgmkbi0TORT9q3EA_C7I04,21
-simple_socket_server-2.0.dist-info/RECORD,,