Skip to content
Browse files

Merge branch 'add/middleware' into gh-pages

  • Loading branch information...
2 parents 84d3ba3 + 38865c8 commit 0ae7998975f0dc210e502828465ff85417131f57 @tj tj committed
View
52 api.html
@@ -1,5 +1,5 @@
<!DOCTYPE html><html><head><title>Express - api reference</title><link rel="stylesheet" href="style.css"><link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700&amp;subset=latin,latin-ext"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script><script src="app.js"></script><script src="retina.js"></script></head><body class="inner"><div class="bar"></div><section id="content"><header><section id="logo"><span class="express">express<em>3.0.0</em></span><span class="description">
-web application framework for <a href="http://nodejs.org">node </a></span></section><nav class="clearfix"><a href="/" class=""> Home</a><a href="/api.html" class="active"> API Reference</a><a href="/guide.html" class=""> Guide</a><a href="/applications.html" class=""> Applications</a><a href="/community.html" class=""> Community</a><a href="/faq.html" class=""> FAQ</a></nav></header><ul id="menu"><li id="app-api"> <a href="#express">Application</a><ul id="app-menu"><li><a href="#express">express()</a></li><li><a href="#app.set">app.set()</a></li><li><a href="#app.get">app.get()</a></li><li><a href="#app.enable">app.enable()</a></li><li><a href="#app.disable">app.disable()</a></li><li><a href="#app.enabled">app.enabled()</a></li><li><a href="#app.disabled">app.disabled()</a></li><li><a href="#app.configure">app.configure()</a></li><li><a href="#app.use">app.use()</a></li><li><a href="#app.engine">app.engine()</a></li><li><a href="#app.param">app.param()</a></li><li><a href="#app-settings">application settings</a></li><li><a href="#app.VERB">application routing</a></li><li><a href="#app.all">app.all()</a></li><li><a href="#app.locals">app.locals</a></li><li><a href="#app.render">app.render()</a></li><li><a href="#app.routes">app.routes</a></li><li><a href="#app.listen">app.listen()</a></li></ul></li><li id="req-api"> <a href="#req.params">Request</a><ul id="req-menu"><li><a href="#req.params">req.params</a></li><li><a href="#req.query">req.query</a></li><li><a href="#req.body">req.body</a></li><li><a href="#req.files">req.files</a></li><li><a href="#req.param">req.param()</a></li><li><a href="#req.route">req.route</a></li><li><a href="#req.cookies">req.cookies</a></li><li><a href="#req.signedCookies">req.signedCookies</a></li><li><a href="#req.get">req.get()</a></li><li><a href="#req.accepts">req.accepts()</a></li><li><a href="#req.accepted">req.accepted</a></li><li><a href="#req.is">req.is()</a></li><li><a href="#req.ip">req.ip</a></li><li><a href="#req.ips">req.ips</a></li><li><a href="#req.path">req.path</a></li><li><a href="#req.host">req.host</a></li><li><a href="#req.fresh">req.fresh</a></li><li><a href="#req.stale">req.stale</a></li><li><a href="#req.xhr">req.xhr</a></li><li><a href="#req.protocol">req.protocol</a></li><li><a href="#req.secure">req.secure</a></li><li><a href="#req.subdomains">req.subdomains</a></li><li><a href="#req.originalUrl">req.originalUrl</a></li><li><a href="#req.acceptedLanguages">req.acceptedLanguages</a></li><li><a href="#req.acceptedCharsets">req.acceptedCharsets</a></li><li><a href="#req.acceptsCharset">req.acceptsCharset()</a></li><li><a href="#req.acceptsLanguage">req.acceptsLanguage()</a></li></ul></li><li id="res-api"> <a href="#res.status">Response</a><ul id="res-menu"><li><a href="#res.status">res.status()</a></li><li><a href="#res.set">res.set()</a></li><li><a href="#res.get">res.get()</a></li><li><a href="#res.cookie">res.cookie()</a></li><li><a href="#res.clearCookie">res.clearCookie()</a></li><li><a href="#res.redirect">res.redirect()</a></li><li><a href="#res.charset">res.charset</a></li><li><a href="#res.send">res.send()</a></li><li><a href="#res.json">res.json()</a></li><li><a href="#res.jsonp">res.jsonp()</a></li><li><a href="#res.type">res.type()</a></li><li><a href="#res.format">res.format()</a></li><li><a href="#res.attachment">res.attachment()</a></li><li><a href="#res.sendfile">res.sendfile()</a></li><li><a href="#res.download">res.download()</a></li><li><a href="#res.links">res.links()</a></li><li><a href="#res.locals">res.locals</a></li><li><a href="#res.render">res.render()</a></li></ul></li></ul><div id="right"><section><h3 id="express">express()</h3><p>Create an express application.
+web application framework for <a href="http://nodejs.org">node </a></span></section><nav class="clearfix"><a href="/" class=""> Home</a><a href="/api.html" class="active"> API Reference</a><a href="/guide.html" class=""> Guide</a><a href="/applications.html" class=""> Applications</a><a href="/community.html" class=""> Community</a><a href="/faq.html" class=""> FAQ</a></nav></header><ul id="menu"><li id="app-api"> <a href="#express">Application</a><ul id="app-menu"><li><a href="#express">express()</a></li><li><a href="#app.set">app.set()</a></li><li><a href="#app.get">app.get()</a></li><li><a href="#app.enable">app.enable()</a></li><li><a href="#app.disable">app.disable()</a></li><li><a href="#app.enabled">app.enabled()</a></li><li><a href="#app.disabled">app.disabled()</a></li><li><a href="#app.configure">app.configure()</a></li><li><a href="#app.use">app.use()</a></li><li><a href="#app.engine">app.engine()</a></li><li><a href="#app.param">app.param()</a></li><li><a href="#app-settings">application settings</a></li><li><a href="#app.VERB">application routing</a></li><li><a href="#app.all">app.all()</a></li><li><a href="#app.locals">app.locals</a></li><li><a href="#app.render">app.render()</a></li><li><a href="#app.routes">app.routes</a></li><li><a href="#app.listen">app.listen()</a></li></ul></li><li id="req-api"> <a href="#req.params">Request</a><ul id="req-menu"><li><a href="#req.params">req.params</a></li><li><a href="#req.query">req.query</a></li><li><a href="#req.body">req.body</a></li><li><a href="#req.files">req.files</a></li><li><a href="#req.param">req.param()</a></li><li><a href="#req.route">req.route</a></li><li><a href="#req.cookies">req.cookies</a></li><li><a href="#req.signedCookies">req.signedCookies</a></li><li><a href="#req.get">req.get()</a></li><li><a href="#req.accepts">req.accepts()</a></li><li><a href="#req.accepted">req.accepted</a></li><li><a href="#req.is">req.is()</a></li><li><a href="#req.ip">req.ip</a></li><li><a href="#req.ips">req.ips</a></li><li><a href="#req.path">req.path</a></li><li><a href="#req.host">req.host</a></li><li><a href="#req.fresh">req.fresh</a></li><li><a href="#req.stale">req.stale</a></li><li><a href="#req.xhr">req.xhr</a></li><li><a href="#req.protocol">req.protocol</a></li><li><a href="#req.secure">req.secure</a></li><li><a href="#req.subdomains">req.subdomains</a></li><li><a href="#req.originalUrl">req.originalUrl</a></li><li><a href="#req.acceptedLanguages">req.acceptedLanguages</a></li><li><a href="#req.acceptedCharsets">req.acceptedCharsets</a></li><li><a href="#req.acceptsCharset">req.acceptsCharset()</a></li><li><a href="#req.acceptsLanguage">req.acceptsLanguage()</a></li></ul></li><li id="res-api"> <a href="#res.status">Response</a><ul id="res-menu"><li><a href="#res.status">res.status()</a></li><li><a href="#res.set">res.set()</a></li><li><a href="#res.get">res.get()</a></li><li><a href="#res.cookie">res.cookie()</a></li><li><a href="#res.clearCookie">res.clearCookie()</a></li><li><a href="#res.redirect">res.redirect()</a></li><li><a href="#res.charset">res.charset</a></li><li><a href="#res.send">res.send()</a></li><li><a href="#res.json">res.json()</a></li><li><a href="#res.jsonp">res.jsonp()</a></li><li><a href="#res.type">res.type()</a></li><li><a href="#res.format">res.format()</a></li><li><a href="#res.attachment">res.attachment()</a></li><li><a href="#res.sendfile">res.sendfile()</a></li><li><a href="#res.download">res.download()</a></li><li><a href="#res.links">res.links()</a></li><li><a href="#res.locals">res.locals</a></li><li><a href="#res.render">res.render()</a></li></ul></li><li id="middleware-api"><a href="#middleware">Middleware</a><ul id="middleware-menu"><li><a href="#basicAuth">basicAuth()</a></li><li><a href="#bodyParser">bodyParser()</a></li><li><a href="#compress">compress()</a></li><li><a href="#cookieParser">cookieParser()</a></li><li><a href="#cookieSession">cookieSession()</a></li><li><a href="#csrf">csrf()</a></li><li><a href="#directory">directory()</a></li></ul></li></ul><div id="right"><section><h3 id="express">express()</h3><p>Create an express application.
</p><pre class="js"><code>var express = require('express');
var app = express();
@@ -793,7 +793,55 @@
res.render('user', { name: 'Tobi' }, function(err, html){
// ...
-});</code></pre></section></div></section><script>var _gaq = _gaq || [];
+});</code></pre></section><h2>Middleware</h2><a name="middleware"></a><section><h3 id="basicAuth">basicAuth()</h3><p>Basic Authentication middleware, populating <code>req.user</code>
+with the username.
+</p><p>Simple username and password:</p><pre class="js"><code>app.use(express.basicAuth('username', 'password'));
+</code></pre><p>Callback verification:</p><pre class="js"><code>app.use(express.basicAuth(function(user, pass){
+ return 'tj' == user & 'wahoo' == pass;
+}));
+</code></pre><p>Async callback verification, accepting <code>fn(err, user)</code>,
+in this case <code>req.user</code> will be the user object passed.
+</p><pre class="js"><code>app.use(connect.basicAuth(function(user, pass, fn){
+ User.authenticate({ user: user, pass: pass }, fn);
+}))</code></pre></section><section><h3 id="bodyParser">bodyParser()</h3><p>Request body parsing middleware supporting JSON, urlencoded,
+and multipart requests. This middleware is simply a wrapper
+the <code>json()</code>, <code>urlencoded()</code>, and
+<code>multipart()</code> middleware.
+</p><pre class="js"><code>app.use(express.bodyParser());
+
+// is equivalent to:
+app.use(express.json());
+app.use(express.urlencoded());
+app.use(express.multipart());</code></pre></section><section><h3 id="compress">compress()</h3><p>Compress response data with gzip / deflate. This middleware
+should be placed "high" within the stack to ensure all
+responses may be compressed.
+</p><pre class="js"><code>app.use(express.logger());
+app.use(express.compress());
+app.use(express.methodOverride());
+app.use(express.bodyParser());</code></pre></section><section><h3 id="cookieParser">cookieParser()</h3><p>Parses the Cookie header field and populates <code>req.cookies</code>
+with an object keyed by the cookie names. Optionally you may enabled
+signed cookie support by passing a <code>secret</code> string.
+</p><pre class="js"><code>app.use(express.cookieParser());
+app.use(express.cookieParser('some secret'));</code></pre></section><section><h3 id="cookieSession">cookieSession()</h3><p>Provides cookie-based sessions, and populates <code>req.session</code>.
+This middleware takes the following options:
+</p><ul><li><code>key</code> cookie name defaulting to <code>connect.sess</code></li><li><code>secret</code> prevents cookie tampering</li><li><code>cookie</code> session cookie settings, defaulting to <code>{ path: '/', httpOnly: true, maxAge: null }</code></li><li><code>proxy</code> trust the reverse proxy when setting secure cookies (via "x-forwarded-proto")</li></ul><pre class="js"><code>app.use(express.cookieSession());
+</code></pre><p>To clear a cookie simply assign the session to null before responding:</p><pre class="js"><code>req.session = null</code></pre></section><section><h3 id="csrf">csrf()</h3><p>CRSF protection middleware.
+</p><p>By default this middleware generates a token named "_csrf"
+which should be added to requests which mutate
+state, within a hidden form field, query-string etc. This
+token is validated against the visitor's <code>req.session._csrf</code>
+property.
+</p><p>The default <code>value</code> function checks <code>req.body</code> generated
+by the <code>bodyParser()</code> middleware, <code>req.query</code> generated
+by <code>query()</code>, and the "X-CSRF-Token" header field.
+</p><p>This middleware requires session support, thus should be added
+somewhere below <code>session()</code>.</p></section><section><h3 id="directory">directory()</h3><p>Directory serving middleware, serves the given <code>path</code>.
+This middleware may be paired with <code>static()</code> to serve
+files, providing a full-featured file browser.
+</p><pre class="js"><code>app.use(express.directory('public'))
+app.use(express.static('public'))
+</code></pre><p>This middleware accepts the following options:
+</p><ul><li><code>hidden</code> display hidden (dot) files. Defaults to false.</li><li><code>icons</code> display icons. Defaults to false.</li><li><code>filter</code> Apply this filter function to files. Defaults to false.</li></ul></section><!--include ./mw-errorHandler--><!--include ./mw-favicon--><!--include ./mw-json--><!--include ./mw-limit--><!--include ./mw-logger--><!--include ./mw-methodOverride--><!--include ./mw-multipart--><!--include ./mw-query--><!--include ./mw-responseTime--><!--include ./mw-static--><!--include ./mw-timeout--><!--include ./mw-urlencoded--><!--include ./mw-vhost--></div></section><script>var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-25235225-1']);
_gaq.push(['_trackPageview']);
View
4 api.jade
@@ -30,4 +30,8 @@ html
a(name='response')
include en/api/res
+ h2 Middleware
+ a(name='middleware')
+ include en/api/middleware
+
include includes/footer
View
10 en/api/menu.jade
@@ -71,3 +71,13 @@ ul#menu
li: a(href='#res.links') res.links()
li: a(href='#res.locals') res.locals
li: a(href='#res.render') res.render()
+ li#middleware-api
+ a(href='#middleware') Middleware
+ ul#middleware-menu
+ li: a(href='#basicAuth') basicAuth()
+ li: a(href='#bodyParser') bodyParser()
+ li: a(href='#compress') compress()
+ li: a(href='#cookieParser') cookieParser()
+ li: a(href='#cookieSession') cookieSession()
+ li: a(href='#csrf') csrf()
+ li: a(href='#directory') directory()
View
20 en/api/middleware.jade
@@ -0,0 +1,20 @@
+include ./mw-basicAuth
+include ./mw-bodyParser
+include ./mw-compress
+include ./mw-cookieParser
+include ./mw-cookieSession
+include ./mw-csrf
+include ./mw-directory
+//include ./mw-errorHandler
+//include ./mw-favicon
+//include ./mw-json
+//include ./mw-limit
+//include ./mw-logger
+//include ./mw-methodOverride
+//include ./mw-multipart
+//include ./mw-query
+//include ./mw-responseTime
+//include ./mw-static
+//include ./mw-timeout
+//include ./mw-urlencoded
+//include ./mw-vhost
View
27 en/api/mw-basicAuth.jade
@@ -0,0 +1,27 @@
+section
+ h3(id='basicAuth') basicAuth()
+
+ p.
+ Basic Authentication middleware, populating <code>req.user</code>
+ with the username.
+
+ p Simple username and password:
+
+ +js.
+ app.use(express.basicAuth('username', 'password'));
+
+ p Callback verification:
+
+ +js.
+ app.use(express.basicAuth(function(user, pass){
+ return 'tj' == user & 'wahoo' == pass;
+ }));
+
+ p.
+ Async callback verification, accepting <code>fn(err, user)</code>,
+ in this case <code>req.user</code> will be the user object passed.
+
+ +js.
+ app.use(connect.basicAuth(function(user, pass, fn){
+ User.authenticate({ user: user, pass: pass }, fn);
+ }))
View
16 en/api/mw-bodyParser.jade
@@ -0,0 +1,16 @@
+section
+ h3(id='bodyParser') bodyParser()
+
+ p.
+ Request body parsing middleware supporting JSON, urlencoded,
+ and multipart requests. This middleware is simply a wrapper
+ the <code>json()</code>, <code>urlencoded()</code>, and
+ <code>multipart()</code> middleware.
+
+ +js.
+ app.use(express.bodyParser());
+
+ // is equivalent to:
+ app.use(express.json());
+ app.use(express.urlencoded());
+ app.use(express.multipart());
View
13 en/api/mw-compress.jade
@@ -0,0 +1,13 @@
+section
+ h3(id='compress') compress()
+
+ p.
+ Compress response data with gzip / deflate. This middleware
+ should be placed "high" within the stack to ensure all
+ responses may be compressed.
+
+ +js.
+ app.use(express.logger());
+ app.use(express.compress());
+ app.use(express.methodOverride());
+ app.use(express.bodyParser());
View
11 en/api/mw-cookieParser.jade
@@ -0,0 +1,11 @@
+section
+ h3(id='cookieParser') cookieParser()
+
+ p.
+ Parses the Cookie header field and populates <code>req.cookies</code>
+ with an object keyed by the cookie names. Optionally you may enabled
+ signed cookie support by passing a <code>secret</code> string.
+
+ +js.
+ app.use(express.cookieParser());
+ app.use(express.cookieParser('some secret'));
View
20 en/api/mw-cookieSession.jade
@@ -0,0 +1,20 @@
+section
+ h3(id='cookieSession') cookieSession()
+
+ p.
+ Provides cookie-based sessions, and populates <code>req.session</code>.
+ This middleware takes the following options:
+
+ ul
+ li <code>key</code> cookie name defaulting to <code>connect.sess</code>
+ li <code>secret</code> prevents cookie tampering
+ li <code>cookie</code> session cookie settings, defaulting to <code>{ path: '/', httpOnly: true, maxAge: null }</code>
+ li <code>proxy</code> trust the reverse proxy when setting secure cookies (via "x-forwarded-proto")
+
+ +js.
+ app.use(express.cookieSession());
+
+ p To clear a cookie simply assign the session to null before responding:
+
+ +js.
+ req.session = null
View
22 en/api/mw-csrf.jade
@@ -0,0 +1,22 @@
+
+section
+ h3(id='csrf') csrf()
+
+ p.
+ CRSF protection middleware.
+
+ p.
+ By default this middleware generates a token named "_csrf"
+ which should be added to requests which mutate
+ state, within a hidden form field, query-string etc. This
+ token is validated against the visitor's <code>req.session._csrf</code>
+ property.
+
+ p.
+ The default <code>value</code> function checks <code>req.body</code> generated
+ by the <code>bodyParser()</code> middleware, <code>req.query</code> generated
+ by <code>query()</code>, and the "X-CSRF-Token" header field.
+
+ p.
+ This middleware requires session support, thus should be added
+ somewhere below <code>session()</code>.
View
21 en/api/mw-directory.jade
@@ -0,0 +1,21 @@
+
+section
+ h3(id='directory') directory()
+
+ p.
+ Directory serving middleware, serves the given <code>path</code>.
+ This middleware may be paired with <code>static()</code> to serve
+ files, providing a full-featured file browser.
+
+ +js.
+ app.use(express.directory('public'))
+ app.use(express.static('public'))
+
+ p.
+ This middleware accepts the following options:
+
+ ul
+ li<code>hidden</code> display hidden (dot) files. Defaults to false.
+ li<code>icons</code> display icons. Defaults to false.
+ li<code>filter</code> Apply this filter function to files. Defaults to false.
+

0 comments on commit 0ae7998

Please sign in to comment.
Something went wrong with that request. Please try again.