spudly/http-fantasy-land

functional http server

[WIP] http-fantasy-land

A web server library that allows you to create your server using functional concepts.

Getting Started

npm install --save http-fantasy-land

import {listen, get} from 'http-fantasy-land';

const home = (response, request) => ({
  ...response,
  statusCode: 200,
  body: 'It works!',
});

const router = composeRoutes(
  get('/', home),
);

listen(router, {port: 8080}).then(stop => {
  console.log('Listening @ http://localhost:8080');
});

API

route functions

A route is a function that, given a request object and a response object, returns a new response (or a promise that resolves to one).

[TODO: elaborate]

request

The request object is serialized, immutable representation of an http.IncomingMessage object.

{
  method: String,
  url: String,
  headers: {
    [key: String]: String,
  },
}

response

The response object is a serialized, immutable representation of an http.ServerResponse object.

{
  status: Number,
  body: String|Stream,
  headers: {
    [key: String]: String,
  },
}

listen

listen :: ((Object, Object) -> Object, Object) -> Promise<() -> void>

Description: Creates and starts a http/https server using the supplied route and options. Returns a promise that resolves to a stop() function.

Arguments

route :: (Object, Object) -> Object

A Route function. Accepts a response object and a request object. Returns a new response object.

options :: Object

Server Configuration Options. Accepts port, hostname, and backlog from http.listen, as well as any option accepted by https.createServer

See the links above for detailed descriptions of each option.

Return Value: Function - A function that stops the server.

Example:

listen(route, {port: 8080}).then(stop => {
  console.log('Listening @ http://localhost:8080');
  setTimeout(() => {
    stop();
    console.log('Server stopped!');
  }, 500);
});

composeRoutes(...routes) => route

sendFile(file) => route

setHeader(name)(value) => route

get('/path', route) => route

head('/path', route) => route

post('/path', route) => route

put('/path', route) => route

del('/path', route) => route

connect('/path', route) => route

options('/path', route) => route

trace('/path', route) => route

patch('/path', route) => route

Compatibility

[TODO: document usage w/ express/connect/etc.]

http-fantasy-land's Issues

getCookie, setCookie

Add support for request.cookies and response.cookies keys.

request.rawHeaders

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_message_rawheaders

request.headers & response.headers

Right now we only support the Content-Type header via the response.type property.

Add a response.headers key that supports any type of header. Also add request.headers.

Integration

• Travis CI
• Greenkeeper
• Semantic-release
• Codecov

Others?

improved path matching, request.params

get(), post(), etc. should use path-to-regexp for path matching, and when the path pattern contains parameter names, it should provide those parameters to the function they wrap as request.params.

Unit Tests

Shoot for 100% Unit Test Coverage

request.hostname

Support a new request.hostname property.

request.httpVersion, request.httpVersionMajor, request.httpVersionMinor

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_message_httpversion

Use http.METHODS

Make use of http.METHODS.

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_http_methods

This can be used for: generating method functions: get(), post(), etc.

Validating response before sending...

accepts() function

Create a function called accept that takes a provided map of routes and chooses the best one to handle the request.

accepts({
  'text/html': sendHtml,
  'application/json': sendJson,
})(response, request);

Handle aborted event

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_event_aborted_1

response.statusMessage, rename response.status to response.statusCode

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_message_statuscode

static file server

create a function that makes a static file server (like express.static)

connect/express integration

Create a function that makes it so users can create middleware functions using this module that work inside of express/connect.

https support

Add https support to the listen() function.

Handle close event

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_event_close_2

Documentation

• Getting Started Guide
• API Documentation

Use http.STATUS_CODES

See https://nodejs.org/dist/latest-v7.x/docs/api/http.html#http_http_status_codes

We can use this to create a default for response.statusMessage, and we should probably throw an error if response.statusCode is not in http.STATUS_CODES.

Auto-Generate Changelogs

Contributing Guide

Create a contributing guide

License

Add license info to the repo

composeRoutesLeft?

Typically, a compose function works from right to left:

compose(thirdFn, secondFn, firstFn);

Our composeRoutes function follows this convention, and runs routes from right to left, but this doesn't read well in the code. For example:

composeRoutes(
  get('/', home),
  get('/about', about),
  get('/contact', contact),
);

This code looks like it should try home() first, then about(), then `contact() last.

Let's introduce a function that composes routes and runs them left-to-right instead.

Only question: what should we call it?

• composeRoutesLeft / composeRoutesRight ?
• router?
• left / right ?
• ltr / rtl ?