A small, experimental, functional Node.js web server
focused on middleware, immutability, and the
simple abstraction of Handler(Request) -> Response.
klobb boils down to this:
- Handlers are async functions of signature
Request -> Response. - Middleware are higher-order functions of signature
Handler -> Handler. - Requests and Responses are Immutable.js Records.
import { Response } from 'klobb'
export default function handler (request) {
return Response.ok('Hello, world!')
}npm install --save klobb
package.json:
{
...
"scripts": {
"start": "klobb -p 3000 index.js"
}
}An app in klobb just needs to export a default async handler function.
index.js:
import { Response } from 'klobb';
export default async function (request) {
return Response.ok('Hello, world!')
}Now serve it:
$ npm start
Listening on 3000
Sometimes I have trouble getting klobb's CLI to launch the server
til I add a .babelrc to my project root:
{
"presets": ["es2015"],
"plugins": [
"transform-runtime",
"syntax-async-functions",
"transform-async-to-generator",
"transform-object-rest-spread"
]
}I have a weak understanding of where Babel looks for config. #willfix
Inspired by Clojure's ring, klobb aims to make systems slower and easier to reason about by modeling the request/response cycle as a succession of pure transformations:
Handler(Request) -> Response
For contrast, Node itself and thus other Node frameworks like Express and Koa expose the request and response as mutable arguments to all functions:
(Response, Response) -> ??? -> (Request, Response)
My goal with klobb is to see if I can arrive at a nice developer experience for this abstraction in Javascript.
Logging is a classic demonstration of the middleware abstraction.
// server.js
import { Response, compose } from 'klobb'
function logger () {
return function middleware (handler) {
return async function newHandler (request) {
console.log(`--> ${request.method} ${request.url}`)
const start = Date.now()
const response = await handler(request)
console.log(`<-- ${response.status} - ${Date.now() - start} ms`)
return response
}
}
}
const middleware = logger()
const handler = async function (request) {
return Response.ok('Hello world')
}
export default middleware(handler)klobb also comes with a Batteries module that implements (untested)
common and demonstratively useful middleware.
import { Response, Batteries, compose } from 'klobb'
const Cookie = Batteries.Cookie
const middleware = compose(
Batteries.logger(),
Batteries.notModified({ etag: true }),
Batteries.serveStatic('public', { maxage: 1000 * 60 * 60 * 24 }),
Batteries.jsonBodyParser(),
Batteries.Cookie.middleware(),
Batteries.Flash.middleware()
)
// You update cookies by simply returning a response with the
// cookies you want to send to the client
async function handler (request) {
const views = (parseInt(Cookie.get('views', request), 10) || 0) + 1
return Response.ok(`You have viewed this page ${views} time(s)`)
.tap(Cookie.set('views', views))
}
export default middleware(handler)I cobbled together a router that takes a tree and outputs a handler function.
Here's Reddits URL structure:
import { Response, Batteries, compose } from 'klobb'
const middleware = compose(...)
const handler = Batteries.router({
'/': {
// stick middleware anywhere. they'll get applied to all downstream
// routes and compose with any downstream middleware.
middleware: [mw1(), mw2()],
'/r': {
'/:subreddit': {
middleware: [loadSubreddit()],
GET: (request) => {
const subreddit = request.getIn(['state', 'params', 'subreddit'])
return Response.ok(`viewing subreddit ${subreddit}`)
}
}
},
'/u' {
'/:user': {
middleware: [loadUser()],
GET: (request) => {
const user = request.getIn(['state', 'params', 'user']);
return Response.ok(`viewing user ${user}`)
}
}
}
}
})
export default middleware(handler)Wildcard segments like '/:user' accrete a params map that can be found
in request.getIn(['state', 'params']).
Wildcards only match if there isn't an exact match segment on the same level.
For instance, GET /foo will always match /foo before /:uname.
If GET /users/42/big/zzz matches the route path '/users/:id/:size/zzz',
then request.getIn(['state', 'params']):
{ id: '42', size: 'big' }
const adminRoutes = {
'/admin': {
middleware: [ensureAdmin()],
GET: () => Response.ok('admin panel'),
'/users': {
'/:user_id': {
DELETE: () => {}
}
}
}
}
const authenticationRoutes = {
'/login': { GET: ..., POST: ... },
'/logout': { GET: ..., DELETE: ... },
'/register': { GET: ..., POST: ... }
}
const handler = Batteries.router({
'/': {
GET: () => Response.ok('Homepage'),
// Mount them to a root
'/admin': adminRoutes['/admin'],
// Or spread them in when they're flat
...authenticationRoutes
}
})Caveat: The router is naive and doesn't do any sort of backtracking.
Given these two routes:
/users/admin
/users/:user/info
The request GET /users/admin/info will 404 since the router makes no
attempt to reverse into the /:user/info branch once it commits to the
/admin branch.
It's trivial to bring your own templating. Just wrap your favorite library
with a promise that resolves into HTML and then await it.
klobb comes with a wrapper for Nunjucks in its Batteries module. It's just 28 lines of code.
import { Batteries } from 'klobb'
const render = Batteries.nunjucks('views', {
ext: '.html',
noCache: process.env.NODE_ENV === 'development'
})
const handler = Batteries.router({
'/': {
GET: async (request) => Response.ok(await render('homepage'))
'/:uname': {
middleware: [ensureAuthorized()],
GET: async (request) => {
const user = await db.getUser(request.getIn(['state', 'params', 'uname']))
if (!user) return Response.notFound()
return Response.ok(await render('show-user', { user: user }))
}
}
}
})The code above would expect views/homepage.html and views/show-user.html
to exist, relative to the project root.
I also put together a quick and dirty validation library in
Batteries/Validate.js.
For demonstration, I'll reimplement koa-skeleton's moderately advanced user-register validation.
import { Batteries, Response, Middleware } from 'klobb'
const Flash = Batteries.Flash
const { v, validateBody, ValidationError } = Batteries.Validate
async function handleSignup (req) {
// Throws ValidationError if the following fails
const vals = validateBody(req, {
uname: [
v.tip('Username required'),
v.required(),
v.isString(),
v.trim(),
v.checkPred(s => s.length > 0),
v.match(/^[a-z0-9_-]+$/i,
'Username must only contain a-z, 0-9, underscore (_), or hypen (-)'),
v.match(/[a-z]/i,
'Username must contain at least one letter (a-z)'),
v.checkNotPredMemo(memo => db.findUserByUname(memo.val), 'Username taken')
],
password2: [
v.tip('Password confirmation is required'),
v.required(),
v.isString(),
v.checkPred(s => s.length > 0)
],
password1: [
v.tip('Password is required'),
v.required(),
v.isString(),
v.checkPred(s => s.length > 0),
v.isLength(6, 100, 'Password must be 6-100 chars'),
v.tip('Password must match confirmation'),
v.checkPredMemo(memo => memo.vals.password2 === memo.val)
],
email: [
v.optional(),
v.tip('Invalid email address'),
v.trim(),
v.isEmail(),
v.isLength(1, 140, 'Email is too long')
]
})
// If it succeeds, then we will make it down here and `vals`
// will be set to an obj of our validated parameters.
const user = await db.insertUser(vals.uname, vals.password1, vals.email)
return Response.redirect(user.url)
.tap(Flash.set('message', ['success', 'Successfully registered. Welcome!']))
}
const interceptValidationError = Middleware.make(async (handler, request) => {
try {
return await handler(request)
} catch(err) {
if (err instanceof ValidationError) {
return Response.redirectBack(request)
.tap(Flash.set('message', ['dange', err.message || 'Validation error']))
.tap(Flash.set('progress', request.body))
}
throw err
}
})
const handler = Batteries.router({
'/': {
'/users': {
middleware: [interceptValidationError()],
POST: handleCreateUser
}
}
})klobb wraps your handler with its own top-level try/catch middleware
that turns any uncaught Error object into a response.
By default, it returns a 500 response with the body 'Internal Server Error'.
If you want to throw a custom status code and message, then just throw
an Error with those fields set:
if (invalid) {
const err = new Error("I can't let you do that, Starfox.")
err.status = 400
throw err
}Though klobb has a convenience function for throwing custom errors, mainly helpful in that it allows for one-liners:
import { createError } from 'klobb'
if (invalid) {
throw createError(400, 'My custom message')
throw createError(400)
}If an error has no err.message set, klobb sets the response body to the
standard HTTP description for the status code:
import { createError } from 'klobb';
throw new Error() => 500 'Internal Server Error'
throw new Error('Uh oh!') => 500 'Uh oh!'
throw createError(500) => 500 'Internal Server Error'
throw createError(500, 'Uh oh!') => 500 'Uh oh!'
throw createError(503) => 503 'Service Unavailable'
throw createError(413) => 400 'Payload Too Large'If you want to handle uncaught errors yourself, just wrap your handler in your
own try/catch middleware which will get to handle errors before klobb.
Example: Logging errors and then re-throwing them for klobb to handle:
import { Middleware } from 'klobb'
const logOnErrors = Middleware.make(async (handler, request) => {
try {
return await handler(request)
} catch(err) {
logError(err)
throw err
}
})
const middleware = compose(logOnErrors(), serveStatic('public'), ...)
export default middleware(handler)Or you can just return a response so that klobb's error handling never even catches any errors, effectively overriding klobb.
Example: Custom error-handler that converts all errors into JSON responses:
import { Middleware, Response } from 'klobb'
import statuses from 'statuses' // npm install --save statuses
const jsonErrors = Middleware.make(async (handler, request) => {
try {
return await handler(request)
} catch(err) {
const status = err.status || 500
const message = err.message || statuses[status]
return new Response(status).json({ error: message })
}
})
const middleware = compose(jsonErrors(), serveStatic('public'), ...)
export default middleware(handler)klobb's Request and Response objects are Immutable.js Records.
This basically means that their core keys cannot be removed, and arbitrary keys cannot be added. But they have most of the instance methods of Immutable.js Maps.
Instead, each Request and Response has a .state field which is an
Immutable.js Map that can be arbitrarily modified. Any extensions to
a Request or Response should be stored in the state map.
For example, here's an example of common middleware that uses the "session_id" cookie to load the current user from the database and then attaches the user to the request so that downstream middleware and handlers can access it:
import { Middleware, Batteries, compose } from 'klobb'
const Cookie = Batteries.Cookie
const loadCurrentUser = Middleware.make(async (handler, request) => {
const sessionId = Cookie.get('session_id', request)
if (!sessionId) return handler(request)
const currUser = await database.getUserBySessionId(sessionId)
if (!currUser) return handler(request)
return handler(request.setIn(['state', 'currUser'], currUser))
})
const handler = (request) => {
const currUser = request.getIn(['state', 'currUser'])
if (!currUser) return Response.ok('You are not logged in')
return Response.ok(`You are logged in as ${currUser.uname}`)
};
const middleware = compose(Cookie.middleware(), loadCurrentUser())
export default middleware(handler)Since a klobb app is just a function that takes a Request and returns a Response (i.e. a handler), it's trivial to compose multiple apps together.
import { Batteries } from 'klobb'
import app1 from './app1'
import app2 from './app2'
import app3 from './app3'
export default Batteries.router({
'/': {
'/app1': app1,
'/app2': app2,
'/app3': app3
}
})This abstraction was inspired by Express' res.format.
If you want to respond differently based on the request's Accept header,
then Batteries.negotiate takes a mapping of accept headers -> handlers and
returns a new handler.
It matches based on Request#accepts(...types).
If none of the branches match, then the negotiate handler returns a "406 Not Acceptable" response.
const handler = Batteries.negotiate({
'text/plain': () => Response.ok('Hello'),
'text/html': () => Response.ok('<p>Hello</p>'),
'application/json': () => Response.json({ message: 'Hello' })
})Or, even simpler:
const handler = Batteries.negotiate({
text: () => Response.ok('Hello'),
html: () => Response.ok('<p>Hello</p>'),
json: () => Response.json({ message: 'Hello' })
})If you want to hook into the case where none of the branches match, then
you can either wrap the final handle in middleware that checks if
response.status === 406.
Or you can provide a default branch:
const handler = Batteries.negotiate({
text: () => ...,
json: () => ...,
default: request => {
console.log('Unhandled accept header: ${request.getHeader('accept')}')
return new Response(406)
}
})Though be sure to respond with the appropriate 406 status code if you implement your own default branch handler.
A basic response just needs three keys:
{
status: 200,
headers: { 'content-type': 'text/plain' },
body: 'Hello, world!' // body can be one of String, Buffer, or Stream
}A request looks something like this:
{
method: 'GET',
url: '/test?foo=42',
path: '/test',
headers: {},
body: 'Hello, world!',
querystring: '?foo=42',
ip: '1.2.3.4,'
nreq: { ... underlying Node request ... }
}Though without any additional middleware, klobb does not parse the body at all.
The underlying Node request is always available at request.nreq and
is never converted into an immutable map itself.
A handler is an async function that takes a request and returns a response.
Being an async function, it actually returns a promise that you await,
but like Koa, klobb tries to free you from having to work with promises
directly in your middleware/handlers.
Here's a basic handler:
async function handler (request) {
return new Response(200, {}, 'Hello, world!')
}And here are some conveniences functions for making responses:
async function handler (request) {
return Response.make(200, {}, body) // alternative to `new` constructor
return Response.ok(body) // 200
return Response.notFound() // 404
return Response.notModified() // 304
return Response.json({ foo: 'bar' }) // 200, JSON encoded
return Response.redirect(url) // 302 Temporary
return Response.redirect(url, 301) // 301 Permanent
return Response.redirectBack() // 302 Permanent to referrer || homepage
}Middleware are functions that take and return handlers.
function noop (handler) {
return newHandler (request) {
// request is going downstream
const response = await handler(request)
// response is coming upstream
return response
}
}Use Middleware.compose to compose middleware.
// compose is re-exported from the root module for convenience
import { compose } from 'klobb'
const middleware = compose(mw1, mw2, mw3)
export default middleware(handler)compose returns a function that applies middleware from right to left
to the handler argument:
const middleware = compose(a, b, c)(handler)
const middleware = a(b(c(handler)))During a request, the above middleware execution order can be visualized as this:
+-------------------------------------------------+
| +---------------------------------------+ |
| | +-----------------------------+ | |
| | | | | |
request -> a -> b -> c -> (handler -> response) -> c -> b -> a -> response
^ | | | | | | |
| | | +-----------------------------+ | | v
client | +---------------------------------------+ | client
+-------------------------------------------------+
That is, in compose(a, b, c), middleware a touches the request first
and the response last.
The benefit of using klobb's own compose function is that it wraps
each middleware function to promote null responses into 404 responses.
async function handler (request) {
return // will get promoted into a 404
}
// e.g.
import { Response } from 'klobb'
async function handler (request) {
return Response.notFound()
}I would pefer to find a way to achieve this without having to provide my own compose function.
Middleware.make saves you some boilerplate by letting you create a
Middleware function by passing it a function of signature
(Handler, Request) -> Response:
const mw = Middleware.make(async (handler, req) => {
console.log('>>')
const res = await handler(req)
console.log('<<')
return res
});
const middleware = compose(mw(), mw(), mw())As per [unnecessary?] middleware convention, you must still invoke
the function mw() to get the middleware function. This is so that you
don't always need to look up whether a function is middleware or if it
returns middleware. i.e. mw(opts) vs mw.
MIT