Document current connector status and WebDAV migration plan

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.