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 = ;protocolHandlerprotocol's3://' 'https://example.com'; // Standalone usageprotocolHandler;//=> https://example.com // Using as Express middlewareconst port = 3000;const app = ;app;app;
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 handlersconst handler = ;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 registeredconst handler = ;handlerprotocol's3://' resolve;console;//=> true
resolve
Asynchronously resolves url with registered protocol handler
Parameters
url
String target url
Examples
// create handlerconst handler = ;handlerprotocol's3://' 'https://example.com';// resolve urlhandler;//=> https://example.comhandler;//=> file:///local/file.txthandler;//=> 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 handlerconst handler = ;handlerprotocol's3://' resolve;// attach to express appapp;
module.exports
Create new ProtocolHandler instance
Parameters
options
ProtocolHandlerOptions protocol handler options (optional, default{}
)
Examples
const handler = ;
Returns ProtocolHandler instance
ProtocolHandlerOptions
Type: Object
Properties
ProtocolCallback
Resolver function for specific protocol
Type: Function
Parameters
url
String target url
Examples
// Resolve gdrive urlsconst fetchInfo = ; { const itemId = urlpathname; const fileInfo = await ; return fileInfodownloadUrl;}
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 = ;handlerprotocol's3://' resolve;// Redirect ONLY registered protocolsapp;