feat: new onRequestAbort hook (fastify#4582)

* feat: Added onClientAbort hook.

* test: Removed leftovers.

* docs: Added client detection reliability disclaimer.

* feat: Renamed hook.

* feat: Handle errors and don't forward the reply.

* chore: Updated docs.

Co-authored-by: Frazer Smith <[email protected]>

* test: apply PR review suggestions

Co-authored-by: Manuel Spigolon <[email protected]>

---------

Co-authored-by: Frazer Smith <[email protected]>
Co-authored-by: Manuel Spigolon <[email protected]>

Author: 3 people

docs/Reference/Hooks.md

@@ -19,6 +19,7 @@ are Request/Reply hooks and application hooks:
   - [onSend](#onsend)
   - [onResponse](#onresponse)
   - [onTimeout](#ontimeout)
+  - [onRequestAbort](#onrequestabort)
   - [Manage Errors from a hook](#manage-errors-from-a-hook)
   - [Respond to a request from a hook](#respond-to-a-request-from-a-hook)
 - [Application Hooks](#application-hooks)
@@ -267,6 +268,26 @@ service (if the `connectionTimeout` property is set on the Fastify instance).
 The `onTimeout` hook is executed when a request is timed out and the HTTP socket
 has been hanged up. Therefore, you will not be able to send data to the client.
 
+### onRequestAbort
+
+```js
+fastify.addHook('onRequestAbort', (request, reply, done) => {
+  // Some code
+  done()
+})
+```
+Or `async/await`:
+```js
+fastify.addHook('onRequestAbort', async (request, reply) => {
+  // Some code
+  await asyncMethod()
+})
+```
+The `onRequestAbort` hook is executed when a client closes the connection before
+the entire request has been received. Therefore, you will not be able to send
+data to the client.
+
+**Notice:** client abort detection is not completely reliable. See: [`Detecting-When-Clients-Abort.md`](../Guides/Detecting-When-Clients-Abort.md)
 
 ### Manage Errors from a hook
 If you get an error during the execution of your hook, just pass it to `done()`

fastify.d.ts

@@ -12,7 +12,7 @@ import { Chain as LightMyRequestChain, InjectOptions, Response as LightMyRequest
 import { FastifyBodyParser, FastifyContentTypeParser, AddContentTypeParser, hasContentTypeParser, getDefaultJsonParser, ProtoAction, ConstructorAction } from './types/content-type-parser'
 import { FastifyContext, FastifyContextConfig } from './types/context'
 import { FastifyErrorCodes } from './types/errors'
-import { DoneFuncWithErrOrRes, HookHandlerDoneFunction, RequestPayload, onCloseAsyncHookHandler, onCloseHookHandler, onErrorAsyncHookHandler, onErrorHookHandler, onReadyAsyncHookHandler, onReadyHookHandler, onRegisterHookHandler, onRequestAsyncHookHandler, onRequestHookHandler, onResponseAsyncHookHandler, onResponseHookHandler, onRouteHookHandler, onSendAsyncHookHandler, onSendHookHandler, onTimeoutAsyncHookHandler, onTimeoutHookHandler, preHandlerAsyncHookHandler, preHandlerHookHandler, preParsingAsyncHookHandler, preParsingHookHandler, preSerializationAsyncHookHandler, preSerializationHookHandler, preValidationAsyncHookHandler, preValidationHookHandler } from './types/hooks'
+import { DoneFuncWithErrOrRes, HookHandlerDoneFunction, RequestPayload, onCloseAsyncHookHandler, onCloseHookHandler, onErrorAsyncHookHandler, onErrorHookHandler, onReadyAsyncHookHandler, onReadyHookHandler, onRegisterHookHandler, onRequestAsyncHookHandler, onRequestHookHandler, onResponseAsyncHookHandler, onResponseHookHandler, onRouteHookHandler, onSendAsyncHookHandler, onSendHookHandler, onTimeoutAsyncHookHandler, onTimeoutHookHandler, preHandlerAsyncHookHandler, preHandlerHookHandler, preParsingAsyncHookHandler, preParsingHookHandler, preSerializationAsyncHookHandler, preSerializationHookHandler, preValidationAsyncHookHandler, preValidationHookHandler, onRequestAbortHookHandler, onRequestAbortAsyncHookHandler } from './types/hooks'
 import { FastifyListenOptions, FastifyInstance, PrintRoutesOptions } from './types/instance'
 import { FastifyBaseLogger, FastifyLoggerInstance, FastifyLoggerOptions, PinoLoggerOptions, FastifyLogFn, LogLevel } from './types/logger'
 import { FastifyPluginCallback, FastifyPluginAsync, FastifyPluginOptions, FastifyPlugin } from './types/plugin'
@@ -179,7 +179,7 @@ declare namespace fastify {
     FastifyError, // '@fastify/error'
     FastifySchema, FastifySchemaCompiler, // './types/schema'
     HTTPMethods, RawServerBase, RawRequestDefaultExpression, RawReplyDefaultExpression, RawServerDefault, ContextConfigDefault, RequestBodyDefault, RequestQuerystringDefault, RequestParamsDefault, RequestHeadersDefault, // './types/utils'
-    DoneFuncWithErrOrRes, HookHandlerDoneFunction, RequestPayload, onCloseAsyncHookHandler, onCloseHookHandler, onErrorAsyncHookHandler, onErrorHookHandler, onReadyAsyncHookHandler, onReadyHookHandler, onRegisterHookHandler, onRequestAsyncHookHandler, onRequestHookHandler, onResponseAsyncHookHandler, onResponseHookHandler, onRouteHookHandler, onSendAsyncHookHandler, onSendHookHandler, onTimeoutAsyncHookHandler, onTimeoutHookHandler, preHandlerAsyncHookHandler, preHandlerHookHandler, preParsingAsyncHookHandler, preParsingHookHandler, preSerializationAsyncHookHandler, preSerializationHookHandler, preValidationAsyncHookHandler, preValidationHookHandler, // './types/hooks'
+    DoneFuncWithErrOrRes, HookHandlerDoneFunction, RequestPayload, onCloseAsyncHookHandler, onCloseHookHandler, onErrorAsyncHookHandler, onErrorHookHandler, onReadyAsyncHookHandler, onReadyHookHandler, onRegisterHookHandler, onRequestAsyncHookHandler, onRequestHookHandler, onResponseAsyncHookHandler, onResponseHookHandler, onRouteHookHandler, onSendAsyncHookHandler, onSendHookHandler, onTimeoutAsyncHookHandler, onTimeoutHookHandler, preHandlerAsyncHookHandler, preHandlerHookHandler, preParsingAsyncHookHandler, preParsingHookHandler, preSerializationAsyncHookHandler, preSerializationHookHandler, preValidationAsyncHookHandler, preValidationHookHandler, onRequestAbortHookHandler, onRequestAbortAsyncHookHandler, // './types/hooks'
     FastifyServerFactory, FastifyServerFactoryHandler, // './types/serverFactory'
     FastifyTypeProvider, FastifyTypeProviderDefault, // './types/type-provider'
     FastifyErrorCodes, // './types/errors'

fastify.js

@@ -588,6 +588,10 @@ function fastify (options) {
       if (fn.constructor.name === 'AsyncFunction' && fn.length !== 0) {
         throw new errorCodes.FST_ERR_HOOK_INVALID_ASYNC_HANDLER()
       }
+    } else if (name === 'onRequestAbort') {
+      if (fn.constructor.name === 'AsyncFunction' && fn.length !== 1) {
+        throw new errorCodes.FST_ERR_HOOK_INVALID_ASYNC_HANDLER()
+      }
     } else {
       if (fn.constructor.name === 'AsyncFunction' && fn.length === 3) {
         throw new errorCodes.FST_ERR_HOOK_INVALID_ASYNC_HANDLER()

lib/context.js

@@ -48,6 +48,7 @@ function Context ({
   this.preHandler = null
   this.onResponse = null
   this.preSerialization = null
+  this.onRequestAbort = null
   this.config = config
   this.errorHandler = errorHandler || server[kErrorHandler]
   this._middie = null

lib/hooks.js

@@ -15,7 +15,8 @@ const lifecycleHooks = [
   'preHandler',
   'onSend',
   'onResponse',
-  'onError'
+  'onError',
+  'onRequestAbort'
 ]
 const supportedHooks = lifecycleHooks.concat(applicationHooks)
 const {
@@ -46,6 +47,7 @@ function Hooks () {
   this.onRegister = []
   this.onReady = []
   this.onTimeout = []
+  this.onRequestAbort = []
 }
 
 Hooks.prototype.validate = function (hook, fn) {
@@ -74,6 +76,7 @@ function buildHooks (h) {
   hooks.onRoute = h.onRoute.slice()
   hooks.onRegister = h.onRegister.slice()
   hooks.onTimeout = h.onTimeout.slice()
+  hooks.onRequestAbort = h.onRequestAbort.slice()
   hooks.onReady = []
   return hooks
 }
@@ -246,6 +249,42 @@ function onSendHookRunner (functions, request, reply, payload, cb) {
   next()
 }
 
+function onRequestAbortHookRunner (functions, runner, request, cb) {
+  let i = 0
+
+  function next (err) {
+    if (err || i === functions.length) {
+      cb(err, request)
+      return
+    }
+
+    let result
+    try {
+      result = runner(functions[i++], request, next)
+    } catch (error) {
+      next(error)
+      return
+    }
+    if (result && typeof result.then === 'function') {
+      result.then(handleResolve, handleReject)
+    }
+  }
+
+  function handleResolve () {
+    next()
+  }
+
+  function handleReject (err) {
+    if (!err) {
+      err = new FST_ERR_SEND_UNDEFINED_ERR()
+    }
+
+    cb(err, request)
+  }
+
+  next()
+}
+
 function hookIterator (fn, request, reply, next) {
   if (reply.sent === true) return undefined
   return fn(request, reply, next)
@@ -256,6 +295,7 @@ module.exports = {
   buildHooks,
   hookRunner,
   onSendHookRunner,
+  onRequestAbortHookRunner,
   hookIterator,
   hookRunnerApplication,
   lifecycleHooks,

lib/route.js

@@ -3,7 +3,7 @@
 const FindMyWay = require('find-my-way')
 const Context = require('./context')
 const handleRequest = require('./handleRequest')
-const { hookRunner, hookIterator, lifecycleHooks } = require('./hooks')
+const { hookRunner, hookIterator, onRequestAbortHookRunner, lifecycleHooks } = require('./hooks')
 const { supportedMethods } = require('./httpMethods')
 const { normalizeSchema } = require('./schemas')
 const { parseHeadOnSendHandlers } = require('./headRoute')
@@ -484,6 +484,20 @@ function buildRouting (options) {
       runPreParsing(null, request, reply)
     }
 
+    if (context.onRequestAbort !== null) {
+      req.on('close', () => {
+        /* istanbul ignore else */
+        if (req.aborted) {
+          onRequestAbortHookRunner(
+            context.onRequestAbort,
+            hookIterator,
+            request,
+            handleOnRequestAbortHooksErrors.bind(null, reply)
+          )
+        }
+      })
+    }
+
     if (context.onTimeout !== null) {
       if (!request.raw.socket._meta) {
         request.raw.socket.on('timeout', handleTimeout)
@@ -493,6 +507,12 @@ function buildRouting (options) {
   }
 }
 
+function handleOnRequestAbortHooksErrors (reply, err) {
+  if (err) {
+    reply.log.error({ err }, 'onRequestAborted hook failed')
+  }
+}
+
 function handleTimeout () {
   const { context, request, reply } = this._meta
   hookRunner(

test/hooks-async.test.js

@@ -584,6 +584,18 @@ test('preHandler respond with a stream', t => {
 })
 
 test('Should log a warning if is an async function with `done`', t => {
+  t.test('2 arguments', t => {
+    t.plan(2)
+    const fastify = Fastify()
+
+    try {
+      fastify.addHook('onRequestAbort', async (req, done) => {})
+    } catch (e) {
+      t.ok(e.code, 'FST_ERR_HOOK_INVALID_ASYNC_HANDLER')
+      t.ok(e.message === 'Async function has too many arguments. Async hooks should not use the \'done\' argument.')
+    }
+  })
+
   t.test('3 arguments', t => {
     t.plan(2)
     const fastify = Fastify()