jsocket 1.9.5__py3-none-any.whl → 2.0.0__py3-none-any.whl

jsocket/__init__.py

@@ -73,3 +73,4 @@
 """
 from jsocket.jsocket_base import *
 from jsocket.tserver import *
+from ._version import __version__

jsocket/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "2.0.0"

jsocket/jsocket_base.py

@@ -19,16 +19,26 @@ __copyright__= """
     See the License for the specific language governing permissions and
     limitations under the License.
 """
-__version__  = "1.0.3"
-
 import json
 import socket
 import struct
 import logging
 import time
+import zlib
+
+from ._version import __version__
 
 logger = logging.getLogger("jsocket")
 
+FRAME_MAGIC = b"JSN1"
+FRAME_HEADER_FMT = "!4sII"
+FRAME_HEADER_SIZE = struct.calcsize(FRAME_HEADER_FMT)
+DEFAULT_MAX_MESSAGE_SIZE = 10 * 1024 * 1024
+
+
+class FramingError(RuntimeError):
+    """Raised when a message fails framing or integrity checks."""
+
 
 def _socket_fileno(sock):
     try:
@@ -40,12 +50,15 @@ def _socket_fileno(sock):
 class JsonSocket:
     """Lightweight JSON-over-TCP socket wrapper with length-prefixed framing."""
 
-    def __init__(self, address='127.0.0.1', port=5489, timeout=2.0):
+    def __init__(self, address='127.0.0.1', port=5489, timeout=2.0, max_message_size=DEFAULT_MAX_MESSAGE_SIZE):
         self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         self.conn = self.socket
         self._timeout = timeout
         self._address = address
         self._port = port
+        self._max_message_size = None
+        self.max_message_size = max_message_size
+        self._last_client_addr = None
         # Ensure the primary socket respects timeout for accept/connect operations
         self.socket.settimeout(self._timeout)
 
@@ -54,11 +67,12 @@ class JsonSocket:
         msg = json.dumps(obj, ensure_ascii=False)
         if self.socket:
             payload = msg.encode('utf-8')
-            frmt = f"={len(payload)}s"
-            packed_msg = struct.pack(frmt, payload)
-            packed_hdr = struct.pack('!I', len(packed_msg))
+            if self._max_message_size is not None and len(payload) > self._max_message_size:
+                raise ValueError(f"message exceeds max_message_size ({len(payload)} > {self._max_message_size})")
+            checksum = zlib.crc32(payload) & 0xFFFFFFFF
+            packed_hdr = struct.pack(FRAME_HEADER_FMT, FRAME_MAGIC, len(payload), checksum)
             self._send(packed_hdr)
-            self._send(packed_msg)
+            self._send(payload)
 
     def _send(self, msg):
         """Send all bytes in `msg` to the peer."""
@@ -66,29 +80,53 @@ class JsonSocket:
         while sent < len(msg):
             sent += self.conn.send(msg[sent:])
 
-    def _read(self, size):
+    def _read(self, size, allow_timeout=False):
         """Read exactly `size` bytes from the peer or raise on disconnect."""
         data = b''
         while len(data) < size:
-            data_tmp = self.conn.recv(size - len(data))
-            data += data_tmp
+            try:
+                data_tmp = self.conn.recv(size - len(data))
+            except socket.timeout:
+                if allow_timeout and not data:
+                    raise
+                self._close_connection()
+                raise FramingError("socket read timeout during message")
             if data_tmp == b'':
+                self._close_connection()
                 raise RuntimeError("socket connection broken")
+            data += data_tmp
         return data
 
-    def _msg_length(self):
-        """Read and unpack the 4-byte big-endian length header."""
-        d = self._read(4)
-        s = struct.unpack('!I', d)
-        return s[0]
+    def _read_header(self):
+        """Read and unpack the framing header."""
+        header = self._read(FRAME_HEADER_SIZE, allow_timeout=True)
+        magic, size, checksum = struct.unpack(FRAME_HEADER_FMT, header)
+        if magic != FRAME_MAGIC:
+            self._close_connection()
+            raise FramingError("invalid message header magic")
+        if self._max_message_size is not None and size > self._max_message_size:
+            self._close_connection()
+            raise FramingError(f"message length {size} exceeds max_message_size {self._max_message_size}")
+        return size, checksum
 
     def read_obj(self):
         """Read a full message and decode it as JSON, returning a Python object."""
-        size = self._msg_length()
+        size, checksum = self._read_header()
         data = self._read(size)
-        frmt = f"={size}s"
-        msg = struct.unpack(frmt, data)
-        return json.loads(msg[0].decode('utf-8'))
+        actual = zlib.crc32(data) & 0xFFFFFFFF
+        if actual != checksum:
+            self._close_connection()
+            raise FramingError("message checksum mismatch")
+        try:
+            decoded = data.decode('utf-8')
+        except UnicodeDecodeError as e:
+            self._close_connection()
+            raise FramingError("invalid UTF-8 payload") from e
+        try:
+            return json.loads(decoded)
+        except json.JSONDecodeError as e:
+            self._close_connection()
+            raise FramingError("invalid JSON payload") from e
 
     def close(self):
         """Close active connection and the listening socket if open."""
@@ -117,10 +155,10 @@ class JsonSocket:
             pass
 
     def _close_connection(self):
-        """Best-effort shutdown and close of the accepted connection socket."""
+        """Best-effort shutdown and close of the connection socket."""
         logger.debug("closing connection socket (fd=%s)", _socket_fileno(self.conn))
         try:
-            if self.conn and self.conn is not self.socket and self.conn.fileno() != -1:
+            if self.conn and self.conn.fileno() != -1:
                 try:
                     self.conn.shutdown(socket.SHUT_RDWR)
                 except OSError:
@@ -157,9 +195,24 @@ class JsonSocket:
         """No-op: port is read-only after initialization."""
         return None
 
+    def _get_max_message_size(self):
+        """Get the maximum allowed message size in bytes."""
+        return self._max_message_size
+
+    def _set_max_message_size(self, size):
+        """Set the maximum allowed message size in bytes."""
+        if size is None:
+            self._max_message_size = None
+            return
+        size = int(size)
+        if size <= 0:
+            raise ValueError("max_message_size must be positive")
+        self._max_message_size = size
+
     timeout = property(_get_timeout, _set_timeout, doc='Get/set the socket timeout')
     address = property(_get_address, _set_address, doc='read only property socket address')
     port = property(_get_port, _set_port, doc='read only property socket port')
+    max_message_size = property(_get_max_message_size, _set_max_message_size, doc='Get/set max message size in bytes')
 
 
 class JsonServer(JsonSocket):
@@ -169,6 +222,22 @@ class JsonServer(JsonSocket):
         super().__init__(address, port)
         self._bind()
 
+    def _close_connection(self):
+        """Best-effort shutdown and close of the accepted connection socket."""
+        logger.debug("closing connection socket (fd=%s)", _socket_fileno(self.conn))
+        try:
+            if self.conn and self.conn is not self.socket and self.conn.fileno() != -1:
+                try:
+                    self.conn.shutdown(socket.SHUT_RDWR)
+                except OSError:
+                    pass
+                try:
+                    self.conn.close()
+                except OSError:
+                    pass
+        except OSError:
+            pass
+
     def _bind(self):
         self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
         self.socket.bind((self.address, self.port))
@@ -183,6 +252,7 @@ class JsonServer(JsonSocket):
         """Listen and accept a single client connection; set timeout accordingly."""
         self._listen()
         self.conn, addr = self._accept()
+        self._last_client_addr = addr
         self.conn.settimeout(self.timeout)
         logger.debug(
             "connection accepted, conn socket (%s,%d,%s)", addr[0], addr[1], str(self.conn.gettimeout())

jsocket/tserver.py

@@ -20,15 +20,15 @@ __copyright__= """
     See the License for the specific language governing permissions and
     limitations under the License.
 """
-__version__  = "1.0.3"
-
 import threading
 import socket
 import time
 import logging
 import abc
 from typing import Optional
+
 from jsocket import jsocket_base
+from ._version import __version__
 
 logger = logging.getLogger("jsocket.tserver")
 
@@ -41,6 +41,16 @@ def _response_summary(resp_obj) -> str:
     return f"type={type(resp_obj).__name__}"
 
 
+def _format_client_id(addr) -> str:
+    try:
+        host, port = addr[0], addr[1]
+        if ":" in host:
+            return f"[{host}]:{port}"
+        return f"{host}:{port}"
+    except Exception:  # pylint: disable=broad-exception-caught
+        return "unknown"
+
+
 class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.ABCMeta):
     """Single-threaded server that accepts one connection and processes messages in its thread."""
 
@@ -48,6 +58,9 @@ class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.AB
         threading.Thread.__init__(self)
         jsocket_base.JsonServer.__init__(self, **kwargs)
         self._is_alive = False
+        self._stats_lock = threading.Lock()
+        self._client_started_at = None
+        self._client_id = None
 
     @abc.abstractmethod
     def _process_message(self, obj) -> Optional[dict]:
@@ -61,6 +74,32 @@ class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.AB
         # Return None in the base class to satisfy linters; subclasses should override.
         return None
 
+    def _record_client_start(self):
+        addr = getattr(self, "_last_client_addr", None)
+        if addr is None:
+            try:
+                addr = self.conn.getpeername()
+            except OSError:
+                addr = None
+        with self._stats_lock:
+            self._client_started_at = time.monotonic()
+            self._client_id = _format_client_id(addr)
+
+    def _clear_client_stats(self):
+        with self._stats_lock:
+            self._client_started_at = None
+            self._client_id = None
+
+    def get_client_stats(self) -> dict:
+        """Return connected client count and per-client durations in seconds."""
+        with self._stats_lock:
+            started_at = self._client_started_at
+            client_id = self._client_id
+        if not started_at or not client_id or not self.connected:
+            return {"connected_clients": 0, "clients": {}}
+        duration = time.monotonic() - started_at
+        return {"connected_clients": 1, "clients": {client_id: duration}}
+
     def _accept_client(self) -> bool:
         """Accept an incoming connection; return True when a client connects."""
         try:
@@ -76,6 +115,7 @@ class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.AB
             logger.debug("server stopping; accept loop exiting (%s:%s)", self.address, self.port)
             self._is_alive = False
             return False
+        self._record_client_start()
         return True
 
     def _handle_client_messages(self):
@@ -99,6 +139,7 @@ class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.AB
                     logger.debug("handler error (%s): %s", type(e).__name__, e)
                 self._close_connection()
                 break
+        self._clear_client_stats()
 
     def run(self):
         # Ensure the run loop is active even when run() is invoked directly
@@ -132,6 +173,7 @@ class ThreadedServer(threading.Thread, jsocket_base.JsonServer, metaclass=abc.AB
             @retval None 
         """
         self._is_alive = False
