distributed-state-network 0.0.2__tar.gz → 0.0.4__tar.gz

{distributed_state_network-0.0.2 → distributed_state_network-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed-state-network
-Version: 0.0.2
+Version: 0.0.4
 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,26 +79,6 @@ 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()
-```
-
 ## Example: Distributed Temperature Monitoring
 
 Create a network of temperature sensors that share readings:
@@ -126,4 +106,13 @@ for node_id in monitor.node.peers():
     if node_id.startswith("sensor_"):
         temp = monitor.node.read_data(node_id, "temperature")
         print(f"{node_id}: {temp}°F")
-```
+```
+  
+### 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.2 → distributed_state_network-0.0.4}/README.md

@@ -54,26 +54,6 @@ 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()
-```
-
 ## Example: Distributed Temperature Monitoring
 
 Create a network of temperature sensors that share readings:
@@ -101,4 +81,13 @@ for node_id in monitor.node.peers():
     if node_id.startswith("sensor_"):
         temp = monitor.node.read_data(node_id, "temperature")
         print(f"{node_id}: {temp}°F")
-```
+```
+  
+### 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.4/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.4/documentation/ds-node-server.md

@@ -0,0 +1,58 @@
+## 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
+- `update_callback` (`Optional[Callable]`): Callback for state update 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.4/documentation/ds-node.md

@@ -0,0 +1,65 @@
+## 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, update_callback=on_update)
+```
+
+**Parameters:**
+- `config` (`DSNodeConfig`): Node configuration
+- `version` (`str`): Protocol version string for compatibility checking
+- `disconnect_callback` (`Optional[Callable]`): Callback function invoked when a peer disconnects
+- `update_callback` (`Optional[Callable]`): Callback function invoked when the state of node updates
+
+### 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.4/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.4/documentation/usage.md

@@ -0,0 +1,84 @@
+## 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)
+```
+
+### With Update Callback
+
+```python
+def handle_update():
+    print("A peer has updated!")
+
+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, update_callback=handle_update)
+```

{distributed_state_network-0.0.2 → distributed_state_network-0.0.4}/pyproject.toml

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

@@ -5,7 +5,7 @@ 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
@@ -29,6 +29,8 @@ class DSNode:
             self, 
             config: DSNodeConfig,
             version: str,
+            disconnect_callback: Optional[Callable] = None,
+            update_callback: Optional[Callable] = None
         ):
         self.config = config
         self.version = version
@@ -48,6 +50,8 @@ class DSNode:
         }
         
         self.logger = logging.getLogger("DSN: " + config.node_id)
+        self.disconnect_cb = disconnect_callback
+        self.update_cb = update_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()
@@ -80,6 +84,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)
@@ -227,6 +233,9 @@ class DSNode:
         if get_dict_hash(self.node_states[pkt.node_id].state_data) != get_dict_hash(pkt.state_data):
             self.node_states[pkt.node_id] = pkt
 
+        if self.update_cb is not None:
+            self.update_cb()
+
         return self.my_state().to_bytes()
 
     def my_state(self):

{distributed_state_network-0.0.2 → distributed_state_network-0.0.4}/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,13 @@ def serve(httpd):
 class DSNodeServer(HTTPServer):
     def __init__(
         self, 
-        config: DSNodeConfig
+        config: DSNodeConfig,
+        disconnect_callback: Optional[Callable] = None,
+        update_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, update_callback)
         self.node.logger.info(f'Started DSNode on port {config.port}')
 
     def stop(self):
@@ -91,8 +91,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, update_callback: Optional[Callable] = None) -> 'NodeServer':
+        n = DSNodeServer(config, disconnect_callback, update_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.2 → distributed_state_network-0.0.4}/tests/connections.py

@@ -2,6 +2,7 @@ import os
 import sys
 import time
 import unittest
+from typing import Optional, Callable
 
 sys.path.append(os.path.join(os.path.dirname(__file__), '../src'))
 
@@ -12,9 +13,11 @@ KEY_FILE = "network.key"
 if not os.path.exists(KEY_FILE):
     DSNodeServer.generate_key("network.key")
 
+cb_test = 0
+
 current_port = 5000
 
-def start_node(node_id: str, bootstrap_port: int = None):
+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,
@@ -30,7 +33,7 @@ def start_node(node_id: str, bootstrap_port: int = None):
     else:
         args["bootstrap_nodes"] = []
 
-    return DSNodeServer.start(DSNodeConfig(**args))
+    return DSNodeServer.start(DSNodeConfig(**args), disconnect_cb, update_cb)
 
 class ConnectionsTest(unittest.TestCase):
     def test_one(self):
@@ -71,5 +74,32 @@ class ConnectionsTest(unittest.TestCase):
         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 cb_test
+        cb_test = 0
+        def inc():
+            global cb_test
+            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(cb_test, 1)
+
+    def test_update_cb(self):
+        global cb_test
+        cb_test = 0
+        def inc():
+            global cb_test
+            cb_test = 1
+        node1 = start_node("node-1", None, None, inc)
+        node2 = start_node("node-2", node1.config.port)
+        
+        node2.node.update_data("key", "value")
+        time.sleep(1)
+
+        self.assertEqual(cb_test, 1)
+
 if __name__ == '__main__':
     unittest.main()