source: trip-planner-front/node_modules/send/README.md@ 8d391a1

Last change on this file since 8d391a1 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 9.2 KB
Line 
1# send
2
3[![NPM Version][npm-version-image]][npm-url]
4[![NPM Downloads][npm-downloads-image]][npm-url]
5[![Linux Build][travis-image]][travis-url]
6[![Windows Build][appveyor-image]][appveyor-url]
7[![Test Coverage][coveralls-image]][coveralls-url]
8
9Send is a library for streaming files from the file system as a http response
10supporting partial responses (Ranges), conditional-GET negotiation (If-Match,
11If-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,
12and granular events which may be leveraged to take appropriate actions in your
13application or framework.
14
15Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).
16
17## Installation
18
19This is a [Node.js](https://nodejs.org/en/) module available through the
20[npm registry](https://www.npmjs.com/). Installation is done using the
21[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
22
23```bash
24$ npm install send
25```
26
27## API
28
29<!-- eslint-disable no-unused-vars -->
30
31```js
32var send = require('send')
33```
34
35### send(req, path, [options])
36
37Create a new `SendStream` for the given path to send to a `res`. The `req` is
38the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
39not the actual file-system path).
40
41#### Options
42
43##### acceptRanges
44
45Enable or disable accepting ranged requests, defaults to true.
46Disabling this will not send `Accept-Ranges` and ignore the contents
47of the `Range` request header.
48
49##### cacheControl
50
51Enable or disable setting `Cache-Control` response header, defaults to
52true. Disabling this will ignore the `immutable` and `maxAge` options.
53
54##### dotfiles
55
56Set how "dotfiles" are treated when encountered. A dotfile is a file
57or directory that begins with a dot ("."). Note this check is done on
58the path itself without checking if the path actually exists on the
59disk. If `root` is specified, only the dotfiles above the root are
60checked (i.e. the root itself can be within a dotfile when when set
61to "deny").
62
63 - `'allow'` No special treatment for dotfiles.
64 - `'deny'` Send a 403 for any request for a dotfile.
65 - `'ignore'` Pretend like the dotfile does not exist and 404.
66
67The default value is _similar_ to `'ignore'`, with the exception that
68this default will not ignore the files within a directory that begins
69with a dot, for backward-compatibility.
70
71##### end
72
73Byte offset at which the stream ends, defaults to the length of the file
74minus 1. The end is inclusive in the stream, meaning `end: 3` will include
75the 4th byte in the stream.
76
77##### etag
78
79Enable or disable etag generation, defaults to true.
80
81##### extensions
82
83If a given file doesn't exist, try appending one of the given extensions,
84in the given order. By default, this is disabled (set to `false`). An
85example value that will serve extension-less HTML files: `['html', 'htm']`.
86This is skipped if the requested file already has an extension.
87
88##### immutable
89
90Enable or diable the `immutable` directive in the `Cache-Control` response
91header, defaults to `false`. If set to `true`, the `maxAge` option should
92also be specified to enable caching. The `immutable` directive will prevent
93supported clients from making conditional requests during the life of the
94`maxAge` option to check if the file has changed.
95
96##### index
97
98By default send supports "index.html" files, to disable this
99set `false` or to supply a new index pass a string or an array
100in preferred order.
101
102##### lastModified
103
104Enable or disable `Last-Modified` header, defaults to true. Uses the file
105system's last modified value.
106
107##### maxAge
108
109Provide a max-age in milliseconds for http caching, defaults to 0.
110This can also be a string accepted by the
111[ms](https://www.npmjs.org/package/ms#readme) module.
112
113##### root
114
115Serve files relative to `path`.
116
117##### start
118
119Byte offset at which the stream starts, defaults to 0. The start is inclusive,
120meaning `start: 2` will include the 3rd byte in the stream.
121
122#### Events
123
124The `SendStream` is an event emitter and will emit the following events:
125
126 - `error` an error occurred `(err)`
127 - `directory` a directory was requested `(res, path)`
128 - `file` a file was requested `(path, stat)`
129 - `headers` the headers are about to be set on a file `(res, path, stat)`
130 - `stream` file streaming has started `(stream)`
131 - `end` streaming has completed
132
133#### .pipe
134
135The `pipe` method is used to pipe the response into the Node.js HTTP response
136object, typically `send(req, path, options).pipe(res)`.
137
138### .mime
139
140The `mime` export is the global instance of of the
141[`mime` npm module](https://www.npmjs.com/package/mime).
142
143This is used to configure the MIME types that are associated with file extensions
144as well as other options for how to resolve the MIME type of a file (like the
145default type to use for an unknown file extension).
146
147## Error-handling
148
149By default when no `error` listeners are present an automatic response will be
150made, otherwise you have full control over the response, aka you may show a 5xx
151page etc.
152
153## Caching
154
155It does _not_ perform internal caching, you should use a reverse proxy cache
156such as Varnish for this, or those fancy things called CDNs. If your
157application is small enough that it would benefit from single-node memory
158caching, it's small enough that it does not need caching at all ;).
159
160## Debugging
161
162To enable `debug()` instrumentation output export __DEBUG__:
163
164```
165$ DEBUG=send node app
166```
167
168## Running tests
169
170```
171$ npm install
172$ npm test
173```
174
175## Examples
176
177### Serve a specific file
178
179This simple example will send a specific file to all requests.
180
181```js
182var http = require('http')
183var send = require('send')
184
185var server = http.createServer(function onRequest (req, res) {
186 send(req, '/path/to/index.html')
187 .pipe(res)
188})
189
190server.listen(3000)
191```
192
193### Serve all files from a directory
194
195This simple example will just serve up all the files in a
196given directory as the top-level. For example, a request
197`GET /foo.txt` will send back `/www/public/foo.txt`.
198
199```js
200var http = require('http')
201var parseUrl = require('parseurl')
202var send = require('send')
203
204var server = http.createServer(function onRequest (req, res) {
205 send(req, parseUrl(req).pathname, { root: '/www/public' })
206 .pipe(res)
207})
208
209server.listen(3000)
210```
211
212### Custom file types
213
214```js
215var http = require('http')
216var parseUrl = require('parseurl')
217var send = require('send')
218
219// Default unknown types to text/plain
220send.mime.default_type = 'text/plain'
221
222// Add a custom type
223send.mime.define({
224 'application/x-my-type': ['x-mt', 'x-mtt']
225})
226
227var server = http.createServer(function onRequest (req, res) {
228 send(req, parseUrl(req).pathname, { root: '/www/public' })
229 .pipe(res)
230})
231
232server.listen(3000)
233```
234
235### Custom directory index view
236
237This is a example of serving up a structure of directories with a
238custom function to render a listing of a directory.
239
240```js
241var http = require('http')
242var fs = require('fs')
243var parseUrl = require('parseurl')
244var send = require('send')
245
246// Transfer arbitrary files from within /www/example.com/public/*
247// with a custom handler for directory listing
248var server = http.createServer(function onRequest (req, res) {
249 send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })
250 .once('directory', directory)
251 .pipe(res)
252})
253
254server.listen(3000)
255
256// Custom directory handler
257function directory (res, path) {
258 var stream = this
259
260 // redirect to trailing slash for consistent url
261 if (!stream.hasTrailingSlash()) {
262 return stream.redirect(path)
263 }
264
265 // get directory list
266 fs.readdir(path, function onReaddir (err, list) {
267 if (err) return stream.error(err)
268
269 // render an index for the directory
270 res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
271 res.end(list.join('\n') + '\n')
272 })
273}
274```
275
276### Serving from a root directory with custom error-handling
277
278```js
279var http = require('http')
280var parseUrl = require('parseurl')
281var send = require('send')
282
283var server = http.createServer(function onRequest (req, res) {
284 // your custom error-handling logic:
285 function error (err) {
286 res.statusCode = err.status || 500
287 res.end(err.message)
288 }
289
290 // your custom headers
291 function headers (res, path, stat) {
292 // serve all files for download
293 res.setHeader('Content-Disposition', 'attachment')
294 }
295
296 // your custom directory handling logic:
297 function redirect () {
298 res.statusCode = 301
299 res.setHeader('Location', req.url + '/')
300 res.end('Redirecting to ' + req.url + '/')
301 }
302
303 // transfer arbitrary files from within
304 // /www/example.com/public/*
305 send(req, parseUrl(req).pathname, { root: '/www/public' })
306 .on('error', error)
307 .on('directory', redirect)
308 .on('headers', headers)
309 .pipe(res)
310})
311
312server.listen(3000)
313```
314
315## License
316
317[MIT](LICENSE)
318
319[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/send/master?label=windows
320[appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
321[coveralls-image]: https://badgen.net/coveralls/c/github/pillarjs/send/master
322[coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
323[node-image]: https://badgen.net/npm/node/send
324[node-url]: https://nodejs.org/en/download/
325[npm-downloads-image]: https://badgen.net/npm/dm/send
326[npm-url]: https://npmjs.org/package/send
327[npm-version-image]: https://badgen.net/npm/v/send
328[travis-image]: https://badgen.net/travis/pillarjs/send/master?label=linux
329[travis-url]: https://travis-ci.org/pillarjs/send
Note: See TracBrowser for help on using the repository browser.