KoalaSync/SYNC_GUIDE.md

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 a fresh git clone or git pull (as the synced files are ignored by git).
2. After modifying shared/constants.js.
3. After modifying shared/blacklist.js.
4. Before committing changes to the repository if any protocol-related files were touched.
5. Before deploying the server or releasing the extension.

How to sync

On Windows

Run the batch script from the repository root:

.\scripts\sync-constants.bat

On macOS / Linux

Run the shell script from the repository root:

./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.