blackbird-server

Master Branch:

Blackbird is an HTTP server that runs on Node (ES6+). It has the following goals:

• Simplicity: straightforward mapping of HTTP requests to JavaScript function calls
• Asynchronous: responses can be deferred using Promises/A+ promises
• Streaming: request and response bodies can be streamed
• Composability: middleware composes easily using promises
• Robustness: promises propagate errors up the call stack, simplifying error handling

Servers

Writing a "Hello world" HTTP server in BB is simple.

let BB = require('blackbird-server');
 
BB.serve(function (conn) {
  return "Hello world!";
});

All Blackbird applications receive a single argument: a Connection object. This object contains information about both the request and the response, as well as metadata including the method used in the request, the location of the request, the status of the response, and some helper methods.

Applications can send responses asynchronously using JavaScript promises. Simply return a promise from your app that resolves when the response is ready.

let app = BB.stack();
 
app.use(BB.logger);
 
app.get('/users/:id', function (conn) {
  let id = conn.params.id;
 
  return getUser(id).then(function (user) {
    conn.json(200, user);
  });
});

The call to app.use above illustrates how middleware is used to compose applications. BB ships with the following middleware:

• BB.basicAuth: Provides authentication using HTTP Basic auth
• BB.catch: Error handling at any position in the stack
• BB.charset: Provides a default charset in responses
• BB.contentType: Provides a default Content-Type
• BB.favicon: Handles requests for /favicon.ico
• BB.file: Efficiently serves static files
• BB.gzip: Gzip-encodes response content for clients that Accept: gzip
• BB.logger: Logs HTTP requests to the console
• BB.mapper: Provides virtual host mapping, similar to Apache's Virtual Hosts or nginx server blocks
• BB.methodOverride: Overrides the HTTP method used in the request, for clients (like HTML forms) that don't support methods other than GET and POST
• BB.modified: HTTP caching using Last-Modified and ETag
• BB.params: Multipart request parsing and handling
• BB.proxy: Proxy request through to an alternate location
• BB.rewrite: Rewrites request URLs on the fly, similar to Apache's mod_rewrite
• BB.router: Request routing (ala Sinatra) based on the URL pathname
• BB.session: HTTP sessions with pluggable storage including memory (for development and testing), cookies, and Redis
• BB.stack: Provides a use mechanism for composing applications fronted by middleware
• BB.token: Cross-site request forgery protection

Proxies

Because all BB applications share the same signature, it's easy to combine them in interesting ways. BB's HTTP proxy implementation illustrates this beautifully: a proxy is simply an application that forwards the request somewhere else.

let proxyApp = BB.createProxy('http://twitter.com');
 
// In a server environment we can use the BB.proxy middleware
// to proxy all requests to the proxy's location.
app.use(BB.proxy, proxyApp);
 
// In a client application we can call the proxy directly to
// send a request to the proxy's location.
BB.post(proxyApp, {
  params: {
    username: 'bkeown'
  }
});

Installation

Using npm:

$ npm install blackbird

Issues

Please file issues on the issue tracker on GitHub.

Tests

To run the tests in node:

$ npm install
$ npm test

The Redis session store tests rely on Redis to run successfully. By default they are skipped, but if you want to run them fire up a Redis server on the default host and port and set the $WITH_REDIS environment variable.

$ WITH_REDIS=1 npm test

To run the tests in Chrome:

$ npm install
$ npm run test-browser

Influences

• Strata
• Q-HTTP
• JSGI & Jack
• node.js
• Mach

License

MIT