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).
  • .header(name, value) - Sets a response header.
  • .getHeader(name) - Retrieve value of already set header.
  • .removeHeader(key) - Remove the value of a previously set header.
  • .hasHeader(name) - Determine if a header has been set.
  • .type(value) - Sets the header Content-Type.
  • .redirect([code,] url) - 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.
  • .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.
  • .res - The http.ServerResponse from Node core.
  • .log - The logger instance of the incoming request.
  • .request - The incoming request.
  1. fastify.get('/', options, function (request, reply) {
  2.   // Your code
  3.   reply
  4.     .code(200)
  5.     .header('Content-Type', 'application/json; charset=utf-8')
  6.     .send({ hello: 'world' })
  7. })

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

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

.code(statusCode)

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

.header(key, value)

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

For more information, see http.ServerResponse#setHeader.

.getHeader(key)

Retrieves the value of a previously set header.

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

.removeHeader(key)

Remove the value of a previously set header.

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

.hasHeader(key)

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

.redirect(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).

  1. reply.redirect('/home')

.callNotFound()

Invokes the custom not found handler.

  1. reply.callNotFound()

.getResponseTime()

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

  1. const milliseconds = reply.getResponseTime()

.type(contentType)

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

  1. reply.type('text/html')

.serializer(func)

.send() will by default JSON-serialize any value that is not one of: Buffer, stream, string, undefined, 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.

  1. reply
  2.   .header('Content-Type', 'application/x-protobuf')
  3.   .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.

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

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

.sent

As the name suggests, .sent is a property to indicate if a response has been sent via reply.send().

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

As an example:

  1. app.get('/', (req, reply) => {
  2.   reply.sent = true
  3.   reply.res.end('hello world')
  5.   return Promise.resolve('this will be skipped')
  6. })

If the handler rejects, the error will be logged.

.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.

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

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).

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

Streams

send can also handle streams out of the box, internally uses pump to avoid leaks of file descriptors. If you are sending a stream and you have not set a 'Content-Type' header, send will set it at 'application/octet-stream'.

  1. fastify.get('/streams', function (request, reply) {
  2.   const fs = require('fs')
  3.   const stream = fs.createReadStream('some-file', 'utf8')
  4.   reply.send(stream)
  5. })

Buffers

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

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

Errors

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

  1. {
  2.   error: String        // the http error message
  3.   code: String         // the Fastify error code
  4.   message: String      // the user error message
  5.   statusCode: Number   // the http status code
  6. }

You can add some custom property 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:

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

If you want to completely customize the error handling, checkout setErrorHandler API.Note: you are responsibile for logging when customizing the error handler

API:

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

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

API:

  1. fastify.setNotFoundHandler(function (request, reply) {
  2.   reply
  3.     .code(404)
  4.     .type('text/plain')
  5.     .send('a custom not found')
  6. })

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.

  1. const delay = promisify(setTimeout)
  3. fastify.get('/promises', options, function (request, reply) {
  4.  return delay(200).then(() => { return { hello: 'world' }})
  5. })
  7. fastify.get('/async-await', options, async function (request, reply) {
  8.   await delay(200)
  9.   return { hello: 'world' }
  10. })

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.

  1. fastify.get('/teapot', async function (request, reply) => {
  2.   const err = new Error()
  3.   err.statusCode = 418
  4.   err.message = 'short and stout'
  5.   throw err
  6. })

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

.then(fullfilled, 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(fullfilled, rejected) accepts two parameters:

  • fullfilled 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: