fix: DockerSecretsResolver - don't normalize absolute paths like /var/www/html/...

2025-11-24 21:28:25 +01:00
parent 4eb7134853
commit 77abc65cd7
1327 changed files with 91915 additions and 9909 deletions
--- a/docs/livecomponents/implementation-plan-testing-docs-middleware.md
+++ b/docs/livecomponents/implementation-plan-testing-docs-middleware.md
@@ -0,0 +1,521 @@
+# Implementation Plan: Testing Infrastructure, Documentation & Middleware Support
+
+## Übersicht
+
+Dieser Plan umfasst drei große Bereiche:
+1. **Test Infrastructure** - Verbesserte Test-Harness und Testing-Tools
+2. **Documentation** - Vollständige Dokumentation für alle LiveComponents Features
+3. **Middleware Support** - Component-Level Middleware für flexible Request/Response Transformation
+
+---
+
+## Phase 1: Test Infrastructure Verbesserung
+
+### 1.1 LiveComponentTestCase Base Class
+
+**Ziel**: Zentrale Test-Base-Class mit allen Helpers für einfache Component-Tests
+
+**Datei**: `tests/Feature/Framework/LiveComponents/TestHarness/LiveComponentTestCase.php`
+
+**Features**:
+- `mount(string $componentId, array $initialData = [])` - Component mounten
+- `call(string $action, array $params = [])` - Action aufrufen
+- `seeHtmlHas(string $needle)` - HTML-Assertion
+- `seeStateEquals(array $expectedState)` - State-Assertion
+- `seeStateKey(string $key, mixed $value)` - Einzelne State-Key-Assertion
+- `seeEventDispatched(string $eventName, ?array $payload = null)` - Event-Assertion
+- `seeFragment(string $fragmentName, string $content)` - Fragment-Assertion
+- `assertComponent(LiveComponentContract $component)` - Component-Instance-Assertion
+
+**Architektur**:
+```php
+abstract class LiveComponentTestCase extends TestCase
+{
+    protected ComponentRegistry $registry;
+    protected LiveComponentHandler $handler;
+    protected LiveComponentRenderer $renderer;
+    protected ?LiveComponentContract $currentComponent = null;
+    
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->registry = container()->get(ComponentRegistry::class);
+        $this->handler = container()->get(LiveComponentHandler::class);
+        $this->renderer = container()->get(LiveComponentRenderer::class);
+    }
+    
+    protected function mount(string $componentId, array $initialData = []): self
+    {
+        $this->currentComponent = $this->registry->resolve(
+            ComponentId::fromString($componentId),
+            $initialData
+        );
+        return $this;
+    }
+    
+    protected function call(string $action, array $params = []): self
+    {
+        // Action ausführen und Component aktualisieren
+        return $this;
+    }
+    
+    protected function seeHtmlHas(string $needle): self
+    {
+        $html = $this->renderer->render($this->currentComponent);
+        expect($html)->toContain($needle);
+        return $this;
+    }
+    
+    // ... weitere Helper-Methoden
+}
+```
+
+### 1.2 Snapshot Testing
+
+**Ziel**: Render-Ausgabe als Snapshots speichern und vergleichen
+
+**Datei**: `tests/Feature/Framework/LiveComponents/TestHarness/ComponentSnapshotTest.php`
+
+**Features**:
+- Whitespace-normalisierte Snapshots
+- Automatische Snapshot-Generierung
+- Snapshot-Vergleich mit Diff-Output
+- Snapshot-Update-Modus für Refactoring
+
+**Usage**:
+```php
+it('renders counter component correctly', function () {
+    $component = mountComponent('counter:test', ['count' => 5]);
+    
+    expect($component['html'])->toMatchSnapshot('counter-initial-state');
+});
+```
+
+### 1.3 Contract Compliance Tests
+
+**Ziel**: Automatische Tests für Interface-Compliance
+
+**Datei**: `tests/Feature/Framework/LiveComponents/ContractComplianceTest.php`
+
+**Tests**:
+- `Pollable` Interface Compliance
+- `Cacheable` Interface Compliance
+- `Uploadable` Interface Compliance
+- `LifecycleAware` Interface Compliance
+- `SupportsSlots` Interface Compliance
+
+**Features**:
+- Reflection-basierte Interface-Checks
+- Method-Signature-Validierung
+- Return-Type-Validierung
+- Required-Method-Checks
+
+### 1.4 Security Tests
+
+**Ziel**: Umfassende Security-Tests für alle Security-Features
+
+**Datei**: `tests/Feature/Framework/LiveComponents/SecurityTest.php`
+
+**Tests**:
+- CSRF Protection Tests
+- Rate Limiting Tests
+- Idempotency Tests
+- Action Allow-List Tests
+- Authorization Tests (`#[RequiresPermission]`)
+
+**Features**:
+- Test für alle Security-Patterns
+- Edge-Case-Tests (Token-Manipulation, etc.)
+- Integration-Tests mit echten Requests
+
+### 1.5 E2E Tests
+
+**Ziel**: End-to-End Tests für komplexe Szenarien
+
+**Datei**: `tests/e2e/livecomponents/`
+
+**Tests**:
+- Partial Rendering E2E
+- Batch Operations E2E
+- SSE Reconnect E2E
+- Upload Chunking E2E
+- Island Loading E2E
+- Lazy Loading E2E
+
+**Tools**:
+- Playwright für Browser-Tests
+- Real HTTP Requests
+- Component-Interaction-Tests
+
+---
+
+## Phase 2: Documentation Vervollständigung
+
+### 2.1 End-to-End Guide
+
+**Datei**: `docs/livecomponents/end-to-end-guide.md`
+
+**Inhalte**:
+- Component erstellen (von Grund auf)
+- RenderData definieren
+- Actions implementieren
+- Events dispatchen
+- State Management
+- Caching konfigurieren
+- Fragments verwenden
+- Slots nutzen
+- Lifecycle Hooks
+- Best Practices
+
+**Struktur**:
+1. Quick Start (5 Minuten)
+2. Component Basics
+3. State Management
+4. Actions & Events
+5. Advanced Features
+6. Performance Optimization
+7. Real-World Examples
+
+### 2.2 Security Guide
+
+**Datei**: `docs/livecomponents/security-guide-complete.md`
+
+**Inhalte**:
+- CSRF Protection (wie es funktioniert, Best Practices)
+- Rate Limiting (Konfiguration, Custom Limits)
+- Idempotency (Use Cases, Implementation)
+- Action Allow-List (Security-Pattern)
+- Authorization (`#[RequiresPermission]`)
+- Input Validation
+- XSS Prevention
+- Secure State Management
+
+**Beispiele**:
+- Secure Component Patterns
+- Common Security Pitfalls
+- Security Checklist
+
+### 2.3 Performance Guide
+
+**Datei**: `docs/livecomponents/performance-guide-complete.md`
+
+**Inhalte**:
+- Caching Strategies (varyBy, SWR)
+- Request Batching
+- Debounce/Throttle Patterns
+- Lazy Loading Best Practices
+- Island Components für Performance
+- Fragment Updates
+- SSE Optimization
+- Memory Management
+
+**Beispiele**:
+- Performance-Optimierte Components
+- Benchmarking-Strategien
+- Performance Checklist
+
+### 2.4 Upload Guide
+
+**Datei**: `docs/livecomponents/upload-guide-complete.md`
+
+**Inhalte**:
+- File Upload Basics
+- Validation Patterns
+- Chunked Uploads
+- Progress Tracking
+- Quarantine System
+- Virus Scanning Integration
+- Error Handling
+- Security Considerations
+
+**Beispiele**:
+- Image Upload Component
+- Large File Upload
+- Multi-File Upload
+
+### 2.5 DevTools/Debugging Guide
+
+**Datei**: `docs/livecomponents/devtools-debugging-guide.md`
+
+**Inhalte**:
+- DevTools Overlay verwenden
+- Component Inspector
+- Action Logging
+- Event Monitoring
+- Network Timeline
+- Performance Profiling
+- Debugging-Tipps
+- Common Issues & Solutions
+
+### 2.6 API Reference
+
+**Datei**: `docs/livecomponents/api-reference-complete.md`
+
+**Inhalte**:
+- Alle Contracts (LiveComponentContract, Pollable, Cacheable, etc.)
+- Alle Attributes (`#[LiveComponent]`, `#[Action]`, `#[Island]`, etc.)
+- Alle Controller-Endpoints
+- Alle Value Objects
+- JavaScript API
+- Events API
+
+**Format**:
+- Vollständige Method-Signatures
+- Parameter-Beschreibungen
+- Return-Types
+- Examples für jede Methode
+
+---
+
+## Phase 3: Middleware Support
+
+### 3.1 Component Middleware Interface
+
+**Ziel**: Interface für Component-Level Middleware
+
+**Datei**: `src/Framework/LiveComponents/Middleware/ComponentMiddlewareInterface.php`
+
+**Interface**:
+```php
+interface ComponentMiddlewareInterface
+{
+    public function handle(
+        LiveComponentContract $component,
+        string $action,
+        ActionParameters $params,
+        callable $next
+    ): ComponentUpdate;
+}
+```
+
+### 3.2 Middleware Attribute
+
+**Ziel**: Attribute zum Registrieren von Middleware auf Component-Level
+
+**Datei**: `src/Framework/LiveComponents/Attributes/Middleware.php`
+
+**Usage**:
+```php
+#[LiveComponent('user-profile')]
+#[Middleware(LoggingMiddleware::class)]
+#[Middleware(CachingMiddleware::class, priority: 10)]
+final readonly class UserProfileComponent implements LiveComponentContract
+{
+}
+```
+
+### 3.3 Built-in Middleware
+
+**Ziel**: Standard-Middleware für häufige Use Cases
+
+**Middleware**:
+1. **LoggingMiddleware** - Action-Logging
+2. **CachingMiddleware** - Response-Caching
+3. **RateLimitMiddleware** - Component-Level Rate Limiting
+4. **ValidationMiddleware** - Input-Validation
+5. **TransformMiddleware** - Request/Response Transformation
+
+**Dateien**:
+- `src/Framework/LiveComponents/Middleware/LoggingMiddleware.php`
+- `src/Framework/LiveComponents/Middleware/CachingMiddleware.php`
+- `src/Framework/LiveComponents/Middleware/RateLimitMiddleware.php`
+- `src/Framework/LiveComponents/Middleware/ValidationMiddleware.php`
+- `src/Framework/LiveComponents/Middleware/TransformMiddleware.php`
+
+### 3.4 Middleware Pipeline
+
+**Ziel**: Middleware-Pipeline für Component Actions
+
+**Datei**: `src/Framework/LiveComponents/Middleware/ComponentMiddlewarePipeline.php`
+
+**Features**:
+- Middleware-Stack-Verwaltung
+- Priority-basierte Ausführung
+- Request/Response Transformation
+- Error Handling in Middleware
+
+**Architektur**:
+```php
+final readonly class ComponentMiddlewarePipeline
+{
+    public function __construct(
+        private array $middlewares
+    ) {}
+    
+    public function process(
+        LiveComponentContract $component,
+        string $action,
+        ActionParameters $params
+    ): ComponentUpdate {
+        // Execute middleware stack
+    }
+}
+```
+
+### 3.5 Middleware Integration
+
+**Ziel**: Integration in LiveComponentHandler
+
+**Datei**: `src/Framework/LiveComponents/LiveComponentHandler.php`
+
+**Änderungen**:
+- Middleware-Discovery aus Component-Attributes
+- Middleware-Pipeline vor Action-Execution
+- Middleware-Configuration aus Metadata
+
+### 3.6 Middleware Tests
+
+**Ziel**: Umfassende Tests für Middleware-System
+
+**Dateien**:
+- `tests/Unit/Framework/LiveComponents/Middleware/ComponentMiddlewarePipelineTest.php`
+- `tests/Unit/Framework/LiveComponents/Middleware/LoggingMiddlewareTest.php`
+- `tests/Unit/Framework/LiveComponents/Middleware/CachingMiddlewareTest.php`
+- `tests/Feature/Framework/LiveComponents/MiddlewareIntegrationTest.php`
+
+---
+
+## Implementierungsreihenfolge
+
+### Sprint 1: Test Infrastructure (Woche 1-2)
+1. LiveComponentTestCase Base Class
+2. Snapshot Testing
+3. Contract Compliance Tests
+4. Security Tests (Basis)
+
+### Sprint 2: Documentation Phase 1 (Woche 3)
+1. End-to-End Guide
+2. Security Guide
+3. Performance Guide
+
+### Sprint 3: Middleware Support (Woche 4-5)
+1. ComponentMiddlewareInterface
+2. Middleware Attribute
+3. Middleware Pipeline
+4. Built-in Middleware (Logging, Caching)
+
+### Sprint 4: Documentation Phase 2 & Testing Completion (Woche 6)
+1. Upload Guide
+2. DevTools Guide
+3. API Reference
+4. E2E Tests
+5. Security Tests (Vollständig)
+
+---
+
+## Akzeptanzkriterien
+
+### Test Infrastructure
+- [ ] LiveComponentTestCase mit allen Helpers implementiert
+- [ ] Snapshot Testing funktional
+- [ ] Contract Compliance Tests für alle Interfaces
+- [ ] Security Tests für alle Security-Features
+- [ ] E2E Tests für komplexe Szenarien
+- [ ] Alle Tests dokumentiert mit Examples
+
+### Documentation
+- [ ] End-to-End Guide vollständig
+- [ ] Security Guide vollständig
+- [ ] Performance Guide vollständig
+- [ ] Upload Guide vollständig
+- [ ] DevTools Guide vollständig
+- [ ] API Reference vollständig
+- [ ] Alle Guides mit praktischen Examples
+
+### Middleware Support
+- [ ] ComponentMiddlewareInterface definiert
+- [ ] Middleware Attribute implementiert
+- [ ] Middleware Pipeline funktional
+- [ ] Built-in Middleware implementiert (Logging, Caching, RateLimit)
+- [ ] Integration in LiveComponentHandler
+- [ ] Umfassende Tests
+- [ ] Dokumentation mit Examples
+
+---
+
+## Technische Details
+
+### Test Infrastructure
+
+**Pest Integration**:
+- Custom Expectations erweitern
+- Helper-Functions in `tests/Pest.php`
+- Test-Harness als Trait für Wiederverwendung
+
+**Snapshot Format**:
+- JSON-basiert für strukturierte Daten
+- HTML-Snapshots mit Whitespace-Normalisierung
+- Versionierte Snapshots für Breaking Changes
+
+### Middleware Architecture
+
+**Execution Order**:
+1. Request Transformation (TransformMiddleware)
+2. Validation (ValidationMiddleware)
+3. Rate Limiting (RateLimitMiddleware)
+4. Caching (CachingMiddleware)
+5. Logging (LoggingMiddleware)
+6. Action Execution
+7. Response Transformation
+
+**Priority System**:
+- Higher priority = earlier execution
+- Default priority: 100
+- Built-in middleware: 50-150 range
+
+### Documentation Structure
+
+**Markdown Format**:
+- Code-Beispiele mit Syntax-Highlighting
+- TOC für Navigation
+- Cross-References zwischen Guides
+- Version-Info für Breaking Changes
+
+---
+
+## Erfolgsmetriken
+
+### Test Infrastructure
+- 90%+ Test Coverage für alle Core-Features
+- Alle Security-Features getestet
+- E2E Tests für kritische Flows
+
+### Documentation
+- Alle Guides vollständig
+- Praktische Examples für alle Features
+- Positive Developer Feedback
+
+### Middleware Support
+- Middleware-System funktional
+- Built-in Middleware getestet
+- Developer können Custom Middleware erstellen
+
+---
+
+## Risiken & Mitigation
+
+### Test Infrastructure
+- **Risiko**: Snapshot-Tests können bei Refactoring störend sein
+- **Mitigation**: Update-Modus für einfaches Refactoring
+
+### Documentation
+- **Risiko**: Dokumentation kann schnell veralten
+- **Mitigation**: Automatische Tests für Code-Examples, regelmäßige Reviews
+
+### Middleware Support
+- **Risiko**: Performance-Impact durch Middleware-Stack
+- **Mitigation**: Caching, Lazy Loading, Performance-Tests
+
+---
+
+## Nächste Schritte
+
+1. **Sprint Planning**: Detaillierte Task-Aufteilung
+2. **Implementation Start**: Mit Test Infrastructure beginnen
+3. **Documentation**: Parallel zur Implementation
+4. **Middleware**: Nach Test Infrastructure
+
+
+
+
+