# tinysync

**Repository Path**: uchenily/tinysync

## Basic Information

- **Project Name**: tinysync
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tinysync

tinysync is a Linux-only encrypted UDP peer-to-peer file sync prototype.

It implements:

- UDP rendezvous registration and NAT hole-punch probes
- Peer heartbeats
- Quiet rendezvous behavior after direct P2P connectivity is established
- Shared-secret authentication with encrypted packets
- AES-GCM encryption for all network messages
- Recursive Linux `inotify` file monitoring
- Last-writer-wins conflict handling by file mtime
- File manifests, block hashes, block requests, chunk transfer, and atomic reassembly
- Structured logs

## Build

```sh
go build ./cmd/tinysync
```

## Run a rendezvous server

The rendezvous server only coordinates peer discovery. It does not see plaintext.

```sh
./tinysync rendezvous --listen :9000 --secret shared-passphrase
```

## Run peers

Run this on two Linux machines, using the same `room` and `secret`.

```sh
./tinysync peer --dir ./sync-a --listen :10001 --server SERVER_IP:9000 --room demo --secret shared-passphrase
./tinysync peer --dir ./sync-b --listen :10002 --server SERVER_IP:9000 --room demo --secret shared-passphrase
```

Files created or modified under either directory are announced by manifest. The receiver compares mtimes and block hashes, requests missing blocks, writes a temporary file, then atomically renames it into place.

After peers have discovered each other and direct P2P traffic is flowing, peers stop periodically registering with the rendezvous server. They keep peer-to-peer heartbeats for liveness. If all active peers time out, the peer resumes rendezvous registration to rediscover the room.

## Management UI

The `frontend` directory contains a Deno + React management console. It is not only a command builder: the Deno server starts and stops managed `tinysync` child processes, captures logs, exposes status, and derives basic runtime statistics. The UI supports one rendezvous service and multiple peer instances. It starts with `Peer A` and `Peer B`, and you can add more peers from the sidebar.

Build the CLI binary and frontend:

```sh
go build -o tinysync ./cmd/tinysync
cd frontend
deno task build
```

Start the local management service:

```sh
deno task serve
```

Open:

```text
http://127.0.0.1:8080/
```

Environment variables:

- `TINYSYNC_BIN`: path to the `tinysync` binary, defaults to `../tinysync` from the frontend server.
- `TINYSYNC_UI_HOST`: bind host, defaults to `127.0.0.1`.
- `TINYSYNC_UI_PORT`: bind port, defaults to `8080`.

The management API is served under `/api/status`, `/api/services/{peer|rendezvous}/start`, `/api/services/{peer|rendezvous}/stop`, and `/api/stats/reset`.

For a pure-UI local sync test:

1. Open the management UI.
2. Select `Rendezvous`, keep `127.0.0.1:19000` and `test-secret`, then click `Start`.
3. Select `Peer A`, keep `/tmp/tinysync-a`, `127.0.0.1:19001`, server `127.0.0.1:19000`, room `demo`, secret `test-secret`, node `a`, then click `Start`.
4. Select `Peer B`, keep `/tmp/tinysync-b`, `127.0.0.1:19002`, server `127.0.0.1:19000`, room `demo`, secret `test-secret`, node `b`, then click `Start`.
5. Watch `Live Logs` for `peer reachable`; `Reachable Peers` should increase.
6. Create or edit files in `/tmp/tinysync-a` or `/tmp/tinysync-b` with your file manager or terminal. The UI will show `local change`, `requesting blocks`, and `assembled file` as sync happens.

## Notes

This is intentionally dependency-free and uses only the Go standard library. It is suitable as a clear starting implementation, not as a hardened production sync system. UDP delivery is handled by repeated manifests, requests, and block sends; very large deployments would need a stronger reliability/windowing layer.