Max P.
0846dbb758
All checks were successful
Test http-kernel / Run Tests (pull_request) Successful in 10s
- Introduce a detailed plan for the PipelineExecutor class - Describe its purpose, interface, hooks, and internal workflow - Highlight advantages such as decoupling, testability, and extensibility - Will be removed before merge
73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
# 🧩 Plan: `PipelineExecutor<TContext>`
|
|
|
|
## 🎯 Ziel
|
|
Eine eigenständige, testbare Klasse zur Ausführung einer Middleware- und Handler-Pipeline, die:
|
|
- Linear und sauber das `next()`-Verhalten abbildet
|
|
- Typvalidierung durchführt (`isMiddleware`, `isHandler`)
|
|
- Fehler behandelt und an konfigurierbare Handler weiterleitet
|
|
- Optionale Hooks zur Tracing-Integration bietet (z. B. für Zeitmessung, Logging)
|
|
- Am Ende eine dekorierte `Response` zurückliefert
|
|
|
|
---
|
|
|
|
## 🧩 Schnittstelle (API)
|
|
|
|
```ts
|
|
class PipelineExecutor<TContext extends IContext> {
|
|
constructor(cfg: IHttpKernelConfig<TContext>);
|
|
|
|
run(
|
|
ctx: TContext,
|
|
middleware: Middleware<TContext>[],
|
|
handler: Handler<TContext>,
|
|
hooks?: IPipelineHooks<TContext>, // optional
|
|
): Promise<Response>;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🪝 Hook-Schnittstelle (`IPipelineHooks`)
|
|
|
|
```ts
|
|
interface IPipelineHooks<TContext> {
|
|
onPipelineStart?(ctx: TContext): void;
|
|
onStepStart?(name: string | undefined, ctx: TContext): void;
|
|
onStepEnd?(name: string | undefined, ctx: TContext, duration: number): void;
|
|
onPipelineEnd?(ctx: TContext, totalDuration: number): void;
|
|
}
|
|
```
|
|
|
|
- `name` ist `undefined`, wenn keine `.name` am Handler/Middleware gesetzt ist
|
|
- Diese Hooks ermöglichen später Logging, Zeitmessung, Statistiken etc.
|
|
- Der `TraceManager` wird dieses Interface implementieren
|
|
|
|
---
|
|
|
|
## 🛠️ Interne Aufgaben / Ablauf
|
|
|
|
1. `run(...)` beginnt mit Aufruf `onPipelineStart(ctx)`
|
|
2. Zeitmessung (`performance.now()`)
|
|
3. Dispatcher-Funktion führt jede Middleware mit `next()`-Kette aus
|
|
4. Vor jedem Aufruf: `onStepStart(name, ctx)`
|
|
5. Nach jedem Aufruf: `onStepEnd(name, ctx, duration)`
|
|
6. Nach letztem Handler: `onPipelineEnd(ctx, totalDuration)`
|
|
7. Ergebnis wird durch `cfg.decorateResponse(res, ctx)` geschickt
|
|
8. Im Fehlerfall: `cfg.httpErrorHandlers[500](ctx, error)`
|
|
|
|
---
|
|
|
|
## ✅ Vorteile
|
|
|
|
- `HttpKernel` ist von Ausführungsdetails entkoppelt
|
|
- Tracing-/Logging-System kann ohne Invasivität angeschlossen werden
|
|
- Sehr gut testbar (z. B. Middleware-Mock + Hook-Aufrufe prüfen)
|
|
- Erweiterbar für Timeout, Async-Context, Abbruchlogik etc.
|
|
|
|
---
|
|
|
|
## 📦 Dateiname-Vorschlag
|
|
|
|
- `src/Core/PipelineExecutor.ts` oder
|
|
- `src/HttpKernel/PipelineExecutor.ts`
|