{"id":39584729,"url":"https://github.com/Kayleexx/conflux","last_synced_at":"2026-01-26T15:01:15.191Z","repository":{"id":323902727,"uuid":"1083269937","full_name":"Kayleexx/conflux","owner":"Kayleexx","description":"conflux is a realtime collaboration engine with automatic lifecycle management while using YRS crate and purely written in rust.","archived":false,"fork":false,"pushed_at":"2025-11-12T17:43:52.000Z","size":124,"stargazers_count":50,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-21T12:32:53.348Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kayleexx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-25T17:19:25.000Z","updated_at":"2026-01-19T02:58:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kayleexx/conflux","commit_stats":null,"previous_names":["kayleexx/conflux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Kayleexx/conflux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kayleexx%2Fconflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kayleexx%2Fconflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kayleexx%2Fconflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kayleexx%2Fconflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kayleexx","download_url":"https://codeload.github.com/Kayleexx/conflux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kayleexx%2Fconflux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28781308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T07:35:27.099Z","updated_at":"2026-01-26T15:01:15.186Z","avatar_url":"https://github.com/Kayleexx.png","language":"Rust","readme":"# Conflux\n\nConflux is a modular, actor-based real-time collaboration engine written in Rust.  \nIt provides room-based CRDT synchronization, presence/awareness broadcasting, and text chat — all over WebSockets with JWT authentication.\n\nIt’s designed as the backend core for collaborative editors, shared boards, or multiplayer apps where multiple users edit or interact in real time.\n\n---\n\n## Features\n\n- Room-based collaboration with automatic lifecycle management\n- Real-time document synchronization using [Yrs (Yjs for Rust)](https://github.com/y-crdt/yrs)\n- Awareness broadcasting (cursor, selection, etc.)\n- Chat messages and text communication between clients\n- JWT authentication and per-session tracking\n- Dashboard API to list active rooms and their metrics\n- Automatic cleanup for idle rooms\n- Modular architecture split into `room`, `room_manager`, `auth`, and `server`\n\n---\n\n## Architecture Overview\n\n```\n    ┌────────────────────────────────────────┐\n    │               Client A                 │\n    │ WebSocket → send text / CRDT / cursor  │\n    └────────────────────────────────────────┘\n                 ▲\n                 │ ws://127.0.0.1:8080/ws/:room?token=\u003cJWT\u003e\n                 ▼\n    ┌────────────────────────────────────────┐\n    │               Conflux                  │\n    │ Axum server + Room Manager + CRDT Core │\n    │ ├── auth.rs        → JWT validation    │\n    │ ├── room.rs        → per-room actor    │\n    │ ├── room_manager.rs → cleanup, metrics │\n    │ ├── server.rs      → WebSocket routing │\n    │ └── crdt.rs        → Yrs document API  │\n    └────────────────────────────────────────┘\n```\n\n---\n\n## Project Structure\n\n```\n\nconflux-workspace/\n├── conflux/             # Core backend library\n│   ├── src/\n│   │   ├── auth.rs\n│   │   ├── crdt.rs\n│   │   ├── errors.rs\n│   │   ├── room.rs\n│   │   ├── room_manager.rs\n│   │   ├── server.rs\n│   │   └── lib.rs\n│   └── Cargo.toml\n│\n├── confluxd/            # Binary executable\n│   ├── src/main.rs\n│   └── Cargo.toml\n│\n├── frontend/            # Optional Y.js client (future)\n│   └── index.html\n│\n└── README.md\n\n````\n\n---\n\n## Endpoints\n\n### `POST /login`\n\nAuthenticate and receive a JWT token.\n\n**Request**\n```json\n{ \"username\": \"kaylee\" }\n````\n\n**Response**\n\n```json\n{ \"token\": \"\u003cJWT_TOKEN\u003e\" }\n```\n\nEach login creates a new session with a unique session ID (`sid`).\n\n---\n\n### `GET /dashboard`\n\nReturns all active rooms and their current state.\n\n**Response**\n\n```json\n[\n  {\n    \"document_id\": \"testroom\",\n    \"clients\": 2,\n    \"updates\": 14,\n    \"awareness_events\": 5\n  }\n]\n```\n\n---\n\n### `GET /ws/:document_id?token=\u003cJWT\u003e`\n\nConnect to a collaborative room via WebSocket.\n\n**Example:**\n\n```bash\nwebsocat \"ws://127.0.0.1:8080/ws/testroom?token=\u003cJWT\u003e\"\n```\n\n---\n\n## Sending Messages (Client → Server)\n\nYou can send three kinds of messages to the server:\n\n### 1. Text / Chat\n\n```json\n{ \"type\": \"chat\", \"message\": \"Hello everyone\" }\n```\n\n→ Broadcasts to all clients in the same room:\n\n```json\n{ \"Chat\": { \"document_id\": \"testroom\", \"from\": \"kaylee\", \"message\": \"Hello everyone\" } }\n```\n\n---\n\n### 2. Awareness (Presence)\n\n```json\n{ \"type\": \"awareness\", \"data\": { \"cursor\": 42 } }\n```\n\n→ Notifies all connected clients about your cursor or user state.\n\n---\n\n### 3. CRDT Updates\n\n```json\n{ \"type\": \"update\", \"data\": \"\u003cbase64_encoded_update\u003e\" }\n```\n\n→ The CRDT engine merges the update into the shared document using Yrs.\n\n---\n\n### 4. Sync Request\n\n```json\n{ \"type\": \"sync_request\" }\n```\n\n→ Requests the latest document state from the server if the client missed updates.\n\n---\n\n## Running the Server\n\n```bash\ncargo run -p confluxd\n```\n\nOutput:\n\n```\nINFO confluxd: Conflux server running at ws://127.0.0.1:8080\n```\n\n---\n\n## Example Session\n\n1. Start the server\n\n   ```bash\n   cargo run -p confluxd\n   ```\n\n2. Get a JWT\n\n   ```bash\n   curl -X POST http://127.0.0.1:8080/login \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"username\":\"kaylee\"}'\n   ```\n\n3. Connect with the token\n\n   ```bash\n   websocat \"ws://127.0.0.1:8080/ws/testroom?token=\u003cJWT\u003e\"\n   ```\n\n4. Send messages from the client:\n\n   ```\n   {\"type\": \"chat\", \"message\": \"hi from client 1\"}\n   {\"type\": \"awareness\", \"data\": {\"cursor\": 101}}\n   {\"type\": \"sync_request\"}\n   ```\n\n---\n\n## Security\n\n* JWT tokens expire after 24 hours\n* Each login generates a unique session ID (`sid`)\n* Tokens can be revoked by rotating the `SECRET_KEY`\n* All state is ephemeral (no DB dependency)\n\n---\n\n## License\n\nMIT License\nCopyright (c) 2025 Kaylee\n\n## Demo\n\n\u003cimg width=\"1919\" height=\"864\" alt=\"image\" src=\"https://github.com/user-attachments/assets/77d83bb1-d392-48c7-adca-49943b120382\" /\u003e\n\n\n","funding_links":[],"categories":["\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKayleexx%2Fconflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKayleexx%2Fconflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKayleexx%2Fconflux/lists"}