- Reply
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..header(name, value)
- Sets a response header..headers(object)
- Sets all the keys of the object as a 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..type(value)
- Sets the headerContent-Type
..redirect([code,] dest)
- Redirect to the specified url, the status code is optional (default to302
)..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 ifsend
has already been called..raw
- Thehttp.ServerResponse
from Node core..res
(deprecated, use.raw
instead) - Thehttp.ServerResponse
from Node core..log
- The logger instance of the incoming request..request
- The incoming request.
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)
})
If not set via reply.code
, the resulting statusCode
will be 200
.
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
}
Sets a response header. If the value is omitted or undefined it is coerced
to ''
.
For more information, see http.ServerResponse#setHeader
.
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'
})
Retrieves the value of a previously set header.
reply.header('x-foo', 'foo') // setHeader: key, value
reply.getHeader('x-foo') // 'foo'
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' }
Remove the value of a previously set header.
reply.header('x-foo', 'foo')
reply.removeHeader('x-foo')
reply.getHeader('x-foo') // undefined
Returns a boolean indicating if the specified header has been set.
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
).
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')
Invokes the custom not found handler. Note that it will only call preHandler
hook specified in setNotFoundHandler
.
reply.callNotFound()
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()
Sets the content type for the response.
This is a shortcut for reply.header('Content-Type', 'the/type')
.
reply.type('text/html')
.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.
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.
This is the http.ServerResponse
from Node core. While you're using the fastify Reply
object, the use of Reply.raw
functions is at your own risk as you're skipping all the fastify
logic of handling the http response. eg:
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.
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:
app.get('/', (req, reply) => {
reply.sent = true
reply.raw.end('hello world')
return Promise.resolve('this will be skipped')
})
If the handler rejects, the error will be logged.
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 method reply.hijack()
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).
NB (*): If reply.raw
is used to send a response back to the user, onResponse
hooks will still be executed
As the name suggests, .send()
is the function that sends the payload to the end user.
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' })
})
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')
})
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'
.
fastify.get('/streams', function (request, reply) {
const fs = require('fs')
const stream = fs.createReadStream('some-file', 'utf8')
reply.send(stream)
})
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)
})
})
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 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:
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 completely customize the error handling, checkout 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)
})
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')
})
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
Fastify natively handles promises and supports async-await.
Note that in the following examples we are not using reply.send.
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.
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:
- fastify#1864 for the discussion about this feature
- https://promisesaplus.com/ for the definition of thenables
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then for the signature