diff --git a/README.md b/README.md index 8775ee8..61c6c6d 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,141 @@ - - - +
+ +# π» GhostLink + +**High-Performance Serverless P2P Messaging** + +GhostLink is a decentralized chat application engineered for direct peer-to-peer communication. By leveraging UDP hole punching and a custom reliability layer, it eliminates the need for central relay servers, ensuring messages travel the shortest path possible between peers. + +This project prioritizes low-latency networking, asynchronous runtime efficiency, and clean architecture. --- -# π» GhostLink +## πΊοΈ Roadmap & Status + +| Version | Status | Description | +|---------|--------------|---------------------------------------------------------------------------------------------------------------| +| v1.0 | **Stable** | Current release. Feature complete for text exchange and reliable UDP transport. | +| v1.1 | **In Progress** | Security Hardening (QUIC). Replacing the KCP stack with QUIC (via `quinn`) to implement TLS 1.3 End-to-End Encryption. | + +--- + +## βοΈ Architectural Overview + +GhostLink operates by decoupling the Web Interface from the P2P Networking Core, bridging them via shared thread-safe state. + +[](https://mermaid.live/edit#pako:eNqFVFtv2jAU_iuWHyYqESBcSskQUkt3QYOWNUVIW_ZgklNikdiZ7YzSqv99xwnXdWrzdI59vu87t_iZhjIC6lHHcQIRSvHAl14gCDExpOARAdKJmFoFogh4SOQ6jJkyZHyHUTpfLBXLYmt8sUbjZ0CnCjQIwwyXgozZBhSpzEZnAf1lectvDguM7C8GaJCJjPIE-vXFoL9Qg8vHPK3PmcqID-oPqC0ORPQ_QRdphlIYJRMyTZgAUrmPgVwpxsWp5DYqAVUqTzDi6HAn72PiQCYsjDmSfWBp9pEMYyYEJPqEbwJasyUXyy3dziVjueThjg6hhnzl2ki12bJ9liplxmDo26U1kfheMaEzaftdNvIOEs4WPOFmc1qefz-7KTOxVtE7Hu6bes11KLGZmxPMt-G0hKBB5qiZHfpwJLTN-1ZFoN7NuoWMN2DWUq32ObM1GdVv_8lXhiswpfzserr1yR1omatD4n6GGRCfi1XdNwpY-rZ6Gwm_xFKbMSLIpcIpGghNruBEfL-ur4_c10fN10etQw7lNpO-4-z3BPddY-FDmaZMRPqMOM7gaNVK0MHHa6z7dw7akNGUVK6kUnK97UgJtjMtYcV0nRr5nuM0Sc3eFXHHt5YOaxaW7X3pkeCGs4Q_AW6N1vavtaD9QpeYw37bSq82BnQRhqtTBtgdsld22lNmUyoDjtM7FZ5lEbM0Fd__VJ_7ZaXYS1qlS8Uj6hmVQ5WmgP-LdemzZQlo8TQF1EOzeJpoIF4QkzHxQ8p0B1MyX8bUe2CJRi8vtK45w305hOAEQQ1lLgz1Wm5BQb1n-kg9t9eqNc4vXLfTbLVb3U6VbqjnNBu13oXbcbvdntttXzTa3ZcqfSpE3VoDMW6v0eueu63OebtKIeL420_K97V8WunLX189u5E) + +### Communication Flow -**Direct. Simple. Yours.** +[](https://mermaid.live/edit#pako:eNqVVsFu20YQ_ZXpnmxUZEnKsiweXJB2ERupBcK0EaRVUWzIkUSY5LK7yzSq4d5yyye0P5cv6SxJhZIluYkOAld8M_Pe25ldPbJEpMh8pvCPGssELzO-kLyYlUAfXmtR1sU7lO26_a641FmSVbzUEABXcK9Q0tPRq6VQ-uesfDjeBU6Du98bMD0Y7K2oNco9wNiAXgmxyBHiu_vp_lThOlX4QqrwC7lwm1wLnQqNIN4b7oPQh2jJFYLrw3WKpc70Ci4zlZj3KzgyTI43TQis8_PvYx_eLAXwAq5_hKMwK9OsXMCtsVLpDh5bhLQCH96KGrhE8Jyh7diuO7Rdf-Q4DhxF9bs8S-A62qoQfluFsK_gTs7skWu7jmN7_ulOib3qjU0KElGtrIorenUdKSh4WfM8X8H7jLduyPSH-CZ-0UHPhzgr6lzzEkWt4ErQTkZ1mSyJ-nMLg7YyJMTuQcGMXYiyxETPWG9C-AKmReVCVPBTs1PkaKGM3rYexJpr7Izq-gMibPo10BqLSqv-5ZpV06wkA8uUysVvpzMGWkC4jWxQHdpwvIwg4skDamoXmfiGijOAS6V9MJtw_CzaeCezxVKDmENXsR2ORCKRViDrHH0I8lz82WQA67xJ-n-JiMznfz9145FKUSmS3RKbiiYrzIVxYIV6gxUntY014QFrwl7sc2uCXWvC3sgda057a0YHrMlxvimoFbPPmVHnzOl-ZzbzBL0xwTNjbnmC1P40XzoT5QYhEtoumoe9fW_bNgRzOoPgb9fyQKHJo8zP6wDTdXGdJKjUvM7hTnIKVjzvy3xd2x1suW1INzWf__m4tr2xCtPvSKjZfvyQKa02VIZWO4x9bSu4eL2eQr724Ou74GAH7IoJvolpYLXi9jM9vEnt4TT0jfmlqoTUcF_RVZfinjPpihQ3obFoSJG21xfR1pH0EqTPRcBf6eff4Ia2ni-oaWfsCkkivBEyT_tjrq3bYkkPG7CFzFLma1njgBUoC26W7NEEzJheYoEzZtKlXD6YPE8UQ9feL0IU6zAp6sWS-XOeK1rVVUrD013wXyDkGMoLUZea-cNhk4L5j-wD890JXVSnZ6478oYnw_FowFbMtzzHnpy5I3c8nrjjkzPnZPw0YH81RV3boRh34njDoeedjJzxgCENlJA37Z8Mmot5tmBP_wHtB3Ud) -Welcome to **GhostLink**! This is a serverless P2P chat application built with love (and a lot of Rust). It helps you connect directly with a friend without needing big central servers, complicated setups, or port forwarding headaches. It just works! +1. **Initialization**: The application starts the Axum web server and the Tokio UDP listener simultaneously. +2. **Discovery**: The UDP layer queries a STUN server to resolve the machine's Public IP and punch a NAT hole. +3. **Signaling**: The user manually exchanges Public IPs with a peer via the Web UI. +4. **Transport**: Messages are routed from the UI β Shared State β KCP Stream β Peer. --- -## β¨ What is it? +## π Key Technical Features -Imagine two tin cans connected by a string, but digital and engineered for speed. GhostLink lets you establish a direct link with another computer anywhere in the world. +- **True Peer-to-Peer**: Direct client-to-client connections minimize latency and remove dependency on third-party infrastructure. +- **Reliable UDP (ARQ)**: Utilizes KCP (via `tokio_kcp`) to provide TCP-like reliability with the speed advantages of UDP. +- **Automated NAT Traversal**: Integrated STUN client allows for seamless connectivity across different network configurations without manual port forwarding. +- **Asynchronous Core**: Built entirely on the Tokio runtime for non-blocking I/O and high concurrency. +- **Real-Time Updates**: State changes are pushed to the browser immediately via Server-Sent Events (SSE). -* **No Intermediaries:** Your messages go straight to your friend. -* **Serverless:** We use a little magic (called STUN) to find each other, but the chat is all you. -* **Web Interface:** Comes with a clean, dark-mode UI that runs right in your browser. +--- + +## π οΈ Technology Stack + +| Component | Technology | Role | +|---------------|---------------|-----------------------------------------------------| +| Runtime | Tokio | Asynchronous I/O scheduler and task management. | +| Transport | Tokio KCP | Reliable UDP protocol implementation. | +| Web Framework | Axum | HTTP/REST interface and SSE stream handling. | +| State | Arc/RwLock | Thread-safe state synchronization between tasks. | +| Discovery | STUN | Public IP resolution and NAT hole punching. | -## β οΈ A Little Heads-Up (Important!) +--- + +## π Security Notice -While GhostLink is super cool for direct chats, please keep this in mind: +> **WARNING**: *Protocol Status: Cleartext* -**There is NO Encryption.** π +GhostLink v1.0 transmits data in plain text. While the transport layer provides reliability, it does not currently implement end-to-end encryption. -Think of this like passing a note in class or shouting across a playground. It's fast and direct, but it sends data as "plain text." Please **do not** send passwords, credit card numbers, or your deepest secrets over this link just yet. It's strictly for fun, casual chats! +Do not transmit sensitive data (PII, credentials, financial information) over this version. Encryption is slated for the v1.1 release cycle (via QUIC). -## π οΈ Under the Hood (For the Geeks) +--- -We didn't just throw this together; we built it on a robust asynchronous stack. Here is the tech that makes the ghost fly: +## π¦ Installation & Usage -* **Runtime:** Built on **Tokio** for asynchronous, non-blocking I/O, ensuring the app stays responsive even when juggling network packets. -* **Web Framework:** The UI is served by **Axum**, which also handles the REST API and pushes real-time updates to your browser via **Server-Sent Events (SSE)**. -* **Reliability:** We use **KCP** (via `tokio_kcp`) over UDP. This gives us the speed of UDP with the reliability of TCP (ARQ), meaning your messages won't get lost even if the network is a bit shaky. -* **NAT Traversal:** We implement **STUN** (Session Traversal Utilities for NAT) to punch holes through routers, allowing direct P2P connections without manual port forwarding. -* **State Management:** Thread-safe state sharing using `Arc