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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed-state-network
-Version: 0.1.3
+Version: 0.2.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
@@ -77,7 +77,7 @@ DSN creates a peer-to-peer network where each node maintains its own state datab
 - Each node owns its state and is the only one who can modify it
 - State changes are automatically broadcast to all connected nodes
 - Any node can read any other node's state instantly
-- All communication is encrypted with AES + ECDSA + HTTPS
+- All communication is encrypted with AES
 
 ## Example: Distributed Temperature Monitoring
 
@@ -110,6 +110,9 @@ for node_id in monitor.node.peers():
   
 ### Documentation
 * [Usage Examples](./documentation/usage.md)  
+* [Configuration Class](./documentation/ds-node-config.md)
+* [Server Class](./documentation/ds-node-server.md)
+* [Protocol Class](./documentation/ds-node.md)
 * [Protocol](./documentation/protocol.md)
 
 #### API Reference

{distributed_state_network-0.1.3 → distributed_state_network-0.2.0}/README.md

@@ -52,7 +52,7 @@ DSN creates a peer-to-peer network where each node maintains its own state datab
 - Each node owns its state and is the only one who can modify it
 - State changes are automatically broadcast to all connected nodes
 - Any node can read any other node's state instantly
-- All communication is encrypted with AES + ECDSA + HTTPS
+- All communication is encrypted with AES
 
 ## Example: Distributed Temperature Monitoring
 
@@ -85,6 +85,9 @@ for node_id in monitor.node.peers():
   
 ### Documentation
 * [Usage Examples](./documentation/usage.md)  
+* [Configuration Class](./documentation/ds-node-config.md)
+* [Server Class](./documentation/ds-node-server.md)
+* [Protocol Class](./documentation/ds-node.md)
 * [Protocol](./documentation/protocol.md)
 
 #### API Reference

{distributed_state_network-0.1.3 → distributed_state_network-0.2.0}/documentation/ds-node-config.md

@@ -12,20 +12,18 @@ from distributed_state_network import DSNodeConfig
 class DSNodeConfig:
     node_id: str
     port: int
-    https: bool
-    network_ip: str
     aes_key_file: str
     bootstrap_nodes: List[Endpoint]
 ```
 
 ### Attributes
 - **node_id** (`str`): Unique identifier for the node
-- **port** (`int`): Port number for the node to listen on
+- **port** (`int`): Port number for the node to listen on (UDP)
 - **aes_key_file** (`str`): Path to the AES key file for encryption/decryption
-- **https** (`bool`): whether to use HTTPS network requests (true) or http (false)
-- **network_ip** (`str`): Must match network address of the current computer (only if https is on)
 - **bootstrap_nodes** (`List[Endpoint]`): List of initial nodes to connect to when joining the network
 
+**Note:** The node's public IP address is automatically detected by the bootstrap server during the initial handshake.
+
 ### Methods
 
 ### `from_dict(data: Dict) -> DSNodeConfig`
@@ -43,11 +41,19 @@ config_dict = {
     "node_id": "node1",
     "port": 8000,
     "aes_key_file": "/path/to/key.aes",
-    "https": false,
-    "network_ip": "192.168.0.1",
     "bootstrap_nodes": [
         {"address": "127.0.0.1", "port": 8001}
     ]
 }
 config = DSNodeConfig.from_dict(config_dict)
-```
+```
+
+**Example for bootstrap node (first node in network):**
+```python
+config_dict = {
+    "node_id": "bootstrap",
+    "port": 8000,
+    "aes_key_file": "/path/to/key.aes",
+    "bootstrap_nodes": []  # Empty for first node
+}
+config = DSNodeConfig.from_dict(config_dict)

{distributed_state_network-0.1.3 → distributed_state_network-0.2.0}/documentation/ds-node-server.md

@@ -30,8 +30,8 @@ server = DSNodeServer.start(config)
 
 **Parameters:**
 - `config` (`DSNodeConfig`): Node configuration
