1 | <h1 align="center">Fastify</h1>
|
2 |
|
3 | ## Reply
|
4 | - [Reply](#reply)
|
5 | - [Introduction](#introduction)
|
6 | - [.code(statusCode)](#codestatuscode)
|
7 | - [.statusCode](#statusCode)
|
8 | - [.header(key, value)](#headerkey-value)
|
9 | - [.headers(object)](#headersobject)
|
10 | - [.getHeader(key)](#getheaderkey)
|
11 | - [.removeHeader(key)](#removeheaderkey)
|
12 | - [.hasHeader(key)](#hasheaderkey)
|
13 | - [.redirect(dest)](#redirectdest)
|
14 | - [.callNotFound()](#callnotfound)
|
15 | - [.getResponseTime()](#getresponsetime)
|
16 | - [.type(contentType)](#typecontenttype)
|
17 | - [.serializer(func)](#serializerfunc)
|
18 | - [.sent](#sent)
|
19 | - [.send(data)](#senddata)
|
20 | - [Objects](#objects)
|
21 | - [Strings](#strings)
|
22 | - [Streams](#streams)
|
23 | - [Buffers](#buffers)
|
24 | - [Errors](#errors)
|
25 | - [Type of the final payload](#type-of-the-final-payload)
|
26 | - [Async-Await and Promises](#async-await-and-promises)
|
27 | - [.then](#then)
|
28 |
|
29 | <a name="introduction"></a>
|
30 | ### Introduction
|
31 | The second parameter of the handler function is `Reply`.
|
32 | Reply is a core Fastify object that exposes the following functions
|
33 | and properties:
|
34 |
|
35 | - `.code(statusCode)` - Sets the status code.
|
36 | - `.status(statusCode)` - An alias for `.code(statusCode)`.
|
37 | - `.statusCode` - Read and set the HTTP status code.
|
38 | - `.header(name, value)` - Sets a response header.
|
39 | - `.headers(object)` - Sets all the keys of the object as a response headers.
|
40 | - `.getHeader(name)` - Retrieve value of already set header.
|
41 | - `.removeHeader(key)` - Remove the value of a previously set header.
|
42 | - `.hasHeader(name)` - Determine if a header has been set.
|
43 | - `.type(value)` - Sets the header `Content-Type`.
|
44 | - `.redirect([code,] url)` - Redirect to the specified url, the status code is optional (default to `302`).
|
45 | - `.callNotFound()` - Invokes the custom not found handler.
|
46 | - `.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.
|
47 | - `.serializer(function)` - Sets a custom serializer for the payload.
|
48 | - `.send(payload)` - Sends the payload to the user, could be a plain text, a buffer, JSON, stream, or an Error object.
|
49 | - `.sent` - A boolean value that you can use if you need to know if `send` has already been called.
|
50 | - `.res` - The [`http.ServerResponse`](https://nodejs.org/dist/latest/docs/api/http.html#http_class_http_serverresponse) from Node core.
|
51 | - `.log` - The logger instance of the incoming request.
|
52 | - `.request` - The incoming request.
|
53 |
|
54 | ```js
|
55 | fastify.get('/', options, function (request, reply) {
|
56 | // Your code
|
57 | reply
|
58 | .code(200)
|
59 | .header('Content-Type', 'application/json; charset=utf-8')
|
60 | .send({ hello: 'world' })
|
61 | })
|
62 | ```
|
63 |
|
64 | Additionally, `Reply` provides access to the context of the request:
|
65 |
|
66 | ```js
|
67 | fastify.get('/', {config: {foo: 'bar'}}, function (request, reply) {
|
68 | reply.send('handler config.foo = ' + reply.context.config.foo)
|
69 | })
|
70 | ```
|
71 |
|
72 | <a name="code"></a>
|
73 | ### .code(statusCode)
|
74 | If not set via `reply.code`, the resulting `statusCode` will be `200`.
|
75 |
|
76 | <a name="statusCode"></a>
|
77 | ### .statusCode
|
78 | This property reads and sets the HTTP status code. It is an alias for `reply.code()` when used as a setter.
|
79 | ```js
|
80 | if (reply.statusCode >= 299) {
|
81 | reply.statusCode = 500
|
82 | }
|
83 | ```
|
84 |
|
85 | <a name="header"></a>
|
86 | ### .header(key, value)
|
87 | Sets a response header. If the value is omitted or undefined it is coerced
|
88 | to `''`.
|
89 |
|
90 | For more information, see [`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest/docs/api/http.html#http_response_setheader_name_value).
|
91 |
|
92 | <a name="headers"></a>
|
93 | ### .headers(object)
|
94 | Sets all the keys of the object as response headers. [`.header`](#headerkey-value) will be called under the hood.
|
95 | ```js
|
96 | reply.headers({
|
97 | 'x-foo': 'foo',
|
98 | 'x-bar': 'bar'
|
99 | })
|
100 | ```
|
101 |
|
102 | <a name="getHeader"></a>
|
103 | ### .getHeader(key)
|
104 | Retrieves the value of a previously set header.
|
105 | ```js
|
106 | reply.header('x-foo', 'foo') // setHeader: key, value
|
107 | reply.getHeader('x-foo') // 'foo'
|
108 | ```
|
109 |
|
110 | <a name="getHeader"></a>
|
111 | ### .removeHeader(key)
|
112 |
|
113 | Remove the value of a previously set header.
|
114 | ```js
|
115 | reply.header('x-foo', 'foo')
|
116 | reply.removeHeader('x-foo')
|
117 | reply.getHeader('x-foo') // undefined
|
118 | ```
|
119 |
|
120 | <a name="hasHeader"></a>
|
121 | ### .hasHeader(key)
|
122 | Returns a boolean indicating if the specified header has been set.
|
123 |
|
124 | <a name="redirect"></a>
|
125 | ### .redirect([code ,] dest)
|
126 | 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`).
|
127 |
|
128 | Example (no `reply.code()` call) sets status code to `302` and redirects to `/home`
|
129 | ```js
|
130 | reply.redirect('/home')
|
131 | ```
|
132 |
|
133 | Example (no `reply.code()` call) sets status code to `303` and redirects to `/home`
|
134 | ```js
|
135 | reply.redirect(303, '/home')
|
136 | ```
|
137 |
|
138 | Example (`reply.code()` call) sets status code to `303` and redirects to `/home`
|
139 | ```js
|
140 | reply.code(303).redirect('/home')
|
141 | ```
|
142 |
|
143 | Example (`reply.code()` call) sets status code to `302` and redirects to `/home`
|
144 | ```js
|
145 | reply.code(303).redirect(302, '/home')
|
146 | ```
|
147 |
|
148 | <a name="call-not-found"></a>
|
149 | ### .callNotFound()
|
150 | Invokes the custom not found handler. Note that it will only call `preHandler` hook specified in [`setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#set-not-found-handler).
|
151 |
|
152 | ```js
|
153 | reply.callNotFound()
|
154 | ```
|
155 |
|
156 | <a name="getResponseTime"></a>
|
157 | ### .getResponseTime()
|
158 | Invokes the custom response time getter to calculate the amount of time passed since the request was started.
|
159 |
|
160 | ```js
|
161 | const milliseconds = reply.getResponseTime()
|
162 | ```
|
163 |
|
164 | <a name="type"></a>
|
165 | ### .type(contentType)
|
166 | Sets the content type for the response.
|
167 | This is a shortcut for `reply.header('Content-Type', 'the/type')`.
|
168 |
|
169 | ```js
|
170 | reply.type('text/html')
|
171 | ```
|
172 |
|
173 | <a name="serializer"></a>
|
174 | ### .serializer(func)
|
175 | `.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.
|
176 |
|
177 | ```js
|
178 | reply
|
179 | .header('Content-Type', 'application/x-protobuf')
|
180 | .serializer(protoBuf.serialize)
|
181 | ```
|
182 |
|
183 | 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.
|
184 |
|
185 | ```js
|
186 | reply
|
187 | .header('Content-Type', 'application/x-protobuf')
|
188 | .send(protoBuf.serialize(data))
|
189 | ```
|
190 |
|
191 | See [`.send()`](#send) for more information on sending different types of values.
|
192 |
|
193 | <a name="sent"></a>
|
194 | ### .sent
|
195 |
|
196 | As the name suggests, `.sent` is a property to indicate if
|
197 | a response has been sent via `reply.send()`.
|
198 |
|
199 | In case a route handler is defined as an async function or it
|
200 | returns a promise, it is possible to set `reply.sent = true`
|
201 | to indicate that the automatic invocation of `reply.send()` once the
|
202 | handler promise resolve should be skipped. By setting `reply.sent =
|
203 | true`, an application claims full responsibility of the low-level
|
204 | request and response. Moreover, hooks will not be invoked.
|
205 |
|
206 | As an example:
|
207 |
|
208 | ```js
|
209 | app.get('/', (req, reply) => {
|
210 | reply.sent = true
|
211 | reply.res.end('hello world')
|
212 |
|
213 | return Promise.resolve('this will be skipped')
|
214 | })
|
215 | ```
|
216 |
|
217 | If the handler rejects, the error will be logged.
|
218 |
|
219 | <a name="send"></a>
|
220 | ### .send(data)
|
221 | As the name suggests, `.send()` is the function that sends the payload to the end user.
|
222 |
|
223 | <a name="send-object"></a>
|
224 | #### Objects
|
225 | As noted above, if you are sending JSON objects, `send` will serialize the object with [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) if you set an output schema, otherwise `JSON.stringify()` will be used.
|
226 | ```js
|
227 | fastify.get('/json', options, function (request, reply) {
|
228 | reply.send({ hello: 'world' })
|
229 | })
|
230 | ```
|
231 |
|
232 | <a name="send-string"></a>
|
233 | #### Strings
|
234 | 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).
|
235 | ```js
|
236 | fastify.get('/json', options, function (request, reply) {
|
237 | reply.send('plain string')
|
238 | })
|
239 | ```
|
240 |
|
241 | <a name="send-streams"></a>
|
242 | #### Streams
|
243 | *send* can also handle streams out of the box, internally uses [pump](https://www.npmjs.com/package/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'`.
|
244 | ```js
|
245 | fastify.get('/streams', function (request, reply) {
|
246 | const fs = require('fs')
|
247 | const stream = fs.createReadStream('some-file', 'utf8')
|
248 | reply.send(stream)
|
249 | })
|
250 | ```
|
251 |
|
252 | <a name="send-buffers"></a>
|
253 | #### Buffers
|
254 | If you are sending a buffer and you have not set a `'Content-Type'` header, *send* will set it to `'application/octet-stream'`.
|
255 | ```js
|
256 | const fs = require('fs')
|
257 | fastify.get('/streams', function (request, reply) {
|
258 | fs.readFile('some-file', (err, fileBuffer) => {
|
259 | reply.send(err || fileBuffer)
|
260 | })
|
261 | })
|
262 | ```
|
263 |
|
264 | <a name="errors"></a>
|
265 | #### Errors
|
266 | If you pass to *send* an object that is an instance of *Error*, Fastify will automatically create an error structured as the following:
|
267 | ```js
|
268 | {
|
269 | error: String // the http error message
|
270 | code: String // the Fastify error code
|
271 | message: String // the user error message
|
272 | statusCode: Number // the http status code
|
273 | }
|
274 | ```
|
275 | You can add some custom property to the Error object, such as `headers`, that will be used to enhance the http response.<br>
|
276 | *Note: If you are passing an error to `send` and the statusCode is less than 400, Fastify will automatically set it at 500.*
|
277 |
|
278 | Tip: you can simplify errors by using the [`http-errors`](https://npm.im/http-errors) module or [`fastify-sensible`](https://github.com/fastify/fastify-sensible) plugin to generate errors:
|
279 |
|
280 | ```js
|
281 | fastify.get('/', function (request, reply) {
|
282 | reply.send(httpErrors.Gone())
|
283 | })
|
284 | ```
|
285 |
|
286 | If you want to completely customize the error handling, checkout [`setErrorHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#seterrorhandler) API.<br>
|
287 | *Note: you are responsibile for logging when customizing the error handler*
|
288 |
|
289 | API:
|
290 |
|
291 | ```js
|
292 | fastify.setErrorHandler(function (error, request, reply) {
|
293 | request.log.warn(error)
|
294 | var statusCode = error.statusCode >= 400 ? error.statusCode : 500
|
295 | reply
|
296 | .code(statusCode)
|
297 | .type('text/plain')
|
298 | .send(statusCode >= 500 ? 'Internal server error' : error.message)
|
299 | })
|
300 | ```
|
301 |
|
302 | The not found errors generated by the router will use the [`setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#setnotfoundhandler)
|
303 |
|
304 | API:
|
305 |
|
306 | ```js
|
307 | fastify.setNotFoundHandler(function (request, reply) {
|
308 | reply
|
309 | .code(404)
|
310 | .type('text/plain')
|
311 | .send('a custom not found')
|
312 | })
|
313 | ```
|
314 |
|
315 | <a name="payload-type"></a>
|
316 | #### Type of the final payload
|
317 | The type of the sent payload (after serialization and going through any [`onSend` hooks](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#the-onsend-hook)) must be one of the following types, otherwise an error will be thrown:
|
318 |
|
319 | - `string`
|
320 | - `Buffer`
|
321 | - `stream`
|
322 | - `undefined`
|
323 | - `null`
|
324 |
|
325 | <a name="async-await-promise"></a>
|
326 | #### Async-Await and Promises
|
327 | Fastify natively handles promises and supports async-await.<br>
|
328 | *Note that in the following examples we are not using reply.send.*
|
329 | ```js
|
330 | const delay = promisify(setTimeout)
|
331 |
|
332 | fastify.get('/promises', options, function (request, reply) {
|
333 | return delay(200).then(() => { return { hello: 'world' }})
|
334 | })
|
335 |
|
336 | fastify.get('/async-await', options, async function (request, reply) {
|
337 | await delay(200)
|
338 | return { hello: 'world' }
|
339 | })
|
340 | ```
|
341 |
|
342 | Rejected promises default to a `500` HTTP status code. Reject the promise, or `throw` in an `async function`, with an _Error_ object that has `statusCode` (or `status`) and `message` properties to modify the reply. Throwing plain objects is not supported, it must be an instance of _Error_, see:
|
343 |
|
344 | ```js
|
345 | fastify.get('/teapot', async function (request, reply) => {
|
346 | const err = new Error()
|
347 | err.statusCode = 418
|
348 | err.message = 'short and stout'
|
349 | throw err
|
350 | })
|
351 | ```
|
352 |
|
353 | If you want to know more please review [Routes#async-await](https://github.com/fastify/fastify/blob/master/docs/Routes.md#async-await).
|
354 |
|
355 | <a name="then"></a>
|
356 | ### .then(fullfilled, rejected)
|
357 |
|
358 | As the name suggests, a `Reply` object can be awaited upon, i.e. `await reply` will wait until the reply is sent.
|
359 | The `await` syntax calls the `reply.then()`.
|
360 |
|
361 | `reply.then(fullfilled, rejected)` accepts two parameters:
|
362 |
|
363 | - `fullfilled` will be called when a response has been fully sent,
|
364 | - `rejected` will be called if the underlying stream had an error, e.g.
|
365 | the socket has been destroyed.
|
366 |
|
367 | For more details, see:
|
368 |
|
369 | - https://github.com/fastify/fastify/issues/1864 for the discussion about this feature
|
370 | - https://promisesaplus.com/ for the definition of thenables
|
371 | - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then for the signature
|