mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-07-26 12:08:15 +00:00

Files

T

Timo e7b59d61ac docs: update all docs for lazy-connect, refactor, and .cjs rename

- ARCHITECTURE.md: startup -> lazy connect, reconnect when in room
- HOW_IT_WORKS.md: on-demand connection, heartbeat while connected
- PRIVACY.md: clarify alarms only during active sessions
- SYNC_GUIDE.md: build-extension.cjs + episode-utils injection
- StoreDescription.md: on-demand relay, no persistent connection
- README.md + extension/README.md: npm run build:extension
- extension/README.md: replace Dual Heartbeat with On-Demand Connection
- website/privacy.html: add lazy-connect privacy note

2026-06-16 14:17:19 +02:00

2.4 KiB

Raw Blame History

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, Browser 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 build script?

You MUST run the build script in any of the following scenarios:

After a fresh git clone or git pull (as the synced files are ignored by git).
After modifying shared/constants.js.
After modifying shared/blacklist.js.
Before committing changes to the repository if any protocol-related files were touched.
Before deploying the server or releasing the extension.

How to sync

Run the Node.js build script from the repository root:

node scripts/build-extension.cjs
# or simply:
npm run build:extension

What does it do?

The build script performs the following actions:

Synchronizes protocol constants by copying shared/constants.js, shared/blacklist.js, and shared/README.md into extension/shared/.
Injects EVENTS, HEARTBEAT_INTERVAL, and episode-utils.js functions (extractEpisodeId, sameEpisode) into content.js via marker-based replacement.
Compiles browser-specific manifest files.
Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the dist/ directory.

Protocol Versioning

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.
Never manually bump version numbers. The CI pipeline automatically injects the version from the git tag into manifest.base.json, shared/constants.js, and package.json during release builds. Run the build script to synchronize other constant updates.

Caution

NEVER edit the files inside extension/shared/ directly. They will be overwritten the next time the build script is run. Always edit the files in the root shared/ directory and then run the build script.

2.4 KiB Raw Blame History