-- `disconnect_callback` (`Optional[Callable]`): Callback for disconnect events
-- `update_callback` (`Optional[Callable]`): Callback for state update events
+- `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

distributed_state_network-0.2.0/documentation/protocol.md

@@ -0,0 +1,65 @@
+## Network Protocol
+
+### Transport Layer
+The network now uses **UDP (User Datagram Protocol)** for all communication instead of HTTP/HTTPS. This provides:
+- Lower latency for peer-to-peer communication
+- Reduced overhead compared to HTTP
+- Simpler connection management
+- More suitable for real-time distributed systems
+
+### Message Types
+All UDP packets use a message type byte prefix to identify the packet type:
+
+- **Type 1 (HELLO)**: Exchange node information and credentials
+- **Type 2 (PEERS)**: Request/share peer list
+- **Type 3 (UPDATE)**: Send/receive state updates
+- **Type 4 (PING)**: Connectivity check
+
+### Packet Structure
+Each UDP packet follows this structure:
+1. **AES Encrypted Payload** containing:
+   - Message type (1 byte)
+   - Message payload (variable length)
+
+### Security
+- All communication is encrypted using AES with a shared key
+- Messages are signed using ECDSA for authentication
+- UDP packets are encrypted end-to-end
+- HTTPS/TLS is not supported with UDP (certificates are no longer used)
+
+### State Synchronization
+- Nodes maintain a copy of all peers' states
+- Updates are broadcast to all connected peers
+- Timestamps prevent older updates from overwriting newer ones
+
+### Socket Management
+- You can provide a custom UDP socket when starting a server
+- If no socket is provided, one will be created and bound automatically
+- Socket timeout is set to 2 seconds for requests
+- Maximum UDP packet size is 65507 bytes
+
+## Important Notes
+
+1. **Shared AES Key**: All nodes in the network must use the same AES key file
+2. **Unique Node IDs**: Each node must have a unique node_id
+3. **Port Availability**: Ensure the specified UDP port is available before starting
+4. **Bootstrap Nodes**: At least one bootstrap node is required to join an existing network
+5. **Network Tick**: The network performs maintenance checks every 3 seconds
+6. **Credential Management**: ECDSA keys are automatically generated and stored in `credentials/` directory
+7. **UDP Reliability**: The protocol implements retry logic (up to 3 attempts) for failed requests
+8. **HTTPS Not Supported**: The `https` configuration option is ignored when using UDP
+
+## Error Handling
+
+Common error codes (embedded in exception messages):
+- **401**: Not Authorized (signature verification failed)
+- **406**: Not Acceptable (invalid data, stale update, or version mismatch)
+- **505**: Version not supported
+
+## Migration from HTTP
+
+If you're migrating from the HTTP-based version:
+1. Remove any HTTPS certificate dependencies
+2. Update firewall rules to allow UDP traffic on your ports
+3. The API remains largely the same, but transport is now UDP
+4. The `https` flag in configuration is now ignored

distributed_state_network-0.2.0/documentation/usage.md

@@ -0,0 +1,159 @@
+## Usage Examples
+
+### Basic Setup
+
+```python
+from distributed_state_network import DSNodeServer, DSNodeConfig, Endpoint
+
+# Create configuration
+config = DSNodeConfig(
+    node_id="node1",
+    port=8000,
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[]  # Empty for first node
+)
+
+# Start server (UDP socket will be created automatically)
+server = DSNodeServer.start(config)
+
+# Update state
+server.node.update_data("status", "online")
+server.node.update_data("version", "1.0.0")
+
+# Read own state
+my_status = server.node.read_data("node1", "status")
+
+# Get connected peers
+peers = server.node.peers()
+print(f"Connected peers: {peers}")
+
+# Shutdown
+server.stop()
+```
+
+### Joining Existing Network
+
+```python
+# Node 2 configuration with bootstrap
+config2 = DSNodeConfig(
+    node_id="node2",
+    port=8001,
+    aes_key_file="/path/to/shared.key",  # Same key file as network
+    bootstrap_nodes=[
+        Endpoint("127.0.0.1", 8000)  # Node 1's endpoint
+    ]
+)
+
+server2 = DSNodeServer.start(config2)
+
+# Read state from peer
+peer_status = server2.node.read_data("node1", "status")
+```
+
+### With Custom Socket
+
+```python
+import socket
+
+# Create a custom UDP socket
+custom_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+custom_socket.bind(("0.0.0.0", 8003))
+
+# You can configure socket options before passing it to the server
+custom_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+config = DSNodeConfig(
+    node_id="node3",
+    port=8003,  # Should match the bound port
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[Endpoint("127.0.0.1", 8000)]
+)
+
+# Pass the custom socket when starting the server
+server = DSNodeServer.start(config, sock=custom_socket)
+```
+
+### With Disconnect Callback
+
+```python
+def handle_disconnect():
+    print("A peer has disconnected!")
+    # Handle reconnection logic
+
+config = DSNodeConfig(
+    node_id="node4",
+    port=8004,
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[Endpoint("127.0.0.1", 8000)]
+)
+
+server = DSNodeServer.start(config, disconnect_callback=handle_disconnect)
+```
+
+### With Update Callback
+
+```python
+def handle_update():
+    print("A peer has updated their state!")
+    # React to state changes
+
+config = DSNodeConfig(
+    node_id="node5",
+    port=8005,
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[Endpoint("127.0.0.1", 8000)]
+)
+
+server = DSNodeServer.start(config, update_callback=handle_update)
+```
+
+### Complete Example with All Options
+
+```python
+import socket
+from distributed_state_network import DSNodeServer, DSNodeConfig, Endpoint
+
+def on_peer_disconnect():
+    print("Peer disconnected from network")
+
+def on_state_update():
+    print("Peer state was updated")
+
+# Create custom socket (optional)
+custom_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+custom_sock.bind(("0.0.0.0", 8006))
+
+config = DSNodeConfig(
+    node_id="node6",
+    port=8006,
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[
+        Endpoint("127.0.0.1", 8000),
+        Endpoint("127.0.0.1", 8001)  # Multiple bootstrap options
+    ]
+)
+
+# Start with all options
+server = DSNodeServer.start(
+    config,
+    sock=custom_sock,  # Optional custom socket
+    disconnect_callback=on_peer_disconnect,
+    update_callback=on_state_update
+)
+
+# Use the server
+server.node.update_data("role", "worker")
+peers = server.node.peers()
+
+# When done
+server.stop()
+```
+
+### Network Protocol Notes
+
+- All communication uses **UDP** instead of HTTP/HTTPS
+- Packets are encrypted with AES using the shared key
+- Messages are signed with ECDSA for authentication
+- Maximum UDP packet size is 65507 bytes
+- Request timeout is 2 seconds with up to 3 retry attempts
+- Network health checks occur every 3 seconds

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "distributed-state-network"
-version = "0.1.3"
+version = "0.2.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"]