diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index e9301cd..54563e3 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -4,119 +4,279 @@ Stand: 18.08.2026 ## Plugin -- Aktuelle Plugin-Version: **0.9.4.4** -- Aktueller Entwicklungsblock: **NC Connector – Endnutzer-Assistent und Konsolidierung** -- `0.9.3.43` markiert den abgeschlossenen vorherigen Meilenstein. -- `0.9.4.x` ist der neue Entwicklungsblock. +- Aktuelle Plugin-Version: **0.9.5.5** +- Aktueller Entwicklungsblock: **NC Connector – WebDAV-basierter Quellenweg bei vollständigem Erhalt des bestehenden produktiven Wegs** +- GitHub ist das führende Repository. +- Das private Gitea-System bleibt Mirror/Fallback. ## Produktiver Stand -Der lokale NC Connector ist im aktuellen Bratonien-Einsatz End-to-End funktionsfähig: +Der bestehende lokale NC Connector bleibt vollständig erhalten und ist weiterhin der produktive Referenzweg. -- Nextcloud-Freigaben `folder` und `file` werden verarbeitet. -- Ordnerfreigaben werden als physische Piwigo-Alben synchronisiert. -- Einzeldateifreigaben werden als echte Piwigo-Orphans ohne Albumzuordnung registriert. -- Entfernte Freigaben werden aus Piwigo entfernt, Originaldateien bleiben erhalten. -- Neue physische Connector-Alben werden privat angelegt. -- API-first-Synchronisierung ist produktiv für Piwigo **16.4.0** freigegeben. -- Piwigo-Album- und Fotoinformationen werden nach dem direkten Sync aktualisiert. -- Der gemeinsame systemd-Timer verarbeitet aktive Verbindungen regelmäßig. +Aktuell vorhandene Quellenmodi: -## 0.9.4.1 +- `legacy-view` +- `user-shares` +- `selected-fileids` -Die Statusaktualisierung im Admin-UI wurde von Seiten-Reload auf gezielte DOM-Aktualisierung umgestellt. Der Poller aktualisiert nur noch **Letzter Lauf** und **Nächster Lauf**. Offene Dialoge, Details und der Assistent bleiben dadurch erhalten. +Diese Modi dürfen durch die neue WebDAV-Entwicklung weder automatisch migriert noch deaktiviert, überschrieben oder in ihrer Laufzeitlogik verändert werden. -## 0.9.4.2 +Der bestehende Connector kann weiterhin: -### Verbindungsassistent +- 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. -Der Assistent wurde aus Endnutzersicht konsolidiert. Technische Werte werden nur gezielt abgefragt, wenn eine automatische Prüfung sie nicht bestätigen kann. +## 0.9.5.4 -### Storage-Mappings +- 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. -Das Storage-Format erlaubt einen leeren `source_prefix`. Damit kann ein kompletter Storage direkt auf einen lokalen Mount zeigen. +## 0.9.5.5 -### Native Aktivierung +Das Löschen von Connector-Verbindungen wurde gegen unterschiedliche Dateibesitzer zwischen Webserver und Runtime abgesichert. -`nc-connector-install.php` unterstützt API-only-Verbindungen ohne dauerhaft gespeicherten Login-Fallback. Ein Fallback ist nur nötig, wenn keine nutzbare API gespeichert ist. +Vorher konnte das Löschen scheitern, wenn PHP keinen Tombstone im Connector-Statusverzeichnis anlegen durfte. Jetzt gilt: -## 0.9.4.3 +- 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. -- Syntaxfehler im Wizard-Abschluss korrigiert. -- Neue Wizard-Durchläufe werden von alten serverseitigen Zuständen getrennt. -- Abbrechen und Schließen verwerfen den laufenden Wizard-State. - -## 0.9.4.4 - -Der Connector-Benutzer aus Schritt 1 ist zugleich der lesende Datenbank-Benutzer. Der Assistent fragt deshalb Benutzername und Passwort nicht erneut ab. - -Ablauf: - -1. Nextcloud-Adresse + Connector-Benutzer + Passwort. -2. Web-Zugang und OCS werden geprüft. -3. Derselbe Benutzer und dasselbe Passwort werden automatisch für PostgreSQL verwendet. -4. Der Assistent prüft den üblichen Weg mit Nextcloud-Host, Port 5432 und Datenbank `nextcloud` bzw. bekannte passende Verbindungswerte. -5. Nur wenn die Datenbank dort nicht erreichbar ist, werden Host, Port und Datenbankname abgefragt. Benutzer und Passwort bleiben unverändert aus Schritt 1. -6. Danach folgen gegebenenfalls Storage-Zuordnung, Showcase-Benutzer, Piwigo-API und Fallback. - -Die PHP-Datei `include/nc_connector_wizard.inc.php` wurde vor dem Versionsbump mit dem PHP-Parser geprüft. - -## Architektur NC Connector +## Architektur – unverändert produktiver Weg - Nextcloud ist Quelle der Originalbilder. -- Piwigo erhält einen Shadow Tree aus Verzeichnissen und Symlinks. -- PostgreSQL-Reader und die Views `piwigo_showcase_sources` / `piwigo_showcase_activity` liefern Quellen und Aktivität. +- 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` -## Piwigo-Synchronisierung +## Neuer WebDAV-Weg – Zielbild -Priorität: +Der neue Weg soll als zusätzlicher eigener Quellenmodus entstehen, zum Beispiel: -1. gespeicherter Piwigo-API-Key; -2. bei nicht nutzbarer API gespeicherter Benutzername/Passwort-Fallback; -3. ohne beide Wege Abbruch mit Fehlerstatus. +- `webdav-placeholder` -Produktive API-Methoden: +Er wird ausdrücklich **neben** den bestehenden Modi entwickelt. -- `bratonien.nc.syncProductive` -- `bratonien.nc.syncOrphans` +### Rahmenbedingungen -`bratonien.nc.syncProductive` ist auf Piwigo 16.4.0 versionsgebunden. Der direkte Sync verwendet Bratonien-eigene Logik auf Basis der Piwigo-Core-Funktionen, nicht das Rendern oder Fernsteuern einer Admin-Seite. +Der neue Weg darf nur Dinge voraussetzen, die bei einer normalen Piwigo-Installation und der bereits erforderlichen Linux-/PHP-Umgebung vorhanden sind. -## Activity Gate und Shadow Tree +Nicht als Voraussetzung zulässig: -Das Activity Gate berücksichtigt: +- Rootzugriff des Betreibers; +- 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. -- Aktivitätsstand; -- Share-Fingerprint; -- Quiet-Time; -- Max-Wartezeit; -- periodischen Full-Sync; -- Reparaturbedarf bei beschädigter lokaler Struktur. +Benötigt werden sollen nur: -Der Shadow-Tree-Wechsel besitzt einen Rollback auf den vorherigen Baum, falls das Umschalten fehlschlägt. +- Nextcloud-Adresse; +- normaler Nextcloud-Benutzer bzw. App-Passwort; +- WebDAV-Zugriff auf genau die Inhalte, die dieser Benutzer sehen darf; +- Piwigo selbst und das Plugin. -## Sicherheit +### 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. +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. + +### Anzeige und Derivate + +Ziel ist nicht, Originale dauerhaft nach Piwigo zu kopieren. + +Vorgesehener Ablauf: + +- 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. + +## Gemessene WebDAV-Performance + +Realer Test vom Piwigo-System auf ein Nextcloud-Bild mit 16.091.204 Byte: + +Interne Nextcloud-Adresse: + +- 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: + +- `nextcloud_user` +- `nextcloud_password` + +Bestehende Secrets müssen weiterhin lesbar bleiben. + +### 3. Wizard-Abschluss für WebDAV-Verbindungen + +Eine neue WebDAV-Verbindung darf keine PostgreSQL- oder Storage-Mount-Pflicht haben. + +Gespeichert werden müssen mindestens: + +- 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`. + +### 4. Reconcile und Runtime + +`runtime/reconcile.php` muss WebDAV-Verbindungen gesondert behandeln: + +- keine PostgreSQL-Konfiguration verlangen; +- keine Storage-Mappings verlangen; +- WebDAV-Zugang sicher in eine verbindungseigene Runtime-Datei überführen; +- bestehende lokale Verbindungstypen unverändert lassen. + +`runtime/sync.sh` muss einen eigenen Zweig für `webdav-placeholder` erhalten. + +### 5. Shadow Tree + +Der bestehende Shadow Tree bleibt erhalten. + +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. + +### 6. Piwigo-Erkennung testen + +Erster PoC: + +- 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. + +Der bestehende produktive Connector bleibt währenddessen aktiv und unverändert. + +### 7. Echte Bilddaten statt Platzhalter ausliefern + +Erst wenn Piwigo die Platzhalterstruktur korrekt registriert, wird der zweite Teil umgesetzt: + +- 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. + +### 8. Lastverhalten absichern + +Vor einer produktiven Umstellung muss geprüft werden: + +- 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. + +## Migrationsregel + +Der bisherige Weg bleibt so lange vollständig erhalten, bis der WebDAV-Weg funktional vollständig ist. + +Es gibt bis dahin keine automatische Migration bestehender Verbindungen. + +Erst nach erfolgreichem End-to-End-Test von: + +- Verbindungsanlage; +- Verzeichnisauswahl; +- Shadow Tree; +- Piwigo-Registrierung; +- echter Bildausgabe; +- Derivat-Cache; +- Änderungserkennung; +- Löschen/Deaktivieren; +- Fehlerbehandlung + +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. -- Storage-Pfade werden validiert. -- SQL-View-Namen werden validiert. -- Piwigo-API ist versionsgebunden. -- Mutierende Admin-Aktionen verwenden Post/Redirect/Get, sodass Browser-Reloads sie nicht erneut ausführen. +- 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. -## Noch offen +## Nächster konkreter Entwicklungsschritt -- vollständiger Remote-Nextcloud-Adapter ohne direkten PostgreSQL-/Storage-Zugriff; -- weitere Bereinigung alter Legacy-Migrationshelfer, sobald sie nicht mehr benötigt werden; -- weitere Endnutzer-Optimierung des Assistenten auf Basis realer Fehler- und Installationspfade. +Rückwärtskompatible Verbindungsschicht für `webdav-placeholder` bauen: -## Repository-Fallback - -GitHub bleibt das führende Repository. Das private Gitea-System dient weiterhin als Mirror/Fallback. +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.