DKX/Http/Server
Super simple HTTP server with middlewares support for node.js.
Installation
$ npm install --save @dkx/http-server
or with yarn
$ yarn add @dkx/http-server
Basic usage
const {Server} = require('@dkx/http-server');
const {someRandomMiddleware} = require('some-random-middleware');
const app = new Server;
app.use(someRandomMiddleware);
app.run(8080, () => {
console.log('Server is running on port 8080');
});
Writing middlewares
Each middleware is just an ordinary async function.
Middleware must call the next
function with current response
.
const {Server} = require('@dkx/http-server');
async function appendHeaderMiddleware(request, response, next)
{
response = response.withHeader('X-My-custom-header', 'hello world');
return next(response);
}
const app = new Server;
app.use(appendHeaderMiddleware);
Writing response data
function writeResponseDataMiddleware(request, response, next)
{
response.write('hello');
response.write(' ');
response.write('world');
return next(response);
}
Passing data between middlewares
function middlewareA(request, response, next, state)
{
state.message = 'hello world';
return next(response);
}
function middlewareB(request, response, next, state)
{
console.log(state.message); // output: hello world
return next(response);
}
Testing middlewares
Testing new middlewares is really easy with the built in helper function. It construct all the necessary objects and runs the middleware for you.
const {testMiddleware} = require('@dkx/http-server');
function myUselessMiddleware(request, response, next)
{
response.write('hello world');
response = response.withHeader('X-Middleware-header', 'lorem ipsum');
return next(response);
}
const data = [];
const response = await testMiddleware(myUselessMiddleware, {
method: 'POST',
url: '/v1/users/5',
body: 'some HTTP body',
headers: {
'X-My-custom-http-header': 'hello world'
},
state: {
msg: 'My custom shared state'
},
onBodyWrite: function(chunk) {
data.push(chunk.toString());
},
next: async function(res) {
console.log('Custom next function called');
return res;
},
});
console.log(response.getHeader('X-Middleware-header')); // output: "lorem ipsum"
console.log(data); // output: ["hello world"]
The testMiddleware
function can be used just with your middleware:
testMiddleware(myUselessMiddleware);
Server object
-
use
Append middleware.
Arguments:
middleware: Middleware
: middleware to attach. -
run()
Start the HTTP server.
Arguments:
port: number
: port where the HTTP server will be listening for new requests.fn: () => void
: callback called when server is ready to handle requests. -
close()
Stop running HTTP server.
Arguments:
fn: () => void
: callback called when server is completely shut down. -
middleware()
Run custom
Request
andResponse
.Arguments:
request: Request
: CustomRequest
objectresponse: Response
: CustomResponse
objectReturn:
Promise<Response>
: New response after running through the middleware stack.
Request object
-
method
Contains request method (
GET
,POST
, ...). -
url
Contains requested URL.
-
headers
Contains request HTTP headers.
-
body
Readable stream for accessing request data.
-
hasHeader()
Test if header exists.
Arguments:
name: string
: Name of header.Return:
boolean
-
getHeader()
Return HTTP header.
Arguments:
name: string
: Name of header.Return:
string|Array<string>|undefined
Response object
The Response
is an immutable object.
-
statusCode
Response status code, default
200
. -
statusMessage
Response status message, default is an empty string.
-
headers
Contains list of currently returned HTTP headers.
-
write()
Method for writing data into response body.
Arguments:
chunk: any
: data to write. -
withStatus()
Write response status.
Arguments:
code: number
: new response status code.message: string
: new response status message, default is an empty string.Return:
Response
: clonedResponse
object with modified status. -
hasHeader()
Check whether header exists.
Arguments:
name: string
: name of HTTP header to check.Return:
boolean
-
getHeader()
Get HTTP response header.
Arguments:
name: string
: name of HTTP header.defaultValue: undefined|string|number|Array<string>
: default value to return if HTTP header does not exists.Return:
undefined|string|number|Array<string>
-
withHeader()
Write response header.
Arguments:
name: string
: name of the new header.value: string
: value of the new header.Return:
Response
: clonedResponse
object with modified headers. -
withVaryHeader()
Write vary HTTP response header.
Arguments:
field: string|Array<string>
: name of header you wish to add into vary headerReturn:
Response
: clonedResponse
object with modified headers. -
removeHeader()
Remove response header.
Arguments:
name: string
: name of the removed header.Return:
Response
: clonedResponse
object with modified headers.
ResponseBody object
Writable stream for writing the response data.
-
write()
Write response chunk
Arguments:
chunk
: chunk of data to write.