safekeep 0.5.2__tar.gz → 0.7.0__tar.gz

{safekeep-0.5.2/safekeep.egg-info → safekeep-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: safekeep
-Version: 0.5.2
+Version: 0.7.0
 Summary: Selective always-on backups for macOS and Linux: fswatch-driven copy of allow-listed files, never deletes
 License-Expression: MIT
 Project-URL: Repository, https://github.com/foxhound87/safekeep
@@ -21,6 +21,8 @@ Classifier: Topic :: System :: Archiving :: Backup
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: s3
+Requires-Dist: botocore<2,>=1.31; extra == "s3"
 Dynamic: license-file
 
 # safekeep
@@ -56,13 +58,19 @@ Documentation: https://foxhound87.github.io/safekeep/
   `.sync` file can neither add nor remove destinations (a `dest:` line is an
   invalid line), so a repo cloned from a third party can't redirect the backup
   somewhere else.
+- **S3-compatible destination** (optional `safekeep[s3]` extra): one
+  S3-compatible bucket alongside the filesystem destinations — same
+  size/mtime idempotency, metadata-based, and **never deletes anything**
+  (`--prune` only touches filesystem destinations).
 
 ## Installation
 
 ```bash
-pipx install safekeep     # recommended for a CLI
+pipx install safekeep        # recommended for a CLI
+pipx install "safekeep[s3]"  # + S3-compatible destination (botocore)
 # or
 pip install safekeep
+pip install "safekeep[s3]"
 ```
 
 **Requirements**: macOS or Linux (POSIX with systemd), Python >= 3.9 and
@@ -76,21 +84,22 @@ sudo dnf install fswatch  # Fedora
 ```
 
 The **agent** (daemon at boot: launchd on macOS, a systemd *user unit* on Linux)
-is installed from a checkout of this repository with `./install.sh` — not from
-the wheel — see [Agent](#agent) below.
+is installed from the installed package with `safekeep daemon install` — the
+unit templates ship inside the wheel, no checkout needed — see
+[Agent](#agent) below. The old `./install.sh` wrapper is deprecated.
 
 ## Agent
 
 ```bash
-git clone https://github.com/foxhound87/safekeep.git
-cd safekeep
+pipx install safekeep        # or: pip install --user safekeep
 
 # only external dependency, if not installed yet (see the per-OS list above)
-brew install fswatch      # macOS — the script suggests the right command on Linux
+brew install fswatch      # macOS — the preflight suggests the right command on Linux
 
-# copies the example into ~/.safekeep, renders the plist / systemd unit,
-# runs preflight checks
-bash install.sh
+# preflight (fswatch / shim on PATH / python / WSL systemd-on), then renders
+# the plist or systemd user unit from the embedded template into place —
+# idempotent, does NOT start anything yet
+safekeep daemon install        # --dry-run to preview, nothing is written
 ```
 
 Then:
@@ -104,16 +113,18 @@ Then:
 3. load the agent:
 
 ```bash
-# macOS (launchd)
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.safekeep.agent.plist
-# unload with: launchctl bootout gui/$(id -u)/com.safekeep.agent
-
-# Linux (systemd user unit)
-systemctl --user enable --now safekeep
-# status with: systemctl --user status safekeep
-# logs with:   journalctl --user -u safekeep -f
-# unload with: systemctl --user disable --now safekeep
-# start at boot without a login session: loginctl enable-linger $USER
+safekeep daemon start        # launchctl bootstrap (macOS) / systemctl --user enable --now (Linux)
+safekeep daemon status       # exit 0 while running, 1 otherwise
+safekeep daemon stop         # unload
+
+# logs (Linux): journalctl --user -u safekeep -f
+# remove the unit (config and logs stay): safekeep daemon uninstall
+# remove everything, incl. ~/.safekeep:    safekeep daemon uninstall --purge
+
+# Linux - start at boot without a login session (linger = user units active
+# without a login), either pass
+safekeep daemon install --enable-linger
+# or run once: loginctl enable-linger $USER
 ```
 
 On macOS, once you have granted TCC/FDA (Full Disk Access) permissions to the
@@ -144,7 +155,8 @@ exactly those entries, as always. Without it safekeep switches to
 **auto-discovery**: it scans `$HOME` for `.sync` files (skipping hidden
 directories, `Library`, `.Trash`, `.cache`, `node_modules`, `.git`, `.venv`,
 `__pycache__`, `venv`), watches `$HOME`, and picks up any `.sync` created after
-startup. `dest:` stays mandatory in both modes.
+startup. `dest:` stays mandatory in both modes — unless `s3_bucket:` is set
+(at least one of the two must be present).
 
 `~/Code/myapp/.sync` (rules only, no destinations):
 
@@ -171,6 +183,66 @@ safekeep sync-once --dry-run   # prints what would be copied, copies nothing
 safekeep run                   # daemon: watch + copy (foreground)
 ```
 
+## S3-compatible destinations
+
+safekeep can push every project to **one S3-compatible bucket**
+(S3 = Simple Storage Service) in addition to (or instead of) the filesystem
+destinations. The client is [botocore](https://botocore.amazonaws.com/),
+installed via the optional extra — the core package stays stdlib-only:
+
+```bash
+pipx install "safekeep[s3]"      # or: pip install "safekeep[s3]"
+```
+
+Without the extra the config still parses, but any `s3_*` key fails fast with
+an install hint (`doctor` reports it as a **non-fatal** warning).
+
+`~/.safekeep` (the `s3_*` keys are valid **only** in this file — a `.sync`
+can't add them; keep the file at `chmod 600`):
+
+```ini
+s3_endpoint: https://s3.example.com:443   # http:// → cleartext warning
+s3_bucket: my-backup-bucket               # at least one dest: OR s3_bucket:
+s3_prefix: safekeep                       # optional, no '..'
+s3_region: us-east-1                      # default
+s3_access_key: REPLACEME_ACCESS_KEY       # required when s3_bucket is set
+s3_secret_key: REPLACEME_SECRET_KEY       # chmod 600 — or use s3_secret_key_env:
+# s3_secret_key_env: SAFEKEEP_S3_SECRET   # secret from env, never in the file
+s3_addressing: path                       # path (default) | virtual
+s3_tls_check: true                        # false = self-signed certificates
+```
+
+With `s3_secret_key_env:` the variable must be in the **agent's** environment
+(launchd `EnvironmentVariables`, systemd `Environment=`) — a shell `export`
+alone doesn't reach a daemon started at boot.
+
+Semantics (see [SPEC.md](SPEC.md) §18): upload-only with `needs_copy` based on
+object metadata (`x-amz-meta-mtime` in nanoseconds, `x-amz-meta-mode`,
+symlinks = zero-byte objects with `x-amz-meta-symlink`), same 1s mtime
+tolerance as filesystem destinations, network errors → `pending` with
+backoff, and **no deletions ever** — `--prune` never touches S3. A slow PUT
+blocks the single-process daemon until it times out (connect 10s / read 60s);
+that's an accepted v1 limitation.
+
+Compatible services:
+
+| Service | Example `s3_endpoint` | `s3_addressing` | `s3_region` | TLS |
+|---|---|---|---|---|
+| MinIO (self-hosted) | `https://minio.example.com:9000` | `path` | any (`us-east-1` default) | `https` + `s3_tls_check: false` if self-signed |
+| Silo (fork of MinIO) | `https://s3.example.com:443` | `path` | any (`us-east-1` default) | as the endpoint's own certificate |
+| Ceph RGW | `https://rgw.example.com` | `path` | any, must match the RGW zone (`us-east-1` default) | as configured on the RGW |
+| Wasabi | `https://s3.wasabisys.com` | `path` | **required**, must match the bucket (`us-east-1` on that endpoint) | `https` |
+| Backblaze B2 | `https://s3.<region>.backblazeb2.com` | `virtual` or `path` | **required**, must match the bucket region | `https` only — cleartext rejected |
+| AWS S3 | *(omit `s3_endpoint`)* | `virtual` | must match the bucket (`us-east-1` default) | `https` |
+
+All of them speak SigV4 (Signature Version 4) with the same client — no
+service-specific code path. B2 wants an **Application Key** (not the Master
+Key) as `s3_access_key`/`s3_secret_key`.
+
+`safekeep status` shows the bucket as `[ok]`/`[offline]` (cached HeadBucket),
+and `safekeep doctor` reports credentials, file permissions and bucket
+reachability — all as **non-fatal** warnings.
+
 ## CLI commands
 
 ```
@@ -183,6 +255,7 @@ safekeep <command> [--config PATH] [-v]
 | `sync-once [--dry-run] [--project PATH] [--prune]` | a single pass: walks the source and copies whatever differs (`--dry-run` only prints what it would copy; `--prune` also removes dest files whose source still exists but is no longer included) |
 | `status` | read-only: config, sources, discovered projects with N rules, destination states |
 | `doctor [--json]` | diagnostics: config, fswatch + platform monitor, python, TCC/launchd plist (macOS), inotify limit and systemd unit (Linux) — exits non-zero if a fatal check fails; `--json` prints the same checks as one JSON document on stdout with the same exit code, including a structured `permission_errors` count of the last 24h |
+| `daemon {install,start,stop,status,uninstall}` | manage the boot agent: `install` runs preflight (fswatch, shim on PATH, WSL systemd-on) and renders the launchd plist / systemd user unit from the embedded templates (idempotent, `--dry-run`, `--enable-linger`); `start`/`stop`/`status` load, unload and probe it; `uninstall` removes the unit (`--purge` also drops `~/.safekeep` and state) |
 
 ## Tests
 
@@ -190,7 +263,7 @@ safekeep <command> [--config PATH] [-v]
 python3 -m unittest discover -s tests
 ```
 
-Stdlib (`unittest`) suite, zero dependencies: 221 tests covering the matcher,
+Stdlib (`unittest`) suite, zero dependencies: 287 tests covering the matcher,
 config, atomic copy, volumes, daemon, auto-discovery, CLI, the permission-trend
 wrapper and the POSIX portability layer (platform helper, per-OS fswatch
 monitor, systemd template).
@@ -198,6 +271,20 @@ monitor, systemd template).
 the real binary are skipped when it's missing — but CI installs it so the
 Linux job exercises the real `inotify` monitor.
 
+The S3 integration test talks to a real bucket and is **skipped** unless every
+`SAFEKEEP_S3_TEST_*` variable is set (no credential is hard-coded; it uploads
+under a throwaway timestamped prefix and performs **no** DeleteObject):
+
+```bash
+export SAFEKEEP_S3_TEST_ENDPOINT=https://s3.example.com:443 \
+       SAFEKEEP_S3_TEST_BUCKET=my-backup-bucket \
+       SAFEKEEP_S3_TEST_ACCESS_KEY=REPLACEME_ACCESS_KEY \
+       SAFEKEEP_S3_TEST_SECRET_KEY=REPLACEME_SECRET_KEY \
+       SAFEKEEP_S3_TEST_REGION=us-east-1        # optional, default us-east-1
+       # SAFEKEEP_S3_TEST_PREFIX=safekeep       # optional, default safekeep-itest
+python3 -m unittest tests.test_s3_itest -v
+```
+
 ## Documentation
 
 Everything in detail (config format, pattern semantics, event → sync flow,

{safekeep-0.5.2 → safekeep-0.7.0}/README.md

@@ -31,13 +31,19 @@ Documentation: https://foxhound87.github.io/safekeep/
   `.sync` file can neither add nor remove destinations (a `dest:` line is an
   invalid line), so a repo cloned from a third party can't redirect the backup
   somewhere else.
+- **S3-compatible destination** (optional `safekeep[s3]` extra): one
+  S3-compatible bucket alongside the filesystem destinations — same
+  size/mtime idempotency, metadata-based, and **never deletes anything**
+  (`--prune` only touches filesystem destinations).
 
 ## Installation
 
 ```bash
-pipx install safekeep     # recommended for a CLI
+pipx install safekeep        # recommended for a CLI
+pipx install "safekeep[s3]"  # + S3-compatible destination (botocore)
 # or
 pip install safekeep
+pip install "safekeep[s3]"
 ```
 
 **Requirements**: macOS or Linux (POSIX with systemd), Python >= 3.9 and
@@ -51,21 +57,22 @@ sudo dnf install fswatch  # Fedora
 ```
 
 The **agent** (daemon at boot: launchd on macOS, a systemd *user unit* on Linux)
-is installed from a checkout of this repository with `./install.sh` — not from
-the wheel — see [Agent](#agent) below.
+is installed from the installed package with `safekeep daemon install` — the
+unit templates ship inside the wheel, no checkout needed — see
+[Agent](#agent) below. The old `./install.sh` wrapper is deprecated.
 
 ## Agent
 
 ```bash
-git clone https://github.com/foxhound87/safekeep.git
-cd safekeep
+pipx install safekeep        # or: pip install --user safekeep
 
 # only external dependency, if not installed yet (see the per-OS list above)
-brew install fswatch      # macOS — the script suggests the right command on Linux
+brew install fswatch      # macOS — the preflight suggests the right command on Linux
 
-# copies the example into ~/.safekeep, renders the plist / systemd unit,
-# runs preflight checks
-bash install.sh
+# preflight (fswatch / shim on PATH / python / WSL systemd-on), then renders
+# the plist or systemd user unit from the embedded template into place —
+# idempotent, does NOT start anything yet
+safekeep daemon install        # --dry-run to preview, nothing is written
 ```
 
 Then:
@@ -79,16 +86,18 @@ Then:
 3. load the agent:
 
 ```bash
-# macOS (launchd)
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.safekeep.agent.plist
-# unload with: launchctl bootout gui/$(id -u)/com.safekeep.agent
-
-# Linux (systemd user unit)
-systemctl --user enable --now safekeep
-# status with: systemctl --user status safekeep
-# logs with:   journalctl --user -u safekeep -f
-# unload with: systemctl --user disable --now safekeep
-# start at boot without a login session: loginctl enable-linger $USER
+safekeep daemon start        # launchctl bootstrap (macOS) / systemctl --user enable --now (Linux)
+safekeep daemon status       # exit 0 while running, 1 otherwise
+safekeep daemon stop         # unload
+
+# logs (Linux): journalctl --user -u safekeep -f
+# remove the unit (config and logs stay): safekeep daemon uninstall
+# remove everything, incl. ~/.safekeep:    safekeep daemon uninstall --purge
+
+# Linux - start at boot without a login session (linger = user units active
+# without a login), either pass
+safekeep daemon install --enable-linger
+# or run once: loginctl enable-linger $USER
 ```
 
 On macOS, once you have granted TCC/FDA (Full Disk Access) permissions to the
@@ -119,7 +128,8 @@ exactly those entries, as always. Without it safekeep switches to
 **auto-discovery**: it scans `$HOME` for `.sync` files (skipping hidden
 directories, `Library`, `.Trash`, `.cache`, `node_modules`, `.git`, `.venv`,
 `__pycache__`, `venv`), watches `$HOME`, and picks up any `.sync` created after
-startup. `dest:` stays mandatory in both modes.
+startup. `dest:` stays mandatory in both modes — unless `s3_bucket:` is set
+(at least one of the two must be present).
 
 `~/Code/myapp/.sync` (rules only, no destinations):
 
@@ -146,6 +156,66 @@ safekeep sync-once --dry-run   # prints what would be copied, copies nothing
 safekeep run                   # daemon: watch + copy (foreground)
 ```
 
+## S3-compatible destinations
+
+safekeep can push every project to **one S3-compatible bucket**
+(S3 = Simple Storage Service) in addition to (or instead of) the filesystem
+destinations. The client is [botocore](https://botocore.amazonaws.com/),
+installed via the optional extra — the core package stays stdlib-only:
+
+```bash
+pipx install "safekeep[s3]"      # or: pip install "safekeep[s3]"
+```
+
+Without the extra the config still parses, but any `s3_*` key fails fast with
+an install hint (`doctor` reports it as a **non-fatal** warning).
+
+`~/.safekeep` (the `s3_*` keys are valid **only** in this file — a `.sync`
+can't add them; keep the file at `chmod 600`):
+
+```ini
+s3_endpoint: https://s3.example.com:443   # http:// → cleartext warning
+s3_bucket: my-backup-bucket               # at least one dest: OR s3_bucket:
+s3_prefix: safekeep                       # optional, no '..'
+s3_region: us-east-1                      # default
+s3_access_key: REPLACEME_ACCESS_KEY       # required when s3_bucket is set
+s3_secret_key: REPLACEME_SECRET_KEY       # chmod 600 — or use s3_secret_key_env:
+# s3_secret_key_env: SAFEKEEP_S3_SECRET   # secret from env, never in the file
+s3_addressing: path                       # path (default) | virtual
+s3_tls_check: true                        # false = self-signed certificates
+```
+
+With `s3_secret_key_env:` the variable must be in the **agent's** environment
+(launchd `EnvironmentVariables`, systemd `Environment=`) — a shell `export`
+alone doesn't reach a daemon started at boot.
+
+Semantics (see [SPEC.md](SPEC.md) §18): upload-only with `needs_copy` based on
+object metadata (`x-amz-meta-mtime` in nanoseconds, `x-amz-meta-mode`,
+symlinks = zero-byte objects with `x-amz-meta-symlink`), same 1s mtime
+tolerance as filesystem destinations, network errors → `pending` with
+backoff, and **no deletions ever** — `--prune` never touches S3. A slow PUT
+blocks the single-process daemon until it times out (connect 10s / read 60s);
+that's an accepted v1 limitation.
+
+Compatible services:
+
+| Service | Example `s3_endpoint` | `s3_addressing` | `s3_region` | TLS |
+|---|---|---|---|---|
+| MinIO (self-hosted) | `https://minio.example.com:9000` | `path` | any (`us-east-1` default) | `https` + `s3_tls_check: false` if self-signed |
+| Silo (fork of MinIO) | `https://s3.example.com:443` | `path` | any (`us-east-1` default) | as the endpoint's own certificate |
+| Ceph RGW | `https://rgw.example.com` | `path` | any, must match the RGW zone (`us-east-1` default) | as configured on the RGW |
+| Wasabi | `https://s3.wasabisys.com` | `path` | **required**, must match the bucket (`us-east-1` on that endpoint) | `https` |
+| Backblaze B2 | `https://s3.<region>.backblazeb2.com` | `virtual` or `path` | **required**, must match the bucket region | `https` only — cleartext rejected |
+| AWS S3 | *(omit `s3_endpoint`)* | `virtual` | must match the bucket (`us-east-1` default) | `https` |
+
+All of them speak SigV4 (Signature Version 4) with the same client — no
+service-specific code path. B2 wants an **Application Key** (not the Master
+Key) as `s3_access_key`/`s3_secret_key`.
+
+`safekeep status` shows the bucket as `[ok]`/`[offline]` (cached HeadBucket),
+and `safekeep doctor` reports credentials, file permissions and bucket
+reachability — all as **non-fatal** warnings.
+
 ## CLI commands
 
 ```
@@ -158,6 +228,7 @@ safekeep <command> [--config PATH] [-v]
 | `sync-once [--dry-run] [--project PATH] [--prune]` | a single pass: walks the source and copies whatever differs (`--dry-run` only prints what it would copy; `--prune` also removes dest files whose source still exists but is no longer included) |
 | `status` | read-only: config, sources, discovered projects with N rules, destination states |
 | `doctor [--json]` | diagnostics: config, fswatch + platform monitor, python, TCC/launchd plist (macOS), inotify limit and systemd unit (Linux) — exits non-zero if a fatal check fails; `--json` prints the same checks as one JSON document on stdout with the same exit code, including a structured `permission_errors` count of the last 24h |
+| `daemon {install,start,stop,status,uninstall}` | manage the boot agent: `install` runs preflight (fswatch, shim on PATH, WSL systemd-on) and renders the launchd plist / systemd user unit from the embedded templates (idempotent, `--dry-run`, `--enable-linger`); `start`/`stop`/`status` load, unload and probe it; `uninstall` removes the unit (`--purge` also drops `~/.safekeep` and state) |
 
 ## Tests
 
@@ -165,7 +236,7 @@ safekeep <command> [--config PATH] [-v]
 python3 -m unittest discover -s tests
 ```
 
-Stdlib (`unittest`) suite, zero dependencies: 221 tests covering the matcher,
+Stdlib (`unittest`) suite, zero dependencies: 287 tests covering the matcher,
 config, atomic copy, volumes, daemon, auto-discovery, CLI, the permission-trend
 wrapper and the POSIX portability layer (platform helper, per-OS fswatch
 monitor, systemd template).
@@ -173,6 +244,20 @@ monitor, systemd template).
 the real binary are skipped when it's missing — but CI installs it so the
 Linux job exercises the real `inotify` monitor.
 
+The S3 integration test talks to a real bucket and is **skipped** unless every
+`SAFEKEEP_S3_TEST_*` variable is set (no credential is hard-coded; it uploads
+under a throwaway timestamped prefix and performs **no** DeleteObject):
+
+```bash
+export SAFEKEEP_S3_TEST_ENDPOINT=https://s3.example.com:443 \
+       SAFEKEEP_S3_TEST_BUCKET=my-backup-bucket \
+       SAFEKEEP_S3_TEST_ACCESS_KEY=REPLACEME_ACCESS_KEY \
+       SAFEKEEP_S3_TEST_SECRET_KEY=REPLACEME_SECRET_KEY \
+       SAFEKEEP_S3_TEST_REGION=us-east-1        # optional, default us-east-1
+       # SAFEKEEP_S3_TEST_PREFIX=safekeep       # optional, default safekeep-itest
+python3 -m unittest tests.test_s3_itest -v
+```
+
 ## Documentation
 
 Everything in detail (config format, pattern semantics, event → sync flow,

{safekeep-0.5.2 → safekeep-0.7.0}/pyproject.toml

@@ -25,7 +25,11 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
     "Topic :: System :: Archiving :: Backup",
 ]
-# zero runtime dependencies: solo stdlib (fswatch è un binario esterno)
+# zero runtime dependencies: solo stdlib (fswatch è un binario esterno).
+# L'extra `s3` (botocore, import lazy in s3dest.py) è l'unica dipendenza
+# opzionale: serve SOLO se il config usa le chiavi `s3_*` (SPEC.md §18).
+[project.optional-dependencies]
+s3 = ["botocore>=1.31,<2"]
 
 [project.urls]
 Repository = "https://github.com/foxhound87/safekeep"
@@ -39,5 +43,10 @@ safekeep = "safekeep.cli:main"
 # NO auto-discovery: bin/ e tests/ farebbero errore di build
 packages = ["safekeep"]
 
+[tool.setuptools.package-data]
+# 0.7.0: template unit + example config embedded — `safekeep daemon install`
+# funziona da PyPI senza git clone (sorgente unica: safekeep/data/)
+safekeep = ["data/*"]
+
 [tool.setuptools.dynamic]
 version = {attr = "safekeep.__version__"}

{safekeep-0.5.2 → safekeep-0.7.0}/safekeep/__init__.py

@@ -3,4 +3,4 @@ import logging
 
 logging.getLogger('safekeep').addHandler(logging.NullHandler())
 
-__version__ = '0.5.2'
+__version__ = '0.7.0'