minisync

個人利用を想定した小規模ファイル同期ツール

minisyncは、PC間でファイルを手動同期するための軽量ツールです。Gitで管理するほどではない雑多なファイルを、明示的に制御しながら安全に共有できます。

特徴

• 手動同期: 自動同期ではなく、PUSHとPULLを明示的に指定
• マルチspace対応: 複数のプロジェクトを1つのサーバーで管理
• 安全装置: 上書き前に自動スナップショット（.minisync.bak）
• トークン認証: 簡易的なトークンベース認証
• LAN内自動検出: UDP broadcastで同一ネットワーク内のspaceを発見
• バイナリ安全: あらゆる種類のファイルを転送可能

インストール

クイックインストール（推奨）

ワンライナーで自動インストール：

curl -fsSL https://raw.githubusercontent.com/K16858/minisync/main/install.sh | bash

これにより最新リリースのバイナリが~/.local/binにインストールされます。

ソースからビルド

git clone https://github.com/K16858/minisync.git
cd minisync/src
make
make install

make installは~/.local/bin/msyncと~/.local/bin/msync-serverにインストールします。

手動インストール

1. Releasesから最新版をダウンロード
2. バイナリに実行権限を付与：chmod +x msync msync-server
3. PATHの通った場所に配置：mv msync msync-server ~/.local/bin/

使い方

1. 初期化

プロジェクトディレクトリで初期化：

cd /path/to/your/project
msync init my-project

これにより：

• .msync/ディレクトリが作成される
• ~/.config/minisync/config.jsonにspaceとして登録される
• 一意のID、認証トークン、space名が生成される

2. サーバー起動

どこかのマシンでサーバーを起動：

msync-server

サーバーは：

• ポート61001でTCP接続を待ち受け
• ポート61002でUDP discover要求に応答
• 登録されている全てのspaceを提供

3. 他のspaceを検出

LAN内の他のspaceを検出：

msync discover

出力例：

#  ID                               NAME            HOSTNAME        IP              PORT
0  e82d4697cf26f4c82092b34a8587743c space-alpha     laptop         192.168.1.100   61001
1  c23234a0d00afb89ddfba000b9c0e0f0 space-beta      desktop        192.168.1.101   61001

4. 接続先を保存

検出したspaceに接続：

msync connect 0
# または
msync connect e82d4697cf26f4c82092b34a8587743c

5. ファイル同期

PUSH（ローカル → リモート）:

msync push myfile.txt

PULL（リモート → ローカル）:

msync pull myfile.txt

接続先を明示的に指定する場合：

msync push myfile.txt --host 192.168.1.100 --port 61001

トークンを明示的に指定する場合：

msync push myfile.txt --host 192.168.1.100 --port 61001 --token a59f2921c9b101499d001ac005dad7bc

上書き確認をスキップする場合：

msync pull myfile.txt --yes

認証の仕組み

minisyncは簡易的なトークンベース認証を使用します。

トークンの生成と保存

msync initを実行すると：

1. 32文字のランダムなトークンが自動生成される
2. .msync/config.jsonに保存される
3. 同じspaceを持つ全てのマシンが同じトークンを共有する

認証フロー

1. クライアントがサーバーに接続
2. クライアントが自分のspace IDを送信（HELLO）
3. サーバーがspace IDで該当spaceを特定
4. クライアントがトークンを送信（TOKEN）
5. サーバーが該当spaceの.msync/config.jsonからトークンを読み込んで照合
6. トークンが一致すれば認証成功、不一致ならエラー

セキュリティ上の注意

• トークンは平文で保存される - ファイルシステムのアクセス権限で保護
• 通信は暗号化されない - LAN内での使用を想定
• インターネット経由での使用は非推奨 - VPN越しの使用を推奨

同じspaceを複数マシンで使用する場合、.msync/config.jsonを安全にコピーしてください。

アーキテクチャ

ディレクトリ構造

~/.local/bin/
  ├── msync              # クライアント実行ファイル
  └── msync-server       # サーバー実行ファイル

~/.config/minisync/
  └── config.json        # グローバル設定（全spaceの一覧）

/path/to/project/.msync/
  ├── config.json        # space固有設定（ID, token, name）
  └── targets.json       # 接続先リスト

マルチspace対応

1つのサーバープロセスで複数のspaceを扱います：

• クライアントは接続時に自分のspace IDを送信
• サーバーはspace IDで該当spaceを検索
• 該当spaceのディレクトリに切り替えて処理
• 各spaceのトークンで認証

これにより：

• 全space共通でポート61001を使用（ファイアウォール設定が簡単）
• 1つのサーバーで複数プロジェクトを管理
• 各spaceは完全に独立

プロトコル

minisyncは独自のバイナリプロトコルを使用：

1. HELLO: クライアントがspace IDを送信
2. HELLO_ACK: サーバーが応答
3. TOKEN: クライアントが認証トークンを送信
4. PUSH_FILE / PULL_FILE: ファイル操作要求
5. META: ファイルサイズなどのメタデータ
6. DATA: 実際のファイルデータ（4KBチャンク）
7. DONE: 操作完了
8. ERROR: エラー通知

設定ファイル

グローバル設定 (~/.config/minisync/config.json)

{
  "spaces": [
    {
      "id": "e82d4697cf26f4c82092b34a8587743c",
      "name": "my-project",
      "path": "/home/user/projects/my-project"
    }
  ]
}

Space設定 (.msync/config.json)

{
  "id": "e82d4697cf26f4c82092b34a8587743c",
  "name": "my-project",
  "hostname": "laptop",
  "token": "a59f2921c9b101499d001ac005dad7bc",
  "port": 61001
}

現在の制限事項

• ディレクトリ同期: 未対応（単一ファイルのみ）
• 差分転送: 未対応（全体転送のみ）
• ハッシュ検証: 未対応（サイズチェックのみ）
• 中断/再開: 未対応
• 暗号化: 未対応（LAN内での使用を想定）

今後の予定

• SHA-256によるファイル整合性検証
• ブロック単位の差分転送
• ディレクトリ全体の同期
• .minisyncignoreによるファイル除外
• 中断/再開機能
• 進捗表示の改善

ライセンス

MIT License

貢献

Issue、Pull Requestを歓迎します。

注意事項

• このツールはLAN内での使用を想定しています
• インターネット経由での使用は推奨しません（暗号化未対応）
• 重要なファイルは必ずバックアップを取ってください
• 本番環境での使用前に十分なテストを行ってください