.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "CONNECT" "1" "September 2010" "" ""
.
.SH "NAME"
\fBconnect\fR \- high performance middleware framework for node
.
.P
Connect is a high performance middleware framework for node \fIhttp://nodejs\.org\fR featuring robust middleware for serving static files, advanced routing, cookie and session implementations, error handling and much more\.
.
.SH "Middleware Usage"
Below is an example which shows usage of the \fIlogger\fR middleware bundled with Connect, as well as \fIstaticProvder\fR\.
.
.IP "" 4
.
.nf

var connect = require(\'connect\');

var server = connect\.createServer(
    connect\.logger(),
    connect\.staticProvider(__dirname + \'/public\')
);

server\.listen(3000);
.
.fi
.
.IP "" 0
.
.SH "Middleware Authoring"
Connect middleware is simply a function which accepts the \fIrequest\fR, \fIresponse\fR objects\. Optionally the third parameter \fInext\fR can be used to continue down the middleware stack\. For example below is a middleware layer that simply responds with "hello world"\.
.
.IP "" 4
.
.nf

function helloWorld(req, res) {
    res\.writeHead(200, { \'Content\-Type\': \'text/plain\' });
    res\.end(\'hello world\');
}

connect\.createServer(helloWorld)\.listen(3000);
.
.fi
.
.IP "" 0
.
.P
Lets say we now have some middleware that will require a setup step, this can be done by returning a closure:
.
.IP "" 4
.
.nf

function respond(msg) {
    msg = msg || \'hello world\';
    return function(req, res) {
        res\.writeHead(200, { \'Content\-Type\': \'text/plain\' });
        res\.end(msg);
    }
}

connect\.createServer(respond(\'wahoo\'))\.listen(3000);
.
.fi
.
.IP "" 0
.
.P
To pass control to the next middleware layer, we may call the \fBnext()\fR function with an optional instanceof \fBError\fR\. Middleware with four parameters is an error handling middleware, the \fBerr\fR object can then be logged, used to issue a response, ignored, etc\.
.
.IP "" 4
.
.nf

function fail(req, res, next) {
    // Exceptions thrown will be automatically passed to next()
    // however for custom exceptions / async exceptions you may pass them
    next(new Error(\'something broke!\'));
}

function errorHandler(err, req, res, next) {
    res\.writeHead(500, { \'Content\-Type\': \'text/plain\' });
    res\.end(err\.stack);
}

connect\.createServer(fail, errorHandler)\.listen(3000);
.
.fi
.
.IP "" 0
.
.P
To make your middleware available to others, typically you write a module, and export the function itself:
.
.IP "" 4
.
.nf

  // delay\.js
  module\.exports = function(ms){
      ms = ms || 1000;
      return function(req, res, next){
        setTimeout(next, ms);
      }
  };

 // app\.js
 // delay one second before continuing down the stack
 connect\.createServer(require(\'\./delay\')(1000))\.listen(3000);
.
.fi
.
.IP "" 0
.
.SH "Bundled Middleware"
Connect ships with several helpful middleware modules, the following are currently provided out of the box:
.
.IP "" 4
.
.nf

bodyDecoder      Buffers and parses json and urlencoded request bodies (extenable)
conditionalGet   Provides 304 "Not Modified" support
errorHandler     Handles exceptions thrown, or passed through the stack
gzip             Compresses response bodies with gzip executable
lint             Aids in middleware development
logger           Provides common logger support, and custom log formats
methodOverride   Provides faux HTTP method support by using the "_method" key by default
redirect         Provides req\.redirect() with "magic" urls, ex: req\.redirect("back")
compiler         Supports arbitrary static compilation of files, currently supports less and sass\.
cacheManifest    Provides cache manifest for offline apps
jsonrpc          Provides JSON\-RPC 2\.0 support
staticProvider   Serves static files
router           Provides a feature rich routing API similar to Sinatra and Express
cookieDecoder    Provides cookie parsing support
session          Provides session support
cache            Provides memory caching
repl             Read Evaluate Print Loop attached to "/tmp/connect\.sock" for inspecting live servers
vhost            Virtual host support
.
.fi
.
.IP "" 0
.
.SS "Middleware Documentation"
To view middleware specific documentation execute:
.
.IP "" 4
.
.nf

$ man connect\-MIDDLEWARE
.
.fi
.
.IP "" 0
.
.P
For example:
.
.IP "" 4
.
.nf

$ man connect\-bodyDecoder
.
.fi
.
.IP "" 0