Skip to content

Latest commit

 

History

History
897 lines (724 loc) · 27.3 KB

Reply.md

File metadata and controls

897 lines (724 loc) · 27.3 KB
Raw

Fastify

Reply

Introduction

The second parameter of the handler function is Reply. Reply is a core Fastify object that exposes the following functions and properties:

  • .code(statusCode) - Sets the status code.
  • .status(statusCode) - An alias for .code(statusCode).
  • .statusCode - Read and set the HTTP status code.
  • .server - A reference to the fastify instance object.
  • .header(name, value) - Sets a response header.
  • .headers(object) - Sets all the keys of the object as response headers.
  • .getHeader(name) - Retrieve value of already set header.
  • .getHeaders() - Gets a shallow copy of all current response headers.
  • .removeHeader(key) - Remove the value of a previously set header.
  • .hasHeader(name) - Determine if a header has been set.
  • .trailer(key, function) - Sets a response trailer.
  • .hasTrailer(key) - Determine if a trailer has been set.
  • .removeTrailer(key) - Remove the value of a previously set trailer.
  • .type(value) - Sets the header Content-Type.
  • .redirect([code,] dest) - Redirect to the specified url, the status code is optional (default to 302).
  • .callNotFound() - Invokes the custom not found handler.
  • .serialize(payload) - Serializes the specified payload using the default JSON serializer or using the custom serializer (if one is set) and returns the serialized payload.
  • .getSerializationFunction(schema | httpStatus, [contentType]) - Returns the serialization function for the specified schema or http status, if any of either are set.
  • .compileSerializationSchema(schema, [httpStatus], [contentType]) - Compiles the specified schema and returns a serialization function using the default (or customized) SerializerCompiler. The optional httpStatus is forwarded to the SerializerCompiler if provided, default to undefined.
  • .serializeInput(data, schema, [,httpStatus], [contentType]) - Serializes the specified data using the specified schema and returns the serialized payload. If the optional httpStatus, and contentType are provided, the function will use the serializer function given for that specific content type and HTTP Status Code. Default to undefined.
  • .serializer(function) - Sets a custom serializer for the payload.
  • .send(payload) - Sends the payload to the user, could be a plain text, a buffer, JSON, stream, or an Error object.
  • .sent - A boolean value that you can use if you need to know if send has already been called.
  • .hijack() - interrupt the normal request lifecycle.
  • .raw - The http.ServerResponse from Node core.
  • .log - The logger instance of the incoming request.
  • .request - The incoming request.
  • .context - Access the Request's context property.
fastify.get('/', options, function (request, reply) {
  // Your code
  reply
    .code(200)
    .header('Content-Type', 'application/json; charset=utf-8')
    .send({ hello: 'world' })
})

Additionally, Reply provides access to the context of the request:

fastify.get('/', {config: {foo: 'bar'}}, function (request, reply) {
  reply.send('handler config.foo = ' + reply.context.config.foo)
})

.code(statusCode)

If not set via reply.code, the resulting statusCode will be 200.

.statusCode

This property reads and sets the HTTP status code. It is an alias for reply.code() when used as a setter.

if (reply.statusCode >= 299) {
  reply.statusCode = 500
}

.server

The Fastify server instance, scoped to the current encapsulation context.

fastify.decorate('util', function util () {
  return 'foo'
})

fastify.get('/', async function (req, rep) {
  return rep.server.util() // foo
})

.header(key, value)

Sets a response header. If the value is omitted or undefined, it is coerced to ''.

Note: the header's value must be properly encoded using encodeURI or similar modules such as encodeurl. Invalid characters will result in a 500 TypeError response.

For more information, see http.ServerResponse#setHeader.

  • set-cookie

    • When sending different values as a cookie with set-cookie as the key, every value will be sent as a cookie instead of replacing the previous value.
    reply.header('set-cookie', 'foo');
reply.header('set-cookie', 'bar');

    • The browser will only consider the latest reference of a key for the set-cookie header. This is done to avoid parsing the set-cookie header when added to a reply and speeds up the serialization of the reply.

    • To reset the set-cookie header, you need to make an explicit call to reply.removeHeader('set-cookie'), read more about .removeHeader(key) here.

