Metadata-Version: 2.4
Name: neon-rings
Version: 0.1.1
Summary: A lightweight P2P transport layer adapted for the Red-Pill ecosystem
Author-email: "Joan F. Garcia" <joan@example.com>
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=41.0.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: aiohttp>=3.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Neon-Rings

A purely Python, lightweight, P2P WebSocket-based transport layer and SQLite-backed DHT for the Red-Pill ecosystem.

---

## 1. CLI Usage

### 1.1 Server (Bootstrap Node)
Run the bootstrap server with an in-memory SQLite database (for testing) or a file for persistence:

```bash
neon-rings-server --host 0.0.0.0 --port 50000 --db node.db
```

### 1.2 Client CLI
You can test the server from the command line:

```bash
neon-rings-client --endpoint ws://127.0.0.1:50000 info
neon-rings-client put --key "greeting" --value "Hello Swarm!"
neon-rings-client get --key "greeting"
```

---

## 2. Programmatic Python SDK Usage

Below is a complete example demonstrating how to integrate `RingsClient` programmatically.

```python
import asyncio
from neon_rings.client import RingsClient
from neon_rings.crypto import KeyPair

async def main():
	# 1. Instantiate and connect client
	async with RingsClient("ws://127.0.0.1:50000") as client:
		# 2. Register node unique identifier
		await client.register("node-alpha-01")

		# 3. Define callback to handle incoming messages
		async def on_message(sender_id: str, payload: any):
			print(f"📩 Received message from {sender_id}: {payload}")

		client.set_message_handler(on_message)

		# 4. Perform SQLite-backed DHT operations (signed cryptographically)
		kp = KeyPair.generate()
		await client.dht_put(kp, "secure_payload_data")
		
		# Retrieve the value using the public key hex
		value = await client.dht_get(kp.public_key_hex)
		print(f"🔑 DHT Value retrieved: {value}")

		# 5. Route a message to a specific registered node
		await client.send_message(
			target_id="node-beta-02",
			payload={"event": "sync_request", "data": {"version": "0.1.1"}}
		)

		# Keep the listen loop alive
		await asyncio.sleep(2)

if __name__ == "__main__":
	asyncio.run(main())
```

---

## 3. System Architecture & Message Flow

The sequence below illustrates how nodes register on the `neon-rings` hub and exchange payloads or interact with the DHT:

```mermaid
sequenceDiagram
    autonumber
    participant A as Agent A (Client)
    participant H as Neon-Rings Hub (Server)
    participant B as Agent B (Client)

    A->>H: JSON-RPC {"method": "register", "params": {"node_id": "agent-a"}}
    H-->>A: {"result": {"ok": true, "node_id": "agent-a"}}
    B->>H: JSON-RPC {"method": "register", "params": {"node_id": "agent-b"}}
    H-->>B: {"result": {"ok": true, "node_id": "agent-b"}}

    Note over A,B: Direct Routing (P2P-over-WebSocket)
    A->>H: {"method": "send_message", "params": {"target_id": "agent-b", "payload": "..."}}
    H->>B: Push Event {"method": "message_receive", "params": {"sender_id": "agent-a", "payload": "..."}}
    H-->>A: {"result": {"ok": true, "delivered": true}}
```

---

## 4. JSON-RPC 2.0 Protocol Specification

`neon-rings` communicates over WebSockets using JSON-RPC 2.0. Clients can implement this specification in any language.

### 4.1 `register`
Registers a unique node identifier with the server.

*   **Request:**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "register",
      "params": {
        "node_id": "client-node-01"
      },
      "id": 1
    }
    ```
*   **Response:**
    ```json
    {
      "jsonrpc": "2.0",
      "result": {
        "ok": true,
        "node_id": "client-node-01"
      },
      "id": 1
    }
    ```

### 4.2 `send_message`
Routes a payload to another connected node or broadcasts it to all other registered connections.

*   **Request (Direct Message):**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "send_message",
      "params": {
        "target_id": "client-node-02",
        "payload": {
          "type": "heartbeat",
          "status": "active"
        }
      },
      "id": 2
    }
    ```
*   **Response (Successful delivery):**
    ```json
    {
      "jsonrpc": "2.0",
      "result": {
        "ok": true,
        "delivered": true
      },
      "id": 2
    }
    ```
*   **Response (Target offline):**
    ```json
    {
      "jsonrpc": "2.0",
      "result": {
        "ok": true,
        "delivered": false,
        "reason": "Node offline"
      },
      "id": 2
    }
    ```
*   **Request (Broadcast):**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "send_message",
      "params": {
        "target_id": "broadcast",
        "payload": {
          "message": "Global swarm alert"
        }
      },
      "id": 3
    }
    ```
*   **Response (Broadcast):**
    ```json
    {
      "jsonrpc": "2.0",
      "result": {
        "ok": true,
        "delivered": true,
        "broadcast_count": 3
      },
      "id": 3
    }
    ```

### 4.3 `message_receive` (Server-to-Client Notification)
Pushes a message sent via `send_message` to the target client.

*   **Event Notification:**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "message_receive",
      "params": {
        "sender_id": "client-node-01",
        "payload": {
          "type": "heartbeat",
          "status": "active"
        },
        "ts": 1716654890.123
      }
    }
    ```

### 4.4 `dht_put`
Stores a cryptographically signed key-value pair in the SQLite-backed DHT. The key must be the hexadecimal representation of the public key verifying the signature.

*   **Request:**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "dht_put",
      "params": {
        "key": "025cf26d9c...",
        "value": "payload_content",
        "signature": "30440220..."
      },
      "id": 4
    }
    ```
*   **Response:**
    ```json
    {
      "jsonrpc": "2.0",
      "result": {
        "ok": true
      },
      "id": 4
    }
    ```

### 4.5 `dht_get`
Retrieves the stored value for a given public key hex.

*   **Request:**
    ```json
    {
      "jsonrpc": "2.0",
      "method": "dht_get",
      "params": {
        "key": "025cf26d9c..."
      },
      "id": 5
    }
    ```
*   **Response:**
    ```json
    {
      "jsonrpc": "2.0",
      "result": "payload_content",
      "id": 5
    }
    ```

---

## 5. High Availability & Scaling
`neon-rings` supports horizontal scale-out architectures via **LiteFS** for SQLite replication or node-to-node **Federation**. 

See [docs/HIGH_AVAILABILITY.md](docs/HIGH_AVAILABILITY.md) for architectural and deployment details.

---

## 6. Security & Encryption
**Important**: `neon-rings` is **100% payload-agnostic**. It is designed to run quickly without decrypting client payloads. In the Red-Pill architecture, `pure-mls` or `openmls` is used to encrypt payloads *before* they are transmitted via `neon-rings`.

---

## 7. Development & Conventions
This repository is co-authored by Biological and Artificial agents under the [docs/CORE/PROTOCOL_OF_SILENCE.md](docs/CORE/PROTOCOL_OF_SILENCE.md) and [CONVENTIONS.md](CONVENTIONS.md). 
- All python code must use **tabs only** for indentation.
- Double-blank lines and ornamental comments are forbidden.
- Code coverage is enforced by CI to be at or above **96%**.
