|
| 1 | +node-static |
| 2 | +=========== |
| 3 | + |
| 4 | +> a simple, *rfc 2616 compliant* file streaming module for [node](http://nodejs.org) |
| 5 | +
|
| 6 | +node-static has an in-memory file cache, making it highly efficient. |
| 7 | +node-static understands and supports *conditional GET* and *HEAD* requests. |
| 8 | +node-static was inspired by some of the other static-file serving modules out there, |
| 9 | +such as node-paperboy and antinode. |
| 10 | + |
| 11 | +synopsis |
| 12 | +-------- |
| 13 | + |
| 14 | + var static = require('node-static'); |
| 15 | + |
| 16 | + // |
| 17 | + // Create a node-static server instance to serve the './public' folder |
| 18 | + // |
| 19 | + var file = new(static.Server)('./public'); |
| 20 | + |
| 21 | + require('http').createServer(function (request, response) { |
| 22 | + request.addListener('end', function () { |
| 23 | + // |
| 24 | + // Serve files! |
| 25 | + // |
| 26 | + file.serve(request, response); |
| 27 | + }); |
| 28 | + }).listen(8080); |
| 29 | + |
| 30 | +API |
| 31 | +--- |
| 32 | + |
| 33 | +### Creating a node-static Server # |
| 34 | + |
| 35 | +Creating a file server instance is as simple as: |
| 36 | + |
| 37 | + new static.Server(); |
| 38 | + |
| 39 | +This will serve files in the current directory. If you want to serve files in a specific |
| 40 | +directory, pass it as the first argument: |
| 41 | + |
| 42 | + new static.Server('./public'); |
| 43 | + |
| 44 | +You can also specify how long the client is supposed to cache the files node-static serves: |
| 45 | + |
| 46 | + new static.Server('./public', { cache: 3600 }); |
| 47 | + |
| 48 | +This will set the `Cache-Control` header, telling clients to cache the file for an hour. |
| 49 | +This is the default setting. |
| 50 | + |
| 51 | +### Serving files under a directory # |
| 52 | + |
| 53 | +To serve files under a directory, simply call the `serve` method on a `Server` instance, passing it |
| 54 | +the HTTP request and response object: |
| 55 | + |
| 56 | + var fileServer = new static.Server('./public'); |
| 57 | + |
| 58 | + require('http').createServer(function (request, response) { |
| 59 | + request.addListener('end', function () { |
| 60 | + fileServer.serve(request, response); |
| 61 | + }); |
| 62 | + }).listen(8080); |
| 63 | + |
| 64 | +### Serving specific files # |
| 65 | + |
| 66 | +If you want to serve a specific file, like an error page for example, use the `serveFile` method: |
| 67 | + |
| 68 | + fileServer.serveFile('/error.html', 500, {}, request, response); |
| 69 | + |
| 70 | +This will serve the `error.html` file, from under the file root directory, with a `500` status code. |
| 71 | +For example, you could serve an error page, when the initial request wasn't found: |
| 72 | + |
| 73 | + require('http').createServer(function (request, response) { |
| 74 | + request.addListener('end', function () { |
| 75 | + fileServer.serve(request, response, function (e, res) { |
| 76 | + if (e && (e.status === 404)) { // If the file wasn't found |
| 77 | + fileServer.serveFile('/not-found.html', request, response); |
| 78 | + } |
| 79 | + }); |
| 80 | + }); |
| 81 | + }).listen(8080); |
| 82 | + |
| 83 | +More on intercepting errors bellow. |
| 84 | + |
| 85 | +### Intercepting errors & Listening # |
| 86 | + |
| 87 | +An optional callback can be passed as last argument, it will be called every time a file |
| 88 | +has been served successfully, or if there was an error serving the file: |
| 89 | + |
| 90 | + var fileServer = new static.Server('./public'); |
| 91 | + |
| 92 | + require('http').createServer(function (request, response) { |
| 93 | + request.addListener('end', function () { |
| 94 | + fileServer.serve(request, response, function (err, result) { |
| 95 | + if (err) { // There was an error serving the file |
| 96 | + sys.error("Error serving " + request.url + " - " + err.message); |
| 97 | + |
| 98 | + // Respond to the client |
| 99 | + response.writeHead(err.status, err.headers); |
| 100 | + response.end(); |
| 101 | + } |
| 102 | + }); |
| 103 | + }); |
| 104 | + }).listen(8080); |
| 105 | + |
| 106 | +Note that if you pass a callback, and there is an error serving the file, node-static |
| 107 | +*will not* respond to the client. This gives you the opportunity to re-route the request, |
| 108 | +or handle it differently. |
| 109 | + |
| 110 | +For example, you may want to interpret a request as a static request, but if the file isn't found, |
| 111 | +send it to an application. |
| 112 | + |
| 113 | +If you only want to *listen* for errors, you can use *event listeners*: |
| 114 | + |
| 115 | + fileServer.serve(request, response).addListener('error', function (err) { |
| 116 | + sys.error("Error serving " + request.url + " - " + err.message); |
| 117 | + }); |
| 118 | + |
| 119 | +With this method, you don't have to explicitly send the response back, in case of an error. |
| 120 | + |
| 121 | +### Options when creating an instance of `Server` # |
| 122 | + |
| 123 | +#### `cache` # |
| 124 | + |
| 125 | +Sets the `Cache-Control` header. |
| 126 | + |
| 127 | +example: `{ cache: 7200 }` |
| 128 | + |
| 129 | +Passing a number will set the cache duration to that number of seconds. |
| 130 | +Passing `false` will disable the `Cache-Control` header. |
| 131 | + |
| 132 | +> Defaults to `3600` |
| 133 | +
|
| 134 | +#### `headers` # |
| 135 | + |
| 136 | +Sets response headers. |
| 137 | + |
| 138 | +example: `{ 'X-Hello': 'World!' }` |
| 139 | + |
| 140 | +> Defaults to `{}` |
| 141 | +
|
| 142 | +#### `AutoIndex` # |
| 143 | + |
| 144 | +Automatically generates an html index page for directory listings |
| 145 | + |
| 146 | +example: `{ 'AutoIndex': true }` |
| 147 | + |
| 148 | +> Defaults to `false` |
| 149 | +
|
0 commit comments