preParsing hook payload manipulation and consistent Content Type Parser API

[ShogunPanda]

Hi all!

This PR focuses on two main things: preParsing hook payload manipulation hook and consistent Content Type Parser API.
The description are below.

This PR solves #1986 and it is needed for fastify/fastify-compress#105 (via fastify/fastify-compress#110).

This PR supersedes #2278.

Hope this helps!
Paolo

preParsing hook payload manipulation

This PR add supports for a third parameter for the the preParsing hook before the callback, in order to allow manipulation of request body stream before attempting to parse.

The new hook signature is fn(request,reply,payload,[done]). Payload is the current request body stream. The done function argument (or the async return value) must be a stream itself.

The rationale for this is to being able to handle compressed or encrypted request payload.
At the moment this can be achieved only inside the handler, which forces the developer to give up on fastify's serialization or validation and reimplement them inside the handler itself.

Example of gzipped request payload:

fastify.addHook('preParsing', (request, reply, payload, done) => {
  if(request.headers['content-encoding'] !== 'gzip') {
    done(null, payload)
  }
  // Some code
  done(null, payload.pipe(zlib.createGunzip()))
})

The hook should also ideally set the receivedEncodedLength property on the returned stream. The property is used to correctly match the request payload with the Content-Length header value. Ideally, but completely optional, this property should be updated on each received chunk in order to allow earlier termination for large request payloads.

Consistent Content Type Parser API

The PR deprecates the fn(req, done) and async fn(req) style Content Type Parser in favor of fn(request, payload, done) and async fn(request, payload).

The rationale for this change is to have a consistent callback styles API across all Fastify API. This was the last one.

The newer forms are used in all cases:

• If parseAs is not passed to addContentTypeParser, then payload is a stream.
• If parseAs is passed to addContentTypeParser, then payload is a string or a buffer accordingly.

Note that request, unlike in the past is a Fastify request object, not an IncomingMessage.

The older forms are still supported but emit a warning when used.

TypeScript notes

For both changes, I did not keep existing types.
The reason for this are the following:

1. Forbid use of deprecated forms
2. For the preParsing hook, I was not able to provided non ambigous callback typings.

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows Code of conduct

[jsumners]

The migration guide should be updated.

[mcollina]

lgtm

[ShogunPanda]

@jsumners Ok, will update this tomorrow.

[Ethan-Arrowood]

types lgtm

[ShogunPanda]

Migration guide and test symbols updated.

[delvedor]

Amazing work!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.