| Name | distributed-state-network JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | None |
| Summary | A tool to distribute the state of a network device to other devices on the network |
| upload_time | 2025-07-19 15:56:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
distributed
networking
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Distributed State Network
A Python framework for building distributed applications where nodes automatically share state without explicit data requests.
## Why DSN?
Traditional distributed systems require constant polling or complex pub/sub mechanisms to share state between nodes. DSN solves this by providing:
- **Automatic state synchronization** - Changes propagate instantly across the network
- **No single point of failure** - Every node maintains its own state
- **Simple key-value interface** - Read any node's data as easily as local variables
- **Complete Security** - Triple-layer encryption protects your network
Perfect for building distributed monitoring systems, IoT networks, or any application where multiple machines need to share state efficiently.
## Installation
```bash
pip install distributed-state-network
```
## Quick Start
### 1. Create Your First Node
The simplest DSN network is a single node:
```python
from distributed_state_network import DSNodeServer, DSNodeConfig
# Generate a network key (do this once for your entire network)
DSNodeServer.generate_key("network.key")
# Start a node
node = DSNodeServer.start(DSNodeConfig(
node_id="my_first_node",
port=8000,
aes_key_file="network.key",
bootstrap_nodes=[] # Empty for the first node
))
# Write some data
node.node.update_data("status", "online")
node.node.update_data("temperature", "72.5")
```
## How It Works
DSN creates a peer-to-peer network where each node maintains its own state database:
**Key concepts:**
- 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
## 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
Create a network of temperature sensors that share readings:
```python
# On each Raspberry Pi with a sensor:
sensor_node = DSNodeServer.start(DSNodeConfig(
node_id=f"sensor_{location}",
port=8000,
aes_key_file="network.key",
bootstrap_nodes=[{"address": "coordinator.local", "port": 8000}]
))
# Continuously update temperature
while True:
temp = read_temperature_sensor()
sensor_node.node.update_data("temperature", str(temp))
sensor_node.node.update_data("timestamp", str(time.time()))
time.sleep(60)
```
On the monitoring station:
```python
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")
```
## 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "distributed-state-network",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "distributed, networking",
"author": null,
"author_email": "Erin Clemmer <erin.c.clemmer@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/26/2e/4d4d52c971515c5607ff2f962ab5c71148dd61ef1ed17b0772f94714b063/distributed_state_network-0.0.1.tar.gz",
"platform": null,
"description": "# Distributed State Network\n\nA Python framework for building distributed applications where nodes automatically share state without explicit data requests.\n\n## Why DSN?\n\nTraditional distributed systems require constant polling or complex pub/sub mechanisms to share state between nodes. DSN solves this by providing:\n\n- **Automatic state synchronization** - Changes propagate instantly across the network\n- **No single point of failure** - Every node maintains its own state\n- **Simple key-value interface** - Read any node's data as easily as local variables\n- **Complete Security** - Triple-layer encryption protects your network\n\nPerfect for building distributed monitoring systems, IoT networks, or any application where multiple machines need to share state efficiently.\n\n## Installation\n\n```bash\npip install distributed-state-network\n```\n\n## Quick Start\n\n### 1. Create Your First Node\n\nThe simplest DSN network is a single node:\n\n```python\nfrom distributed_state_network import DSNodeServer, DSNodeConfig\n\n# Generate a network key (do this once for your entire network)\nDSNodeServer.generate_key(\"network.key\")\n\n# Start a node\nnode = DSNodeServer.start(DSNodeConfig(\n node_id=\"my_first_node\",\n port=8000,\n aes_key_file=\"network.key\",\n bootstrap_nodes=[] # Empty for the first node\n))\n\n# Write some data\nnode.node.update_data(\"status\", \"online\")\nnode.node.update_data(\"temperature\", \"72.5\")\n```\n\n## How It Works\n\nDSN creates a peer-to-peer network where each node maintains its own state database:\n\n**Key concepts:**\n- Each node owns its state and is the only one who can modify it\n- State changes are automatically broadcast to all connected nodes\n- Any node can read any other node's state instantly\n- All communication is encrypted with AES + ECDSA + HTTPS\n\n## API Reference\n\n### Node Methods\n\n**update_data(key, value)** - Update a key in this node's state\n```python\nnode.update_data(\"sensor_reading\", \"42.0\")\n```\n\n**read_data(node_id, key)** - Read a value from any node's state\n\n```python\ntemperature = node.read_data(\"sensor_node\", \"temperature\")\n```\n\n**peers()** - List all connected nodes\n```python\nconnected_nodes = node.peers()\n```\n\n## Real-World Examples\n\n### Distributed Temperature Monitoring\n\nCreate a network of temperature sensors that share readings:\n\n```python\n# On each Raspberry Pi with a sensor:\nsensor_node = DSNodeServer.start(DSNodeConfig(\n node_id=f\"sensor_{location}\",\n port=8000,\n aes_key_file=\"network.key\",\n bootstrap_nodes=[{\"address\": \"coordinator.local\", \"port\": 8000}]\n))\n\n# Continuously update temperature\nwhile True:\n temp = read_temperature_sensor()\n sensor_node.node.update_data(\"temperature\", str(temp))\n sensor_node.node.update_data(\"timestamp\", str(time.time()))\n time.sleep(60)\n```\n\nOn the monitoring station:\n```python\nfor node_id in monitor.node.peers():\n if node_id.startswith(\"sensor_\"):\n temp = monitor.node.read_data(node_id, \"temperature\")\n print(f\"{node_id}: {temp}\u00b0F\")\n```\n\n## Troubleshooting\n\n### Node Can't Connect\n- Verify the AES key file is identical on all nodes\n- Check firewall rules allow traffic on the configured port\n- Ensure bootstrap node address is reachable\n\n### State Not Updating\n- Confirm nodes show as connected with `node.peers()`\n- Check network latency between nodes\n- Verify no duplicate node IDs (each must be unique)\n\n## Performance Characteristics\n- State updates typically propagate in <100ms on local networks\n- Each node stores the complete state of all other nodes\n- Suitable for networks up to ~100 nodes\n- State values should be kept reasonably small (< 1MB per key)",
"bugtrack_url": null,
"license": null,
"summary": "A tool to distribute the state of a network device to other devices on the network",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/erinclemmer/distributed_state_network",
"Issues": "https://github.com/erinclemmer/distributed_state_network/issues"
},
"split_keywords": [
"distributed",
" networking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7dc85348cb15acd4b44cd46e227980e8159d5ef28d90f72ff9a8adacb9268586",
"md5": "9c8c6a6e5202166b2ac548ef3878a7c6",
"sha256": "bb26fee90e753fcbd410e4643b2f73f28658d17f92e4a2009bfee0d7ac5444e3"
},
"downloads": -1,
"filename": "distributed_state_network-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c8c6a6e5202166b2ac548ef3878a7c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16706,
"upload_time": "2025-07-19T15:56:35",
"upload_time_iso_8601": "2025-07-19T15:56:35.060423Z",
"url": "https://files.pythonhosted.org/packages/7d/c8/5348cb15acd4b44cd46e227980e8159d5ef28d90f72ff9a8adacb9268586/distributed_state_network-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "262e4d4d52c971515c5607ff2f962ab5c71148dd61ef1ed17b0772f94714b063",
"md5": "5d422b27a0e048f473573c71a5249c38",
"sha256": "a191c7c3c23475b34aa2af4e9728eb4272e268df3ded6d77c04e4287d843c6b8"
},
"downloads": -1,
"filename": "distributed_state_network-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5d422b27a0e048f473573c71a5249c38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16915,
"upload_time": "2025-07-19T15:56:36",
"upload_time_iso_8601": "2025-07-19T15:56:36.546560Z",
"url": "https://files.pythonhosted.org/packages/26/2e/4d4d52c971515c5607ff2f962ab5c71148dd61ef1ed17b0772f94714b063/distributed_state_network-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 15:56:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "erinclemmer",
"github_project": "distributed_state_network",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "distributed-state-network"
}