.headers(object)

Sets all the keys of the object as response headers. .header will be called under the hood.

reply.headers({
  'x-foo': 'foo',
  'x-bar': 'bar'
})

.getHeader(key)

Retrieves the value of a previously set header.

reply.header('x-foo', 'foo') // setHeader: key, value
reply.getHeader('x-foo') // 'foo'

.getHeaders()

Gets a shallow copy of all current response headers, including those set via the raw http.ServerResponse. Note that headers set via Fastify take precedence over those set via http.ServerResponse.

reply.header('x-foo', 'foo')
reply.header('x-bar', 'bar')
reply.raw.setHeader('x-foo', 'foo2')
reply.getHeaders() // { 'x-foo': 'foo', 'x-bar': 'bar' }

.removeHeader(key)

Remove the value of a previously set header.

reply.header('x-foo', 'foo')
reply.removeHeader('x-foo')
reply.getHeader('x-foo') // undefined

.hasHeader(key)

Returns a boolean indicating if the specified header has been set.

.trailer(key, function)

Sets a response trailer. Trailer is usually used when you need a header that requires heavy resources to be sent after the data, for example, Server-Timing and Etag. It can ensure the client receives the response data as soon as possible.

Note: The header Transfer-Encoding: chunked will be added once you use the trailer. It is a hard requirement for using trailer in Node.js.

Note: Any error passed to done callback will be ignored. If you interested in the error, you can turn on debug level logging.

reply.trailer('server-timing', function() {
  return 'db;dur=53, app;dur=47.2'
})

const { createHash } = require('crypto')
// trailer function also receive two argument
// @param {object} reply fastify reply
// @param {string|Buffer|null} payload payload that already sent, note that it will be null when stream is sent
// @param {function} done callback to set trailer value
reply.trailer('content-md5', function(reply, payload, done) {
  const hash = createHash('md5')
  hash.update(payload)
  done(null, hash.disgest('hex'))
})

// when you prefer async-await
reply.trailer('content-md5', async function(reply, payload) {
  const hash = createHash('md5')
  hash.update(payload)
  return hash.disgest('hex')
})

.hasTrailer(key)

Returns a boolean indicating if the specified trailer has been set.

.removeTrailer(key)

Remove the value of a previously set trailer.

reply.trailer('server-timing', function() {
  return 'db;dur=53, app;dur=47.2'
})
reply.removeTrailer('server-timing')
reply.getTrailer('server-timing') // undefined

.redirect([code ,] dest)

Redirects a request to the specified URL, the status code is optional, default to 302 (if status code is not already set by calling code).

Note: the input URL must be properly encoded using encodeURI or similar modules such as encodeurl. Invalid URLs will result in a 500 TypeError response.

Example (no reply.code() call) sets status code to 302 and redirects to /home

reply.redirect('/home')

Example (no reply.code() call) sets status code to 303 and redirects to /home

reply.redirect(303, '/home')

Example (reply.code() call) sets status code to 303 and redirects to /home

reply.code(303).redirect('/home')

Example (reply.code() call) sets status code to 302 and redirects to /home

reply.code(303).redirect(302, '/home')

.callNotFound()

Invokes the custom not found handler. Note that it will only call preHandler hook specified in setNotFoundHandler.

reply.callNotFound()

.getResponseTime()

Invokes the custom response time getter to calculate the amount of time passed since the request was started.

Note that unless this function is called in the onResponse hook it will always return 0.

const milliseconds = reply.getResponseTime()

.type(contentType)

Sets the content type for the response. This is a shortcut for reply.header('Content-Type', 'the/type').

reply.type('text/html')

If the Content-Type has a JSON subtype, and the charset parameter is not set, utf-8 will be used as the charset by default.

.getSerializationFunction(schema | httpStatus, [contentType])

By calling this function using a provided schema or httpStatus, and the optional contentType, it will return a serialzation function that can be used to serialize diverse inputs. It returns undefined if no serialization function was found using either of the provided inputs.

This heavily depends of the schema#responses attached to the route, or the serialization functions compiled by using compileSerializationSchema.

