1 | get-uri
|
2 | =======
|
3 | ### Returns a `stream.Readable` from a URI string
|
4 | [![Build Status](https://github.com/TooTallNate/node-get-uri/workflows/Node%20CI/badge.svg)](https://github.com/TooTallNate/node-get-uri/actions?workflow=Node+CI)
|
5 |
|
6 | This high-level module accepts a URI string and returns a `Readable` stream
|
7 | instance. There is built-in support for a variety of "protocols", and it's
|
8 | easily extensible with more:
|
9 |
|
10 | | Protocol | Description | Example
|
11 | |:---------:|:-------------------------------:|:---------------------------------:
|
12 | | `data` | [Data URIs][data] | `data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D`
|
13 | | `file` | [File URIs][file] | `file:///c:/windows/example.ini`
|
14 | | `ftp` | [FTP URIs][ftp] | `ftp://ftp.kernel.org/pub/site/README`
|
15 | | `http` | [HTTP URIs][http] | `http://www.example.com/path/to/name`
|
16 | | `https` | [HTTPS URIs][https] | `https://www.example.com/path/to/name`
|
17 |
|
18 |
|
19 | Installation
|
20 | ------------
|
21 |
|
22 | Install with `npm`:
|
23 |
|
24 | ``` bash
|
25 | $ npm install get-uri
|
26 | ```
|
27 |
|
28 |
|
29 | Example
|
30 | -------
|
31 |
|
32 | To simply get a `stream.Readable` instance from a `file:` URI, try something like:
|
33 |
|
34 | ``` js
|
35 | var getUri = require('get-uri');
|
36 |
|
37 | // `file:` maps to a `fs.ReadStream` instance…
|
38 | getUri('file:///Users/nrajlich/wat.json', function (err, rs) {
|
39 | if (err) throw err;
|
40 | rs.pipe(process.stdout);
|
41 | });
|
42 | ```
|
43 |
|
44 |
|
45 | Missing Endpoints
|
46 | -----------------
|
47 |
|
48 | When you pass in a URI in which the resource referenced does not exist on the
|
49 | destination server, then a `NotFoundError` will be returned. The `code` of the
|
50 | error instance is set to `"ENOTFOUND"`, so you can special-case that in your code
|
51 | to detect when a bad filename is requested:
|
52 |
|
53 | ``` js
|
54 | getUri('http://example.com/resource.json', function (err, rs) {
|
55 | if (err) {
|
56 | if ('ENOTFOUND' == err.code) {
|
57 | // bad file path requested
|
58 | } else {
|
59 | // something else bad happened...
|
60 | throw err;
|
61 | }
|
62 | }
|
63 |
|
64 | // your app code…
|
65 | });
|
66 | ```
|
67 |
|
68 |
|
69 | Cacheability
|
70 | ------------
|
71 |
|
72 | When calling `getUri()` with the same URI multiple times, the `get-uri` module
|
73 | supports sending an indicator that the remote resource has not been modified
|
74 | since the last time it has been retreived from that node process.
|
75 |
|
76 | To do this, pass in a `cache` option to the "options object" argument
|
77 | with the value set to the `stream.Readable` instance that was previously
|
78 | returned. If the remote resource has not been changed since the last call for
|
79 | that same URI, then a `NotModifiedError` instance will be returned with it's
|
80 | `code` property set to `"ENOTMODIFIED"`.
|
81 |
|
82 | When the `"ENOTMODIFIED"` error occurs, then you can safely re-use the
|
83 | results from the previous `getUri()` call for that same URI:
|
84 |
|
85 | ``` js
|
86 | // maps to a `fs.ReadStream` instance
|
87 | getUri('http://example.com/resource.json', function (err, rs) {
|
88 | if (err) throw err;
|
89 |
|
90 | // … some time later, if you need to get this same URI again, pass in the
|
91 | // previous `stream.Readable` instance as `cache` option to potentially
|
92 | // receive an "ENOTMODIFIED" response:
|
93 | var opts = { cache: rs };
|
94 | getUri('http://example.com/resource.json', opts, function (err, rs2) {
|
95 | if (err) {
|
96 | if ('ENOTFOUND' == err.code) {
|
97 | // bad file path requested
|
98 | } else if ('ENOTMODIFIED' == err.code) {
|
99 | // source file has not been modified since last time it was requested,
|
100 | // so `rs2` is undefined and you are expected to re-use results from
|
101 | // a previous call to `getUri()`
|
102 | } else {
|
103 | // something else bad happened...
|
104 | throw err;
|
105 | }
|
106 | }
|
107 | });
|
108 | });
|
109 | ```
|
110 |
|
111 |
|
112 | API
|
113 | ---
|
114 |
|
115 | ### getUri(String uri[, Object options,] Function callback)
|
116 |
|
117 | A `uri` String is required. An optional `options` object may be passed in:
|
118 |
|
119 | - `cache` - A `stream.Readable` instance from a previous call to `getUri()` with the same URI. If this option is passed in, and the destination endpoint has not been modified, then an `ENOTMODIFIED` error is returned
|
120 |
|
121 | Any other options passed in to the `options` object will be passed through
|
122 | to the low-level connection creation functions (`http.get()`, `ftp.connect()`,
|
123 | etc).
|
124 |
|
125 | Invokes the given `callback` function with a `stream.Readable` instance to
|
126 | read the resource at the given `uri`.
|
127 |
|
128 | License
|
129 | -------
|
130 |
|
131 | (The MIT License)
|
132 |
|
133 | Copyright (c) 2014 Nathan Rajlich <nathan@tootallnate.net>
|
134 |
|
135 | Permission is hereby granted, free of charge, to any person obtaining
|
136 | a copy of this software and associated documentation files (the
|
137 | 'Software'), to deal in the Software without restriction, including
|
138 | without limitation the rights to use, copy, modify, merge, publish,
|
139 | distribute, sublicense, and/or sell copies of the Software, and to
|
140 | permit persons to whom the Software is furnished to do so, subject to
|
141 | the following conditions:
|
142 |
|
143 | The above copyright notice and this permission notice shall be
|
144 | included in all copies or substantial portions of the Software.
|
145 |
|
146 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
147 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
148 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
149 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
150 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
151 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
152 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
153 |
|
154 | [data]: http://tools.ietf.org/html/rfc2397
|
155 | [file]: http://tools.ietf.org/html/draft-hoffman-file-uri-03
|
156 | [ftp]: http://www.w3.org/Protocols/rfc959/
|
157 | [http]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
|
158 | [https]: http://wikipedia.org/wiki/HTTP_Secure
|