From afa6d02c4657305c5fbf07404c3a4fe7de6bbf1a Mon Sep 17 00:00:00 2001 From: Terranom674 Date: Thu, 20 Aug 2026 19:30:02 +0200 Subject: [PATCH] Update current status for preview-backed derivatives --- CURRENT_STATUS.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index d09b35f..263487d 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -2,7 +2,7 @@ ## Version -**Bratonien Tools 0.9.6.8.19** +**Bratonien Tools 0.9.6.8.25** Zielplattform der produktiven NC-Connector-Synchronisierung ist derzeit **Piwigo 16.4.0**. @@ -40,10 +40,12 @@ Die verbindungsspezifischen Runtime-Konfigurationen liegen unter `/etc/bratonien Der Reconcile- und Shell-Pfad unterstützt den leeren WebDAV-Root ausdrücklich und gibt ihn als `--root ""` an den Platzhalter-Builder weiter. -### Platzhalterquelle und Shadow Tree +### Platzhalterquelle, Metadaten und Shadow Tree `runtime/lib/build_webdav_placeholder_source.py` bildet die Nextcloud-Inhalte als lokale Platzhalterquelle ab. Für Bilder existieren physische 1×1-Platzhalterdateien; die Originale werden dabei nicht dauerhaft heruntergeladen. +Der WebDAV-Scan übernimmt zusätzlich die von Nextcloud gelieferten Bildmaße aus `nc:metadata-photos-size`. `width`, `height` und `fileid` werden im `webdav-map.json` geführt. Nach dem normalen Piwigo-Dateisync überträgt `runtime/lib/sync-webdav-metadata.php` die Originalmaße in `piwigo_images`, damit Piwigo seine Derivatgrößen und Lazy-Loading-Geometrie auf Basis der echten Bildabmessungen berechnet. + `runtime/lib/shadow_tree.py` erzeugt atomar die Dateisystemstruktur, die Piwigo als physische Site sieht. Shadow-Verzeichnisse werden so angelegt, dass der Webserver die für die On-Demand-Materialisierung nötigen Dateisystemoperationen ausführen kann. Jede WebDAV-Verbindung besitzt ihre eigene Piwigo-Site. Es gibt keinen zusätzlichen Sync auf Site 1. @@ -56,23 +58,26 @@ Danach wird `bratonien.nc.syncOrphans` für die konkrete WebDAV-Site ausgeführt Der Shadow Tree stellt Piwigo ausschließlich die physische Album-/Bildstruktur bereit. Albumdatensätze, Bilddatensätze, Bild-Kategorie-Verknüpfungen und Piwigo-Derivate bleiben Aufgabe von Piwigo. -### On-Demand-Materialisierung vor `i.php` +### On-Demand-Materialisierung und Derivaterzeugung -Die produktive WebDAV-Derivaterzeugung sitzt vor Piwigos `i.php`. - -`include/webdav_materialize_runtime.inc.php` löst aus dem Piwigo-Bildpfad die konkrete Verbindung, den ausgewählten Nextcloud-Root und den relativen WebDAV-Pfad auf. +`include/webdav_materialize_runtime.inc.php` löst aus dem Piwigo-Bildpfad die konkrete Verbindung, den ausgewählten Nextcloud-Root, den relativen WebDAV-Pfad sowie die Mapping-Metadaten `fileid`, `width`, `height`, MIME-Typ, Größe und ETag auf. Für ein noch nicht vorhandenes Derivat läuft `webdav-derivative.php`: 1. Zugriffsprüfung für das Piwigo-Bild; -2. Download des Originals aus Nextcloud in eine temporäre Datei; -3. temporäres Bereitstellen des Originals am exakten von Piwigo erwarteten Quellpfad; -4. Aufruf des nativen Piwigo-`i.php`; -5. Piwigo erzeugt sein normales Derivat; -6. Wiederherstellung des Shadow-/Platzhalterzustands; -7. Auslieferung des Piwigo-Derivats. +2. Auswahl einer temporären Nextcloud-Quelle; +3. temporäres Bereitstellen dieser Quelle am exakten von Piwigo erwarteten Quellpfad; +4. Erzeugung des normalen Piwigo-Derivats mit Piwigos eigener `pwg_image`-/Derivative-Logik im selben PHP-Prozess; +5. Wiederherstellung des Shadow-/Platzhalterzustands; +6. Auslieferung des Piwigo-Derivats. -Das Original verbleibt in Nextcloud. Es gibt keine dauerhafte vollständige Originalkopie in Piwigo. +Ein interner HTTP-Self-Request auf `i.php` wird nicht mehr verwendet. Damit wird kein zusätzlicher PHP-FPM-Worker pro Derivaterzeugung benötigt. + +Für die erste Preview-Stufe verwenden ausschließlich `custom:s9999x250` und `standard:square` den authentifizierten Nextcloud-Endpunkt `/core/preview` anhand der Nextcloud-`fileid`. Die Preview wird mit etwa doppelter benötigter Piwigo-Auflösung und erhaltenem Seitenverhältnis angefordert. Die Berechnung berücksichtigt das Original-Seitenverhältnis, damit auch Crop-Derivate genügend Pixel erhalten. Varianten mit Bildrotation werden in dieser Stufe nicht über Preview erzeugt. + +Ist keine geeignete Preview planbar oder schlägt der Preview-Abruf fehl, fällt der Gate automatisch auf den vollständigen WebDAV-Originaldownload zurück. Große/originale Anforderungen verwenden weiterhin die Originalquelle. + +Die temporäre Preview bzw. das temporäre Original wird nach der Derivaterzeugung entfernt. Das fertige Derivat verbleibt ausschließlich in Piwigos normalem `_data/i`-Cache. Der Connector führt keinen parallelen permanenten Derivat-Cache. ### Orphan-Logik @@ -104,13 +109,13 @@ Eine WebDAV-Verbindung kann unabhängig von ihrer Reihenfolge gelöscht werden. ### Diagnose -Der WebDAV-Derivative-Gate schreibt Request-bezogene `[BRAT-WD ...]`-Diagnoseeinträge. Der Verbindungsstatus wird pro Verbindung geführt. Runtime-Probleme lassen sich zusätzlich über `bratonien-nc-connector.service` nachvollziehen. +Der WebDAV-Derivative-Gate schreibt Request-bezogene `[BRAT-WD ...]`-Diagnoseeinträge. Für neue Derivate zeigen `preview_start`, `preview_failed`, `download_done mode=preview|original`, `generate_start` und `generate_done` den verwendeten Quellpfad und die Laufzeiten. Der Verbindungsstatus wird pro Verbindung geführt. Runtime-Probleme lassen sich zusätzlich über `bratonien-nc-connector.service` nachvollziehen. ## Aktuell relevante Dateien - `main.inc.php` – Plugin-Hooks, Connector-Sync-Hilfen, Dashboard-Prefilter -- `include/webdav_materialize_runtime.inc.php` – WebDAV-Quellauflösung und Materialisierung -- `webdav-derivative.php` – On-Demand-Gate vor Piwigos `i.php` +- `include/webdav_materialize_runtime.inc.php` – WebDAV-Quellauflösung einschließlich `fileid` und Originalmaßen +- `webdav-derivative.php` – On-Demand-Gate, Nextcloud-Preview/Original-Fallback und Piwigo-Derivaterzeugung - `webdav-image.php` – direkte WebDAV-Originalauslieferung - `include/nc_productive_ws.inc.php` – direkter Piwigo-Core-Sync für 16.4.0 - `include/nc_orphan_ws.inc.php` – Root-Orphan-Synchronisierung @@ -119,15 +124,16 @@ Der WebDAV-Derivative-Gate schreibt Request-bezogene `[BRAT-WD ...]`-Diagnoseein - `runtime/cleanup-webdav-piwigo.php` – Bereinigung verwaister Piwigo-Sites - `runtime/sync-webdav.sh` – verbindungsspezifischer Sync - `runtime/run-all.sh` – gemeinsamer Runner -- `runtime/lib/build_webdav_placeholder_source.py` – WebDAV-Scan und Platzhalterquelle +- `runtime/lib/build_webdav_placeholder_source.py` – WebDAV-Scan, Bildmetadaten und Platzhalterquelle +- `runtime/lib/sync-webdav-metadata.php` – Übernahme der Originalmaße nach Piwigo - `runtime/lib/shadow_tree.py` – atomarer Shadow Tree - `runtime/lib/piwigo-sync.php` – Piwigo-API/Fallback-Sync ## Nicht mehr das produktive WebDAV-Modell -Nicht mehr maßgeblich für die produktive WebDAV-Derivaterzeugung ist das frühere Modell, bei dem Bild-URLs einfach auf einen separaten WebDAV-Bildstream umgebogen wurden oder der Connector selbst einen parallelen vollständigen Derivatbestand verwalten sollte. +Nicht mehr maßgeblich sind das frühere Modell eines separaten WebDAV-Bildstreams als Derivatquelle, ein paralleler vollständiger Connector-Derivatbestand oder ein interner HTTP-Aufruf von `webdav-derivative.php` zurück auf Piwigos `i.php`. -Maßgeblich ist: **physischer Platzhalter + On-Demand-Original + natives Piwigo-`i.php` + Wiederherstellung des Platzhalters**. +Maßgeblich ist: **physischer Platzhalter + passende temporäre Nextcloud-Preview bzw. Original-Fallback + Piwigos Bildverarbeitung im selben PHP-Prozess + normales Piwigo-Derivat + Wiederherstellung des Platzhalters**. ## Prüfpflicht vor Merge