const serialize = reply
                  .getSerializationFunction({
                    type: 'object', 
                    properties: { 
                      foo: { 
                        type: 'string' 
                      } 
                    } 
                  })
serialize({ foo: 'bar' }) // '{"foo":"bar"}'

// or

const serialize = reply
                  .getSerializationFunction(200)
serialize({ foo: 'bar' }) // '{"foo":"bar"}'

// or

const serialize = reply
                  .getSerializationFunction(200, 'application/json')
serialize({ foo: 'bar' }) // '{"foo":"bar"}'

See .compileSerializationSchema(schema, [httpStatus], [contentType]) for more information on how to compile serialization schemas.

.compileSerializationSchema(schema, [httpStatus], [contentType])

This function will compile a serialization schema and return a function that can be used to serialize data. The function returned (a.k.a. serialization function) returned is compiled by using the provided SerializerCompiler. Also this is cached by using a WeakMap for reducing compilation calls.

The optional parameters httpStatus and contentType, if provided, are forwarded directly to the SerializerCompiler, so it can be used to compile the serialization function if a custom SerializerCompiler is used.

This heavily depends of the schema#responses attached to the route, or the serialization functions compiled by using compileSerializationSchema.

const serialize = reply
                  .compileSerializationSchema({
                    type: 'object', 
                    properties: { 
                      foo: { 
                        type: 'string' 
                      } 
                    } 
                  })
serialize({ foo: 'bar' }) // '{"foo":"bar"}'

// or

const serialize = reply
                  .compileSerializationSchema({
                    type: 'object', 
                    properties: { 
                      foo: { 
                        type: 'string' 
                      } 
                    } 
                  }, 200)
serialize({ foo: 'bar' }) // '{"foo":"bar"}'

// or

const serialize = reply
                  .compileSerializationSchema({
                        '3xx': {
                          content: {
                            'application/json': {
                              schema: {
                                name: { type: 'string' },
                                phone: { type: 'number' }
                              }
                            }
                          }
                        }
                  }, '3xx', 'application/json')
serialize({ name: 'Jone', phone: 201090909090 }) // '{"name":"Jone", "phone":201090909090}'

Note that you should be careful when using this function, as it will cache the compiled serialization functions based on the schema provided. If the schemas provided is mutated or changed, the serialization functions will not detect that the schema has been altered and for instance it will reuse the previously compiled serialization function based on the reference of the schema previously provided.

If there's a need to change the properties of a schema, always opt to create a totally new object, otherwise the implementation won't benefit from the cache mechanism.

:Using the following schema as example:

const schema1 = {
  type: 'object',
  properties: {
    foo: {
      type: 'string'
    }
  }
}

Not

const serialize = reply.compileSerializationSchema(schema1)

// Later on...
schema1.properties.foo.type. = 'integer'
const newSerialize = reply.compileSerializationSchema(schema1)

console.log(newSerialize === serialize) // true

Instead

const serialize = reply.compileSerializationSchema(schema1)

// Later on...
const newSchema = Object.assign({}, schema1)
newSchema.properties.foo.type = 'integer'

const newSerialize = reply.compileSerializationSchema(newSchema)

console.log(newSerialize === serialize) // false

.serializeInput(data, [schema | httpStatus], [httpStatus], [contentType])

This function will serialize the input data based on the provided schema or HTTP status code. If both are provided the httpStatus will take precedence.

If there is not a serialization function for a given schema a new serialization function will be compiled, forwarding the httpStatus and contentType if provided.

reply
  .serializeInput({ foo: 'bar'}, {  
    type: 'object', 
    properties: { 
      foo: { 
        type: 'string' 
      } 
    } 
  }) // '{"foo":"bar"}'

// or

reply
  .serializeInput({ foo: 'bar'}, {
    type: 'object', 
    properties: { 
      foo: { 
        type: 'string' 
      } 
    } 
  }, 200) // '{"foo":"bar"}'

// or

reply
  .serializeInput({ foo: 'bar'}, 200) // '{"foo":"bar"}'

// or

