astrapi-sync 26.8.1__tar.gz

astrapi_sync-26.8.1/.github/copilot-instructions.md

@@ -0,0 +1,89 @@
+# astrapi-sync – Projektkontext für GitHub Copilot
+
+Wird im Repo versioniert und von VS Code Copilot automatisch geladen.
+
+---
+
+## Was ist astrapi-sync?
+
+Persönlicher Datei-Synchronisationsdienst nach dem Vorbild von Syncthing/Nextcloud
+(Server + CLI-Client, später GTK4/Android). Nur Michaels eigene Geräte (Auth über
+Geräte-Token statt Accounts), Block-/Delta-Sync (Syncthing-Stil, fixe Blockgröße,
+SHA256 je Block), Änderungs-Push per WebSocket statt Polling.
+Basiert auf **astrapi-core** (FastAPI + HTMX + Jinja2).
+PyPI-Paketname: `astrapi-sync`, Python-Paket: `astrapi_sync`.
+
+Zugehöriges Client-Repo: [astrapi-sync-client](https://github.com/astrapi/astrapi-sync-client)
+(geteilte Sync-Engine + CLI, kein astrapi-core-Abhängigkeit).
+
+---
+
+## Stack
+
+| Komponente | Details |
+|---|---|
+| Framework | astrapi-core (FastAPI + HTMX) |
+| API | FastAPI (`/api/...`) |
+| UI | FastAPI + HTMX + Jinja2 (`/ui/...`) |
+| Persistenz | SQLite (über astrapi-core) |
+| Auth (Sync-API) | Bearer-Geräte-Token, SHA256-gehasht gespeichert |
+| Python | ≥ 3.11 |
+
+---
+
+## Verzeichnisstruktur
+
+```
+astrapi_sync/
+├── _app.py              # ASGI-App-Factory (uvicorn-Einstiegspunkt)
+├── _cli.py               # Console-Script: astrapi-sync
+├── _paths.py              # package_dir(), work_dir(), folder_path(), extra_disk_options()
+├── app.yaml               # name: astrapi-sync, display_name: Sync
+├── navigation.yaml         # App-Navigation
+├── api/
+│   ├── fastapi_app.py     # FastAPI-Factory, Router-Registrierung
+│   ├── auth.py             # Geräte-Token-Auth (require_device, require_device_only)
+│   ├── block_hash.py       # Block-Hashing, Datei-/Verzeichnis-Index
+│   ├── sync.py              # Pairing, Datei-Index, Upload/Download/Delete, WebSocket-Push
+│   └── ws_manager.py        # In-Process-WebSocket-Verbindungsmanager je Ordner
+└── modules/
+    ├── folders/            # Sync-Ordner (Admin-CRUD, Speicherort, Dateibrowser-Modal)
+    └── devices/            # Gepairte Geräte, Pairing-Flow, Reconnect
+```
+
+---
+
+## App-Start
+
+```
+astrapi-sync --work-dir /opt/astrapi-sync --port 5004
+```
+
+- `_configure_paths("astrapi-sync")` setzt Runtime-Pfade
+- `configure_updater(_pkg)` registriert `astrapi-sync` + `astrapi-core` im Updater
+- Sync-Ordner liegen standardmäßig unter `<work-dir>/folders/<id>/`, oder auf einem
+  konfigurierten Zusatzspeicher (`extra_disks`-Systemeinstellung) unter
+  `<speicherort>/astrapi-sync/<id>/` — siehe `_paths.py::folder_path()`.
+
+---
+
+## Sync-Protokoll (Kurzüberblick)
+
+- `POST /api/sync/pair` — Pairing-Token → langlebiges Geräte-Token (Bearer).
+- `GET  /api/sync/folders/{id}/index` — Datei- und Verzeichnis-Index
+  (`build_index()`/`build_dir_index()` in `block_hash.py`).
+- `POST/GET /api/sync/folders/{id}/files/{path}` — Block-Delta-Upload/Download.
+- `DELETE /api/sync/folders/{id}/files/{path}` — Löschung propagieren.
+- `POST/DELETE /api/sync/folders/{id}/dirs/{path}` — leere Verzeichnisse anlegen/entfernen
+  (nicht-leere entstehen implizit über Datei-Pfade).
+- `WS /api/sync/folders/{id}/events` — Push bei Änderungen an alle verbundenen Geräte.
+
+Kein rsync-Rolling-Hash, kein Blob-Store: reale Verzeichnisbäume auf Platte,
+Block-Hashes nur als Übertragungstechnik.
+
+---
+
+## Versionsschema
+
+CalVer: `YY.MM.patch.devN` – gesteuert via setuptools-scm + Git-Tags.
+Release über `astrapi-tools/release.sh sync` (Tag `v*` triggert `publish.yml` → PyPI).

astrapi_sync-26.8.1/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # nötig für setuptools-scm
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install --quiet build
+          python -m build --wheel --sdist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

astrapi_sync-26.8.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+var/
+app.db
+pip_*.txt

astrapi_sync-26.8.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: astrapi-sync
+Version: 26.8.1
+Summary: astrapi-sync – Ordner-Synchronisation über mehrere Geräte
+Requires-Python: >=3.11
+Requires-Dist: fastapi==0.141.1
+Requires-Dist: uvicorn[standard]==0.52.4
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: APScheduler==3.11.3
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: python-multipart==0.0.32
+Requires-Dist: cryptography==50.0.0
+Requires-Dist: psutil==7.2.2
+Requires-Dist: apispec==6.10.0
+Requires-Dist: astrapi-core>=26.8.21

astrapi_sync-26.8.1/README.md

@@ -0,0 +1,66 @@
+# astrapi-sync
+
+Ordner-Synchronisation über mehrere Geräte (Server-Komponente) — nach dem
+Vorbild von Syncthing/Nextcloud/Ubuntu One, auf `astrapi-core` aufgebaut.
+
+Ein Ordner wird auf dem Server angelegt (Modul „Ordner", inkl. Wahl des
+Speicherorts und Dateibrowser); Geräte (CLI-Client — GTK4-/Android-App
+folgen) werden per Pairing-Code gekoppelt (Modul „Geräte") und verbinden
+sich dann mit einem lokalen Ordner.
+
+Block-/Delta-Sync (Syncthing-Stil, fixe Blockgröße, SHA256 je Block),
+Änderungs-Push per WebSocket statt Polling, reale Verzeichnisbäume auf
+Platte statt Blob-Store. Nur Michaels eigene Geräte — Auth über
+Geräte-Token statt Accounts.
+
+Zugehöriges Client-Repo: [astrapi-sync-client](https://github.com/astrapi/astrapi-sync-client).
+
+## Stack
+
+| Komponente | Details |
+|---|---|
+| Framework | astrapi-core (FastAPI + HTMX) |
+| Persistenz | SQLite |
+| Auth (Sync-API) | Bearer-Geräte-Token, SHA256-gehasht gespeichert |
+| Python | ≥ 3.11 |
+
+## Setup (Entwicklung)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ../astrapi-core   # Schwesterprojekt
+pip install -e .
+```
+
+## Starten
+
+```bash
+astrapi-sync --work-dir ./data --port 5004 --debug
+```
+
+| Parameter | Standard | Beschreibung |
+|---|---|---|
+| `--work-dir` | (Pflicht) | Datenpfad für SQLite-DB, Sync-Ordner und Laufzeitdaten |
+| `--port` | `5004` | HTTP-Port |
+| `--host` | `0.0.0.0` | Bind-Adresse |
+| `--debug` / `--reload` | – | Auto-Reload bei Dateiänderungen |
+
+Die Web-Oberfläche ist danach erreichbar unter: `http://localhost:5004`
+
+## Projektstruktur
+
+```
+astrapi_sync/
+├── _cli.py            # Einstiegspunkt (CLI)
+├── _app.py            # ASGI-App-Factory
+├── _paths.py          # Pfad-Utilities (Speicherort je Ordner)
+├── api/
+│   ├── auth.py         # Geräte-Token-Auth
+│   ├── block_hash.py   # Block-Hashing, Datei-/Verzeichnis-Index
+│   ├── sync.py          # Pairing, Index, Upload/Download/Delete, WebSocket
+│   └── ws_manager.py     # Verbindungsmanager je Ordner
+└── modules/
+    ├── folders/        # Sync-Ordner (Admin-CRUD, Speicherort, Dateibrowser)
+    └── devices/        # Gepairte Geräte, Pairing-Flow
+```

astrapi_sync-26.8.1/astrapi_sync/_app.py

@@ -0,0 +1,89 @@
+"""astrapi_sync._app – ASGI-App-Factory.
+
+Start:
+    uvicorn astrapi_sync._app:app
+    astrapi-sync --work-dir /opt/astrapi-sync --port 5004
+"""
+
+import time
+
+from astrapi_core.system.paths import configure as _configure_paths
+
+_configure_paths("astrapi-sync")
+
+from astrapi_core.modules.settings.engine import configure as configure_settings
+from astrapi_core.modules.system.engine import configure_updater
+from astrapi_core.system.health import register_health
+from astrapi_core.system.systemd import sd_notify, start_watchdog
+from astrapi_core.system.version import get_display_name
+from astrapi_core.ui import create as create_ui
+from astrapi_core.ui.module_registry import load_modules
+from astrapi_core.ui.settings_registry import init as settings_init
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from astrapi_sync._paths import db_path, package_dir, work_dir
+from astrapi_sync.api.fastapi_app import create as create_api
+
+_START_TIME = time.time()
+
+
+def _db_check() -> tuple[bool, dict]:
+    from astrapi_core.system.db import _conn
+
+    try:
+        _conn().execute("SELECT 1").fetchone()
+        return True, {"db": True}
+    except Exception:
+        return False, {"db": False}
+
+
+def _migrate_folders_storage_location() -> None:
+    """register_table()'s DDL ist CREATE TABLE IF NOT EXISTS -- legt bei
+    bereits bestehender Tabelle keine neuen Spalten nach. storage_location
+    kam nachträglich dazu (T-202-SYNC), hier per ALTER TABLE ergänzt."""
+    from astrapi_core.system.db import _conn
+
+    con = _conn()
+    try:
+        cols = [r[1] for r in con.execute("PRAGMA table_info(folders)")]
+        if "storage_location" not in cols:
+            con.execute("ALTER TABLE folders ADD COLUMN storage_location TEXT NOT NULL DEFAULT ''")
+            con.commit()
+    except Exception:
+        pass
+
+
+def create_app() -> FastAPI:
+    _pkg = package_dir()
+    configure_settings(health_fn=_db_check, app_name=get_display_name(_pkg))
+    configure_updater(_pkg)
+
+    from astrapi_core.system.db import configure as _configure_db
+    from astrapi_core.system.db import create_all_registered_tables
+
+    _configure_db(db_path())
+    create_all_registered_tables()
+    _migrate_folders_storage_location()
+
+    settings_init(work_dir())
+
+    modules, _ = load_modules(_pkg)
+    api = create_api(modules=modules)
+
+    from pathlib import Path
+
+    import astrapi_core.ui
+
+    core_static = Path(astrapi_core.ui.__file__).parent / "static"
+    api.mount("/static", StaticFiles(directory=str(core_static)), name="static")
+
+    create_ui(api, app_root=_pkg, modules=modules)
+
+    register_health(api, check_fn=_db_check, start_time=_START_TIME)
+    start_watchdog(check_fn=lambda: _db_check()[0])
+    sd_notify("READY=1")
+    return api
+
+
+app = create_app()

astrapi_sync-26.8.1/astrapi_sync/_cli.py

@@ -0,0 +1,15 @@
+"""astrapi_sync._cli – Console-Script-Einstiegspunkt.
+
+Start:
+    astrapi-sync --work-dir /opt/astrapi-sync --port 5004
+    astrapi-sync --work-dir /opt/astrapi-sync --port 5004 --debug
+"""
+from astrapi_core.system.paths import run_app
+
+
+def main() -> None:
+    run_app("astrapi_sync._app:app", "astrapi-sync", default_port=5004)
+
+
+if __name__ == "__main__":
+    main()

astrapi_sync-26.8.1/astrapi_sync/_paths.py

@@ -0,0 +1,51 @@
+# astrapi_sync/_paths.py
+from pathlib import Path
+
+from astrapi_core.system.paths import db_path, log_dir, work_dir  # noqa: F401 – re-export
+
+
+def package_dir() -> Path:
+    """Pfad zum installierten Package – für app.yaml, Templates, Modul-YAMLs."""
+    return Path(__file__).resolve().parent
+
+
+def extra_disk_options() -> list[str]:
+    """Alle konfigurierten Zusatzspeicher-Pfade (Einstellungen -> System ->
+    "Zusätzlicher Speicher", core-weites Setting system.extra_disks).
+
+    get_module() liefert für type:list-Settings eine echte Python-Liste
+    zurück (astrapi_mirror._paths::_extra_disk() geht von einem
+    Komma-String aus und würde bei einer echten Liste mit AttributeError
+    abstürzen -- hier bewusst robust gegen beide Formen).
+    """
+    from astrapi_core.ui.settings_registry import get_module
+
+    raw = get_module("system", "extra_disks", default=[]) or []
+    if isinstance(raw, str):
+        raw = raw.split(",")
+    return [p.strip() for p in raw if p and p.strip()]
+
+
+def folder_base(storage_location: str) -> Path:
+    """Wurzelverzeichnis für einen gegebenen Speicherort ("" = Standard,
+    sonst einer der konfigurierten Zusatzspeicher-Pfade)."""
+    if storage_location:
+        return Path(storage_location).resolve() / "astrapi-sync"
+    return work_dir().resolve() / "folders"
+
+
+def folder_path(folder_id) -> Path:
+    """Plattenpfad eines einzelnen Sync-Ordners -- abhängig von dessen
+    eigenem storage_location-Feld (nicht global), legt ihn bei Bedarf an.
+
+    Ordner werden nach ihrer numerischen ID benannt (nicht nach dem
+    änderbaren Namen) -- stabil auch wenn der Anzeigename später geändert
+    wird.
+    """
+    from astrapi_sync.modules.folders.ui.crud import store as folders_store
+
+    folder = folders_store.get(str(folder_id)) or {}
+    location = folder.get("storage_location") or ""
+    p = folder_base(location) / str(folder_id)
+    p.mkdir(parents=True, exist_ok=True)
+    return p

astrapi_sync-26.8.1/astrapi_sync/api/auth.py

@@ -0,0 +1,71 @@
+# astrapi_sync/api/auth.py
+"""Geräte-Authentifizierung für die Sync-API.
+
+astrapi-core kennt keinerlei Auth-Konzept (kein Login, keine Sessions,
+keine API-Keys) -- komplett neu für dieses Projekt gebaut. Ein Gerät
+weist sich mit einem Bearer-Token aus (`Authorization: Bearer <token>`),
+das beim Pairing einmalig im Klartext ausgegeben und seither nur noch als
+SHA256-Hash gespeichert wird (wie ein Passwort).
+"""
+import hashlib
+import time
+
+from fastapi import Header, HTTPException, Path
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def get_device_by_token(token: str) -> tuple[str, dict] | None:
+    from astrapi_sync.modules.devices.ui.crud import store as devices_store
+
+    token_hash = hash_token(token)
+    for device_id, device in devices_store.list().items():
+        if device.get("token_hash") == token_hash:
+            return device_id, device
+    return None
+
+
+def authenticate(token: str) -> tuple[str, dict]:
+    """Prüft ein rohes Token (ohne "Bearer "-Präfix), aktualisiert last_seen.
+
+    Gibt (device_id, device_dict) zurück oder wirft HTTPException.
+    """
+    from astrapi_sync.modules.devices.ui.crud import store as devices_store
+
+    found = get_device_by_token(token)
+    if found is None:
+        raise HTTPException(401, "Ungültiges Geräte-Token")
+    device_id, device = found
+    if not device.get("enabled", True):
+        raise HTTPException(403, "Gerät ist deaktiviert")
+
+    devices_store.update(device_id, {"last_seen": time.strftime("%Y-%m-%d %H:%M:%S")})
+    return device_id, device
+
+
+def require_device_only(authorization: str = Header(default="")) -> tuple[str, dict]:
+    """Dependency für Endpunkte ohne folder_id (z.B. GET /api/sync/folders)."""
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(401, "Kein Geräte-Token angegeben")
+    return authenticate(authorization.removeprefix("Bearer ").strip())
+
+
+def require_device(
+    folder_id: str = Path(...),
+    authorization: str = Header(default=""),
+) -> tuple[str, dict]:
+    """Dependency für Sync-Endpunkte unter /api/sync/folders/{folder_id}/...
+
+    Gibt (device_id, device_dict) zurück, wenn das Token gültig ist, das
+    Gerät aktiviert ist und Zugriff auf diesen Ordner hat.
+    """
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(401, "Kein Geräte-Token angegeben")
+    token = authorization.removeprefix("Bearer ").strip()
+
+    device_id, device = authenticate(token)
+    if folder_id not in (device.get("folder_ids") or []):
+        raise HTTPException(403, "Gerät hat keinen Zugriff auf diesen Ordner")
+    return device_id, device

astrapi_sync-26.8.1/astrapi_sync/api/block_hash.py

@@ -0,0 +1,73 @@
+# astrapi_sync/api/block_hash.py
+"""Block-Hashing für Delta-Sync.
+
+Syncthing-Stil: feste Blockgröße, SHA256 je Block, Vergleich per Position
+-- kein rsync-Rolling-Hash (der auch Byte-Verschiebungen mitten in der
+Datei erkennen würde, dafür deutlich komplexer ist). Bewusste
+Vereinfachung, siehe Architektur-Abschnitt im Plan.
+
+Kein persistenter Hash-Cache in dieser Phase -- Hashes werden bei jeder
+Index-Anfrage neu berechnet. Für sehr große, selten geänderte Dateien
+später ggf. über (Pfad, mtime, Größe) cachen.
+"""
+import hashlib
+from pathlib import Path
+
+DEFAULT_BLOCK_SIZE = 1 << 20  # 1 MiB
+
+
+def hash_blocks(path: Path, block_size: int = DEFAULT_BLOCK_SIZE) -> list[str]:
+    """Liest eine Datei blockweise, gibt die SHA256-Hashes je Block zurück."""
+    hashes = []
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(block_size)
+            if not chunk:
+                break
+            hashes.append(hashlib.sha256(chunk).hexdigest())
+    return hashes
+
+
+def whole_file_hash(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def file_entry(path: Path, rel_path: str, block_size: int = DEFAULT_BLOCK_SIZE) -> dict:
+    stat = path.stat()
+    return {
+        "path": rel_path,
+        "size": stat.st_size,
+        "mtime": stat.st_mtime,
+        "block_size": block_size,
+        "sha256": whole_file_hash(path),
+        "blocks": hash_blocks(path, block_size),
+    }
+
+
+def build_index(root: Path, block_size: int = DEFAULT_BLOCK_SIZE) -> list[dict]:
+    """Läuft den Ordnerbaum ab, gibt eine Liste von file_entry()-Dicts zurück."""
+    entries = []
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        entries.append(file_entry(p, p.relative_to(root).as_posix(), block_size))
+    return entries
+
+
+def build_dir_index(root: Path) -> list[str]:
+    """Relative Pfade aller (rekursiv) leeren Verzeichnisse.
+
+    Ein Verzeichnis, das irgendwo in seinem Baum eine Datei enthält, wird
+    schon implizit durch deren Pfad mitsynchronisiert (upload_file() legt
+    fehlende Elternverzeichnisse an) -- nur komplett leere Verzeichnisse
+    tauchen sonst nirgends im Index auf und würden nie propagiert.
+    """
+    dirs = []
+    for p in sorted(root.rglob("*")):
+        if p.is_dir() and not any(f.is_file() for f in p.rglob("*")):
+            dirs.append(p.relative_to(root).as_posix())
+    return dirs

astrapi_sync-26.8.1/astrapi_sync/api/fastapi_app.py

@@ -0,0 +1,28 @@
+"""astrapi_sync.api.fastapi_app – FastAPI-Factory."""
+from fastapi import FastAPI
+from astrapi_core.system.version import get_app_version
+
+from astrapi_sync._paths import package_dir
+
+APP_ROOT = package_dir()
+
+
+def create(modules: list | None = None) -> FastAPI:
+    _version = get_app_version(APP_ROOT, default="0.0.1")
+    app = FastAPI(
+        title="astrapi-sync API",
+        version=_version,
+        docs_url="/api/docs",
+        redoc_url="/api/redoc",
+        openapi_url="/api/openapi.json",
+    )
+
+    from astrapi_core.ui.module_registry import load_modules, register_fastapi_modules
+    if modules is None:
+        modules, _ = load_modules(APP_ROOT)
+    register_fastapi_modules(app, modules)
+
+    from astrapi_sync.api.sync import router as sync_router
+    app.include_router(sync_router)
+
+    return app