Bring README to current 0.9.5.5 connector architecture

README.md

@@ -2,7 +2,7 @@
 
 Modulares Piwigo-Plugin für Administration, Bildverarbeitung, geschützte Freigaben, Fotoauswahl und die Anbindung von Nextcloud an Piwigo.
 
-Aktuelle Plugin-Version: **0.9.4.4**
+Aktuelle Plugin-Version: **0.9.5.5**
 
 ## Grundprinzip
 
@@ -12,62 +12,102 @@ Für die Administration gilt: Der normale Nutzer sieht Aufgaben, Entscheidungen
 
 ## NC Connector
 
-Der NC Connector synchronisiert ausdrücklich freigegebene Nextcloud-Inhalte mit Piwigo.
+Der NC Connector synchronisiert ausdrücklich ausgewählte Nextcloud-Inhalte mit Piwigo.
 
 ### Datenmodell
 
 - Nextcloud bleibt die Quelle der Originaldateien.
 - Originalbilder werden nicht in eine zweite dauerhafte Bibliothek kopiert.
-- Ein Shadow Tree erzeugt die für Piwigo benötigte Verzeichnisstruktur mit Symlinks.
+- Ein Shadow Tree erzeugt die für Piwigo benötigte Verzeichnisstruktur.
-- Ordnerfreigaben werden als physische Piwigo-Alben synchronisiert.
+- Der bestehende produktive Weg verwendet lokale bereits vorhandene Speicherpfade und Symlinks auf die Originale.
-- Einzeldateifreigaben werden im Galerie-Root verlinkt und als echte Piwigo-Orphans ohne Albumzuordnung registriert.
+- Ordner werden als physische Piwigo-Alben synchronisiert.
-- Entfernte Freigaben werden aus Shadow Tree und Piwigo entfernt, das Nextcloud-Original bleibt erhalten.
+- Root-Dateien können als echte Piwigo-Orphans ohne Albumzuordnung registriert werden.
+- Entfernte Quellen werden aus Shadow Tree und Piwigo entfernt, das Nextcloud-Original bleibt erhalten.
 - Neu importierte physische Connector-Alben werden privat angelegt.
 
+### Bestehende produktive Quellenmodi
+
+Der bestehende Connector unterstützt weiterhin getrennte Quellenmodi:
+
+- `legacy-view`
+- `user-shares`
+- `selected-fileids`
+
+Diese Modi bleiben während der Entwicklung des neuen WebDAV-Wegs vollständig erhalten. Es gibt keine automatische Migration bestehender Verbindungen.
+
 ### Verbindungsassistent
 
 Neue Verbindungen werden bevorzugt mit einem Endnutzer-Assistenten angelegt.
 
-Ablauf:
+Der aktuelle Assistent kann Nextcloud per HTTP/HTTPS und OCS prüfen und Verzeichnisse per WebDAV anzeigen. Für den bestehenden produktiven lokalen Weg existieren weiterhin PostgreSQL-/View-/Storage-Mapping-Schritte, sofern sie benötigt werden.
-
-1. Nextcloud-Adresse, Benutzer und Passwort eingeben.
-2. Der Assistent prüft HTTP/HTTPS, Nextcloud-Status und Anmeldung.
-3. Derselbe in Schritt 1 angegebene Connector-Benutzer und dasselbe Passwort werden auch für den lesenden PostgreSQL-Zugriff verwendet; es gibt im normalen Ablauf keine zweite Benutzer-/Passwortabfrage.
-4. Vorhandene passende Connector-Werte für Host, Port, Datenbank und Storage-Zuordnungen werden wiederverwendet, aber erneut mit dem aktuellen Zugang geprüft.
-5. Nur wenn der übliche PostgreSQL-Weg nicht erreichbar ist, werden abweichende Datenbank-Adresse, Port und Datenbankname gezielt abgefragt. Benutzer und Passwort bleiben dabei die Angaben aus Schritt 1.
-6. Nicht automatisch zuordenbare Storage-Mounts werden einzeln bestätigt.
-7. Danach wird der Nextcloud-Benutzer gewählt, dessen Freigaben verwendet werden sollen. Empfohlen wird ein eigener `showcase`-Benutzer.
-8. Piwigo-API-Zugang testen oder bewusst überspringen.
-9. Optionaler bzw. bei übersprungener API verpflichtender Login-Fallback.
-10. Erst der Abschluss legt die Verbindung dauerhaft an.
 
 Wizard-Geheimnisse werden während der Einrichtung serverseitig in der Sitzung gehalten. Ein fehlgeschlagener Test leert die Eingaben nicht. Ein API-Test verändert die dauerhafte API-Konfiguration erst beim erfolgreichen Abschluss des Assistenten.
 
 Die vollständige technische Maske bleibt weiterhin über **Ohne Assistent anlegen** sowie bei bestehenden Verbindungen unter **Technische Einstellungen** erreichbar.
 
-### Lokaler Adapter
+### Lokaler produktiver Adapter
 
-Der derzeit produktive Adapter verwendet:
+Der derzeit produktive Adapter verwendet je nach bestehender Verbindung:
 
-- PostgreSQL-Reader mit minimalen Leserechten;
+- PostgreSQL-Reader;
-- Source-View `piwigo_showcase_sources`;
+- Source-/Activity-Views;
-- Activity-View `piwigo_showcase_activity`;
 - explizite Storage-Zuordnungen auf bereits vorhandene lokale Mounts;
 - Plugin-eigene Runtime und getrennten State pro Verbindung.
 
-Ein Storage-Mapping besteht aus `storage_id`, einem optionalen `source_prefix` und dem lokalen Mount. Ein leerer Prefix ist zulässig und bedeutet, dass der Mount direkt dem Storage-Root entspricht.
+Dieser Weg bleibt erhalten, bis der neue WebDAV-Weg vollständig End-to-End funktioniert.
+
+### Neuer WebDAV-Weg
+
+Der geplante neue Quellenmodus wird zusätzlich zu den bestehenden Modi entwickelt, vorgesehen als `webdav-placeholder`.
+
+Ziel:
+
+- nur normale Nextcloud-Anmeldung bzw. App-Passwort und WebDAV benötigen;
+- keine Nextcloud-PostgreSQL-Rechte voraussetzen;
+- keine Storage-IDs oder Backend-Pfade voraussetzen;
+- keine zusätzlichen Host-Mounts voraussetzen;
+- kein FUSE, davfs oder rclone voraussetzen;
+- keine Originalbilder dauerhaft nach Piwigo kopieren.
+
+Grundidee:
+
+1. Nextcloud-Verzeichnisse werden über WebDAV/PROPFIND gelesen.
+2. Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad werden erfasst.
+3. Für Bilder wird nur eine winzige lokale Platzhalterquelle erzeugt.
+4. Der bestehende Shadow Tree bildet daraus die reale Ordner-/Dateinamensstruktur für Piwigo.
+5. Ein Mapping verbindet den Piwigo-/Shadow-Tree-Pfad mit der WebDAV-Quelle.
+6. Wenn Piwigo echte Bilddaten benötigt, wird das Original bei Bedarf über WebDAV gelesen.
+7. Piwigo-Derivate werden normal in `_data/i/` gecacht.
+8. Das Original bleibt ausschließlich in Nextcloud.
+
+Der erste experimentelle Baustein dafür ist:
+
+- `runtime/lib/build_webdav_placeholder_source.py`
+
+Dieser Builder ist noch kein vollständiger Connection-Modus. Die Integration in Secret-Speicherung, Wizard, Reconcile und Runtime steht noch aus.
+
+### Gemessene WebDAV-Performance
+
+Ein realer Test mit einem 16.091.204-Byte-Bild ergab vom Piwigo-System:
+
+- interne Nextcloud-Adresse: 1,829 s bei 8.796.915 Byte/s;
+- externe Nextcloud-Adresse: 1,865 s bei 8.627.524 Byte/s.
+
+Damit war die externe Verbindung in diesem Test nur ungefähr 2 % langsamer. Der WebDAV-Ansatz wird deshalb weiterverfolgt. Wichtig bleibt, dass Piwigo-Derivate lokal gecacht werden und WebDAV nicht bei jedem Thumbnail-Aufruf erneut verwendet wird.
 
 ### Activity Gate
 
-Der regelmäßige Lauf berücksichtigt:
+Der bestehende regelmäßige Lauf berücksichtigt:
 
 - Nextcloud-Aktivität;
-- Signatur der sichtbaren Freigaben;
+- Signatur der sichtbaren Quellen;
 - Quiet-Time;
 - maximale Wartezeit;
 - periodischen Full-Sync;
 - notwendigen Reparaturlauf bei beschädigtem Shadow Tree oder fehlenden Piwigo-Alben.
 
+Der neue WebDAV-Modus erhält später eine eigene Änderungserkennung, insbesondere über WebDAV-Metadaten wie ETag.
+
 ### Piwigo-Synchronisierung
 
 Der produktive Lauf ist API-first:
@@ -106,11 +146,25 @@ Bestehende Verbindungen können:
 - technisch bearbeitet, solange sie nicht aktiv sind;
 - deaktiviert und anschließend gelöscht werden.
 
-Das Löschen einer Connector-Verbindung entfernt keine Nextcloud-Originale und keine Piwigo-Bilder. Erreichbare Connector-eigene Status-/State-Daten der Verbindung werden bereinigt.
+Seit 0.9.5.5 hängt das Löschen einer Verbindung nicht mehr davon ab, dass der Webserver in Root-eigene Runtime-Verzeichnisse schreiben kann. Die Datenbankverbindung wird entfernt; verwaiste Runtime-Dateien werden vor einem späteren Sync bereinigt.
 
-### Legacy-Migration
+Das Löschen einer Connector-Verbindung entfernt keine Nextcloud-Originale und keine Piwigo-Bilder.
 
-Für ältere Installationen mit dem früheren separaten `piwigo-sync` existieren weiterhin Migrations-/Cutover-Helfer. Neue Installationen sollen den nativen Connector-Weg verwenden.
+### Migrationsregel für WebDAV
+
+Der bestehende lokale Weg bleibt so lange vollständig erhalten, bis `webdav-placeholder` End-to-End funktioniert.
+
+Vor einer freiwilligen Migration bestehender Verbindungen müssen mindestens erfolgreich getestet sein:
+
+- Verbindungsanlage;
+- Verzeichnisauswahl;
+- Shadow Tree;
+- Piwigo-Registrierung;
+- echte Bildausgabe;
+- Derivat-Cache;
+- Änderungserkennung;
+- Löschen/Deaktivieren;
+- Fehlerbehandlung.
 
 ## Bildcache
 
@@ -187,21 +241,20 @@ Wichtige Dateien und Verzeichnisse:
 - `include/nc_connector.inc.php` – Datenmodell und gemeinsame Connector-Funktionen
 - `include/nc_connector_wizard.inc.php` – Endnutzer-Assistent und Connection-Bearbeitung
 - `include/nc_connector_manage.inc.php` – Credential-Format, Storage-Mappings, Verifikation und Löschen
+- `include/nc_connector_connection_scope.inc.php` – verbindungseigene Authentifizierung und sichere Löschlogik
 - `include/nc_connector_create_api.inc.php` – API-first-Verbindungserstellung
 - `include/nc_connector_piwigo_api.inc.php` – API-Zugang und Fallback-Verwaltung
 - `include/nc_connector_system.inc.php` – Timer- und Laufzeitstatus
 - `include/nc_productive_ws.inc.php` – produktiver Piwigo-Dateisync
 - `include/nc_orphan_ws.inc.php` – Orphan-Synchronisierung
 - `runtime/lib/activity_gate.py` – Activity Gate
