Mach is an HTTP server and client library that runs in both node.js and the browser. It has the following goals:
- 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
Writing a "Hello world" HTTP server in Mach is simple.
var mach = require'mach';machservereturn "Hello world!";;
All mach 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.
var app = machstack;appusemachlogger;appget'/users/:id'var id = connparamsid;return getUseridthenconnjson200 user;;;
The call to
app.use above illustrates how middleware is used to compose applications. Mach ships with the following middleware:
mach.basicAuth: Provides authentication using HTTP Basic auth
mach.catch: Error handling at any position in the stack
mach.charset: Provides a default charset in responses
mach.contentType: Provides a default
mach.favicon: Handles requests for
mach.file: Efficiently serves static files
mach.gzip: Gzip-encodes response content for clients that
mach.logger: Logs HTTP requests to the console
mach.mapper: Provides virtual host mapping, similar to Apache's Virtual Hosts or nginx server blocks
mach.methodOverride: Overrides the HTTP method used in the request, for clients (like HTML forms) that don't support methods other than
mach.modified: HTTP caching using
mach.params: Multipart request parsing and handling
mach.proxy: Proxy request through to an alternate location
mach.rewrite: Rewrites request URLs on the fly, similar to Apache's mod_rewrite
mach.router: Request routing (ala Sinatra) based on the URL pathname
mach.session: HTTP sessions with pluggable storage including memory (for development and testing), cookies, and Redis
mach.stack: Provides a
usemechanism for composing applications fronted by middleware
mach.token: Cross-site request forgery protection
Please check out the source of a middleware file for detailed documentation on how to use it.
Writing an HTTP client is similarly straightforward.
var mach = require'mach';machget''thenconsole.logconnstatus connresponseheaders connresponseText;;
By default client responses are buffered and stored in the
responseText connection variable for convenience. However, if you'd like to access the raw stream of binary data in the response, you can use the
var fs = require'fs';machgeturl: ''binary: truethenconnresponseText; // undefinedconnresponsecontentpipefscreateWriteStream'twitter.html';;
Because all Mach applications share the same signature, it's easy to combine them in interesting ways. Mach's HTTP proxy implementation illustrates this beautifully: a proxy is simply an application that forwards the request somewhere else.
var proxyApp = machcreateProxy'';// In a server environment we can use the mach.proxy middleware// to proxy all requests to the proxy's location.appusemachproxy proxyApp;// In a client application we can call the proxy directly to// send a request to the proxy's location.machpostproxyAppparams:username: 'mjackson';
$ npm install mach
dist/mach.min.js in a
Please file issues on the issue tracker on GitHub.
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