1 | # custom-protocol-handler
|
2 | [![build status](https://badgen.net/travis/vladimyr/custom-protocol-handler)](https://travis-ci.com/vladimyr/custom-protocol-handler/) [![install size](https://badgen.net/packagephobia/install/custom-protocol-handler)](https://packagephobia.now.sh/result?p=custom-protocol-handler) [![npm package version](https://badgen.net/npm/v/custom-protocol-handler)](https://npm.im/custom-protocol-handler) [![github license](https://badgen.net/github/license/vladimyr/custom-protocol-handler)](https://github.com/vladimyr/custom-protocol-handler/blob/master/LICENSE) [![js semistandard style](https://badgen.net/badge/code%20style/semistandard/pink)](https://github.com/Flet/semistandard)
|
3 |
|
4 | > Resolve custom protocols using registered handlers.
|
5 |
|
6 | ## Instalation
|
7 |
|
8 | $ npm install custom-protocol-handler
|
9 |
|
10 | ## Usage
|
11 |
|
12 | This module can be used either in standalone mode or as [Express](https://expressjs.com) middleware.
|
13 |
|
14 | ```js
|
15 | const protocolHandler = require('custom-protocol-handler')();
|
16 | protocolHandler.protocol('s3://', url => 'https://example.com');
|
17 |
|
18 | // Standalone usage
|
19 | protocolHandler.resolve('s3://test').then(url => console.log(url));
|
20 | //=> https://example.com
|
21 |
|
22 | // Using as Express middleware
|
23 | const port = 3000;
|
24 | const app = require('express')();
|
25 | app.get('/resolve', protocolHandler.middleware());
|
26 | app.listen(port, () => console.log('listening on port: %i!', port));
|
27 | ```
|
28 |
|
29 | <details>
|
30 | <summary>Click to open HTTP log</summary>
|
31 |
|
32 | $ ./example.sh
|
33 |
|
34 | # resolve registered protocol: `s3:`
|
35 |
|
36 | GET /resolve?url=s3://test HTTP/1.1
|
37 | Accept: */*
|
38 | Accept-Encoding: gzip, deflate
|
39 | Connection: keep-alive
|
40 | Host: localhost:3000
|
41 | User-Agent: HTTPie/1.0.2
|
42 |
|
43 |
|
44 |
|
45 | HTTP/1.1 302 Found
|
46 | Connection: keep-alive
|
47 | Content-Length: 41
|
48 | Content-Type: text/plain; charset=utf-8
|
49 | Date: Sat, 12 Jan 2019 16:55:26 GMT
|
50 | Location: https://example.com
|
51 | Vary: Accept
|
52 | X-Powered-By: Express
|
53 |
|
54 | Found. Redirecting to https://example.com
|
55 |
|
56 | # resolve standard protocol: `https:`
|
57 |
|
58 | GET /resolve?url=https://google.com HTTP/1.1
|
59 | Accept: */*
|
60 | Accept-Encoding: gzip, deflate
|
61 | Connection: keep-alive
|
62 | Host: localhost:3000
|
63 | User-Agent: HTTPie/1.0.2
|
64 |
|
65 |
|
66 |
|
67 | HTTP/1.1 302 Found
|
68 | Connection: keep-alive
|
69 | Content-Length: 40
|
70 | Content-Type: text/plain; charset=utf-8
|
71 | Date: Sat, 12 Jan 2019 16:55:26 GMT
|
72 | Location: https://google.com
|
73 | Vary: Accept
|
74 | X-Powered-By: Express
|
75 |
|
76 | Found. Redirecting to https://google.com
|
77 |
|
78 | # resolve unknown protocol: `gdrive:`
|
79 |
|
80 | GET /resolve?url=gdrive://test HTTP/1.1
|
81 | Accept: */*
|
82 | Accept-Encoding: gzip, deflate
|
83 | Connection: keep-alive
|
84 | Host: localhost:3000
|
85 | User-Agent: HTTPie/1.0.2
|
86 |
|
87 |
|
88 |
|
89 | HTTP/1.1 400 Bad Request
|
90 | Connection: keep-alive
|
91 | Content-Length: 83
|
92 | Content-Type: application/json; charset=utf-8
|
93 | Date: Sat, 12 Jan 2019 16:55:27 GMT
|
94 | ETag: W/"53-Z2BGf/llR30GzNCkJLqNslE8IJ4"
|
95 | X-Powered-By: Express
|
96 |
|
97 | {
|
98 | "error": {
|
99 | "code": 1,
|
100 | "message": "Unknown protocol: `gdrive:`",
|
101 | "name": "ProtocolError"
|
102 | }
|
103 | }
|
104 | </details>
|
105 |
|
106 | ## API
|
107 |
|
108 |
|
109 |
|
110 | #### Table of Contents
|
111 |
|
112 | - [ProtocolError](#protocolerror)
|
113 | - [Parameters](#parameters)
|
114 | - [ProtocolError.code](#protocolerrorcode)
|
115 | - [Properties](#properties)
|
116 | - [ProtocolHandler](#protocolhandler)
|
117 | - [Parameters](#parameters-1)
|
118 | - [protocol](#protocol)
|
119 | - [Parameters](#parameters-2)
|
120 | - [Examples](#examples)
|
121 | - [protocols](#protocols)
|
122 | - [Properties](#properties-1)
|
123 | - [Examples](#examples-1)
|
124 | - [resolve](#resolve)
|
125 | - [Parameters](#parameters-3)
|
126 | - [Examples](#examples-2)
|
127 | - [middleware](#middleware)
|
128 | - [Parameters](#parameters-4)
|
129 | - [Examples](#examples-3)
|
130 | - [module.exports](#moduleexports)
|
131 | - [Parameters](#parameters-5)
|
132 | - [Examples](#examples-4)
|
133 | - [ProtocolHandlerOptions](#protocolhandleroptions)
|
134 | - [Properties](#properties-2)
|
135 | - [ProtocolCallback](#protocolcallback)
|
136 | - [Parameters](#parameters-6)
|
137 | - [Examples](#examples-5)
|
138 | - [ProtocolErrorCallback](#protocolerrorcallback)
|
139 | - [Parameters](#parameters-7)
|
140 | - [Examples](#examples-6)
|
141 |
|
142 | ### ProtocolError
|
143 |
|
144 | **Extends Error**
|
145 |
|
146 | Custom error indicating invalid, unknown or blacklisted protocol
|
147 |
|
148 | #### Parameters
|
149 |
|
150 | - `code` **[ProtocolError.code](#protocolerrorcode)** Error code
|
151 | - `message` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Error message
|
152 |
|
153 | ### ProtocolError.code
|
154 |
|
155 | Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
|
156 |
|
157 | #### Properties
|
158 |
|
159 | - `ERR_PROTOCOL_INVALID` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
160 | - `ERR_PROTOCOL_UNKNOWN` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
161 | - `ERR_PROTOCOL_BLACKLISTED` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
162 |
|
163 | ### ProtocolHandler
|
164 |
|
165 | Create protocol handler
|
166 |
|
167 | #### Parameters
|
168 |
|
169 | - `options` **[ProtocolHandlerOptions](#protocolhandleroptions)** protocol handler options (optional, default `{}`)
|
170 | - `options.blacklist` (optional, default `[]`)
|
171 |
|
172 | #### protocol
|
173 |
|
174 | Registers protocol handler
|
175 |
|
176 | ##### Parameters
|
177 |
|
178 | - `scheme` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** protocol scheme
|
179 | - `handler` **[ProtocolCallback](#protocolcallback)** protocol handler
|
180 |
|
181 | ##### Examples
|
182 |
|
183 | ```javascript
|
184 | // register multiple handlers
|
185 | const handler = new ProtocolHandler();
|
186 | handler
|
187 | .protocol('s3://', resolve)
|
188 | .protocol('gdrive://', resolve);
|
189 | ```
|
190 |
|
191 | - Throws **[ProtocolError](#protocolerror)** throws if protocol scheme is invalid or blacklisted
|
192 |
|
193 | Returns **[ProtocolHandler](#protocolhandler)** instance to allow chaining
|
194 |
|
195 | #### protocols
|
196 |
|
197 | ##### Properties
|
198 |
|
199 | - `protocols` **[Set](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set)<[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** registered protocols
|
200 |
|
201 | ##### Examples
|
202 |
|
203 | ```javascript
|
204 | // check if protocol is registered
|
205 | const handler = new ProtocolHandler();
|
206 | handler.protocol('s3://', resolve);
|
207 | console.log(handler.protocols.has('s3:'));
|
208 | //=> true
|
209 | ```
|
210 |
|
211 | #### resolve
|
212 |
|
213 | Asynchronously resolves url with registered protocol handler
|
214 |
|
215 | ##### Parameters
|
216 |
|
217 | - `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url
|
218 |
|
219 | ##### Examples
|
220 |
|
221 | ```javascript
|
222 | // create handler
|
223 | const handler = new ProtocolHandler();
|
224 | handler.protocol('s3://', url => 'https://example.com');
|
225 | // resolve url
|
226 | handler.resolve('s3://test').then(url => console.log(url));
|
227 | //=> https://example.com
|
228 | handler.resolve('file:///local/file.txt').then(url => console.log(url));
|
229 | //=> file:///local/file.txt
|
230 | handler.resolve('dummy://unknown/protocol');
|
231 | //=> throws ProtocolError
|
232 | ```
|
233 |
|
234 | - Throws **[ProtocolError](#protocolerror)** throws if url contains invalid or unknown protocol
|
235 |
|
236 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** resolved url, redirect location
|
237 |
|
238 | #### middleware
|
239 |
|
240 | Returns [Express](https://expressjs.com) middleware
|
241 |
|
242 | ##### Parameters
|
243 |
|
244 | - `param` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** name of query param containing target url (optional, default `'url'`)
|
245 | - `cb` **[ProtocolErrorCallback](#protocolerrorcallback)?** custom error handling callback
|
246 |
|
247 | ##### Examples
|
248 |
|
249 | ```javascript
|
250 | // create handler
|
251 | const handler = new ProtocolHandler();
|
252 | handler.protocol('s3://', resolve);
|
253 | // attach to express app
|
254 | app.use(handler.middleware());
|
255 | ```
|
256 |
|
257 | ### module.exports
|
258 |
|
259 | Create new ProtocolHandler instance
|
260 |
|
261 | #### Parameters
|
262 |
|
263 | - `options` **[ProtocolHandlerOptions](#protocolhandleroptions)** protocol handler options (optional, default `{}`)
|
264 |
|
265 | #### Examples
|
266 |
|
267 | ```javascript
|
268 | const handler = require('custom-protocol-handler')();
|
269 | ```
|
270 |
|
271 | Returns **[ProtocolHandler](#protocolhandler)** instance
|
272 |
|
273 | ### ProtocolHandlerOptions
|
274 |
|
275 | Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
|
276 |
|
277 | #### Properties
|
278 |
|
279 | - `blacklist` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?** array of blacklisted schemes
|
280 |
|
281 | ### ProtocolCallback
|
282 |
|
283 | Resolver function for specific protocol
|
284 |
|
285 | Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
|
286 |
|
287 | #### Parameters
|
288 |
|
289 | - `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url
|
290 |
|
291 | #### Examples
|
292 |
|
293 | ```javascript
|
294 | // Resolve gdrive urls
|
295 | const { fetchInfo } = require('gdrive-file-info');
|
296 |
|
297 | async function resolve(url) {
|
298 | const itemId = new URL(url).pathname;
|
299 | const fileInfo = await fetchInfo(itemId);
|
300 | return fileInfo.downloadUrl;
|
301 | }
|
302 | ```
|
303 |
|
304 | Returns **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** resolved url _redirect location_
|
305 |
|
306 | ### ProtocolErrorCallback
|
307 |
|
308 | Custom error calback for Express middleware
|
309 |
|
310 | Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
|
311 |
|
312 | #### Parameters
|
313 |
|
314 | - `err` **[ProtocolError](#protocolerror)** protocol error
|
315 | - `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url
|
316 |
|
317 | #### Examples
|
318 |
|
319 | ```javascript
|
320 | const handler = new ProtocolHandler();
|
321 | handler.protocol('s3://', resolve);
|
322 | // Redirect ONLY registered protocols
|
323 | app.use(handler.middleware('url', (err, url, res) => {
|
324 | if (!err) res.redirect(url);
|
325 | return res.sendStatus(400);
|
326 | }));
|
327 | ```
|