distributed-state-network 0.0.1__tar.gz → 0.0.3__tar.gz

{distributed_state_network-0.0.1 → distributed_state_network-0.0.3}/.gitignore

@@ -7,4 +7,5 @@ test.key
 .coverage
 count.py
 appended.py
-py_line_count_history.jsonl
+py_line_count_history.jsonl
+network.key

{distributed_state_network-0.0.1 → distributed_state_network-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed-state-network
-Version: 0.0.1
+Version: 0.0.3
 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
@@ -79,29 +79,7 @@ DSN creates a peer-to-peer network where each node maintains its own state datab
 - Any node can read any other node's state instantly
 - All communication is encrypted with AES + ECDSA + HTTPS
 
-## API Reference
-
-### Node Methods
-
-**update_data(key, value)** - Update a key in this node's state
-```python
-node.update_data("sensor_reading", "42.0")
-```
-
-**read_data(node_id, key)** - Read a value from any node's state
-
-```python
-temperature = node.read_data("sensor_node", "temperature")
-```
-
-**peers()** - List all connected nodes
-```python
-connected_nodes = node.peers()
-```
-
-## Real-World Examples
-
-### Distributed Temperature Monitoring
+## Example: Distributed Temperature Monitoring
 
 Create a network of temperature sensors that share readings:
 
@@ -129,21 +107,12 @@ for node_id in monitor.node.peers():
         temp = monitor.node.read_data(node_id, "temperature")
         print(f"{node_id}: {temp}°F")
 ```
-
-## Troubleshooting
-
-### Node Can't Connect
-- Verify the AES key file is identical on all nodes
-- Check firewall rules allow traffic on the configured port
-- Ensure bootstrap node address is reachable
-
-### State Not Updating
-- Confirm nodes show as connected with `node.peers()`
-- Check network latency between nodes
-- Verify no duplicate node IDs (each must be unique)
-
-## Performance Characteristics
-- State updates typically propagate in <100ms on local networks
-- Each node stores the complete state of all other nodes
-- Suitable for networks up to ~100 nodes
-- State values should be kept reasonably small (< 1MB per key)
+  
+### Documentation
+* [Usage Examples](./documentation/usage.md)  
+* [Protocol](./documentation/protocol.md)
+
+#### API Reference
+* [DSNodeServer](./documentation/ds-node-server.md)
+* [DSNode](./documentation/ds-node.md)
+* [DSNodeConfig](./documentation/ds-node-config.md)

{distributed_state_network-0.0.1 → distributed_state_network-0.0.3}/README.md

@@ -54,29 +54,7 @@ DSN creates a peer-to-peer network where each node maintains its own state datab
 - Any node can read any other node's state instantly
 - All communication is encrypted with AES + ECDSA + HTTPS
 
-## API Reference
-
-### Node Methods
-
-**update_data(key, value)** - Update a key in this node's state
-```python
-node.update_data("sensor_reading", "42.0")
-```
-
-**read_data(node_id, key)** - Read a value from any node's state
-
-```python
-temperature = node.read_data("sensor_node", "temperature")
-```
-
-**peers()** - List all connected nodes
-```python
-connected_nodes = node.peers()
-```
-
-## Real-World Examples
-
-### Distributed Temperature Monitoring
+## Example: Distributed Temperature Monitoring
 
 Create a network of temperature sensors that share readings:
 
@@ -104,21 +82,12 @@ for node_id in monitor.node.peers():
         temp = monitor.node.read_data(node_id, "temperature")
         print(f"{node_id}: {temp}°F")
 ```
-
-## Troubleshooting
-
-### Node Can't Connect
-- Verify the AES key file is identical on all nodes
-- Check firewall rules allow traffic on the configured port
-- Ensure bootstrap node address is reachable
-
-### State Not Updating
-- Confirm nodes show as connected with `node.peers()`
-- Check network latency between nodes
-- Verify no duplicate node IDs (each must be unique)
-
-## Performance Characteristics
-- State updates typically propagate in <100ms on local networks
-- Each node stores the complete state of all other nodes
-- Suitable for networks up to ~100 nodes
-- State values should be kept reasonably small (< 1MB per key)
+  
+### Documentation
+* [Usage Examples](./documentation/usage.md)  
+* [Protocol](./documentation/protocol.md)
+
+#### API Reference
+* [DSNodeServer](./documentation/ds-node-server.md)
+* [DSNode](./documentation/ds-node.md)
+* [DSNodeConfig](./documentation/ds-node-config.md)

distributed_state_network-0.0.3/documentation/ds-node-config.md

@@ -0,0 +1,47 @@
+## DSNodeConfig
+
+Configuration object for initializing a DSNode instance.
+
+```python
+from distributed_state_network import DSNodeConfig
+```
+
+### Class Definition
+```python
+@dataclass(frozen=True)
+class DSNodeConfig:
+    node_id: str
+    port: int
+    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
+- **aes_key_file** (`str`): Path to the AES key file for encryption/decryption
+- **bootstrap_nodes** (`List[Endpoint]`): List of initial nodes to connect to when joining the network
+
+### Methods
+
+### `from_dict(data: Dict) -> DSNodeConfig`
+Creates a DSNodeConfig instance from a dictionary.
+
+**Parameters:**
+- `data` (`Dict`): Dictionary containing configuration parameters
+
+**Returns:**
+- `DSNodeConfig`: Configuration instance
+
+**Example:**
+```python
+config_dict = {
+    "node_id": "node1",
+    "port": 8000,
+    "aes_key_file": "/path/to/key.aes",
+    "bootstrap_nodes": [
+        {"address": "127.0.0.1", "port": 8001}
+    ]
+}
+config = DSNodeConfig.from_dict(config_dict)
+```

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

@@ -0,0 +1,56 @@
+## 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
+
+### Static Methods
+
+### `start(config: DSNodeConfig, disconnect_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
+
+**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()
+```

distributed_state_network-0.0.3/documentation/ds-node.md

@@ -0,0 +1,64 @@
+## DSNode
+
+Main node class that handles all distributed state network operations including peer management, state synchronization, and encrypted communication.
+
+```python
+from distributed_state_network import DSNode
+```
+
+### Class Definition
+```python
+class DSNode:
+    config: DSNodeConfig
+    address_book: Dict[str, Endpoint]
+    node_states: Dict[str, StatePacket]
+    shutting_down: bool = False
+```
+
+### Constructor
+
+```python
+node = DSNode(config, "0.0.3", disconnect_callback=on_disconnect)
+```
+
+**Parameters:**
+- `config` (`DSNodeConfig`): Node configuration
+- `version` (`str`): Protocol version string for compatibility checking
+- `disconnect_callback` (`Optional[Callable]`): Callback function invoked when a peer disconnects
+
+### Key Methods
+
+### `bootstrap(con: Endpoint) -> None`
+Connects to a bootstrap node to join the network.
+
+**Parameters:**
+- `con` (`Endpoint`): Connection endpoint of the bootstrap node
+
+**Raises:**
+- `Exception`: If connection to bootstrap node fails
+
+### `update_data(key: str, val: str) -> None`
+Updates a key-value pair in the node's state and broadcasts the update to all peers.
+```python
+node.update_data("status", "active")
+```
+
+**Parameters:**
+- `key` (`str`): State key to update
+- `val` (`str`): New value for the key
+
+### `read_data(node_id: str, key: str) -> Optional[str]`
+Reads a value from a specific node's state.
+
+**Parameters:**
+- `node_id` (`str`): ID of the node to read from
+- `key` (`str`): Key to retrieve
+
+**Returns:**
+- `Optional[str]`: Value if exists, None otherwise
+
+### `peers() -> List[str]`
+Returns a list of all connected peer node IDs.
+
+**Returns:**
+- `List[str]`: List of node IDs

distributed_state_network-0.0.3/documentation/protocol.md

@@ -0,0 +1,37 @@
+## Network Protocol
+
+### Endpoints
+The server exposes the following HTTPS endpoints:
+
+- **POST /hello**: Exchange node information and certificates
+- **POST /peers**: Request/share peer list
+- **POST /update**: Send/receive state updates
+- **POST /ping**: Connectivity check
+
+### Security
+- All communication is encrypted using AES with a shared key
+- Messages are signed using ECDSA for authentication
+- HTTPS with self-signed certificates for transport security
+
+### 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
+
+## 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 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. **Certificate Management**: Certificates and keys are automatically generated and stored in `certs/` and `credentials/` directories
+
+## Error Handling
+
+Common HTTP status codes returned:
+- **200**: Success
+- **401**: Not Authorized (signature verification failed)
+- **404**: Endpoint not found
+- **406**: Not Acceptable (invalid data or version mismatch)
+- **505**: Version not supported

distributed_state_network-0.0.3/documentation/usage.md

@@ -0,0 +1,68 @@
+## 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
+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 Disconnect Callback
+
+```python
+def handle_disconnect():
+    print("A peer has disconnected!")
+    # Handle reconnection logic
+
+config = DSNodeConfig(
+    node_id="node3",
+    port=8002,
+    aes_key_file="/path/to/shared.key",
+    bootstrap_nodes=[Endpoint("127.0.0.1", 8000)]
+)
+
+server = DSNodeServer.start(config, disconnect_callback=handle_disconnect)
+```

{distributed_state_network-0.0.1 → distributed_state_network-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "distributed-state-network"
-version = "0.0.1"
+version = "0.0.3"
 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.0.1 → distributed_state_network-0.0.3}/src/distributed_state_network/dsnode.py

@@ -1,12 +1,11 @@
 import os
 import time
-import json
 import logging
 
 import requests
 import threading
 from requests import RequestException
-from typing import Dict, Tuple, List, Optional
+from typing import Dict, Tuple, List, Optional, Callable
 
 from distributed_state_network.objects.endpoint import Endpoint
 from distributed_state_network.objects.hello_packet import HelloPacket
@@ -16,7 +15,7 @@ from distributed_state_network.objects.config import DSNodeConfig
 
 from distributed_state_network.util import get_dict_hash
 from distributed_state_network.util.key_manager import CertManager, CredentialManager
-from distributed_state_network.util.aes import aes_encrypt, aes_decrypt, generate_aes_key
+from distributed_state_network.util.aes import aes_encrypt, aes_decrypt
 
 TICK_INTERVAL = 3
 
@@ -30,6 +29,7 @@ class DSNode:
             self, 
             config: DSNodeConfig,
             version: str,
+            disconnect_callback: Optional[Callable] = None
         ):
         self.config = config
         self.version = version
@@ -49,6 +49,7 @@ class DSNode:
         }
         
         self.logger = logging.getLogger("DSN: " + config.node_id)
+        self.disconnect_cb = disconnect_callback
         if not os.path.exists(config.aes_key_file):
             raise Exception(f"Could not find aes key file in {config.aes_key_file}")
         threading.Thread(target=self.network_tick).start()
@@ -60,7 +61,7 @@ class DSNode:
     def network_tick(self):
         time.sleep(TICK_INTERVAL)
         if self.shutting_down:
-            self.logger.info(f"Shutting down node")
+            self.logger.info("Shutting down node")
             return
         self.test_connections()
         threading.Thread(target=self.network_tick).start()
@@ -69,9 +70,10 @@ class DSNode:
         def remove(node_id: str):
             if node_id in self.node_states:
                 del self.node_states[node_id]
+                del self.address_book[node_id]
                 self.logger.info(f"PING failed for {node_id}, disconnecting...")
         for node_id in self.node_states.copy().keys():
-            if not node_id in self.node_states or node_id == self.config.node_id:
+            if node_id not in self.node_states or node_id == self.config.node_id:
                 continue
             try:
                 if self.shutting_down:
@@ -80,6 +82,8 @@ class DSNode:
             except RequestException:
                 if node_id in self.node_states: # double check if something has changed since the ping request started
                     remove(node_id)
+                    if self.disconnect_cb is not None:
+                        self.disconnect_cb()
 
     def send_request_to_node(self, node_id: str, path: str, payload: bytes, verify) -> Tuple[requests.Response, bytes]:
         con = self.connection_from_node(node_id)

{distributed_state_network-0.0.1 → distributed_state_network-0.0.3}/src/distributed_state_network/handler.py

@@ -1,9 +1,7 @@
 import ssl
 import threading
-import json
 import logging
-from typing import Tuple, Callable, Dict
-from threading import Thread
+from typing import Callable, Optional
 from http.server import HTTPServer, BaseHTTPRequestHandler
 
 from distributed_state_network.dsnode import DSNode
@@ -11,7 +9,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.0.1"
+VERSION = "0.0.3"
 logging.basicConfig(level=logging.INFO)
 
 def respond_bytes(handler: BaseHTTPRequestHandler, data: bytes):
@@ -71,11 +69,12 @@ def serve(httpd):
 class DSNodeServer(HTTPServer):
     def __init__(
         self, 
-        config: DSNodeConfig
+        config: DSNodeConfig,
+        disconnect_callback: Optional[Callable] = None
     ):
         super().__init__(("127.0.0.1", config.port), DSNodeHandler)
         self.config = config
-        self.node = DSNode(config, VERSION)
+        self.node = DSNode(config, VERSION, disconnect_callback)
         self.node.logger.info(f'Started DSNode on port {config.port}')
 
     def stop(self):
@@ -91,8 +90,8 @@ class DSNodeServer(HTTPServer):
             f.write(key)
 
     @staticmethod 
-    def start(config: DSNodeConfig) -> 'NodeServer':
-        n = DSNodeServer(config)
+    def start(config: DSNodeConfig, disconnect_callback: Optional[Callable] = None) -> 'NodeServer':
+        n = DSNodeServer(config, disconnect_callback)
         ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
         public_path = n.node.cert_manager.public_path(n.config.node_id)
         ssl_context.load_cert_chain(

distributed_state_network-0.0.3/tests/connections.py

@@ -0,0 +1,91 @@
+import os
+import sys
+import time
+import unittest
+from typing import Optional, Callable
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '../src'))
+
+from distributed_state_network import DSNodeServer, DSNodeConfig, Endpoint
+
+KEY_FILE = "network.key"
+
+if not os.path.exists(KEY_FILE):
+    DSNodeServer.generate_key("network.key")
+
+d_cb_test = 0
+
+current_port = 5000
+
+def start_node(node_id: str, bootstrap_port: int = None, disconnect_cb: Optional[Callable] = None):
+    global current_port
+    args = {
+        "node_id": node_id,
+        "port": current_port,
+        "aes_key_file": KEY_FILE
+    }
+    current_port += 1
+    if bootstrap_port is not None:
+        args["bootstrap_nodes"] = [Endpoint(
+            address="127.0.0.1",
+            port=bootstrap_port
+        )]
+    else:
+        args["bootstrap_nodes"] = []
+
+    return DSNodeServer.start(DSNodeConfig(**args), disconnect_cb)
+
+class ConnectionsTest(unittest.TestCase):
+    def test_one(self):
+        node = start_node("node-1")
+        self.assertEqual(["node-1"], node.node.peers())
+
+    def test_two(self):
+        node1 = start_node("node-1")
+        node2 = start_node("node-2", node1.config.port)
+        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 = []
+        for i in range(10):
+            nodes.append(start_node(f"node-{i}", bootstrap_node.config.port))
+
+        node_list = ["bootstrap"]
+        node_list.extend([f"node-{i}" for i in range(10)])
+
+        time.sleep(5)
+        self.assertEqual(node_list, sorted(bootstrap_node.node.peers()))
+        for i in range(10):
+            self.assertEqual(node_list, sorted(nodes[i].node.peers()))
+
+    def test_disconnect(self):
+        node1 = start_node("node-1")
+        node2 = start_node("node-2", node1.config.port)
+        node3 = start_node("node-3", node1.config.port)
+
+        time.sleep(1)
+        node2.stop()
+        time.sleep(10)
+        node4 = start_node("node-4", node1.config.port)
+        time.sleep(10)
+        self.assertEqual(["node-1", "node-3", "node-4"], sorted(node1.node.peers()))
+        self.assertEqual(["node-1", "node-3", "node-4"], sorted(node3.node.peers()))
+        self.assertEqual(["node-1", "node-3", "node-4"], sorted(node4.node.peers()))
+
+    def test_disconnect_cb(self):
+        global d_cb_test
+        d_cb_test = 0
+        def inc():
+            global d_cb_test
+            d_cb_test = 1
+        node1 = start_node("node-1", None, inc)
+        node2 = start_node("node-2", node1.config.port)
+        time.sleep(1)
+        node2.stop()
+        time.sleep(5)
+        self.assertEqual(d_cb_test, 1)
+
+if __name__ == '__main__':
+    unittest.main()

distributed_state_network-0.0.1/security.md

@@ -1,14 +0,0 @@
-## Security Architecture
-We use a three-layer security model where each layer addresses a specific vulnerability. Understanding this design helps explain why certain setup steps are necessary and how your data stays protected.
-The Three-Layer Defense
-Think of our security like protecting a secret club where members share sensitive information. You need multiple types of protection because different attacks require different defenses.
-### Layer 1: AES
-AES Encryption acts as the network's membership card. Every message between nodes is encrypted with a shared AES key, making the network invisible to outsiders. If someone intercepts your network traffic without this key, they see only meaningless encrypted bytes. This is why you must carefully share the key file with trusted nodes - it's the fundamental gatekeeper of your network.
-### Layer 2: ECDSA
-ECDSA Signatures solve a critical problem that AES alone cannot address. Once someone has the network key, how do you prevent them from impersonating other nodes? Each node has its own unforgeable cryptographic identity. When node "sensor_1" shares its temperature reading, it signs that data with its private key. Other nodes verify this signature to ensure the data truly came from sensor_1, not from an attacker pretending to be sensor_1. This is why node IDs must be unique - each ID is permanently bound to a specific cryptographic identity.
-### Layer 3: HTTPS
-HTTPS/TLS prevents sophisticated network-level attacks. Even with encryption and signatures, an attacker positioned between two nodes could intercept messages, block updates, or redirect traffic to malicious servers. HTTPS certificates ensure you're communicating with the exact node you intend to reach. During the initial handshake, nodes exchange certificates that get verified on every subsequent connection, creating authenticated channels that can't be hijacked.
-
-## Why This Matters
-Each layer compensates for what the others cannot protect. AES keeps outsiders out but can't distinguish between insiders. ECDSA proves identity but doesn't hide data. HTTPS secures the transport but doesn't control network access. Together, they create a system where only authorized nodes can join, every piece of state data is cryptographically guaranteed to come from its claimed source, and all communications flow through verified channels. This isn't over-engineering - it's the minimum required for nodes to trust each other in a truly distributed system without any central authority.
-When you see the various key files and certificates being generated during setup, you're watching these three defensive layers being constructed. Each one is essential for maintaining the integrity and privacy of your distributed application.