README
custom-protocol-handler
Resolve custom protocols using registered handlers.
Instalation
$ npm install custom-protocol-handler
Usage
This module can be used either in standalone mode or as Express middleware.
const protocolHandler = require('custom-protocol-handler')();
protocolHandler.protocol('s3://', url => 'https://example.com');
// Standalone usage
protocolHandler.resolve('s3://test').then(url => console.log(url));
//=> https://example.com
// Using as Express middleware
const port = 3000;
const app = require('express')();
app.get('/resolve', protocolHandler.middleware());
app.listen(port, () => console.log('listening on port: %i!', port));
Click to open HTTP log
$ ./example.sh
# resolve registered protocol: `s3:`
GET /resolve?url=s3://test HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:3000
User-Agent: HTTPie/1.0.2
HTTP/1.1 302 Found
Connection: keep-alive
Content-Length: 41
Content-Type: text/plain; charset=utf-8
Date: Sat, 12 Jan 2019 16:55:26 GMT
Location: https://example.com
Vary: Accept
X-Powered-By: Express
Found. Redirecting to https://example.com
# resolve standard protocol: `https:`
GET /resolve?url=https://google.com HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:3000
User-Agent: HTTPie/1.0.2
HTTP/1.1 302 Found
Connection: keep-alive
Content-Length: 40
Content-Type: text/plain; charset=utf-8
Date: Sat, 12 Jan 2019 16:55:26 GMT
Location: https://google.com
Vary: Accept
X-Powered-By: Express
Found. Redirecting to https://google.com
# resolve unknown protocol: `gdrive:`
GET /resolve?url=gdrive://test HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:3000
User-Agent: HTTPie/1.0.2
HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Length: 83
Content-Type: application/json; charset=utf-8
Date: Sat, 12 Jan 2019 16:55:27 GMT
ETag: W/"53-Z2BGf/llR30GzNCkJLqNslE8IJ4"
X-Powered-By: Express
{
"error": {
"code": 1,
"message": "Unknown protocol: `gdrive:`",
"name": "ProtocolError"
}
}
API
Table of Contents
- ProtocolError
- ProtocolError.code
- ProtocolHandler
- module.exports
- ProtocolHandlerOptions
- ProtocolCallback
- ProtocolErrorCallback
ProtocolError
Extends Error
Custom error indicating invalid, unknown or blacklisted protocol
Parameters
code
ProtocolError.code Error codemessage
String Error message
ProtocolError.code
Type: Object
Properties
ProtocolHandler
Create protocol handler
Parameters
options
ProtocolHandlerOptions protocol handler options (optional, default{}
)options.blacklist
(optional, default[]
)
protocol
Registers protocol handler
Parameters
scheme
String protocol schemehandler
ProtocolCallback protocol handler
Examples
// register multiple handlers
const handler = new ProtocolHandler();
handler
.protocol('s3://', resolve)
.protocol('gdrive://', resolve);
- Throws ProtocolError throws if protocol scheme is invalid or blacklisted
Returns ProtocolHandler instance to allow chaining
protocols
Properties
Examples
// check if protocol is registered
const handler = new ProtocolHandler();
handler.protocol('s3://', resolve);
console.log(handler.protocols.has('s3:'));
//=> true
resolve
Asynchronously resolves url with registered protocol handler
Parameters
url
String target url
Examples
// create handler
const handler = new ProtocolHandler();
handler.protocol('s3://', url => 'https://example.com');
// resolve url
handler.resolve('s3://test').then(url => console.log(url));
//=> https://example.com
handler.resolve('file:///local/file.txt').then(url => console.log(url));
//=> file:///local/file.txt
handler.resolve('dummy://unknown/protocol');
//=> throws ProtocolError
- Throws ProtocolError throws if url contains invalid or unknown protocol
Returns Promise<String> resolved url, redirect location
middleware
Returns Express middleware
Parameters
param
String name of query param containing target url (optional, default'url'
)cb
ProtocolErrorCallback? custom error handling callback
Examples
// create handler
const handler = new ProtocolHandler();
handler.protocol('s3://', resolve);
// attach to express app
app.use(handler.middleware());
module.exports
Create new ProtocolHandler instance
Parameters
options
ProtocolHandlerOptions protocol handler options (optional, default{}
)
Examples
const handler = require('custom-protocol-handler')();
Returns ProtocolHandler instance
ProtocolHandlerOptions
Type: Object
Properties
ProtocolCallback
Resolver function for specific protocol
Type: Function
Parameters
url
String target url
Examples
// Resolve gdrive urls
const { fetchInfo } = require('gdrive-file-info');
async function resolve(url) {
const itemId = new URL(url).pathname;
const fileInfo = await fetchInfo(itemId);
return fileInfo.downloadUrl;
}
Returns (String | Promise<String>) resolved url redirect location
ProtocolErrorCallback
Custom error calback for Express middleware
Type: Function
Parameters
err
ProtocolError protocol errorurl
String target url
Examples
const handler = new ProtocolHandler();
handler.protocol('s3://', resolve);
// Redirect ONLY registered protocols
app.use(handler.middleware('url', (err, url, res) => {
if (!err) res.redirect(url);
return res.sendStatus(400);
}));