diff --git a/src/Interfaces/IInternalRoute.ts b/src/Interfaces/IInternalRoute.ts index 7fc7d66..fd3e33f 100644 --- a/src/Interfaces/IInternalRoute.ts +++ b/src/Interfaces/IInternalRoute.ts @@ -36,4 +36,29 @@ export interface IInternalRoute { * The final handler that generates the HTTP response after all middleware has run. */ handler: Handler; + + /** + * The fully compiled execution pipeline for this route. + * + * This function is generated at route registration time and encapsulates the + * entire middleware chain as well as the final handler. It is called by the + * HttpKernel during request dispatch when a route has been matched. + * + * Internally, `runRoute` ensures that each middleware is invoked in the correct order + * and receives a `next()` callback to pass control downstream. The final handler is + * invoked once all middleware has completed or short-circuited the pipeline. + * + * It is guaranteed that: + * - The function is statically compiled and does not perform dynamic dispatching. + * - Each middleware can only call `next()` once; repeated invocations will throw. + * - The return value is either a `Response` or a Promise resolving to one. + * + * @param ctx - The context object carrying route, request, response and other scoped data. + * @returns A `Response` object or a Promise resolving to a `Response`. + * + * @throws {Error} If a middleware calls `next()` more than once. + */ + runRoute: ( + ctx: TContext, + ) => Promise | Response; }