feat(pipeline): add configuration and hooks for pipeline execution

- 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

src/Interfaces/IPipelineExecutorConfig.ts

@@ -0,0 +1,33 @@
+import { ResponseDecorator } from '../Types/ResponseDecorator.ts';
+import { IContext } from './IContext.ts';
+import { IHttpErrorHandlers } from './IHttpErrorHandlers.ts';
+import { IPipelineHooks } from './IPipelineHooks.ts';
+
+/**
+ * Configuration object for the PipelineExecutor, defining how to handle
+ * errors, responses, and tracing hooks.
+ *
+ * This allows the execution logic to remain decoupled from kernel-level behavior
+ * while still supporting custom behavior injection.
+ *
+ * @template TContext - The context type propagated during pipeline execution.
+ */
+export interface IPipelineExecutorConfig<TContext extends IContext = IContext> {
+    /**
+     * Optional function used to transform or decorate the final Response object
+     * before it is returned to the client.
+     */
+    decorateResponse?: ResponseDecorator<TContext>;
+
+    /**
+     * Optional map of error handlers, keyed by HTTP status codes (e.g., 404, 500).
+     * These handlers are invoked if an error occurs during middleware or handler execution.
+     */
+    errorHandlers?: IHttpErrorHandlers<TContext>;
+
+    /**
+     * Optional hooks that allow tracing and lifecycle monitoring during pipeline execution.
+     * Each hook is called at a specific phase of the middleware/handler lifecycle.
+     */
+    pipelineHooks?: IPipelineHooks<TContext>;
+}

src/Interfaces/IPipelineHooks.ts

@@ -0,0 +1,36 @@
+import {
+    OnPipelineEnd,
+    OnPipelineStart,
+    OnStepEnd,
+    OnStepStart,
+} from '../Types/mod.ts';
+import { IContext } from './IContext.ts';
+
+/**
+ * A set of optional hook functions that can be triggered during pipeline execution.
+ * These hooks allow tracing, performance measurement, and logging to be integrated
+ * without altering middleware or handler logic.
+ *
+ * @template TContext - The custom context type used within the application.
+ */
+export interface IPipelineHooks<TContext extends IContext = IContext> {
+    /**
+     * Triggered once before any middleware or handler is executed.
+     */
+    onPipelineStart?: OnPipelineStart<TContext>;
+
+    /**
+     * Triggered immediately before each middleware or handler runs.
+     */
+    onStepStart?: OnStepStart<TContext>;
+
+    /**
+     * Triggered immediately after each middleware or handler has finished executing.
+     */
+    onStepEnd?: OnStepEnd<TContext>;
+
+    /**
+     * Triggered after the entire pipeline completes execution.
+     */
+    onPipelineEnd?: OnPipelineEnd<TContext>;
+}

src/Interfaces/mod.ts

@@ -5,6 +5,8 @@ export type { IHttpErrorHandlers } from './IHttpErrorHandlers.ts';
 export type { IHttpKernel } from './IHttpKernel.ts';
 export type { IHttpKernelConfig } from './IHttpKernelConfig.ts';
 export type { IInternalRoute } from './IInternalRoute.ts';
+export type { IPipelineExecutorConfig } from './IPipelineExecutorConfig.ts';
+export type { IPipelineHooks } from './IPipelineHooks.ts';
 export type { IRouteBuilder, IRouteBuilderFactory } from './IRouteBuilder.ts';
 export {
     isDynamicRouteDefinition,

src/Types/PipelineHooks.ts

@@ -0,0 +1,49 @@
+import { IContext } from '../Interfaces/mod.ts';
+
+/**
+ * A callback invoked when the middleware pipeline starts.
+ *
+ * @template TContext - The context type passed throughout the pipeline.
+ * @param ctx - The context object for the current request.
+ */
+export type OnPipelineStart<TContext extends IContext> = (
+    ctx: TContext,
+) => void;
+
+/**
+ * A callback invoked immediately before a middleware or handler is executed.
+ *
+ * @template TContext - The context type passed throughout the pipeline.
+ * @param name - Optional name of the current middleware or handler, if defined.
+ * @param ctx - The context object for the current request.
+ */
+export type OnStepStart<TContext extends IContext> = (
+    name: string | undefined,
+    ctx: TContext,
+) => void;
+
+/**
+ * A callback invoked immediately after a middleware or handler has completed.
+ *
+ * @template TContext - The context type passed throughout the pipeline.
+ * @param name - Optional name of the current middleware or handler, if defined.
+ * @param ctx - The context object for the current request.
+ * @param duration - Execution time in milliseconds.
+ */
+export type OnStepEnd<TContext extends IContext> = (
+    name: string | undefined,
+    ctx: TContext,
+    duration: number,
+) => void;
+
+/**
+ * A callback invoked after the entire pipeline has completed execution.
+ *
+ * @template TContext - The context type passed throughout the pipeline.
+ * @param ctx - The context object for the current request.
+ * @param totalDuration - Total execution time of the pipeline in milliseconds.
+ */
+export type OnPipelineEnd<TContext extends IContext> = (
+    ctx: TContext,
+    totalDuration: number,
+) => void;

src/Types/mod.ts

@@ -39,6 +39,12 @@ export type { HttpStatusCode } from './HttpStatusCode.ts';
 export { isMiddleware } from './Middleware.ts';
 export type { Middleware } from './Middleware.ts';
 export type { Params } from './Params.ts';
+export type {
+    OnPipelineEnd,
+    OnPipelineStart,
+    OnStepEnd,
+    OnStepStart,
+} from './PipelineHooks.ts';
 export type { Query } from './Query.ts';
 export type { RegisterRoute } from './RegisterRoute.ts';
 export type { ResponseDecorator } from './ResponseDecorator.ts';