feat: add synchronous hooks to HTTP server

synchronous hooks can be used to decorate the HTTP context and bind
values into the container resolver specific for that given request

Author: thetutlage

benchmarks/index.ts

@@ -72,4 +72,4 @@ async function fastifyRun() {
   console.log('Completed')
 }
 
-fastifyRun().then(coolOff).then(adonisRun)
+adonisRun().then(coolOff).then(fastifyRun)

src/server/main.ts

@@ -35,6 +35,11 @@ import { middlewareHandler } from './factories/middleware_handler.js'
  * registered routes.
  */
 export class Server {
+  /**
+   * Collection of synchronous request hooks
+   */
+  #requestHooks: Set<(ctx: HttpContext) => void> = new Set()
+
   /**
    * Registered error handler (if any)
    */
@@ -131,21 +136,15 @@ export class Server {
   }
 
   /**
-   * Creates an instance of the HTTP context for the current
-   * request
+   * Handles the HTTP request
    */
-  #createContext(req: IncomingMessage, res: ServerResponse, resolver: ContainerResolver<any>) {
-    const request = new Request(req, res, this.#encryption, this.#config, this.#qsParser)
-    const response = new Response(
-      req,
-      res,
-      this.#encryption,
-      this.#config,
-      this.#router,
-      this.#qsParser
-    )
-
-    return new HttpContext(request, response, this.#app.logger.child({}), resolver)
+  #handleRequest(ctx: HttpContext, resolver: ContainerResolver<any>) {
+    return this.#serverMiddlewareStack!.runner()
+      .finalHandler(finalHandler(this.#router!, resolver, ctx))
+      .run(middlewareHandler(resolver, ctx))
+      .then(useReturnValue(ctx))
+      .catch((error) => this.#resolvedErrorHandler.handle(error, ctx))
+      .finally(writeResponse(ctx))
   }
 
   /**
@@ -202,18 +201,6 @@ export class Server {
     }
   }
 
-  /**
-   * Handles the HTTP request
-   */
-  #handleRequest(ctx: HttpContext, resolver: ContainerResolver<any>) {
-    return this.#serverMiddlewareStack!.runner()
-      .finalHandler(finalHandler(this.#router!, resolver, ctx))
-      .run(middlewareHandler(resolver, ctx))
-      .then(useReturnValue(ctx))
-      .catch((error) => this.#resolvedErrorHandler.handle(error, ctx))
-      .finally(writeResponse(ctx))
-  }
-
   /**
    * Set the HTTP server instance used to listen for requests.
    */
@@ -237,12 +224,39 @@ export class Server {
     return this.#router
   }
 
+  /**
+   * Synchronous hooks to get notified everytime a new HTTP request comes
+   */
+  onRequest(callback: (ctx: HttpContext) => void) {
+    this.#requestHooks.add(callback)
+    return this
+  }
+
   /**
    * Handle request
    */
   handle(req: IncomingMessage, res: ServerResponse) {
+    /**
+     * Creating essential instances
+     */
     const resolver = this.#app.container.createResolver()
-    const ctx = this.#createContext(req, res, resolver)
+    const request = new Request(req, res, this.#encryption, this.#config, this.#qsParser)
+    const response = new Response(
+      req,
+      res,
+      this.#encryption,
+      this.#config,
+      this.#router,
+      this.#qsParser
+    )
+    const ctx = new HttpContext(request, response, this.#app.logger.child({}), resolver)
+
+    /**
+     * Invoking synchronous hooks
+     */
+    for (let hook of this.#requestHooks) {
+      hook(ctx)
+    }
 
     if (this.usingAsyncLocalStorage) {
       return asyncLocalStorage.storage!.run(ctx, () => this.#handleRequest(ctx, resolver))

tests/server.spec.ts

@@ -846,3 +846,28 @@ test.group('Server | force content negotiation', () => {
     })
   })
 })
+
+test.group('Server | synchronous hooks', () => {
+  test('register synchronous hooks', async ({ assert }) => {
+    assert.plan(1)
+
+    let stack: any[] = []
+
+    const app = new AppFactory().create()
+    await app.init()
+
+    const server = new ServerFactory().merge({ app }).create()
+    const httpServer = createServer(server.handle.bind(server))
+
+    server.onRequest((ctx) => {
+      stack.push(ctx)
+    })
+
+    server.getRouter().get('/', async (ctx) => {
+      assert.deepEqual(stack[0], ctx)
+    })
+    await server.boot()
+
+    await supertest(httpServer).get('/').expect(200)
+  })
+})