+        self._clear_client_stats()
         logger.debug("Threaded Server stopped on %s:%s", self.address, self.port)
 
 
@@ -144,6 +186,8 @@ class ServerFactoryThread(threading.Thread, jsocket_base.JsonSocket, metaclass=a
         self.conn = None
         jsocket_base.JsonSocket.__init__(self, **kwargs)
         self._is_alive = False
+        self._client_started_at = None
+        self._client_id = None
 
     def swap_socket(self, new_sock):
         """ Swaps the existing socket with a new one. Useful for setting socket after a new connection.
@@ -153,6 +197,12 @@ class ServerFactoryThread(threading.Thread, jsocket_base.JsonSocket, metaclass=a
         """
         self.socket = new_sock
         self.conn = self.socket
+        try:
+            addr = new_sock.getpeername()
+        except OSError:
+            addr = None
+        self._client_id = _format_client_id(addr)
+        self._client_started_at = time.monotonic()
 
     def run(self):
         """ Should exit when client closes socket conn.
@@ -215,6 +265,7 @@ class ServerFactory(ThreadedServer):
             raise TypeError("serverThread not of type", ServerFactoryThread)
         self._thread_type = server_thread
         self._threads = []
+        self._threads_lock = threading.Lock()
         self._thread_args = kwargs
         self._thread_args.pop('address', None)
         self._thread_args.pop('port', None)
@@ -245,9 +296,21 @@ class ServerFactory(ThreadedServer):
                     accepted_conn = self.conn
                     # Reset server connection reference so we can accept again
                     self._reset_connection_ref()
+                    if not self._is_alive:
+                        # Server is stopping; close the accepted connection without spawning a worker.
+                        try:
+                            accepted_conn.shutdown(socket.SHUT_RDWR)
+                        except OSError:
+                            pass
+                        try:
+                            accepted_conn.close()
+                        except OSError:
+                            pass
+                        break
                     tmp.swap_socket(accepted_conn)
                     tmp.start()
-                    self._threads.append(tmp)
+                    with self._threads_lock:
+                        self._threads.append(tmp)
                     break
 
         self._wait_to_exit()
@@ -255,14 +318,20 @@ class ServerFactory(ThreadedServer):
 
     def stop_all(self):
         """Stop and join all active worker threads."""
-        for t in self._threads:
-            if t.is_alive():
+        while True:
+            with self._threads_lock:
+                threads = [t for t in self._threads if t.is_alive()]
+            if not threads:
+                break
+            for t in threads:
                 t.force_stop()
                 t.join()
+            self._purge_threads()
 
     def _purge_threads(self):
         # Rebuild list to avoid mutating while iterating
-        self._threads = [t for t in self._threads if t.is_alive()]
+        with self._threads_lock:
+            self._threads = [t for t in self._threads if t.is_alive()]
 
     def stop(self):
         # Stop accepting and stop all workers
@@ -279,6 +348,25 @@ class ServerFactory(ThreadedServer):
             time.sleep(0.2)
 
     def _get_num_of_active_threads(self):
-        return len([True for x in self._threads if x.is_alive()])
+        with self._threads_lock:
+            threads = list(self._threads)
+        return len([True for x in threads if x.is_alive()])
+
+    def get_client_stats(self) -> dict:
+        """Return connected client count and per-client durations in seconds."""
+        with self._threads_lock:
+            threads = list(self._threads)
+        now = time.monotonic()
+        clients = {}
+        active = 0
+        for t in threads:
+            if not t.is_alive():
+                continue
+            active += 1
+            started_at = getattr(t, "_client_started_at", None)
+            client_id = getattr(t, "_client_id", None) or f"thread-{t.name}"
+            duration = now - started_at if started_at else 0.0
+            clients[client_id] = duration
+        return {"connected_clients": active, "clients": clients}
 
     active = property(_get_num_of_active_threads, doc="number of active threads")

jsocket-2.0.0.dist-info/METADATA

@@ -0,0 +1,369 @@
+Metadata-Version: 2.4
+Name: jsocket
+Version: 2.0.0
+Summary: Python JSON Server & Client
+Author-email: Christopher Piekarski <chris@cpiekarski.com>
+Maintainer-email: Christopher Piekarski <chris@cpiekarski.com>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [2011] [Christopher Piekarski]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://cpiekarski.com/2012/01/25/python-json-client-server-redux/
+Keywords: json,socket,server,client
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Hardware :: Symmetric Multi-processing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+python-json-socket (jsocket)
+============================
+
+[![CI](https://github.com/chris-piekarski/python-json-socket/actions/workflows/ci.yml/badge.svg)](https://github.com/chris-piekarski/python-json-socket/actions/workflows/ci.yml)
+![PyPI](https://img.shields.io/pypi/v/jsocket.svg)
+![Python Versions](https://img.shields.io/pypi/pyversions/jsocket.svg)
+![License](https://img.shields.io/pypi/l/jsocket.svg)
+
+Simple JSON-over-TCP sockets for Python. This library provides:
+
+- JsonClient/JsonServer: length‑prefixed JSON message framing over TCP
+- ThreadedServer: a single-connection server running in its own thread
+- ServerFactory/ServerFactoryThread: a per‑connection worker model for multiple clients
+
+It aims to be small, predictable, and easy to integrate in tests or small services.
+
+
+Install
+-------
+
+```
+pip install jsocket
+```
+
+Requires Python 3.8+.
+
+
+Quickstart
+----------
+
+Echo server with `ThreadedServer` and a client:
+
+```python
+import time
+import jsocket
+
+class Echo(jsocket.ThreadedServer):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.timeout = 2.0
+
+    # Return a dict to send a response back to the client
+    def _process_message(self, obj):
+        if isinstance(obj, dict) and 'echo' in obj:
+            return obj
+        return None
+
+# Bind to an ephemeral port (port=0)
+server = Echo(address='127.0.0.1', port=0)
+_, port = server.socket.getsockname()
+server.start()
+
+client = jsocket.JsonClient(address='127.0.0.1', port=port)
+assert client.connect() is True
+
+payload = {"echo": "hello"}
+client.send_obj(payload)
+assert client.read_obj() == payload
+
+client.close()
+server.stop()
+server.join()
+```
+
+Per‑connection workers with `ServerFactory`:
+
+```python
+import jsocket
+
+class Worker(jsocket.ServerFactoryThread):
+    def __init__(self):
+        super().__init__()
+        self.timeout = 2.0
+
+    def _process_message(self, obj):
+        if isinstance(obj, dict) and 'message' in obj:
+            return {"reply": f"got: {obj['message']}"}
+
+server = jsocket.ServerFactory(Worker, address='127.0.0.1', port=5489)
+server.start()
+# Connect one or more clients; one Worker is spawned per connection
+```
+
+
+API Highlights
+--------------
+
+- JsonClient:
+  - `connect()` returns True on success
+  - `send_obj(dict)` sends a JSON object
+  - `read_obj()` blocks until a full message is received; raises `socket.timeout` or `RuntimeError("socket connection broken")`
+  - `timeout` property controls socket timeouts
+
+- ThreadedServer:
+  - Subclass and implement `_process_message(self, obj) -> Optional[dict]`
+  - Return a dict to send a response; return `None` to send nothing
+  - `start()`, `stop()`, `join()` manage the server thread
+  - `send_obj(dict)` sends to the currently connected client
+
+- ServerFactory / ServerFactoryThread:
+  - `ServerFactoryThread` is a worker that handles one client connection
+  - `ServerFactory` accepts connections and spawns a worker per client
+
+
+Examples and Tests
+------------------
+
+- Examples: see `examples/example_servers.py` and `scripts/smoke_test.py`
+- Pytest: end-to-end and listener tests under `tests/`
+  - Run: `pytest -q`
+
+
+Behavior-Driven Tests (Behave)
+------------------------------
+
+- Steps live under `features/steps/` and environment hooks in `features/environment.py`.
+- To run Behave scenarios, add one or more `.feature` files under `features/` and run:
+  - `pip install -r requirements-dev.txt`
+  - `PYTHONPATH=. behave -f progress2`
+- A minimal example feature:
+
+  ```gherkin
+  Feature: Echo round-trip
+    Scenario: client/server echo
+      Given I start the server
+      And I connect the client
+      When the client sends the object {"echo": "hi"}
+      Then the client sees a message {"echo": "hi"}
+  ```
+
+
+Notes
+-----
+
+- Breaking change: version 2.0.0 uses a new framing header (magic + length + CRC32). v1 clients are incompatible.
+- Message framing uses a 12‑byte header: 4‑byte magic, 4‑byte big‑endian length, and 4‑byte CRC32 of the payload, followed by a JSON payload encoded as UTF‑8.
+- `max_message_size` defaults to 10MB; set `.max_message_size` to adjust or set to `None` to disable.
+- On disconnect, reads raise `RuntimeError("socket connection broken")` so callers can distinguish cleanly from timeouts.
+- Binding with `port=0` lets the OS choose an ephemeral port; find it with `server.socket.getsockname()`.
+
+
+Links
+-----
+
+- PyPI: https://pypi.org/project/jsocket/
+- License: see `LICENSE`

jsocket-2.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jsocket/__init__.py,sha256=V2M4mp2IwcL1Zy_yoD-6Y5h7PO2sdt5Plf1U0Xw27N8,2870
+jsocket/_version.py,sha256=G_8HyCR_7wKtd1vhEQPneS5oPZmjTSOtVVENsHtdYjU,46
+jsocket/jsocket_base.py,sha256=LZdIiPKLi_iC1pSd3NjgJQrEzQ3hSgnhxIihVMuRFLw,11047
+jsocket/tserver.py,sha256=h19so2UgUc1RIMmkNcJamwZ7gbFFGmaSJqrI2l6XUts,14098
+jsocket-2.0.0.dist-info/licenses/LICENSE,sha256=TIwob4kUNx1DKZ0NVKToEDAFgWsevvTgtZgr_obkDhg,11355
+jsocket-2.0.0.dist-info/METADATA,sha256=1g9-4-2lrq_RpDGeNtZyt8yswhQjG7QXezp4kBPOM9o,18303
+jsocket-2.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+jsocket-2.0.0.dist-info/top_level.txt,sha256=QqfmeUi7avy9cdcsVVvG68CP-4mfg_P6E7OuBuNEcN4,8
+jsocket-2.0.0.dist-info/RECORD,,

{jsocket-1.9.5.dist-info → jsocket-2.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.37.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

jsocket-1.9.5.dist-info/METADATA

@@ -1,27 +0,0 @@
-Metadata-Version: 2.1
-Name: jsocket
-Version: 1.9.5
-Summary: Python JSON Server & Client
-Home-page: https://cpiekarski.com/2012/01/25/python-json-client-server-redux/
-Author: Christopher Piekarski
-Author-email: chris@cpiekarski.com
-Maintainer: Christopher Piekarski
-Maintainer-email: chris@cpiekarski.com
-License: OSI Approved Apache Software License
-Keywords: json,socket,server,client
-Platform: UNKNOWN
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Topic :: System :: Networking
-Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Classifier: Topic :: System :: Distributed Computing
-Classifier: Topic :: System :: Hardware :: Symmetric Multi-processing
-Provides: jsocket
-Requires-Python: >=3.8
-License-File: LICENSE
-
-UNKNOWN
-

jsocket-1.9.5.dist-info/RECORD

@@ -1,8 +0,0 @@
-jsocket/__init__.py,sha256=Im4nFil0iBOXF0G5K5I2nVMkSDIlGNev-rOjy3XUwn8,2836
-jsocket/jsocket_base.py,sha256=65-0DMdgQKymiE3poBpvRnyTMgEv3-VOfqWe-C-6ge4,8025
-jsocket/tserver.py,sha256=bez8pKWwzPQXD0R33sTV-6Z579DS4vfQnnPkklzxt64,10746
-jsocket-1.9.5.dist-info/LICENSE,sha256=TIwob4kUNx1DKZ0NVKToEDAFgWsevvTgtZgr_obkDhg,11355
-jsocket-1.9.5.dist-info/METADATA,sha256=hV3r6UToy38ZkkrSi8ohRGndzCN_xYa8329Ue_hUhXQ,983
-jsocket-1.9.5.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-jsocket-1.9.5.dist-info/top_level.txt,sha256=QqfmeUi7avy9cdcsVVvG68CP-4mfg_P6E7OuBuNEcN4,8
-jsocket-1.9.5.dist-info/RECORD,,