reply
  .serializeInput({ name: 'Jone', age: 18 }, '200', 'application/vnd.v1+json') // '{"name": "Jone", "age": 18}'

See .compileSerializationSchema(schema, [httpStatus], [contentType]) for more information on how to compile serialization schemas.

.serializer(func)

By default, .send() will JSON-serialize any value that is not one of Buffer, stream, string, undefined, or Error. If you need to replace the default serializer with a custom serializer for a particular request, you can do so with the .serializer() utility. Be aware that if you are using a custom serializer, you must set a custom 'Content-Type' header.

reply
  .header('Content-Type', 'application/x-protobuf')
  .serializer(protoBuf.serialize)

Note that you don't need to use this utility inside a handler because Buffers, streams, and strings (unless a serializer is set) are considered to already be serialized.

reply
  .header('Content-Type', 'application/x-protobuf')
  .send(protoBuf.serialize(data))

See .send() for more information on sending different types of values.

.raw

This is the http.ServerResponse from Node core. Whilst you are using the Fastify Reply object, the use of Reply.raw functions is at your own risk as you are skipping all the Fastify logic of handling the HTTP response. e.g.:

app.get('/cookie-2', (req, reply) => {
  reply.setCookie('session', 'value', { secure: false }) // this will not be used

  // in this case we are using only the nodejs http server response object
  reply.raw.writeHead(200, { 'Content-Type': 'text/plain' })
  reply.raw.write('ok')
  reply.raw.end()
})

Another example of the misuse of Reply.raw is explained in Reply.

.sent

As the name suggests, .sent is a property to indicate if a response has been sent via reply.send(). It will also be true in case reply.hijack() was used.

In case a route handler is defined as an async function or it returns a promise, it is possible to call reply.hijack() to indicate that the automatic invocation of reply.send() once the handler promise resolve should be skipped. By calling reply.hijack(), an application claims full responsibility for the low-level request and response. Moreover, hooks will not be invoked.

Modifying the .sent property directly is deprecated. Please use the aforementioned .hijack() method to achieve the same effect.

.hijack()

Sometimes you might need to halt the execution of the normal request lifecycle and handle sending the response manually.

To achieve this, Fastify provides the reply.hijack() method that can be called during the request lifecycle (At any point before reply.send() is called), and allows you to prevent Fastify from sending the response, and from running the remaining hooks (and user handler if the reply was hijacked before).

app.get('/', (req, reply) => {
  reply.hijack()
  reply.raw.end('hello world')

  return Promise.resolve('this will be skipped')
})

If reply.raw is used to send a response back to the user, the onResponse hooks will still be executed.

.send(data)

As the name suggests, .send() is the function that sends the payload to the end user.

Objects

As noted above, if you are sending JSON objects, send will serialize the object with fast-json-stringify if you set an output schema, otherwise, JSON.stringify() will be used.

fastify.get('/json', options, function (request, reply) {
  reply.send({ hello: 'world' })
})

Strings

If you pass a string to send without a Content-Type, it will be sent as text/plain; charset=utf-8. If you set the Content-Type header and pass a string to send, it will be serialized with the custom serializer if one is set, otherwise, it will be sent unmodified (unless the Content-Type header is set to application/json; charset=utf-8, in which case it will be JSON-serialized like an object — see the section above).

fastify.get('/json', options, function (request, reply) {
  reply.send('plain string')
})

Streams

send can also handle streams by setting the 'Content-Type' header to 'application/octet-stream'.

fastify.get('/streams', function (request, reply) {
  const fs = require('fs')
  const stream = fs.createReadStream('some-file', 'utf8')
  reply.header('Content-Type', 'application/octet-stream')
  reply.send(stream)
})

When using async-await you will need to return or await the reply object:

fastify.get('/streams', async function (request, reply) {
  const fs = require('fs')
  const stream = fs.createReadStream('some-file', 'utf8')
  reply.header('Content-Type', 'application/octet-stream')
  return reply.send(stream)
})

Buffers

If you are sending a buffer and you have not set a 'Content-Type' header, send will set it to 'application/octet-stream'.

const fs = require('fs')
fastify.get('/streams', function (request, reply) {
  fs.readFile('some-file', (err, fileBuffer) => {
    reply.send(err || fileBuffer)
  })
})

