Skip to content

Commit 197e53f

Browse files
hyperpolymathhyperpolymath
committed
Add sponsor badge
1 parent 621ff9b commit 197e53f

1 file changed

Lines changed: 295 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath)
2+
3+
image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"]
4+
image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]
5+
6+
7+
// SPDX-License-Identifier: MPL-2.0-or-later
8+
= Cloud Sync Tuner
9+
10+
11+
12+
:toc:
13+
:icons: font
14+
15+
image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR Bronze,link=https://github.com/hyperpolymath/rhodium-standard-repositories]
16+
17+
== License & Philosophy
18+
19+
This project must declare **MPL-2.0-or-later** for platform/tooling compatibility.
20+
21+
Philosophy: **Palimpsest**. The Palimpsest-MPL (PMPL) text is provided in `license/PMPL-1.0.txt`, and the canonical source is the palimpsest-license repository.
22+
23+
Ada TUI for managing rclone cloud mount configurations with rate limiting, SDP (Software-Defined Perimeter) security, and Zig FFI integration.
24+
25+
== Problem
26+
27+
Cloud providers (especially Dropbox) enforce strict API rate limits. Default rclone settings trigger:
28+
29+
[source]
30+
----
31+
Error too_many_requests/. Too many requests. Trying again in 300 seconds.
32+
----
33+
34+
== Solution
35+
36+
Configure optimal VFS cache modes and rate limiting via TUI or CLI, wrapped in a zero-trust SDP architecture with post-quantum identity management.
37+
38+
== Cache Modes
39+
40+
[cols="1,1,1,1"]
41+
|===
42+
|Mode |API Usage |Disk Use |Best For
43+
44+
|Off |🔴 Very High |None |Read-only browsing
45+
|Minimal |🟠 High |Low |Light usage
46+
|**Writes** |🟢 Low |Medium |**Daily use (default)**
47+
|Full |🔴 Very High |High |Offline-first
48+
|===
49+
50+
== Quick Start
51+
52+
[source,bash]
53+
----
54+
# Build
55+
gprbuild -P cloud_sync_tuner.gpr
56+
57+
# Run TUI
58+
./bin/cloud_sync_tuner
59+
60+
# Or CLI mode
61+
./bin/cloud_sync_tuner writes
62+
----
63+
64+
== Container (nerdctl + Wolfi)
65+
66+
[source,bash]
67+
----
68+
# Build
69+
nerdctl build -t cloud-sync-tuner .
70+
71+
# Run interactive
72+
nerdctl run -it --rm cloud-sync-tuner
73+
74+
# With compose (includes optional aria2)
75+
nerdctl compose up
76+
nerdctl compose --profile accelerated up # with aria2
77+
nerdctl compose --profile vpn up # with WireGuard SDP
78+
----
79+
80+
== SDP (Software-Defined Perimeter)
81+
82+
Cloud Sync Tuner supports zero-trust network architecture:
83+
84+
[source]
85+
----
86+
┌─────────────────────────────────────────────────────────────────┐
87+
│ Host System │
88+
├─────────────────────────────────────────────────────────────────┤
89+
│ ┌─────────────────────┐ ┌─────────────────────────────────┐ │
90+
│ │ cicada container │ │ cloud-sync container │ │
91+
│ │ (network: none) │ │ (network: vpn-only) │ │
92+
│ │ │ │ │ │
93+
│ │ Post-quantum │◄───┤ WireGuard + rclone + FUSE │ │
94+
│ │ identity/keys │ │ │ │
95+
│ └─────────────────────┘ └─────────────────────────────────┘ │
96+
│ │ Unix socket only │
97+
│ └──────────────────────────────────────────────────── │
98+
└─────────────────────────────────────────────────────────────────┘
99+
----
100+
101+
Key features:
102+
103+
* **cicada integration** - Post-quantum cryptographic identity (Kyber768 + x25519 hybrid)
104+
* **Network isolation** - cicada container has `network_mode: none`
105+
* **Unix socket IPC** - Key material never touches network interfaces
106+
* **WireGuard VPN** - Encrypted tunnel before any cloud access
107+
108+
See link:sdp/CICADA-ISOLATION.adoc[Cicada Isolation Architecture] for details.
109+
110+
== Zig FFI Libraries
111+
112+
Cloud Sync Tuner integrates with Zig FFI bindings for cross-platform support:
113+
114+
[cols="1,2,1"]
115+
|===
116+
|Library |Purpose |Repo
117+
118+
|**zig-wireguard**
119+
|VPN tunnel management via libwireguard
120+
|https://github.com/hyperpolymath/zig-wireguard[zig-wireguard]
121+
122+
|**zig-rclone**
123+
|Cloud storage via librclone (40+ backends)
124+
|https://github.com/hyperpolymath/zig-rclone[zig-rclone]
125+
126+
|**zig-fuse-ext**
127+
|Extended FUSE with rate limiting/caching
128+
|https://github.com/hyperpolymath/zig-fuse-ext[zig-fuse-ext]
129+
|===
130+
131+
=== Why Zig FFI?
132+
133+
[cols="1,2"]
134+
|===
135+
|Feature |Benefit
136+
137+
|`@cImport` |Direct C header import, no manual bindings
138+
|Cross-compilation |Single build for Linux, macOS, FreeBSD, Windows
139+
|No hidden malloc |Explicit memory, allocator control
140+
|Error unions |Convert C error codes to Zig errors
141+
|===
142+
143+
== Acceleration Options
144+
145+
=== aria2 Integration
146+
147+
aria2 provides significant download acceleration through:
148+
149+
* **Multi-connection downloads** - 16 connections per file
150+
* **Segmented downloading** - splits files for parallel fetch
151+
* **Resume support** - continues interrupted transfers
152+
* **RPC interface** - programmatic control
153+
154+
Enhancement potential: **3-10x faster downloads** for large files.
155+
156+
[source,bash]
157+
----
158+
# Enable in compose
159+
nerdctl compose --profile accelerated up
160+
161+
# aria2 RPC available at localhost:6800
162+
----
163+
164+
=== pssh (Parallel SSH)
165+
166+
For multi-host scenarios (syncing to multiple servers):
167+
168+
* **Parallel execution** - run commands across hosts simultaneously
169+
* **Batch operations** - deploy service files to multiple machines
170+
* **Centralized management** - single point of control
171+
172+
Enhancement potential: **Linear speedup** with host count for deployment.
173+
174+
[source,bash]
175+
----
176+
# Deploy to multiple hosts
177+
pssh -h hosts.txt -i 'systemctl --user restart rclone-dropbox'
178+
179+
# Copy generated configs
180+
pscp -h hosts.txt output/*.service ~/.config/systemd/user/
181+
----
182+
183+
== Architecture
184+
185+
[source]
186+
----
187+
┌─────────────────────────────────────────────────────────────┐
188+
│ Cloud Sync Tuner │
189+
│ (Ada TUI) │
190+
└────────────────────────┬────────────────────────────────────┘
191+
│
192+
┌───────────────┼───────────────┐
193+
│ │ │
194+
▼ ▼ ▼
195+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
196+
│ zig-rclone │ │zig-wireguard│ │zig-fuse-ext │
197+
│ (storage) │ │ (VPN) │ │ (mount) │
198+
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
199+
│ │ │
200+
▼ ▼ ▼
201+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
202+
│ librclone │ │libwireguard │ │ libfuse3 │
203+
│ (Go→C) │ │ (C) │ │ (C) │
204+
└─────────────┘ └─────────────┘ └─────────────┘
205+
----
206+
207+
== Laminar Integration
208+
209+
This tool complements https://github.com/hyperpolymath/laminar[laminar] for cloud-to-cloud transfers:
210+
211+
* Laminar handles streaming transfers between clouds
212+
* Cloud Sync Tuner manages local mount configurations
213+
* Both use rclone as the data plane
214+
* zig-rclone enables embedded transfers without subprocess overhead
215+
216+
== Supported Services
217+
218+
* Dropbox (`dropbox:`)
219+
* Google Drive (`gdrive:`)
220+
* OneDrive (`onedrive:`)
221+
* 40+ additional backends via librclone
222+
223+
== Platform Support
224+
225+
[cols="1,1,1,1,1,1"]
226+
|===
227+
|Platform |i386 |amd64 |ARM |RISC-V |Notes
228+
229+
|Linux |✓ |✓ |✓ |✓ |Full support
230+
|macOS |- |✓ |✓ |- |macFUSE required
231+
|FreeBSD |- |✓ |- |- |fusefs-libs
232+
|Windows |- |✓ |- |- |No FUSE, remote ops only
233+
|Minix |✓ |✓ |- |- |libcurl fallback
234+
|Android |- |✓ |✓ |- |No mounts, remote ops only
235+
|===
236+
237+
== v1.0 Features
238+
239+
=== Smart Sync
240+
241+
[cols="1,2"]
242+
|===
243+
|Feature |Description
244+
245+
|Cache size limits |Auto-evict old files when cache exceeds threshold
246+
|Min free space |Emergency eviction when disk runs low
247+
|Write-back buffering |Buffer writes locally before uploading
248+
|Pinned folders |Mark folders for offline access (like native clients)
249+
|Bandwidth scheduling |Time-based bandwidth limits
250+
|Conflict resolution |Configurable strategy (newer/older/larger/path1)
251+
|===
252+
253+
=== Desktop Integration
254+
255+
* **System tray daemon** (`cloud-sync-tray`) - Real-time sync status icon
256+
* **Nautilus extension** - Sync status emblems in GNOME Files
257+
* **Dolphin service menu** - Context menu actions in KDE
258+
* **Desktop notifications** - Alerts for sync events
259+
260+
=== Enterprise Features
261+
262+
* **SELinux policy** - Confined `rclone_t` domain
263+
* **Auditd rules** - File access logging for compliance
264+
* **Health check** - `cloud-sync-status` command for monitoring
265+
* **Watchdog timer** - Automatic service recovery
266+
267+
=== Just Recipes
268+
269+
[source,bash]
270+
----
271+
just cookbook-dropbox-fix # Fix Dropbox rate limiting
272+
just cookbook-offline-setup # Setup offline folders
273+
just cookbook-max-performance # Maximum caching
274+
just cookbook-enterprise # Enable SELinux + audit
275+
----
276+
277+
== Installation (v1.0)
278+
279+
[source,bash]
280+
----
281+
git clone https://github.com/hyperpolymath/cloud-sync-tuner
282+
cd cloud-sync-tuner
283+
just install
284+
----
285+
286+
See `justfile` for all available recipes.
287+
288+
== License
289+
290+
MPL-2.0
291+
292+
293+
== Architecture
294+
295+
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.

0 commit comments

Comments
 (0)