HSYNC Common Library

hsync-common is the shared foundation that all other HSYNC projects build upon — data formats, compression, file exclusion rules, and security utilities. You don't install or run it directly; it's a library used by the client, server and desktop application.

It is also the single source of truth for the open, versioned wire protocol: the shared models, JSON-Schema builders and committed fixtures live here (hsync_common.protocol, docs/protocol.md, docs/p2p-protocol.md), so every implementation speaks the same contract. The library sends no telemetry or analytics anywhere.

👉 Operational Advisory: integrators are strongly advised to validate the library's behavior against their own data before relying on it in production.

Key modules

Benchmarks

Hot-path micro-benchmarks live in bench/ — L1 only (pure in-process measurement), because the library has no process or transport of its own. Five scripts cover hashing, compression, delta transfer, .hsyncignore matching and model serialization; each accepts --count N and --json-out FILE.

cd hsync-common && .venv/bin/python bench/bench_hashing.py --count 2000

See bench/README.md for the scope of each script, the shared helpers and the measurement methodology.

Documentation

The most-used guides are listed below; docs/README.md is the complete documentation index.

Associated Ecosystem Components

The other components of the HSYNC ecosystem:

• HSYNC Main — Umbrella repository and project overview.
• HSYNC Desktop — Desktop GUI front-end.
• HSYNC Client — Reference client agent: the hsync CLI and its sync engine.
• HSYNC Server — Central sync hub: REST API, WebSocket relay, file storage.
• HSYNC Rendezvous — Optional Internet rendezvous node for P2P (rdv/1, no-log, RAM-only).
• HSYNC Android — Android client app. (in development)

Security & Vulnerability Reporting

To report a vulnerability, please use GitHub's Private Vulnerability Reporting:

👉 Report a vulnerability

🙋‍♂️ A note from the maintainer

This project was born out of the need for a system capable of replicating the contents of a folder from a PC or Android device to a NAS, primarily for backup purposes. Several solutions were already available, but I couldn't find one that met all my requirements. This led to the somewhat questionable decision to develop one from scratch, while also providing an opportunity to gain a deeper understanding of programming languages, algorithms, frameworks, and related technologies.

Originally conceived as a hobby project, HSYNC has been under continuous development ever since. I believe it has now evolved to the point where its capabilities are comparable to those of commercial solutions, while also offering some distinctive features. As a result, it may also be suitable for deployment in certain production environments.

HSYNC is a passion project that I primarily develop and maintain in my spare time. Please keep this in mind when interacting with the project: we're all doing our best to build something great together, but this is not a paid, full-time job for any of us.

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. Although the author has implemented reasonable safety measures, IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY — including, without limitation, any direct, indirect, incidental, special, exemplary, or consequential damages, loss of data, or business interruption — WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This disclaimer supplements, and does not replace, the warranty disclaimer and limitation of liability provisions of the BSD 3-Clause License, which govern this software.

License

Distributed under the BSD 3-Clause License.