When using async-await you will need to return or await the reply object:

const fs = require('fs')
fastify.get('/streams', async function (request, reply) {
  fs.readFile('some-file', (err, fileBuffer) => {
    reply.send(err || fileBuffer)
  })
  return reply
})

TypedArrays

send manages TypedArray and sets the 'Content-Type'=application/octet-stream' header if not already set.

const fs = require('fs')
fastify.get('/streams', function (request, reply) {
  const typedArray = new Uint16Array(10)
  reply.send(typedArray)
})

Errors

If you pass to send an object that is an instance of Error, Fastify will automatically create an error structured as the following:

{
  error: String        // the HTTP error message
  code: String         // the Fastify error code
  message: String      // the user error message
  statusCode: Number   // the HTTP status code
}

You can add custom properties to the Error object, such as headers, that will be used to enhance the HTTP response.

Note: If you are passing an error to send and the statusCode is less than 400, Fastify will automatically set it at 500.

Tip: you can simplify errors by using the http-errors module or @fastify/sensible plugin to generate errors:

fastify.get('/', function (request, reply) {
  reply.send(httpErrors.Gone())
})

To customize the JSON error output you can do it by:

  • setting a response JSON schema for the status code you need
  • add the additional properties to the Error instance

Notice that if the returned status code is not in the response schema list, the default behaviour will be applied.

fastify.get('/', {
  schema: {
    response: {
      501: {
        type: 'object',
        properties: {
          statusCode: { type: 'number' },
          code: { type: 'string' },
          error: { type: 'string' },
          message: { type: 'string' },
          time: { type: 'string' }
        }
      }
    }
  }
}, function (request, reply) {
  const error = new Error('This endpoint has not been implemented')
  error.time = 'it will be implemented in two weeks'
  reply.code(501).send(error)
})

If you want to customize error handling, check out setErrorHandler API.

Note: you are responsible for logging when customizing the error handler

API:

fastify.setErrorHandler(function (error, request, reply) {
  request.log.warn(error)
  var statusCode = error.statusCode >= 400 ? error.statusCode : 500
  reply
    .code(statusCode)
    .type('text/plain')
    .send(statusCode >= 500 ? 'Internal server error' : error.message)
})

Beware that calling reply.send(error) in your custom error handler will send the error to the default error handler. Check out the Reply Lifecycle for more information.

The not found errors generated by the router will use the setNotFoundHandler

API:

fastify.setNotFoundHandler(function (request, reply) {
  reply
    .code(404)
    .type('text/plain')
    .send('a custom not found')
})

Type of the final payload

The type of the sent payload (after serialization and going through any onSend hooks) must be one of the following types, otherwise, an error will be thrown:

  • string
  • Buffer
  • stream
  • undefined
  • null

Async-Await and Promises

Fastify natively handles promises and supports async-await.

Note that in the following examples we are not using reply.send.

const { promisify } = require('util')
const delay = promisify(setTimeout)

fastify.get('/promises', options, function (request, reply) {
 return delay(200).then(() => { return { hello: 'world' }})
})

fastify.get('/async-await', options, async function (request, reply) {
  await delay(200)
  return { hello: 'world' }
})

Rejected promises default to a 500 HTTP status code. Reject the promise, or throw in an async function, with an object that has statusCode (or status) and message properties to modify the reply.

fastify.get('/teapot', async function (request, reply) {
  const err = new Error()
  err.statusCode = 418
  err.message = 'short and stout'
  throw err
})

fastify.get('/botnet', async function (request, reply) {
  throw { statusCode: 418, message: 'short and stout' }
  // will return to the client the same json
})

If you want to know more please review Routes#async-await.

.then(fulfilled, rejected)

As the name suggests, a Reply object can be awaited upon, i.e. await reply will wait until the reply is sent. The await syntax calls the reply.then().

reply.then(fulfilled, rejected) accepts two parameters:

  • fulfilled will be called when a response has been fully sent,
  • rejected will be called if the underlying stream had an error, e.g. the socket has been destroyed.

For more details, see: