chore: update staging branch with current changes
This commit is contained in:
155
src/Framework/Storage/STREAMING_IMPLEMENTATION_PLAN.md
Normal file
155
src/Framework/Storage/STREAMING_IMPLEMENTATION_PLAN.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# Streaming-Implementationsliste (Option 2) – Storage Modul
|
||||
|
||||
Ziel: Dedizierte Streaming-Methoden in der Object Storage API implementieren – ohne externe Dependencies. Fokus auf speichereffiziente Downloads/Uploads großer Dateien via Streams (memory-safe).
|
||||
|
||||
## 1) Interface-Erweiterung (ObjectStorage)
|
||||
- Ergänze folgende Methoden im ObjectStorage-Interface:
|
||||
- get(string $bucket, string $key): string
|
||||
- put(string $bucket, string $key, string|mixed $body, array $opts = []): ObjectInfo
|
||||
- getToStream(string $bucket, string $key, mixed $destination): int
|
||||
- Erwartet eine schreibbare PHP-Stream-Resource als $destination
|
||||
- Rückgabewert: Anzahl geschriebener Bytes
|
||||
- putFromStream(string $bucket, string $key, mixed $source, array $opts = []): ObjectInfo
|
||||
- Erwartet eine lesbare PHP-Stream-Resource als $source
|
||||
- openReadStream(string $bucket, string $key)
|
||||
- Gibt eine lesbare PHP-Stream-Resource zurück
|
||||
- head(string $bucket, string $key): ObjectInfo
|
||||
- delete(string $bucket, string $key): void
|
||||
- exists(string $bucket, string $key): bool
|
||||
- url(string $bucket, string $key): ?string
|
||||
- temporaryUrl(string $bucket, string $key, \DateInterval $ttl, array $opts = []): string
|
||||
|
||||
Hinweise:
|
||||
- Signaturen mit mixed für Stream-Parameter (PHP-Resource), genaue Validierung in den Implementierungen.
|
||||
- Bestehende Methoden get/put bleiben kompatibel; Streaming ist ergänzend.
|
||||
|
||||
## 2) Filesystem-Adapter (lokales Backend)
|
||||
Ziel: ObjectStorage-Implementierung auf Basis des bestehenden Filesystem-Backends.
|
||||
|
||||
- Neue Klasse: src/Framework/Storage/FilesystemObjectStorage.php
|
||||
- Verantwortlichkeiten:
|
||||
- Pfadaufbau: basePath/bucket/key
|
||||
- get/put über Filesystem (kleine Dateien)
|
||||
- Streaming:
|
||||
- getToStream: Datei lesen und via stream_copy_to_stream in $destination schreiben
|
||||
- putFromStream: Stream-Inhalt in Datei schreiben (Chunked Copy)
|
||||
- openReadStream: lesbaren Stream auf die Datei öffnen
|
||||
- head/exists/delete/url/temporaryUrl:
|
||||
- head: Dateigröße, mtime, mimetype (falls verfügbar)
|
||||
- url: für lokales Storage in der Regel null (oder optionaler lokaler URL-Generator)
|
||||
- temporaryUrl: nicht unterstützt -> Exception oder leer lassen mit Doku
|
||||
- Fehlerbehandlung:
|
||||
- File not found, Permission, Read/Write-Errors sauber abbilden
|
||||
- Performance:
|
||||
- Buffersize bei stream_copy_to_stream kontrollierbar machen (Optionen)
|
||||
|
||||
## 3) MinIO-Backend (ohne Dependencies)
|
||||
Ziel: S3-kompatibler MinIO-Client mittels nativer PHP-Funktionen (HTTP-Streams und AWS SigV4) + ObjectStorage-Adapter.
|
||||
|
||||
- Dateien:
|
||||
- src/Framework/Storage/Clients/MinioClient.php
|
||||
- Funktionen: putObject, getObject, headObject, deleteObject, createPresignedUrl
|
||||
- Streaming-Funktionen:
|
||||
- getObjectToStream($bucket, $key, $destination): int
|
||||
- putObjectFromStream($bucket, $key, $source, array $opts = []): array
|
||||
- openStream($bucket, $key) -> resource
|
||||
- Interne Helfer:
|
||||
- AWS SigV4 Signierung (kanonische Anfrage, Header, Query, Hashes)
|
||||
- Response-Parsing (Headers, Status, Fehler-XML)
|
||||
- Chunked Transfer wenn keine Content-Length verfügbar
|
||||
- src/Framework/Storage/MinioObjectStorage.php
|
||||
- Implementiert ObjectStorage
|
||||
- get/put: kleinere Dateien
|
||||
- getToStream/putFromStream/openReadStream: nutzen die Streaming-APIs des MinioClient
|
||||
- head/delete/exists/url/temporaryUrl:
|
||||
- temporaryUrl via createPresignedUrl
|
||||
- Sicherheit:
|
||||
- TTL-Limits für temporaryUrl (z. B. max 24h)
|
||||
- Path-Style vs. Virtual Host Style konfigurierbar
|
||||
- Keine externen Pakete
|
||||
|
||||
## 4) Manager/Factory/DI
|
||||
- Option A: StorageManager für ObjectStorage-Driver (local/minio)
|
||||
- src/Framework/Storage/StorageManager.php
|
||||
- driver(string $name): ObjectStorage
|
||||
- bucket(string $name): Bucket (Convenience)
|
||||
- Option B (einfach): Container-Bindings direkt
|
||||
- Default ObjectStorage anhand ENV
|
||||
- Initializer:
|
||||
- src/Framework/Storage/StorageInitializer.php
|
||||
- Konfig aus ENV (DEFAULT_DRIVER, MINIO_ENDPOINT, KEYS, LOCAL_ROOT, PATH_STYLE etc.)
|
||||
- Registriere:
|
||||
- FilesystemObjectStorage (als "local")
|
||||
- MinioClient + MinioObjectStorage (als "minio")
|
||||
- ObjectStorage (Default: ENV)
|
||||
- Bucket-API (optional aber DX-freundlich):
|
||||
- src/Framework/Storage/Bucket.php
|
||||
- wrappt ObjectStorage für festen Bucket-Namen
|
||||
|
||||
## 5) Konfiguration
|
||||
- ENV Variablen vorschlagen (Beispiele):
|
||||
- STORAGE_DRIVER=local|minio
|
||||
- STORAGE_LOCAL_ROOT=/var/www/html/storage/objects
|
||||
- MINIO_ENDPOINT=http://minio:9000
|
||||
- MINIO_ACCESS_KEY=...
|
||||
- MINIO_SECRET_KEY=...
|
||||
- MINIO_REGION=us-east-1
|
||||
- MINIO_USE_PATH_STYLE=true
|
||||
- StorageConfig Klasse (optional) für strukturierte Konfig-Verwaltung
|
||||
|
||||
## 6) Tests (kritisch, da streaming-sensitiv)
|
||||
- Unit-Tests FilesystemObjectStorage:
|
||||
- put/get mit Strings
|
||||
- putFromStream/getToStream mit temp Streams (php://temp)
|
||||
- openReadStream und sequentielles Lesen
|
||||
- head/exists/delete
|
||||
- Unit-Tests MinioClient (Signierung) – isoliert:
|
||||
- Signatur-Konsistenz (Golden Master)
|
||||
- Parsing von Fehlern/Headers
|
||||
- Integration-Tests (optional, per docker-compose mit MinIO):
|
||||
- Upload/Download großer Dateien (z. B. >100MB) per Streams
|
||||
- temporaryUrl Zugriff (GET) mit TTL
|
||||
- Edge Cases:
|
||||
- fehlende Read-/Write-Berechtigungen (Filesystem)
|
||||
- Netzwerkfehler (MinIO)
|
||||
- Nicht existierende Objekte
|
||||
- Streams ohne bekannte Länge (Chunked Transfer)
|
||||
|
||||
## 7) Fehler- und Ausnahmebehandlung
|
||||
- Konsistente Exceptions im Storage-Namespace (z. B. StorageException)
|
||||
- Filesystem-spezifische Fehler sauber mappen
|
||||
- Aussagekräftige Meldungen (inkl. Pfad/Bucket/Key)
|
||||
|
||||
## 8) Performance/Robustheit
|
||||
- Stream-Buffer konfigurierbar (z. B. 8192 Bytes Default)
|
||||
- Keine vollständigen Dateiladungen in Memory bei Streams
|
||||
- Zeitouts/Retry-Strategie (MinIO) minimal vorsehen (optional)
|
||||
- Sauberes Schließen aller Streams (try/finally)
|
||||
|
||||
## 9) Sicherheit
|
||||
- Path-Sanitizing im Filesystem-Adapter (keine Directory-Traversal)
|
||||
- Eindeutige Handhabung von public URL vs. presigned URL
|
||||
- Limitierung der Presign-Dauer und Validierung von Eingaben
|
||||
|
||||
## 10) Dokumentation
|
||||
- README/HowTo:
|
||||
- Beispiel für lokale und MinIO-Nutzung
|
||||
- Beispiele für Streaming (Upload/Download)
|
||||
- Hinweise zu großen Dateien, Memory-Effizienz
|
||||
- PHPDoc ausführlich an allen Public-APIs
|
||||
|
||||
## 11) Milestones (Reihenfolge)
|
||||
1. Interface-Änderungen (ObjectStorage)
|
||||
2. FilesystemObjectStorage (inkl. Streaming)
|
||||
3. MinioClient (Basis + Signierung)
|
||||
4. MinioObjectStorage (inkl. Streaming)
|
||||
5. Initializer/DI und Konfig
|
||||
6. Tests (Unit), danach optional Integration
|
||||
7. Doku + Beispiele
|
||||
|
||||
## 12) Definition of Done
|
||||
- Alle neuen Methoden implementiert und getestet
|
||||
- Große Dateien via Streams funktionieren, ohne OOM
|
||||
- Kein externer Dependency-Einsatz
|
||||
- Doku und Beispiele vorhanden
|
||||
- CI-Tests grün (Unit; Integration optional)
|
||||
Reference in New Issue
Block a user