diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index 54563e3..8590317 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -4,279 +4,174 @@ Stand: 18.08.2026 ## Plugin -- Aktuelle Plugin-Version: **0.9.5.5** -- Aktueller Entwicklungsblock: **NC Connector – WebDAV-basierter Quellenweg bei vollständigem Erhalt des bestehenden produktiven Wegs** +- Aktuelle Plugin-Version: **0.9.5.6** +- Aktueller Entwicklungsblock: **NC Connector – WebDAV-basierter Parallelweg bei vollständigem Erhalt des bestehenden produktiven Wegs** - GitHub ist das führende Repository. - Das private Gitea-System bleibt Mirror/Fallback. -## Produktiver Stand +## Nicht verhandelbare Migrationsregel -Der bestehende lokale NC Connector bleibt vollständig erhalten und ist weiterhin der produktive Referenzweg. +Der bestehende lokale NC Connector bleibt vollständig erhalten, bis der neue WebDAV-Weg End-to-End funktioniert. -Aktuell vorhandene Quellenmodi: +Bestehende Quellenmodi: - `legacy-view` - `user-shares` - `selected-fileids` -Diese Modi dürfen durch die neue WebDAV-Entwicklung weder automatisch migriert noch deaktiviert, überschrieben oder in ihrer Laufzeitlogik verändert werden. +Sie werden nicht automatisch migriert, deaktiviert oder auf den neuen Weg umgestellt. -Der bestehende Connector kann weiterhin: - -- Nextcloud-Quellen in einen Shadow Tree überführen; -- Ordner als physische Piwigo-Alben synchronisieren; -- Root-Dateien als Orphans registrieren; -- entfernte Quellen aus Piwigo entfernen, ohne Nextcloud-Originale zu löschen; -- neue Connector-Alben privat anlegen; -- Piwigo API-first synchronisieren und bei Bedarf auf einen verbindungseigenen Login-Fallback zurückfallen; -- mehrere aktive Verbindungen über die gemeinsame Runtime verarbeiten. - -## 0.9.5.4 - -- Neuer experimenteller Builder `runtime/lib/build_webdav_placeholder_source.py` hinzugefügt. -- Der Builder liest eine Nextcloud-Quelle rekursiv über WebDAV und erzeugt eine lokale Platzhalterstruktur sowie ein Mapping. -- Es werden keine Originalbilder heruntergeladen. -- Platzhalter sind extrem klein; der derzeitige Builder verwendet ein 1x1-GIF mit wenigen Dutzend Byte. -- Der bestehende produktive Sync wurde dafür nicht umgeschaltet. - -## 0.9.5.5 - -Das Löschen von Connector-Verbindungen wurde gegen unterschiedliche Dateibesitzer zwischen Webserver und Runtime abgesichert. - -Vorher konnte das Löschen scheitern, wenn PHP keinen Tombstone im Connector-Statusverzeichnis anlegen durfte. Jetzt gilt: - -- das Löschen der Verbindung darf nicht von Schreibrechten auf Runtime-Dateien abhängen; -- die Verbindung wird aus der Piwigo-Datenbank entfernt; -- verwaiste Runtime-Dateien werden beim nächsten Connector-Lauf vor der Synchronisierung bereinigt; -- andere bestehende Verbindungen bleiben unangetastet. - -## Architektur – unverändert produktiver Weg - -- Nextcloud ist Quelle der Originalbilder. -- Piwigo verwendet einen Shadow Tree unter dem Galeriepfad. -- Der bisherige Weg arbeitet mit lokalen, bereits vorhandenen Speicherpfaden und Symlinks auf die Originale. -- PostgreSQL-/View-/Storage-Mapping-Logik bleibt für bestehende Verbindungen erhalten. -- Runtime-Konfigurationen: `/etc/bratonien-tools/nc-connector/connection-*.conf` -- State: `/var/lib/bratonien-tools/nc-connector/connection-ID` -- Öffentlicher Admin-Status: Piwigo `_data/bratonien-tools/nc-connector-status/` -- Runner: `runtime/run-all.sh` -- Einzelverbindung: `runtime/sync.sh` -- Shadow Tree: `runtime/lib/shadow_tree.py` - -## Neuer WebDAV-Weg – Zielbild - -Der neue Weg soll als zusätzlicher eigener Quellenmodus entstehen, zum Beispiel: +Der neue Weg entsteht zusätzlich als eigener Modus: - `webdav-placeholder` -Er wird ausdrücklich **neben** den bestehenden Modi entwickelt. +## Ziel des neuen Wegs -### Rahmenbedingungen +Benötigt werden sollen nur: -Der neue Weg darf nur Dinge voraussetzen, die bei einer normalen Piwigo-Installation und der bereits erforderlichen Linux-/PHP-Umgebung vorhanden sind. +- normale Piwigo-Installation; +- bereits vorhandene Linux-/PHP-Umgebung; +- Nextcloud-Adresse; +- Nextcloud-Benutzer bzw. App-Passwort; +- WebDAV-Zugriff auf die Inhalte dieses Benutzers. -Nicht als Voraussetzung zulässig: +Nicht vorausgesetzt werden dürfen: +- PostgreSQL-Zugriff auf Nextcloud; +- `occ`-Adminzugriff; - Rootzugriff des Betreibers; +- Storage-IDs oder Backend-Pfade; - zusätzliche Host-Mounts; - FUSE; - davfs; - rclone; -- zusätzliche Systempakete nur für den Connector; -- PostgreSQL-Zugriff auf die Nextcloud-Datenbank; -- `occ`-Adminzugriff; -- Wissen über Nextcloud-Storage-IDs oder Backend-Pfade. +- zusätzliche Connector-Systempakete. -Benötigt werden sollen nur: +Originalbilder werden nicht dauerhaft nach Piwigo kopiert. -- Nextcloud-Adresse; -- normaler Nextcloud-Benutzer bzw. App-Passwort; -- WebDAV-Zugriff auf genau die Inhalte, die dieser Benutzer sehen darf; -- Piwigo selbst und das Plugin. +## Architektur des WebDAV-Parallelwegs -### Grundidee - -WebDAV wird nicht in einen Linux-Dateipfad umgewandelt. - -Stattdessen: - -1. Das Plugin liest die ausgewählten Nextcloud-Verzeichnisse per WebDAV/PROPFIND. -2. Es erfasst Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad. +1. Ausgewählte Nextcloud-Verzeichnisse werden über WebDAV/PROPFIND gelesen. +2. Das Plugin erfasst Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad. 3. Für jedes Bild wird nur ein winziger lokaler Platzhalter bereitgestellt. -4. Der Shadow Tree behält seine Rolle als Piwigo-Quelle und enthält die reale Ordner-/Dateinamensstruktur. -5. Die Shadow-Tree-Einträge verweisen auf Platzhalter statt auf das Nextcloud-Original. -6. Ein separates Mapping verknüpft Shadow-Tree-Pfad mit Nextcloud-Verbindung, Datei-ID und WebDAV-Pfad. -7. Piwigo soll die Bilder dadurch zunächst als vorhandene physische Einträge erkennen können. -8. Für echte Bilddaten muss das Plugin bei Bedarf das Original über WebDAV lesen. +4. Der bestehende Shadow Tree bleibt die physische Piwigo-Quelle. +5. Der Shadow Tree bildet die reale Ordner- und Dateinamensstruktur ab, seine Bildziele zeigen jedoch auf Platzhalter statt auf Originale. +6. Ein separates Mapping verbindet Shadow-Tree-Pfad, Connection-ID, Nextcloud-Datei-ID und WebDAV-Pfad. +7. Piwigo soll Album und Bild über diese Struktur registrieren. +8. Wenn echte Bilddaten benötigt werden, wird das Original bei Bedarf über WebDAV gelesen. +9. Piwigo-Derivate werden normal lokal unter `_data/i/` gecacht. +10. Das Original bleibt ausschließlich in Nextcloud. -### Anzeige und Derivate +## Bereits vorhandene Bausteine -Ziel ist nicht, Originale dauerhaft nach Piwigo zu kopieren. +### `runtime/lib/build_webdav_placeholder_source.py` -Vorgesehener Ablauf: +- liest WebDAV rekursiv; +- lädt keine Originalbilder herunter; +- erzeugt eine lokale Platzhalterquelle; +- erzeugt Manifest und WebDAV-Mapping; +- verwendet einen nur wenige Dutzend Byte großen Platzhalter. -- Piwigo kennt Album und Bild über Shadow Tree/Platzhalter. -- Wenn ein Piwigo-Derivat noch fehlt, wird das Original einmal über WebDAV gelesen. -- Piwigo erzeugt daraus sein normales lokales Derivat in `_data/i/`. -- Weitere Aufrufe verwenden den vorhandenen Piwigo-Derivat-Cache. -- Das Nextcloud-Original bleibt ausschließlich in Nextcloud. -- Beim tatsächlichen Abruf eines Originals muss die Quelle erneut über WebDAV gelesen werden. +### 0.9.5.6 – Verbindungsschicht begonnen -## Gemessene WebDAV-Performance +Der Parallelweg ist jetzt erstmals als eigener Connection-Typ im Plugin angelegt. -Realer Test vom Piwigo-System auf ein Nextcloud-Bild mit 16.091.204 Byte: +Neu: -Interne Nextcloud-Adresse: +- `include/nc_connector_webdav.inc.php` +- Backend-Aktion `nc_connector_create_webdav_parallel` +- neue Verbindungen dieses Typs erhalten `source_mode=webdav-placeholder`; +- sie werden als `adapter=remote` und zunächst **deaktiviert** gespeichert; +- bestehende Verbindungen werden dabei nicht verändert; +- ausgewählte WebDAV-Wurzeln werden verbindungseigen gespeichert; +- Nextcloud-Basis-URL und Benutzer werden verbindungseigen gespeichert. -- Zeit: **1,829 s** -- Geschwindigkeit: **8.796.915 Byte/s** - -Externe Nextcloud-Adresse: - -- Zeit: **1,865 s** -- Geschwindigkeit: **8.627.524 Byte/s** - -Die externe Verbindung war damit in diesem Test nur ungefähr 2 % langsamer als die interne Verbindung. - -Folgerung für den Plan: - -- WebDAV ist für bedarfsweisen Zugriff auf Originale performant genug, um den Ansatz weiterzuverfolgen. -- Entscheidend ist, dass Piwigo-Derivate normal lokal gecacht werden und WebDAV nicht bei jedem Thumbnail-Aufruf erneut angesprochen wird. - -## Bereits vorhandener WebDAV-Baustein - -`runtime/lib/build_webdav_placeholder_source.py` - -Aufgabe: - -- WebDAV rekursiv lesen; -- keine Originalbilder herunterladen; -- lokale Platzhalterquelle erzeugen; -- Manifest und WebDAV-Mapping erzeugen. - -Dieser Builder ist aktuell nur ein Baustein. Er ist noch nicht als vollständiger Connection-Modus in Wizard, Secret-Speicherung, Reconcile und Runtime integriert. - -## Noch notwendige Umsetzung für `webdav-placeholder` - -### 1. Verbindungstyp rückwärtskompatibel ergänzen - -- neuer eigener `SOURCE_MODE`; -- bestehende drei Modi bleiben unverändert; -- keine automatische Migration alter Verbindungen. - -### 2. Nextcloud-Zugang verbindungseigen speichern - -Der aktuelle Wizard benutzt Nextcloud-Zugangsdaten bereits für WebDAV-Verzeichnisabfragen, speichert sie aber nicht in einer Form, die die spätere Runtime für WebDAV verwenden kann. - -Das Secret-Format muss rückwärtskompatibel erweitert werden um: +Das Secret-Format wurde rückwärtskompatibel auf Version 3 erweitert um: - `nextcloud_user` - `nextcloud_password` -Bestehende Secrets müssen weiterhin lesbar bleiben. +Bestehende v1/v2-Inhalte bleiben lesbar. Neue lokale Wizard-Verbindungen können die Nextcloud-Zugangsdaten ebenfalls mitführen, ohne ihren bisherigen Quellenmodus zu ändern. -### 3. Wizard-Abschluss für WebDAV-Verbindungen +Die verbindungseigene Fallback-Verwaltung wurde so angepasst, dass vorhandene WebDAV-Zugangsdaten bei späteren Secret-Änderungen erhalten bleiben. Für `webdav-placeholder` ist kein `db_password` erforderlich. -Eine neue WebDAV-Verbindung darf keine PostgreSQL- oder Storage-Mount-Pflicht haben. +## Bestehender produktiver Weg -Gespeichert werden müssen mindestens: +Unverändert: -- Connection-Name; -- Nextcloud-Basis-URL; -- Nextcloud-Benutzer; -- verschlüsseltes Nextcloud-Passwort/App-Passwort; -- ausgewählte WebDAV-Wurzeln; -- Piwigo-Galeriepfad; -- Piwigo-Authentifizierung für den Sync, sofern benötigt; -- `source_mode=webdav-placeholder`. +- PostgreSQL-/View-/Storage-Mapping-Logik; +- lokale Symlinks auf bereits vorhandene Originalpfade; +- `runtime/reconcile.php` für bestehende lokale Adapter; +- `runtime/sync.sh` mit `legacy-view`, `user-shares` und `selected-fileids`; +- API-first-Piwigo-Sync; +- gemeinsame Runtime für aktive bestehende Verbindungen. -### 4. Reconcile und Runtime +Die neue WebDAV-Verbindung wird aktuell absichtlich noch nicht von dieser Runtime aktiviert. -`runtime/reconcile.php` muss WebDAV-Verbindungen gesondert behandeln: +## Gemessene WebDAV-Performance -- keine PostgreSQL-Konfiguration verlangen; -- keine Storage-Mappings verlangen; -- WebDAV-Zugang sicher in eine verbindungseigene Runtime-Datei überführen; -- bestehende lokale Verbindungstypen unverändert lassen. +Testbild: 16.091.204 Byte. -`runtime/sync.sh` muss einen eigenen Zweig für `webdav-placeholder` erhalten. +Intern: -### 5. Shadow Tree +- 1,829 s +- 8.796.915 Byte/s -Der bestehende Shadow Tree bleibt erhalten. +Extern: -Der neue Builder muss nur eine Quelle erzeugen, die vom bestehenden `shadow_tree.py` verarbeitet werden kann. Ein kompletter Umbau des Shadow Trees ist nicht vorgesehen. +- 1,865 s +- 8.627.524 Byte/s -### 6. Piwigo-Erkennung testen +Die externe Verbindung war im Test nur ungefähr 2 % langsamer. Der Ansatz bleibt deshalb für bedarfsweisen Originalzugriff geeignet, solange Piwigo-Derivate lokal gecacht werden. -Erster PoC: +## Löschverhalten seit 0.9.5.5 -- kleine neue WebDAV-Testverbindung anlegen; -- einen kleinen ausgewählten Ordner verwenden; -- Platzhalterquelle bauen; -- bestehenden Shadow Tree erzeugen; -- Piwigo synchronisieren; -- prüfen, ob Albumstruktur und Bilder korrekt registriert werden. +Das Löschen einer Connector-Verbindung darf nicht an Dateirechten Root-eigener Runtime-Dateien scheitern. -Der bestehende produktive Connector bleibt währenddessen aktiv und unverändert. +- Datenbankeintrag wird entfernt; +- verwaiste Runtime-Dateien werden vor einem späteren Sync bereinigt; +- andere Verbindungen bleiben unangetastet; +- Nextcloud-Originale und vorhandene Piwigo-Bilder werden nicht gelöscht. -### 7. Echte Bilddaten statt Platzhalter ausliefern +## Nächste Bauphase -Erst wenn Piwigo die Platzhalterstruktur korrekt registriert, wird der zweite Teil umgesetzt: +Der neue Verbindungstyp existiert jetzt parallel. Als Nächstes wird ausschließlich seine Runtime gebaut, ohne die bestehenden drei Modi umzuschreiben. -- Piwigo-Anforderung einem WebDAV-Mapping zuordnen; -- echtes Original bei Bedarf über WebDAV lesen; -- Piwigo-Derivate aus der echten Quelle erzeugen; -- normale Piwigo-Derivate weiterverwenden; -- keine dauerhafte Originalkopie in Piwigo. +Reihenfolge: -### 8. Lastverhalten absichern +1. `runtime/reconcile.php` um einen getrennten Zweig für `adapter=remote` + `source_mode=webdav-placeholder` erweitern. +2. Für diesen Zweig **keine** PostgreSQL- und Storage-Mapping-Prüfung durchführen. +3. Nextcloud-Zugang aus dem verschlüsselten Connection-Secret in eine verbindungseigene, nur für die Runtime lesbare Credential-Datei überführen. +4. WebDAV-Wurzeln mit `webdav_path`, `display_name` und optionaler `fileid` als eigene Runtime-Konfiguration schreiben. +5. `runtime/sync.sh` um einen strikt getrennten `webdav-placeholder`-Zweig erweitern. +6. Dort `build_webdav_placeholder_source.py` aufrufen. +7. Das erzeugte Manifest durch den bestehenden `shadow_tree.py` schicken. +8. Erst dann eine **neue** kleine WebDAV-Testverbindung aktivieren und prüfen, ob Piwigo Albumstruktur und Bilddatensätze korrekt registriert. +9. Bestehende Verbindungen laufen während dieses Tests unverändert weiter. -Vor einer produktiven Umstellung muss geprüft werden: +## Danach – noch nicht umsetzen -- Verhalten bei vielen gleichzeitig noch ungecachten Bildern; -- parallele WebDAV-Abfragen; -- Derivat-Erzeugung; -- Fehlerfall bei nicht erreichbarer Nextcloud; -- geänderte oder gelöschte Remote-Dateien; -- Cache-Invalidierung bei geändertem ETag. +Erst wenn die Registrierung mit Platzhaltern funktioniert: -## Migrationsregel +- echte Bilddaten über WebDAV anfordern; +- Piwigo-Derivate aus echten Originalen erzeugen; +- normalen Derivat-Cache weiterverwenden; +- ETag-basierte Änderungserkennung ergänzen; +- Fehlerfälle und Parallelität testen. -Der bisherige Weg bleibt so lange vollständig erhalten, bis der WebDAV-Weg funktional vollständig ist. +## Voraussetzung vor irgendeinem Umzug -Es gibt bis dahin keine automatische Migration bestehender Verbindungen. - -Erst nach erfolgreichem End-to-End-Test von: +Erfolgreich getestet sein müssen mindestens: - Verbindungsanlage; -- Verzeichnisauswahl; +- WebDAV-Verzeichnisauswahl; - Shadow Tree; - Piwigo-Registrierung; -- echter Bildausgabe; +- echte Bildausgabe; - Derivat-Cache; - Änderungserkennung; - Löschen/Deaktivieren; -- Fehlerbehandlung +- Fehlerbehandlung; +- Verhalten bei vielen noch ungecachten Bildern. -kann über eine freiwillige Migration bestehender Verbindungen entschieden werden. - -## Sicherheit und Datenhaltung - -- Nextcloud-Originale werden nicht gelöscht. -- Nextcloud-Originale werden im neuen WebDAV-Weg nicht dauerhaft nach Piwigo kopiert. -- Lokale Piwigo-Derivate sind ausdrücklich erlaubt und Teil des normalen Piwigo-Caches. -- Connector-Zugangsdaten werden verschlüsselt gespeichert. -- Wizard-Secrets bleiben serverseitig. -- Bestehende Verbindungen bleiben während der Entwicklung unangetastet. -- Mutierende Admin-Aktionen verwenden Post/Redirect/Get. -- Self-Updates sind an einen konkreten Commit und SHA-256 gebunden. - -## Nächster konkreter Entwicklungsschritt - -Rückwärtskompatible Verbindungsschicht für `webdav-placeholder` bauen: - -1. Secret-Format um verbindungseigenen Nextcloud-Zugang erweitern. -2. neuen Source-Modus in Datenmodell/Reconcile/Runtime ergänzen. -3. Wizard so erweitern, dass eine WebDAV-Verbindung ohne PostgreSQL und ohne Storage-Mapping abgeschlossen werden kann. -4. danach eine neue Testverbindung anlegen und den Platzhalter-PoC durch den bestehenden Shadow Tree und Piwigo-Sync schicken. +Erst danach kann eine freiwillige Migration bestehender Verbindungen überhaupt diskutiert werden.