diff --git a/README.md b/README.md index 23c0b7b..aaa278d 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ Both the official KoalaSync website and the **v2.0 Browser Extension** feature f To build the extension from source and synchronize protocol constants: ```bash npm install -node scripts/build-extension.js +npm run build:extension ``` The compiled artifacts will be available in the `dist/` directory. diff --git a/assets/StoreAssets/StoreDescription.md b/assets/StoreAssets/StoreDescription.md index f25d56d..d2ae400 100644 --- a/assets/StoreAssets/StoreDescription.md +++ b/assets/StoreAssets/StoreDescription.md @@ -40,7 +40,7 @@ KoalaSync is built for private watch parties without unnecessary data collection ⚙️ UNDER THE HOOD KoalaSync is lightweight, transparent, and built with privacy in mind. -• Real-Time Relay: Playback state is synchronized through a custom WebSocket-based relay server for fast room updates. +• On-Demand Relay: Playback state is synchronized through a custom WebSocket-based relay server. No persistent connection — the relay is only active while you're in a room. No background traffic, no idle connections. • No Media Streaming: KoalaSync does not stream, proxy, upload, download, or redistribute any video content. Everyone watches from their own browser on the original website. • Temporary Room State Only: The relay server only coordinates room state such as play, pause, seek position, active target, nickname, and readiness status. • Docker Self-Hosting: The relay server can be self-hosted with Docker if you prefer to run your own private instance. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 589ebc0..8f894cf 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,9 +2,10 @@ This document describes the communication flows and internal logic of the KoalaSync system. -## 1. Extension Startup & Connection -- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`. -- **WebSocket Handshake**: +## 1. Extension Connection (Lazy Connect) +- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`. No WebSocket connection is established at this point. +- **On-Demand Connection**: The extension only connects when needed — either the user opens the popup with saved room credentials, or when actively in a room. When not in a room, no connection exists. This improves privacy (IP not exposed while idle) and reduces battery/network usage. +- **WebSocket Handshake (when connecting)**: 1. Background creates a `new WebSocket` to `/socket.io/?EIO=4&transport=websocket&version=1.0.0`. 2. Server performs security checks: - **IP Rate Limit**: Checks if the IP has exceeded connection limits. @@ -45,7 +46,7 @@ To maintain a clean room state and eliminate "Ghost Peers": - **Video Heartbeat (Content)**: Every 15 seconds, `content.js` sends current playback metadata (time, title, state) if a video is found. - **Server Pruning**: The server runs a "Reaper" every 2 minutes. If a peer has sent **zero** activity (no events and no heartbeats) for 5 minutes, they are forcefully disconnected. - **Immediate Cleanup**: Rooms are deleted instantly when the last peer leaves or disconnects. -- **Reconnect Strategy**: Aggressive backoff — 500ms base, 1.5x multiplier, capped at 5s. Max 20 attempts before marking as failed. Events are queued during disconnect and flushed after namespace rejoin. +- **Reconnect Strategy (while in room)**: Aggressive backoff — 500ms base, 1.5x multiplier, capped at 5s. Max 20 attempts before marking as failed. Events are queued during disconnect and flushed after namespace rejoin. When not in a room, no reconnection occurs. > [!CAUTION] > **Identity Rule**: Differentiate between `peerId` and `socket.id`. Use `socket.id` exclusively for ephemeral transport routing on the server. Use `peerId` exclusively for identity, state management, and room tracking across the stack. @@ -70,5 +71,5 @@ KoalaSync uses a megaphone routing approach to minimize server logic: To maintain a "Single Source of Truth" across the server and extension without using a bundler: - **Relay Server & Extension Modules**: `background.js` and `popup.js` import constants directly from `shared/constants.js`. - **Content Scripts**: To ensure zero-latency execution, `content.js` uses a synchronized copy of `EVENTS` and constants. -- **Automation**: The `node scripts/build-extension.js` script automatically injects these constants into `content.js` during the build process, eliminating the risk of manual mirror mismatch. +- **Automation**: The `npm run build:extension` script automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions into `content.js` during the build process, eliminating the risk of manual mirror mismatch. - **Verification**: Any protocol change is automatically propagated across the stack by running the build script. diff --git a/docs/HOW_IT_WORKS.md b/docs/HOW_IT_WORKS.md index 6fa5bc3..7aec053 100644 --- a/docs/HOW_IT_WORKS.md +++ b/docs/HOW_IT_WORKS.md @@ -16,9 +16,9 @@ This guide walks through the complete user flow of KoalaSync, from creating a ro ## Step 2: Connecting to the Relay Server -When you open the extension popup, the background service worker connects to the relay server: +When you open the extension popup (with saved room credentials) or when a saved room configuration exists from a previous session, the background service worker connects to the relay server: -1. **WebSocket Handshake**: `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket`. +1. **WebSocket Handshake** (on demand): `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket` only when needed (popup opened or active room). 2. **Security Checks** (server-side): - The server checks the client's **IP rate limit** (max 10 connections per 60 seconds). - The server validates the **authentication token** (hardcoded in `shared/constants.js`) to verify this is a legitimate KoalaSync client. @@ -155,7 +155,7 @@ While in a room, two heartbeats keep the session alive: | Heartbeat | Interval | Source | Purpose | |:----------|:---------|:-------|:--------| -| **Background** | 30 seconds | `background.js` | Signals "I'm still connected" and triggers aggressive reconnect (500ms base, max 5s) | +| **Background** | 30 seconds | `background.js` | While connected, signals "I'm still connected" and triggers automatic reconnect (500ms base, max 5s). No heartbeats fire when idle (lazy connect). | | **Content** | 15 seconds | `content.js` | Sends video metadata: `currentTime`, `mediaTitle`, `playbackState`, `volume`, `muted` | - **Server Reaper**: Every 2 minutes, the server checks for peers with no activity for 5+ minutes and disconnects them ("dead peer pruning"). diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md index e8afee1..1d98aad 100644 --- a/docs/PRIVACY.md +++ b/docs/PRIVACY.md @@ -33,7 +33,7 @@ The browser extension requires the following permissions: - `storage`: To remember your local preferences (username, server URL, room settings). - `tabs` & `scripting`: To detect and control video elements on the pages you choose to sync. - `` (host permission): Required to detect `