mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-07 18:03:15 +00:00
Timo
43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# KoalaSync Protocol Synchronization Guide
|
|
|
|
## Why do we need to sync?
|
|
KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the root `shared/` directory. However, Chrome Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
|
|
|
|
To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we maintain a mirrored copy of the shared files within the `extension/shared/` folder.
|
|
|
|
## When should you run the sync script?
|
|
You MUST run the synchronization script in any of the following scenarios:
|
|
1. **After modifying** `shared/constants.js`.
|
|
2. **After modifying** `shared/blacklist.js`.
|
|
3. **Before committing** changes to the repository if any protocol-related files were touched.
|
|
4. **Before deploying** the server or releasing the extension.
|
|
|
|
## How to sync
|
|
|
|
### On Windows
|
|
Run the batch script from the repository root:
|
|
```powershell
|
|
.\scripts\sync-constants.bat
|
|
```
|
|
|
|
### On macOS / Linux
|
|
Run the shell script from the repository root:
|
|
```bash
|
|
./scripts/sync-constants.sh
|
|
```
|
|
|
|
## What does it do?
|
|
The script performs the following actions:
|
|
1. Ensures the `extension/shared/` directory exists.
|
|
2. Copies `shared/constants.js` to `extension/shared/constants.js`.
|
|
3. Copies `shared/blacklist.js` to `extension/shared/blacklist.js`.
|
|
|
|
## Protocol Versioning
|
|
As of v1.0.0-RC5, the system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake.
|
|
- The version is defined in `shared/constants.js`.
|
|
- If the extension and server versions mismatch, the server will reject the connection with an `Incompatible protocol version` error.
|
|
- **Always run the sync script** after bumping the version number to ensure both components are updated.
|
|
|
|
> [!CAUTION]
|
|
> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the sync script is run. Always edit the files in the root `shared/` directory and then run the sync script.
|