distributed-state-network 0.2.0__tar.gz → 0.3.0__tar.gz

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed-state-network
-Version: 0.2.0
+Version: 0.3.0
 Summary: A tool to distribute the state of a network device to other devices on the network
 Project-URL: Homepage, https://github.com/erinclemmer/distributed_state_network
 Project-URL: Issues, https://github.com/erinclemmer/distributed_state_network/issues

distributed_state_network-0.3.0/documentation/ds-node-server.md

@@ -0,0 +1,192 @@
+## DSNodeServer
+
+UDP server wrapper for DSNode that handles incoming network requests.
+
+```python
+from distributed_state_network import DSNodeServer
+```
+
+### Class Definition
+```python
+class DSNodeServer:
+    config: DSNodeConfig
+    node: DSNode
+    socket: socket.socket
+    running: bool
+    thread: threading.Thread
+```
+
+### Constructor
+
+**Parameters:**
+- `config` (`DSNodeConfig`): Node configuration
+- `sock` (`Optional[socket.socket]`): Custom UDP socket to use (optional, creates new socket if not provided)
+- `disconnect_callback` (`Optional[Callable]`): Callback for disconnect events
+- `update_callback` (`Optional[Callable]`): Callback for state update events
+
+**Example:**
+```python
+# Create with default socket
+server = DSNodeServer(config)
+
+# Or with custom socket
+custom_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+custom_socket.bind(("0.0.0.0", 8000))
+server = DSNodeServer(config, sock=custom_socket)
+```
+
+### Static Methods
+
+### `start(config: DSNodeConfig, sock: Optional[socket.socket] = None, disconnect_callback: Optional[Callable] = None, update_callback: Optional[Callable] = None) -> DSNodeServer`
+Creates and starts a new DSNodeServer instance with UDP socket.
+
+```python
+server = DSNodeServer.start(config)
+```
+
+**Parameters:**
+- `config` (`DSNodeConfig`): Node configuration
+- `sock` (`Optional[socket.socket]`): Custom UDP socket to use (optional)
+- `disconnect_callback` (`Optional[Callable]`): Callback for disconnect events (no parameters)
+- `update_callback` (`Optional[Callable]`): Callback for state update events (no parameters)
+
+**Returns:**
+- `DSNodeServer`: Running server instance
+
+**Example with bootstrap:**
+```python
+# Bootstrap node (first node in network)
+bootstrap_config = DSNodeConfig(
+    node_id="bootstrap",
+    port=8000,
+    aes_key_file="network.key",
+    bootstrap_nodes=[]
+)
+bootstrap = DSNodeServer.start(bootstrap_config)
+
+# Connector node (joins existing network)
+connector_config = DSNodeConfig(
+    node_id="connector",
+    port=8001,
+    aes_key_file="network.key",
+    bootstrap_nodes=[Endpoint("127.0.0.1", 8000)]
+)
+connector = DSNodeServer.start(connector_config)
+```
+
+### `generate_key(out_file_path: str) -> None`
+Generates a new AES key file for network encryption. All nodes in the same network must share the same AES key.
+
+**Parameters:**
+- `out_file_path` (`str`): Path where the key file will be saved
+
+**Example:**
+```python
+DSNodeServer.generate_key("/path/to/network.key")
+```
+
+### Instance Methods
+
+### `stop() -> None`
+Gracefully shuts down the server and cleans up resources.
+
+**Example:**
+```python
+server.stop()
+```
+
+### `serve_forever() -> None`
+Main UDP server loop. Continuously listens for incoming packets and routes them to appropriate handlers. This method is typically called automatically by `start()` in a daemon thread.
+
+**Note:** This method blocks until the server is stopped.
+
+## Network Protocol
+
+The server uses UDP sockets with the following characteristics:
+
+- **Port**: Configurable via DSNodeConfig
+- **Encryption**: All packets encrypted with AES
+- **Authentication**: ECDSA signatures for message verification
+- **Max Packet Size**: 65507 bytes (UDP limit)
+- **Timeout**: 2 seconds with automatic retry (up to 3 attempts)
+
+## Message Types
+
+The server handles four types of messages:
+
+1. **HELLO (1)**: Node introduction and public key exchange
+2. **PEERS (2)**: Request/response for peer list
+3. **UPDATE (3)**: State synchronization
+4. **PING (4)**: Connection health check
+
+## Automatic IP Detection
+
+When a client connects to a bootstrap server:
+
+1. Server extracts client's IP from UDP packet source address
+2. Server includes detected IP in HELLO response via `detected_address` field
+3. Client updates its own address book with the detected IP
+4. Correct IP propagates to other nodes through peer discovery
+
+This eliminates the need for manual IP configuration and works correctly behind NAT.
+
+## Thread Safety
+
+The server spawns separate threads for:
+- Main UDP receive loop (`serve_forever`)
+- Packet handling (one thread per packet)
+- Node network tick (periodic health checks)
+
+All shared state is protected with appropriate locks.
+
+## Example: Multi-Node Setup
+
+```python
+from distributed_state_network import DSNodeServer, DSNodeConfig, Endpoint
+
+# Generate shared AES key (only once)
+DSNodeServer.generate_key("shared.key")
+
+# Start bootstrap node
+bootstrap = DSNodeServer.start(DSNodeConfig(
+    node_id="bootstrap",
+    port=8000,
+    aes_key_file="shared.key",
+    bootstrap_nodes=[]
+))
+
+# Start additional nodes
+node1 = DSNodeServer.start(DSNodeConfig(
+    node_id="node1",
+    port=8001,
+    aes_key_file="shared.key",
+    bootstrap_nodes=[Endpoint("192.168.1.100", 8000)]
+))
+
+node2 = DSNodeServer.start(DSNodeConfig(
+    node_id="node2",
+    port=8002,
+    aes_key_file="shared.key",
+    bootstrap_nodes=[Endpoint("192.168.1.100", 8000)]
+))
+
+# Nodes automatically discover each other through bootstrap
+```
+
+## Troubleshooting
+
+### Server won't start
+- Check if port is already in use
+- Verify AES key file exists and is readable
+- Ensure firewall allows UDP traffic on specified port
+
+### Nodes can't connect
+- Verify all nodes use the same AES key
+- Check bootstrap node is running and reachable
+- Verify network connectivity (ping bootstrap address)
+- Check firewall rules for UDP ports
+
+### Connection drops
+- Increase timeout if on slow networks
+- Check network stability
+- Verify nodes aren't being stopped unexpectedly

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/documentation/protocol.md

