@amphibian/server
A bare bones node.js server based on Koa that makes setup and maintaining a breeze.
; const server = ; { contextstatus = 200; contextbody = message: 'Hello World!' something: await ;} server;
Handlers
There are two methods for setting up handlers: registerHandler
and registerRouteHandler
. The first method, registerHandler
, does not bind to any specific route and method, while the second, registerRouteHandler
, does.
You will have to call await next()
yourself if the handler should be skipped.
registerHandler
{ if contextmethod === 'get' contextbody = message: 'It works!'; return; await ;} server;
registerRouteHandler
Takes three arguments: name
, handler
and options
. name
can be omitted. options
takes two properties: method
and path
.
registerRouteHandler
takes care of calling await next()
for you.
{ contextbody = message: 'It works!'} server;
Middleware
Creating middleware is as easy as it gets. Just call next
, the second handler argument, to pass the request onto the next handler in the list.
{ console await ; console;} server;
Note that registerMiddleware
is exactly the same function as registerHandler
– using it is syntactic sugar that logs “Registered middleware” instead of “Registered handler”.
Advanced routing
For reference, the provided route (whether it's a RegExp
or a String
) is placed in context.routePath
. This might be useful for measuring the performance of each route.
{ console; // > /^\/message\/([^\/]+)$/} server;
String with parameters
Provide path
as a String
containing parameters prefixed by :
.
{ const yourMessage = contextargs; contextstatus = 200; contextbody = message: `Your message is: `;} server;
Path parameter matches are placed as property of the context.args
Object
.
RegExp
To take advantage of RegExp
routes using the built in router
utility, simply send a regular expression instead of a String
in the path
key of the options
object:
{ const message = contextargs; contextstatus = 200; contextbody = message: `Your message is: `;} server;
Any RegExp
matches are placed as an Array
in context.args
.
Options object
An options object can be passed as an argument in createServer
.
options.port (number)
Sets the port the server will listen on.
Default: 4000
options.logging (boolean|'errors')
Enables or disables logging. Set to String
errors
to only log errors.
Default: true
options.listen (boolean)
Useful when using @amphibian/server
in conjunction with socket.io
. Read more here.
Default: true
Error handling
@amphibian/server
will automatically handle errors by serving an error
object to the body
. The error object has two properties: code
and message
.
error.code
will default to unknown_error
if no code
is set on the Error
instance. The response.status
will default to 500
unless the Error
instance has a status
property. You can safely throw errors from a handler:
{ const error = 'Something went wrong'; errorstatus = 400; errorcode = 'my_error_code'; throw error;} server;
Navigating to /error
will yield the following response.body
, with 400
as response.status
:
Error boundaries
To do handle the errors before @amphibian/server
spits them out, set up an error boundary:
{ try await ; catch error if errorcode === 'fatal_error' console; throw 'camouflaged error'; throw error; } server;
Ensure the errorBoundary
is the first middleware/handler you register. You won't be able to catch errors from those that come before it.
Prevent logging an error
To prevent @amphiban/server
from logging an error, give the error a log
property set to false
.
const error = 'some_error';errorlog = false;throw error;
Graceful shutdown
To avoid dropping active requests when receiving a SIGTERM
signal, you should implement a SIGTERM
signal handler on the node process
. This will allow the server to finish active requests before shutting down.
The @amphibian/server
server
Object
has a Function
close
that returns a Promise
:
; const server = ; process;
New server requests that are received during shutdown will be refused as per net.server.close().
Usage with socket.io (as a koa callback)
;;; const server = ;const httpServer = http;const socket = ; io;httpServer;