File: README.md

package info (click to toggle)
node-static 0.7.3-1
  • links: PTS, VCS
  • area: main
  • in suites: buster, jessie, jessie-kfreebsd, stretch
  • size: 148 kB
  • ctags: 35
  • sloc: makefile: 5
file content (201 lines) | stat: -rw-r--r-- 6,114 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
node-static
===========

> a simple, *rfc 2616 compliant* file streaming module for [node](http://nodejs.org)

node-static has an in-memory file cache, making it highly efficient.
node-static understands and supports *conditional GET* and *HEAD* requests.
node-static was inspired by some of the other static-file serving modules out there,
such as node-paperboy and antinode.

Synopsis
--------

    var static = require('node-static');

    //
    // Create a node-static server instance to serve the './public' folder
    //
    var file = new static.Server('./public');

    require('http').createServer(function (request, response) {
        request.addListener('end', function () {
            //
            // Serve files!
            //
            file.serve(request, response);
        }).resume();
    }).listen(8080);

API
---

### Creating a node-static Server #

Creating a file server instance is as simple as:

    new static.Server();

This will serve files in the current directory. If you want to serve files in a specific
directory, pass it as the first argument:

    new static.Server('./public');

You can also specify how long the client is supposed to cache the files node-static serves:

    new static.Server('./public', { cache: 3600 });

This will set the `Cache-Control` header, telling clients to cache the file for an hour.
This is the default setting.

### Serving files under a directory #

To serve files under a directory, simply call the `serve` method on a `Server` instance, passing it
the HTTP request and response object:
 
    var static = require('node-static');

    var fileServer = new static.Server('./public');

    require('http').createServer(function (request, response) {
        request.addListener('end', function () {
            fileServer.serve(request, response);
        }).resume();
    }).listen(8080);

### Serving specific files #

If you want to serve a specific file, like an error page for example, use the `serveFile` method:

    fileServer.serveFile('/error.html', 500, {}, request, response);

This will serve the `error.html` file, from under the file root directory, with a `500` status code.
For example, you could serve an error page, when the initial request wasn't found:

    require('http').createServer(function (request, response) {
        request.addListener('end', function () {
            fileServer.serve(request, response, function (e, res) {
                if (e && (e.status === 404)) { // If the file wasn't found
                    fileServer.serveFile('/not-found.html', 404, {}, request, response);
                }
            });
        }).resume();
    }).listen(8080);

More on intercepting errors bellow.

### Intercepting errors & Listening #

An optional callback can be passed as last argument, it will be called every time a file
has been served successfully, or if there was an error serving the file:

    var static = require('node-static');
    
    var fileServer = new static.Server('./public');

    require('http').createServer(function (request, response) {
        request.addListener('end', function () {
            fileServer.serve(request, response, function (err, result) {
                if (err) { // There was an error serving the file
                    sys.error("Error serving " + request.url + " - " + err.message);

                    // Respond to the client
                    response.writeHead(err.status, err.headers);
                    response.end();
                }
            });
        }).resume();
    }).listen(8080);

Note that if you pass a callback, and there is an error serving the file, node-static
*will not* respond to the client. This gives you the opportunity to re-route the request,
or handle it differently.

For example, you may want to interpret a request as a static request, but if the file isn't found,
send it to an application.

If you only want to *listen* for errors, you can use *event listeners*:

    fileServer.serve(request, response).addListener('error', function (err) {
        sys.error("Error serving " + request.url + " - " + err.message);
    });

With this method, you don't have to explicitly send the response back, in case of an error.

### Options when creating an instance of `Server` #

#### `cache` #

Sets the `Cache-Control` header.

example: `{ cache: 7200 }`

Passing a number will set the cache duration to that number of seconds.
Passing `false` will disable the `Cache-Control` header.

> Defaults to `3600`


#### `serverInfo` #

Sets the `Server` header.

example: `{ serverInfo: "myserver" }`

> Defaults to `node-static/{version}`

#### `headers` #

Sets response headers.

example: `{ 'X-Hello': 'World!' }`

> defaults to `{}`

#### `gzip` #

Enable support for sending compressed responses.  This will enable a check for a
file with the same name plus '.gz' in the same folder.  If the compressed file is
found and the client has indicated support for gzip file transfer, the contents
of the .gz file will be sent in place of the uncompressed file along with a
Content-Encoding: gzip header to inform the client the data has been compressed.

example: `{ gzip: true }`
example: `{ gzip: /^\/text/ }`

Passing `true` will enable this check for all files.
Passing a RegExp instance will only enable this check if the content-type of the
respond would match that RegExp using its test() method.

> Defaults to `false`


Command Line Interface
----------------------

`node-static` also provides a CLI.

### Installation #

    $ npm install -g node-static

### Example Usage #

    # serve up the current directory
    $ static
    serving "." at http://127.0.0.1:8080

    # serve up a different directory
    $ static public
    serving "public" at http://127.0.0.1:8080

    # specify additional headers (this one is useful for development)
    $ static -H '{"Cache-Control": "no-cache, must-revalidate"}'
    serving "." at http://127.0.0.1:8080

    # set cache control max age
    $ static -c 7200
    serving "." at http://127.0.0.1:8080

    # show help message, including all options
    $ static -h