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.

New to HSYNC? Start with the HSYNC Ecosystem for an overview of the platform before using the library.

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: As with any data-management software, integrators are strongly advised to validate the library's behavior against their own data and to maintain validated, independent backups in the applications built on top of it.

Quick navigation:

• Want to contribute? See Contributing
• Looking for detailed documentation? Navigate to docs/README.md

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

Associated Ecosystem Components

The other components of the HSYNC ecosystem:

• HSYNC Main — Umbrella repository and project overview.
• HSYNC Server — Central sync hub: REST API, WebSocket relay, file storage.
• HSYNC Client — CLI client: Server Mode and p2p Mode.
• HSYNC Desktop — Desktop GUI front-end. (in development)
• HSYNC Android — Android client app. (in development)
• HSYNC Bootnode — Optional Internet discovery node for P2P (boot/1, no-log, RAM-only).

Security & Vulnerability Reporting

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

👉 Report a vulnerability

See our Security Policy for supported versions and hardening recommendations.

🙋‍♂️ 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.