mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-07-27 04:20:25 +00:00
MacBook
5157428e74
Documentation Rewrites: - AI_INIT.md: fix duplicate section numbers, add file responsibility map, fix stale manual mirror instruction, add room ID constraint - PRIVACY.md: add TL;DR statement, data retention table, explicit <all_urls> justification, self-hosted instance disclaimer - CONTRIBUTING.md: add local testing guide, version warning, room ID constraint, bug report requirements - shared/README.md: complete event table (all 15 events), fix stale manifest.json reference - docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list, drop stale RC5 reference - server/README.md: sync env defaults with .env.example (1000/50) New Documentation: - docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation, invitation bridge flow, synchronized playback, force sync protocol, heartbeat system, and episode auto-sync. Includes exact data payloads. Infrastructure Cleanup: - docker-compose.yml: remove deprecated version key - .dockerignore: remove dead .bat/.sh patterns - README.md: add self-hosting extension config tip, link HOW_IT_WORKS
34 lines
2.0 KiB
Markdown
34 lines
2.0 KiB
Markdown
# KoalaSync Shared Constants
|
|
|
|
This directory contains constants and protocol definitions used by both the extension and the server.
|
|
|
|
## Syncing with the Extension
|
|
> [!IMPORTANT]
|
|
> Every time this directory is modified, you must run `node scripts/build-extension.js` to keep the extension's copy up to date.
|
|
|
|
Because Browser Extensions (Manifest V3) cannot load files outside their root directory, all files in this directory must be copied to `extension/shared/` whenever they are modified. The build script handles this automatically.
|
|
|
|
## Security & Versioning Constants
|
|
- `OFFICIAL_SERVER_TOKEN`: A 32-byte hex token required to connect to the official relay server.
|
|
- `APP_VERSION`: The current version of the extension. Automatically injected from the git tag during CI release builds.
|
|
- `OFFICIAL_SERVER_URL`: The default endpoint for the official KoalaSync relay.
|
|
|
|
## Protocol Events
|
|
For the complete and current event list, see the `EVENTS` object in [`constants.js`](constants.js). Key events include:
|
|
|
|
| Event | Direction | Purpose |
|
|
|:------|:----------|:--------|
|
|
| `JOIN_ROOM` | Client → Server | Request to join a room with credentials |
|
|
| `LEAVE_ROOM` | Client → Server | Leave the current room |
|
|
| `ROOM_DATA` | Server → Client | Current room state (peers list) |
|
|
| `PLAY` / `PAUSE` / `SEEK` | Bidirectional relay | Media control commands |
|
|
| `PEER_STATUS` | Bidirectional relay | Heartbeat or join/leave notification |
|
|
| `FORCE_SYNC_PREPARE` | Bidirectional relay | Phase 1: Pause & seek to target time |
|
|
| `FORCE_SYNC_ACK` | Bidirectional relay | Phase 1 confirmation: peer is buffered |
|
|
| `FORCE_SYNC_EXECUTE` | Bidirectional relay | Phase 2: Resume playback simultaneously |
|
|
| `EVENT_ACK` | Server → Client | Delivery confirmation for UI feedback |
|
|
| `EPISODE_LOBBY` | Bidirectional relay | Episode transition: waiting for all peers |
|
|
| `EPISODE_READY` | Bidirectional relay | Episode confirmation: peer has loaded |
|
|
| `GET_ROOMS` / `ROOM_LIST` | Client ↔ Server | Room discovery |
|
|
| `ERROR` | Server → Client | Error message |
|