jsocket 1.9.6__tar.gz → 2.0.0__tar.gz

jsocket-2.0.0/PKG-INFO

@@ -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-1.9.6 → jsocket-2.0.0}/README.md

@@ -132,7 +132,9 @@ Behavior-Driven Tests (Behave)
 Notes
 -----
 
-- Message framing uses a 4‑byte big‑endian length header followed by a JSON payload encoded as UTF‑8.
+- 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()`.
 

{jsocket-1.9.6 → jsocket-2.0.0}/jsocket/_version.py

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

{jsocket-1.9.6 → jsocket-2.0.0}/jsocket/jsocket_base.py

@@ -24,11 +24,21 @@ 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,14 @@ 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)
@@ -55,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."""
@@ -67,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."""
@@ -118,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:
@@ -158,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):
@@ -170,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))