WIP: docs(pipeline): add design plan for PipelineExecutor class #3

Draft

maxp wants to merge 13 commits from feature/pipeline-executor into main

pull from: feature/pipeline-executor

merge into: maxp:main

maxp:main

maxp:pages

Conversation 0 Commits 13 Files Changed 11 +362 -12

maxp commented 2025-05-08 22:06:10 +02:00

Owner

Copy Link

🧩 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)

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)

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

# 🧩 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`

maxp added 1 commit 2025-05-08 22:06:11 +02:00

docs(pipeline): add design plan for PipelineExecutor class ... 0846dbb758

- 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

maxp added this to the Plan: `PipelineExecutor<TContext>` milestone 2025-05-08 22:11:43 +02:00

maxp added 2 commits 2025-05-10 16:34:55 +02:00

feat(pipeline): add configuration and hooks for pipeline execution ... 3f114bb68d

- Introduce `IPipelineExecutorConfig` to enable customizable pipeline behavior
- Add `IPipelineHooks` interface for tracing and monitoring lifecycle events
- Define callback types for pipeline start, step execution, and completion
- Export new types and interfaces for broader integration within the system

chore(workflows): refine branch handling in release process ... 8f94cc915c

- Adjusts workflow to support pushes from all branches
- Ensures main branch-specific conditions for version detection
- Modifies changelog and release steps for non-main branch handling

maxp added 1 commit 2025-05-10 16:50:44 +02:00

feat(interfaces): add pipeline executor interface ... 927a9081d4

- Introduce `IPipelineExecutor` to define pipeline execution
- Add `PipelineExecutorFactory` for instantiating pipeline executors
- Export new types in the interfaces module for external use

maxp added 1 commit 2025-05-10 17:01:02 +02:00

fix(workflows): ensure version detection output is always set ... abd2d6e840

- Move VERSION file change detection behind a branch guard (main only)
- Use a fallback in the output step to ensure 'version_changed' is always defined
- Prevent job skipping and output access errors in feature branches

gitea-actionsbot added 1 commit 2025-05-10 17:01:19 +02:00

chore(changelog): update unreleased changelog 32f3fe5f52

maxp added 2 commits 2025-05-10 17:28:26 +02:00

chore(git): ignore merge conflicts for CHANGELOG.md d04dfcd63e

chore(changelog): update unreleased changelog 2ab74b9859

gitea-actionsbot added 1 commit 2025-05-10 17:28:42 +02:00

chore(changelog): update unreleased changelog b69a51247d

maxp added 1 commit 2025-05-10 17:42:43 +02:00

feat(workflows): conditionally generate changelog ... 2ab6f1b8db

- Add logic to generate changelog only if the file exists or on the main branch
- Prevent unnecessary changelog generation in other contexts

gitea-actionsbot added 1 commit 2025-05-10 17:43:02 +02:00

chore(changelog): update unreleased changelog 0aac2337a0

maxp added 1 commit 2025-05-10 17:50:57 +02:00

docs(release): update guidelines for handling changelog ... 6ce73c14fa

- Add instructions to avoid merge conflicts in `CHANGELOG.md`
- Provide steps for using `.gitattributes` to automate conflict resolution
- Clarify recommended workflows for feature branches and merging

gitea-actionsbot added 1 commit 2025-05-10 17:51:11 +02:00

chore(changelog): update unreleased changelog 5d1b0517a5

This pull request has changes conflicting with the target branch.

• .gitea/workflows/release.yml
• CHANGELOG.md

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feature/pipeline-executor:feature/pipeline-executor

git checkout feature/pipeline-executor

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone Plan: `PipelineExecutor<TContext>`

Projects

Clear projects

No project

Assignees

Clear assignees

maxp

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: maxp/http-kernel#3