Document current connector status and WebDAV migration plan

2026-09-20 01:44:31 +00:00 · 2026-08-18 21:16:56 +02:00
parent c547c9b089
commit 65910375d2
1 changed files with 235 additions and 75 deletions
--- a/CURRENT_STATUS.md
+++ b/CURRENT_STATUS.md
@@ -4,119 +4,279 @@ Stand: 18.08.2026
 ## Plugin
- Aktuelle Plugin-Version: **0.9.4.4**
+- Aktuelle Plugin-Version: **0.9.5.5**
- Aktueller Entwicklungsblock: **NC Connector – Endnutzer-Assistent und Konsolidierung**
+- Aktueller Entwicklungsblock: **NC Connector – WebDAV-basierter Quellenweg bei vollständigem Erhalt des bestehenden produktiven Wegs**
- `0.9.3.43` markiert den abgeschlossenen vorherigen Meilenstein.
+- GitHub ist das führende Repository.
- `0.9.4.x` ist der neue Entwicklungsblock.
+- 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.
+Aktuell vorhandene Quellenmodi:
 - 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.
-## 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.
+## Architektur – unverändert produktiver Weg
 - 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
 - Nextcloud ist Quelle der Originalbilder.
- Piwigo erhält einen Shadow Tree aus Verzeichnissen und Symlinks.
+- Piwigo verwendet einen Shadow Tree unter dem Galeriepfad.
- PostgreSQL-Reader und die Views `piwigo_showcase_sources` / `piwigo_showcase_activity` liefern Quellen und Aktivität.
+- 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;
+- `webdav-placeholder`
 2. bei nicht nutzbarer API gespeicherter Benutzername/Passwort-Fallback;
 3. ohne beide Wege Abbruch mit Fehlerstatus.
-Produktive API-Methoden:
+Er wird ausdrücklich **neben** den bestehenden Modi entwickelt.
- `bratonien.nc.syncProductive`
+### Rahmenbedingungen
 - `bratonien.nc.syncOrphans`
-`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;
+Benötigt werden sollen nur:
 - Share-Fingerprint;
 - Quiet-Time;
 - Max-Wartezeit;
 - periodischen Full-Sync;
 - Reparaturbedarf bei beschädigter lokaler Struktur.
-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.
+- Bestehende Verbindungen bleiben während der Entwicklung unangetastet.
- SQL-View-Namen werden validiert.
+- Mutierende Admin-Aktionen verwenden Post/Redirect/Get.
 - Piwigo-API ist versionsgebunden.
 - Mutierende Admin-Aktionen verwenden Post/Redirect/Get, sodass Browser-Reloads sie nicht erneut ausführen.
 - 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;
+Rückwärtskompatible Verbindungsschicht für `webdav-placeholder` bauen:
 - weitere Bereinigung alter Legacy-Migrationshelfer, sobald sie nicht mehr benötigt werden;
 - weitere Endnutzer-Optimierung des Assistenten auf Basis realer Fehler- und Installationspfade.
-## Repository-Fallback
+1. Secret-Format um verbindungseigenen Nextcloud-Zugang erweitern.
-
+2. neuen Source-Modus in Datenmodell/Reconcile/Runtime ergänzen.
-GitHub bleibt das führende Repository. Das private Gitea-System dient weiterhin als Mirror/Fallback.
+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.