feat: add server.pipeline method

This pipeline method can be used for writing tests that involves executing
middleware chain without making an HTTP request.

Useful for packages and not user land code

Author: thetutlage

src/server/main.ts

@@ -14,12 +14,17 @@ import type { Logger } from '@adonisjs/logger'
 import type { Encryption } from '@adonisjs/encryption'
 import type { Server as HttpsServer } from 'node:https'
 import type { Application } from '@adonisjs/application'
-import { ContainerResolver, moduleImporter } from '@adonisjs/fold'
+import { ContainerResolver, moduleCaller, moduleImporter } from '@adonisjs/fold'
 import type { ServerResponse, IncomingMessage, Server as HttpServer } from 'node:http'
 
 import type { LazyImport } from '../types/base.js'
 import type { MiddlewareAsClass, ParsedGlobalMiddleware } from '../types/middleware.js'
-import type { ErrorHandlerAsAClass, ServerConfig, ServerErrorHandler } from '../types/server.js'
+import type {
+  ServerConfig,
+  ServerErrorHandler,
+  ErrorHandlerAsAClass,
+  TestingMiddlewarePipeline,
+} from '../types/server.js'
 
 import { Qs } from '../qs.js'
 import debug from '../debug.js'
@@ -176,6 +181,35 @@ export class Server {
       .finally(writeResponse(ctx))
   }
 
+  /**
+   * Creates a pipeline of middleware.
+   */
+  pipeline(middleware: MiddlewareAsClass[]): TestingMiddlewarePipeline {
+    const middlewareStack = new Middleware<ParsedGlobalMiddleware>()
+    middleware.forEach((one) => {
+      middlewareStack.add(moduleCaller(one, 'handle').toHandleMethod())
+    })
+
+    middlewareStack.freeze()
+    const stackRunner = middlewareStack.runner()
+
+    return {
+      finalHandler(handler) {
+        stackRunner.finalHandler(handler)
+        return this
+      },
+      errorHandler(handler) {
+        stackRunner.errorHandler(handler)
+        return this
+      },
+      run(ctx) {
+        return stackRunner.run((handler, next) => {
+          return handler.handle(ctx.containerResolver, ctx, next)
+        })
+      },
+    }
+  }
+
   /**
    * Define an array of middleware to use on all the incoming HTTP request.
    * Calling this method multiple times pushes to the existing list

src/types/server.ts

@@ -7,6 +7,9 @@
  * file that was distributed with this source code.
  */
 
+import type { ContainerResolver } from '@adonisjs/fold'
+import type { ErrorHandler, FinalHandler } from '@poppinss/middleware/types'
+
 import type { Constructor } from './base.js'
 import type { QSParserConfig } from './qs.js'
 import type { RequestConfig } from './request.js'
@@ -29,6 +32,15 @@ export type HttpError = {
   report?: (...args: any[]) => any
 }
 
+/**
+ * The pipeline for executing middleware during tests
+ */
+export interface TestingMiddlewarePipeline {
+  finalHandler(handler: FinalHandler): this
+  errorHandler(handler: ErrorHandler): this
+  run(ctx: HttpContext): Promise<any>
+}
+
 /**
  * The expression to define a status page range
  */

tests/server.spec.ts

@@ -9,11 +9,12 @@
 
 import 'reflect-metadata'
 import supertest from 'supertest'
+import { Socket } from 'node:net'
 import { test } from '@japa/runner'
-import { createServer } from 'node:http'
 import { Emitter } from '@adonisjs/events'
 import type { NextFn } from '@poppinss/middleware/types'
 import { AppFactory } from '@adonisjs/application/factories'
+import { createServer, IncomingMessage, ServerResponse } from 'node:http'
 
 import { Router } from '../src/router/main.js'
 import { HttpContext } from '../src/http_context/main.js'
@@ -990,3 +991,128 @@ test.group('Server | force content negotiation', () => {
     })
   })
 })
+
+test.group('Server | Pipeline', () => {
+  test('execute middleware pipeline', async ({ assert }) => {
+    const stack: string[] = []
+    const app = new AppFactory().create(BASE_URL, () => {})
+    await app.init()
+
+    const server = new ServerFactory().merge({ app }).create()
+
+    class MiddlewareOne {
+      handle(_: any, next: NextFn) {
+        stack.push('middleware one')
+        return next()
+      }
+    }
+
+    class MiddlewareTwo {
+      handle(_: any, next: NextFn) {
+        stack.push('middleware two')
+        return next()
+      }
+    }
+
+    const req = new IncomingMessage(new Socket())
+    const res = new ServerResponse(req)
+
+    const ctx = server.createHttpContext(
+      server.createRequest(req, res),
+      server.createResponse(req, res),
+      app.container.createResolver()
+    )
+
+    await server.pipeline([MiddlewareOne, MiddlewareTwo]).run(ctx)
+    assert.deepEqual(stack, ['middleware one', 'middleware two'])
+  })
+
+  test('run final handler', async ({ assert }) => {
+    const stack: string[] = []
+    const app = new AppFactory().create(BASE_URL, () => {})
+    await app.init()
+
+    const server = new ServerFactory().merge({ app }).create()
+
+    class MiddlewareOne {
+      handle(_: any, next: NextFn) {
+        stack.push('middleware one')
+        return next()
+      }
+    }
+
+    class MiddlewareTwo {
+      handle(_: any, next: NextFn) {
+        stack.push('middleware two')
+        return next()
+      }
+    }
+
+    const req = new IncomingMessage(new Socket())
+    const res = new ServerResponse(req)
+
+    const ctx = server.createHttpContext(
+      server.createRequest(req, res),
+      server.createResponse(req, res),
+      app.container.createResolver()
+    )
+
+    await server
+      .pipeline([MiddlewareOne, MiddlewareTwo])
+      .finalHandler(async () => {
+        stack.push('final handler')
+      })
+      .run(ctx)
+
+    assert.deepEqual(stack, ['middleware one', 'middleware two', 'final handler'])
+  })
+
+  test('run error handler when error is thrown', async ({ assert }) => {
+    const stack: string[] = []
+    const app = new AppFactory().create(BASE_URL, () => {})
+    await app.init()
+
+    const server = new ServerFactory().merge({ app }).create()
+
+    class MiddlewareOne {
+      async handle(_: any, next: NextFn) {
+        stack.push('middleware one')
+        await next()
+        stack.push('upstream middleware one')
+      }
+    }
+
+    class MiddlewareTwo {
+      handle(_: any, __: NextFn) {
+        stack.push('middleware two')
+        throw new Error('Fail')
+      }
+    }
+
+    const req = new IncomingMessage(new Socket())
+    const res = new ServerResponse(req)
+
+    const ctx = server.createHttpContext(
+      server.createRequest(req, res),
+      server.createResponse(req, res),
+      app.container.createResolver()
+    )
+
+    await server
+      .pipeline([MiddlewareOne, MiddlewareTwo])
+      .finalHandler(async () => {
+        stack.push('final handler')
+      })
+      .errorHandler(async () => {
+        stack.push('error handler')
+      })
+      .run(ctx)
+
+    assert.deepEqual(stack, [
+      'middleware one',
+      'middleware two',
+      'error handler',
+      'upstream middleware one',
+    ])
+  })
+})