-- `runtime/lib/build_manifest.py` – Auflösung der Nextcloud-Freigaben auf Storage-Mounts
+- `runtime/lib/build_manifest.py` – bestehende Auflösung der Nextcloud-Quellen auf Storage-Mounts
+- `runtime/lib/build_selected_manifest.py` – ausgewählte Nextcloud-Datei-IDs auf bestehende Storage-Pfade auflösen
+- `runtime/lib/build_webdav_placeholder_source.py` – experimentelle WebDAV-Platzhalterquelle
 - `runtime/lib/shadow_tree.py` – atomarer Shadow Tree mit Rollback
 - `runtime/lib/piwigo-sync.php` – API-first-Piwigo-Sync mit Fallback
-- `runtime/run-all.sh` – Multi-Connection-Runner
+- `runtime/run-all.sh` – Multi-Connection-Runner und Bereinigung verwaister Runtime-Dateien
 - `runtime/sync.sh` – Ablauf einer Verbindung
-- `nc-connector-install.php` – native Root-Aktivierung
-- `nc-connector-disable.php` – Deaktivierung
-- `nc-connector-normalize.php` – Normalisierung älterer aktiver Verbindungen
-- `nc-connector-*-cleanup/switch/cutover` – Legacy-Migrationshelfer
 - `include/self_update.inc.php` – Self-Updater
 - `include/album_shares.inc.php` – geschützte Albumfreigaben
 - `include/public_selection.inc.php` – Fotoauswahl
@@ -215,14 +268,18 @@ Wichtige Dateien und Verzeichnisse:
 - administrative Schreibaktionen verwenden Piwigos CSRF-Schutz;
 - Connector-Zugangsdaten werden verschlüsselt gespeichert;
 - Wizard-Geheimnisse werden nicht in Browser-Web-Storage persistiert;
-- Storage-Mounts werden explizit zugeordnet und validiert;
+- bestehende lokale Storage-Mounts werden explizit zugeordnet und validiert;
 - SQL-View-Namen werden vor Verwendung validiert;
-- gefährliche technische Pfade sind nicht Teil des normalen Wizard-Happy-Paths;
 - produktive Piwigo-API ist versionsgebunden;
 - Originalbilder werden vom Connector nicht gelöscht;
+- der neue WebDAV-Weg soll Originalbilder nicht dauerhaft lokal speichern;
 - Update-Pakete werden an Commit und Hash gebunden;
-- Root-Helfer prüfen CLI-/Root-Ausführung, bevor sie Systemdienste oder `/etc`-/`/var/lib`-Daten verändern.
+- bestehende Verbindungen bleiben während der WebDAV-Entwicklung unangetastet.
 
 ## Entwicklungsstand
 
-`0.9.4.x` ist der aktuelle Entwicklungsblock. Der lokale NC Connector ist End-to-End produktiv im Einsatz. Der Verbindungsassistent und die Verwaltung werden weiter aus Endnutzersicht konsolidiert. Ein vollständig entfernter Nextcloud-Adapter ohne direkten PostgreSQL-/Storage-Zugriff ist noch nicht umgesetzt.
+`0.9.5.x` ist der aktuelle Entwicklungsblock. Der bestehende lokale NC Connector bleibt produktiv und wird nicht durch den experimentellen WebDAV-Weg ersetzt.
+
+Der nächste konkrete Schritt ist die rückwärtskompatible Verbindungsschicht für `webdav-placeholder`: verbindungseigene Nextcloud-Zugangsdaten speichern, neuen Source-Modus in Wizard/Reconcile/Runtime ergänzen und danach eine neue Testverbindung durch den bestehenden Shadow Tree und Piwigo-Sync schicken.
+
+Den detaillierten aktuellen Plan enthält `CURRENT_STATUS.md`.