@@ -19,6 +19,7 @@ All UDP packets use a message type byte prefix to identify the packet type:
 Each UDP packet follows this structure:
 1. **AES Encrypted Payload** containing:
    - Message type (1 byte)
+   - Response bit (1 byte): 0 for requests, 1 for responses
    - Message payload (variable length)
 
 ### Security

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "distributed-state-network"
-version = "0.2.0"
+version = "0.3.0"
 authors = [{name="Erin Clemmer", email="erin.c.clemmer@gmail.com"}]
 description = "A tool to distribute the state of a network device to other devices on the network"
 keywords = ["distributed", "networking"]

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/src/distributed_state_network/dsnode.py

@@ -108,8 +108,8 @@ class DSNode:
             raise Exception("Socket not set. Cannot send UDP request.")
         
         try:
-            # Prepend message type to payload
-            data_with_type = bytes([msg_type]) + payload
+            # Prepend message type and response bit (0 for request) to payload
+            data_with_type = bytes([msg_type, 0]) + payload
             encrypted_data = self.encrypt_data(data_with_type)
             
             # Create a unique ID for this request based on endpoint and msg type
@@ -159,12 +159,13 @@ class DSNode:
             # Decrypt the data
             decrypted = self.decrypt_data(data)
             
-            if len(decrypted) == 0:
+            if len(decrypted) < 2:
                 return
             
-            # First byte is message type
+            # First byte is message type, second byte is response bit
             msg_type = decrypted[0]
-            body = decrypted[1:]
+            is_response = decrypted[1]
+            body = decrypted[2:]
             
             # Find matching pending request
             request_id = (addr[0], addr[1], msg_type)

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/src/distributed_state_network/handler.py

@@ -7,7 +7,7 @@ from distributed_state_network.objects.config import DSNodeConfig
 from distributed_state_network.util.aes import generate_aes_key
 from distributed_state_network.util import stop_thread
 
-VERSION = "0.2.0"
+VERSION = "0.3.0"
 logging.basicConfig(level=logging.INFO)
 
 # Message type constants
@@ -53,19 +53,20 @@ class DSNodeServer:
             # Decrypt the data
             decrypted = self.node.decrypt_data(data)
             
-            if len(decrypted) == 0:
+            if len(decrypted) < 2:
                 return
             
-            # First byte is message type
+            # First byte is message type, second byte is response bit
             msg_type = decrypted[0]
-            body = decrypted[1:]
+            is_response = decrypted[1]
+            body = decrypted[2:]
             
-            # Check if this is a response to a pending request
+            # Check if this is a response (either by bit flag or by pending request)
             request_id = (addr[0], addr[1], msg_type)
             with self.node.response_lock:
-                is_response = request_id in self.node.pending_responses
+                has_pending_request = request_id in self.node.pending_responses
             
-            if is_response:
+            if is_response == 1 or has_pending_request:
                 # This is a response to our request - route to response handler
                 self.node.handle_response(data, addr)
             else:
@@ -87,8 +88,8 @@ class DSNodeServer:
                 
                 # Send response if handler returned data
                 if response is not None:
