'use strict'
|
|
/*
|
* node-res
|
*
|
* (c) Harminder Virk <virk@adonisjs.com>
|
*
|
* For the full copyright and license information, please view the LICENSE
|
* file that was distributed with this source code.
|
*/
|
|
const mime = require('mime-types')
|
const etag = require('etag')
|
const vary = require('vary')
|
const onFinished = require('on-finished')
|
const destroy = require('destroy')
|
|
const methods = require('./methods')
|
|
const returnContentAndType = function (body) {
|
/**
|
* Return the body and it's type when
|
* body is a string.
|
*/
|
if (typeof (body) === 'string') {
|
return {
|
body,
|
type: /^\s*</.test(body) ? 'text/html' : 'text/plain'
|
}
|
}
|
|
/**
|
* If body is a buffer, return the exact copy
|
* and type as bin.
|
*/
|
if (Buffer.isBuffer(body)) {
|
return { body, type: 'application/octet-stream' }
|
}
|
|
/**
|
* If body is a number or boolean. Convert it to
|
* a string and return the type as text.
|
*/
|
if (typeof (body) === 'number' || typeof (body) === 'boolean') {
|
return { body: String(body), type: 'text/plain' }
|
}
|
|
/**
|
* Otherwise check whether body is an object or not. If yes
|
* stringify it and otherwise return the exact copy.
|
*/
|
return typeof (body) === 'object'
|
? { body: JSON.stringify(body), type: 'application/json' }
|
: { body }
|
}
|
|
/**
|
* A simple IO module to make consistent HTTP response, without
|
* worrying about underlying details.
|
*
|
* @module Response
|
*/
|
const Response = exports = module.exports = {}
|
|
/**
|
* Copying all the descriptive methods to the response object.
|
*/
|
Response.descriptiveMethods = Object.keys(methods).map((method) => {
|
Response[method] = function (req, res, body) {
|
Response.status(res, methods[method])
|
Response.send(req, res, body)
|
}
|
return method
|
})
|
|
/**
|
* Returns the value of an existing header on
|
* the response object
|
*
|
* @method getHeader
|
*
|
* @param {ServerResponse} res
|
* @param {String} key
|
*
|
* @return {Array|String} Return type depends upon the header existing value
|
*
|
* @example
|
* ```js
|
* nodeRes.getHeader(res, 'Content-type')
|
* ```
|
*/
|
Response.getHeader = function (res, key) {
|
return res.getHeader(key)
|
}
|
|
/**
|
* Sets header on the response object. This method will wipe off
|
* existing values. To append to existing values, use `append`.
|
*
|
* @method header
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} key
|
* @param {String|Array} value
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.header(res, 'Content-type', 'application/json')
|
*
|
* // or set an array of headers
|
* nodeRes.header(res, 'Link', ['<http://localhost/>', '<http://localhost:3000/>'])
|
* ```
|
*/
|
Response.header = function (res, key, value) {
|
const values = Array.isArray(value) ? value.map(String) : value
|
res.setHeader(key, values)
|
}
|
|
/**
|
* Appends value to the header existing values.
|
*
|
* @method append
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} key
|
* @param {String|Array} value
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.append(res, 'Content-type', 'application/json')
|
*
|
* // or append an array of headers
|
* nodeRes.append(res, 'Link', ['<http://localhost/>', '<http://localhost:3000/>'])
|
* ```
|
*/
|
Response.append = function (res, key, value) {
|
const previousValue = Response.getHeader(res, key)
|
|
const headers = previousValue
|
? (Array.isArray(previousValue) ? previousValue.concat(value) : [previousValue].concat(value))
|
: value
|
|
Response.header(res, key, headers)
|
}
|
|
/**
|
* Set status on the HTTP res object
|
*
|
* @method status
|
*
|
* @param {http.ServerResponse} res
|
* @param {Number} code
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.status(res, 200)
|
* ```
|
*/
|
Response.status = function (res, code) {
|
res.statusCode = code
|
}
|
|
/**
|
* Sets the header on response object, only if it
|
* does not exists.
|
*
|
* @method safeHeader
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} key
|
* @param {String|Array} value
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.safeHeader(res, 'Content-type', 'application/json')
|
* ```
|
*/
|
Response.safeHeader = function (res, key, value) {
|
if (!res.getHeader(key)) {
|
Response.header(res, key, value)
|
}
|
}
|
|
/**
|
* Removes the header from response
|
*
|
* @method removeHeader
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} key
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.removeHeader(res, 'Content-type')
|
* ```
|
*/
|
Response.removeHeader = function (res, key) {
|
res.removeHeader(key)
|
}
|
|
/**
|
* Write string or buffer to the response object.
|
*
|
* @method write
|
*
|
* @param {http.ServerResponse} res
|
* @param {String|Buffer} body
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.write(res, 'Hello world')
|
* ```
|
*/
|
Response.write = function (res, body) {
|
res.write(body)
|
}
|
|
/**
|
* Explictly end HTTP response
|
*
|
* @method end
|
*
|
* @param {http.ServerResponse} res
|
* @param {String|Buffer} [payload]
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.end(res, 'Hello world')
|
* ```
|
*/
|
Response.end = function (res, payload) {
|
res.end(payload)
|
}
|
|
/**
|
* Send body as the HTTP response and end it. Also
|
* this method will set the appropriate `Content-type`
|
* and `Content-length`.
|
*
|
* If body is set to null, this method will end the response
|
* as 204.
|
*
|
* @method send
|
*
|
* @param {http.ServerRequest} req
|
* @param {http.ServerResponse} res
|
* @param {String|Buffer|Object|Stream} body
|
* @param {Boolean} [generateEtag = true]
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.send(req, res, 'Hello world')
|
*
|
* // or html
|
* nodeRes.send(req, res, '<h2> Hello world </h2>')
|
*
|
* // or JSON
|
* nodeRes.send(req, res, { greeting: 'Hello world' })
|
*
|
* // or Buffer
|
* nodeRes.send(req, res, Buffer.from('Hello world', 'utf-8'))
|
*
|
* // Ignore etag
|
* nodeRes.send(req, res, 'Hello world', false)
|
* ```
|
*/
|
Response.send = function (req, res, body = null, generateEtag = true) {
|
/**
|
* Handle streams
|
*/
|
if (body && typeof (body.pipe) === 'function') {
|
Response
|
.stream(res, body)
|
.catch((error) => {
|
Response.status(res, error.code === 'ENOENT' ? 404 : 500)
|
Response.send(req, res, error.message, generateEtag)
|
})
|
return
|
}
|
|
const chunk = Response.prepare(res, body)
|
|
if (chunk === null || req.method === 'HEAD') {
|
Response.end(res)
|
return
|
}
|
|
/**
|
* Generate etag when instructured for
|
*/
|
if (generateEtag) {
|
Response.etag(res, chunk)
|
}
|
|
Response.end(res, chunk)
|
}
|
|
/**
|
* Sets the Etag header for a given body chunk
|
*
|
* @method etag
|
*
|
* @param {http.ServerResponse} res
|
* @param {String|Buffer} body
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.etag(res, 'Hello world')
|
* ```
|
*/
|
Response.etag = function (res, body) {
|
Response.header(res, 'ETag', etag(body))
|
}
|
|
/**
|
* Prepares the response body by encoding it properly. Also
|
* sets appropriate headers based upon the body content type.
|
*
|
* This method is used internally by `send`, so you should
|
* never use it when calling `send`.
|
*
|
* It is helpful when you want to get the final payload and end the
|
* response at a later stage.
|
*
|
* @method prepare
|
*
|
* @param {http.ServerResponse} res
|
* @param {Mixed} body
|
*
|
* @return {String}
|
*
|
* @example
|
* ```js
|
* const chunk = nodeRes.prepare(res, '<h2> Hello </h2>')
|
*
|
* if (chunk) {
|
* nodeRes.etag(res, chunk)
|
*
|
* if (nodeReq.fresh(req, res)) {
|
* chunk = null
|
* nodeRes.status(304)
|
* }
|
*
|
* nodeRes.end(chunk)
|
* }
|
* ```
|
*/
|
Response.prepare = function (res, body) {
|
if (body === null) {
|
Response.status(res, 204)
|
Response.removeHeader(res, 'Content-Type')
|
Response.removeHeader(res, 'Content-Length')
|
Response.removeHeader(res, 'Transfer-Encoding')
|
return null
|
}
|
|
let { body: chunk, type } = returnContentAndType(body)
|
|
/**
|
* Remove unwanted headers when statuscode is 204 or 304
|
*/
|
if (res.statusCode === 204 || res.statusCode === 304) {
|
Response.removeHeader(res, 'Content-Type')
|
Response.removeHeader(res, 'Content-Length')
|
Response.removeHeader(res, 'Transfer-Encoding')
|
return chunk
|
}
|
|
const headers = typeof res.getHeaders === 'function' ? res.getHeaders() : (res._headers || {})
|
|
/**
|
* Setting content type. Ideally we can use `Response.type`, which
|
* sets the right charset too. But we will be doing extra
|
* processing for no reasons.
|
*/
|
if (type && !headers['content-type']) {
|
Response.header(res, 'Content-Type', `${type}; charset=utf-8`)
|
}
|
|
/**
|
* setting up content length as response header
|
*/
|
if (chunk && !headers['content-length']) {
|
Response.header(res, 'Content-Length', Buffer.byteLength(chunk))
|
}
|
|
return chunk
|
}
|
|
/**
|
* Prepares response for JSONP
|
*
|
* @method prepareJsonp
|
*
|
* @param {http.ServerResponse} res
|
* @param {Object} body
|
* @param {String} callbackFn
|
*
|
* @return {String}
|
*
|
* @example
|
* ```js
|
* const chunk = nodeRes.prepareJsonp(res, '<h2> Hello </h2>', 'callback')
|
*
|
* if (chunk) {
|
* nodeRes.etag(res, chunk)
|
*
|
* if (nodeReq.fresh(req, res)) {
|
* chunk = null
|
* nodeRes.status(304)
|
* }
|
*
|
* nodeRes.end(chunk)
|
* }
|
* ```
|
*/
|
Response.prepareJsonp = function (res, body, callbackFn) {
|
Response.header(res, 'X-Content-Type-Options', 'nosniff')
|
Response.safeHeader(res, 'Content-Type', 'text/javascript; charset=utf-8')
|
|
const parsedBody = JSON
|
.stringify(body)
|
.replace(/\u2028/g, '\\u2028')
|
.replace(/\u2029/g, '\\u2029')
|
|
/**
|
* setting up callbackFn on response body , typeof will make
|
* sure not to throw error of client if callbackFn is not
|
* a function
|
*/
|
return '/**/ typeof ' + callbackFn + " === 'function' && " + callbackFn + '(' + parsedBody + ');'
|
}
|
|
/**
|
* Returns the HTTP response with `Content-type`
|
* set to `application/json`.
|
*
|
* @method json
|
*
|
* @param {http.IncomingMessage} req
|
* @param {http.ServerResponse} res
|
* @param {Object} body
|
* @param {Boolean} [generateEtag = true]
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.json(req, res, { name: 'virk' })
|
* nodeRes.json(req, res, [ 'virk', 'joe' ])
|
* ```
|
*/
|
Response.json = function (req, res, body, generateEtag) {
|
Response.safeHeader(res, 'Content-Type', 'application/json; charset=utf-8')
|
Response.send(req, res, body, generateEtag)
|
}
|
|
/**
|
* Make JSONP response with `Content-type` set to
|
* `text/javascript`.
|
*
|
* @method jsonp
|
*
|
* @param {http.IncomingMessage} req
|
* @param {http.ServerResponse} res
|
* @param {Object} body
|
* @param {String} [callbackFn = 'callback']
|
* @param {Boolean} [generateEtag = true]
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.jsonp(req, res, { name: 'virk' }, 'callback')
|
* ```
|
*/
|
Response.jsonp = function (req, res, body, callbackFn = 'callback', generateEtag) {
|
Response.send(req, res, Response.prepareJsonp(res, body, callbackFn), generateEtag)
|
}
|
|
/**
|
* Set `Location` header on the HTTP response.
|
*
|
* @method location
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} url
|
*
|
* @return {void}
|
*/
|
Response.location = function (res, url) {
|
Response.header(res, 'Location', url)
|
}
|
|
/**
|
* Redirect the HTTP request to the given url.
|
*
|
* @method redirect
|
*
|
* @param {http.IncomingMessage} req
|
* @param {http.ServerResponse} res
|
* @param {String} url
|
* @param {Number} [status = 302]
|
*
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.redirect(req, res, '/')
|
* ```
|
*/
|
Response.redirect = function (req, res, url, status = 302) {
|
const body = ''
|
Response.status(res, status)
|
Response.location(res, url)
|
Response.send(req, res, body)
|
}
|
|
/**
|
* Add vary header to the HTTP response.
|
*
|
* @method vary
|
*
|
* @param {http.ServerResponse} res
|
* @param {String} field
|
*
|
* @return {void}
|
*/
|
Response.vary = function (res, field) {
|
vary(res, field)
|
}
|
|
/**
|
* Set content type header by looking up the actual
|
* type and setting charset to utf8.
|
*
|
* ### Note
|
* When defining custom charset, you must set pass the complete
|
* content type, otherwise `false` will be set as the
|
* content-type header.
|
*
|
* @method type
|
*
|
* @param {http.IncomingMessage} req
|
* @param {http.ServerResponse} res
|
* @param {String} [charset]
|
* @return {void}
|
*
|
* @example
|
* ```js
|
* nodeRes.type(res, 'html')
|
*
|
* nodeRes.type(res, 'json')
|
*
|
* nodeRes.type(res, 'text/html', 'ascii')
|
* ```
|
*/
|
Response.type = function (res, type, charset) {
|
type = charset ? `${type}; charset=${charset}` : type
|
Response.safeHeader(res, 'Content-Type', mime.contentType(type))
|
}
|
|
/**
|
* Pipe stream to the response. Also this method will make sure
|
* to destroy the stream, if request gets cancelled.
|
*
|
* The promise resolve when response finishes and rejects, when
|
* stream raises errors.
|
*
|
* @method stream
|
*
|
* @param {Object} res
|
* @param {Stream} body
|
*
|
* @returns {Promise}
|
*
|
* @example
|
* ```js
|
* Response.stream(res, fs.createReadStream('foo.txt'))
|
*
|
* // handle stream errors
|
* Response
|
* .stream(res, fs.createReadStream('foo.txt'))
|
* .catch((error) => {
|
* })
|
* ```
|
*/
|
Response.stream = function (res, body) {
|
return new Promise((resolve, reject) => {
|
if (typeof (body.pipe) !== 'function') {
|
reject(new Error('Body is not a valid stream'))
|
return
|
}
|
|
let finished = false
|
|
/**
|
* Error in stream
|
*/
|
body.on('error', (error) => {
|
if (finished) {
|
return
|
}
|
|
finished = true
|
destroy(body)
|
|
reject(error)
|
})
|
|
/**
|
* Consumed stream
|
*/
|
body.on('end', resolve)
|
|
/**
|
* Written response
|
*/
|
onFinished(res, function () {
|
finished = true
|
destroy(body)
|
})
|
|
/**
|
* Pipe to res
|
*/
|
body.pipe(res)
|
})
|
}
|