-                    # Prepend message type to response
-                    response_with_type = bytes([msg_type]) + response
+                    # Prepend message type and response bit (1 for response) to response
+                    response_with_type = bytes([msg_type, 1]) + response
                     encrypted_response = self.node.encrypt_data(response_with_type)
                     self.socket.sendto(encrypted_response, addr)
                 
@@ -104,8 +105,9 @@ class DSNodeServer:
             try:
                 # Receive UDP packet (max 65507 bytes for UDP)
                 data, addr = self.socket.recvfrom(65507)
-                # Handle packet in separate thread to avoid blocking
-                threading.Thread(target=self.handle_packet, args=(data, addr), daemon=True).start()
+                if self.running:
+                    # Handle packet in separate thread to avoid blocking
+                    threading.Thread(target=self.handle_packet, args=(data, addr), daemon=True).start()
             except OSError:
                 # Socket was closed
                 if not self.running:

{distributed_state_network-0.2.0 → distributed_state_network-0.3.0}/tests/connections.py

@@ -17,14 +17,12 @@ cb_test = 0
 
 current_port = 5000
 
-def start_node(node_id: str, bootstrap_port: int = None, disconnect_cb: Optional[Callable] = None, update_cb: Optional[Callable] = None, https: bool = False):
+def start_node(node_id: str, bootstrap_port: int = None, disconnect_cb: Optional[Callable] = None, update_cb: Optional[Callable] = None):
     global current_port
     args = {
         "node_id": node_id,
         "port": current_port,
-        "aes_key_file": KEY_FILE,
-        "https": https,
-        "network_ip": "127.0.0.1"
+        "aes_key_file": KEY_FILE
     }
     current_port += 1
     if bootstrap_port is not None:
@@ -35,7 +33,7 @@ def start_node(node_id: str, bootstrap_port: int = None, disconnect_cb: Optional
     else:
         args["bootstrap_nodes"] = []
 
-    return DSNodeServer.start(DSNodeConfig(**args), disconnect_cb, update_cb)
+    return DSNodeServer.start(DSNodeConfig(**args), None, disconnect_cb, update_cb)
 
 class ConnectionsTest(unittest.TestCase):
     def test_one(self):
@@ -48,12 +46,6 @@ class ConnectionsTest(unittest.TestCase):
         self.assertEqual(["node-1", "node-2"], sorted(node1.node.peers()))
         self.assertEqual(["node-1", "node-2"], sorted(node2.node.peers()))
 
-    def test_https(self):
-        node1 = start_node("node-1", https=True)
-        node2 = start_node("node-2", node1.config.port, https=True)
-        self.assertEqual(["node-1", "node-2"], sorted(node1.node.peers()))
-        self.assertEqual(["node-1", "node-2"], sorted(node2.node.peers()))
-
     def test_many(self):
         bootstrap_node = start_node("bootstrap")
         nodes = []
@@ -92,7 +84,7 @@ class ConnectionsTest(unittest.TestCase):
         node2 = start_node("node-2", node1.config.port)
         time.sleep(1)
         node2.stop()
-        time.sleep(5)
+        time.sleep(10)
         self.assertEqual(cb_test, 1)
 
     def test_update_cb(self):

distributed_state_network-0.2.0/documentation/ds-node-server.md

@@ -1,58 +0,0 @@
-## DSNodeServer
-
-HTTPS server wrapper for DSNode that handles incoming network requests.
-
-```python
-from distributed_state_network import DSNodeServer
-```
-
-### Class Definition
-```python
-class DSNodeServer(HTTPServer):
-    config: DSNodeConfig
-    node: DSNode
-```
-
-### Constructor
-
-**Parameters:**
-- `config` (`DSNodeConfig`): Node configuration
-- `disconnect_callback` (`Optional[Callable]`): Callback for disconnect events
-- `update_callback` (`Optional[Callable]`): Callback for state update events
-
-### Static Methods
-
-### `start(config: DSNodeConfig, disconnect_callback: Optional[Callable] = None, update_callback: Optional[Callable] = None) -> DSNodeServer`
-Creates and starts a new DSNodeServer instance with SSL configuration.
-```python
-server = DSNodeServer.start(config)
-```
-
-**Parameters:**
-- `config` (`DSNodeConfig`): Node configuration
-- `disconnect_callback` (`Optional[Callable]`): Callback for disconnect events (no parameters)
-- `update_callback` (`Optional[Callable]`): Callback for state update events (no parameters)
-
-**Returns:**
-- `DSNodeServer`: Running server instance
-
-### `generate_key(out_file_path: str) -> None`
-Generates a new AES key file for network encryption.
-
-**Parameters:**
-- `out_file_path` (`str`): Path where the key file will be saved
-
-**Example:**
-```python
-DSNodeServer.generate_key("/path/to/network.key")
-```
-
-### Instance Methods
-
-### `stop() -> None`
-Gracefully shuts down the server and cleans up resources.
-
-**Example:**
-```python
-server.stop()
-```