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
  • Parameters
• ProtocolError.code
  • Properties
• ProtocolHandler
  • Parameters
  • protocol
    • Parameters
    • Examples
  • protocols
    • Properties
    • Examples
  • resolve
    • Parameters
    • Examples
  • middleware
    • Parameters
    • Examples
• module.exports
  • Parameters
  • Examples
• ProtocolHandlerOptions
  • Properties
• ProtocolCallback
  • Parameters
  • Examples
• ProtocolErrorCallback
  • Parameters
  • Examples

ProtocolError

Extends Error

Custom error indicating invalid, unknown or blacklisted protocol

Parameters

• code ProtocolError.code Error code
• message String Error message

ProtocolError.code

Type: Object

Properties

• ERR_PROTOCOL_INVALID Number
• ERR_PROTOCOL_UNKNOWN Number
• ERR_PROTOCOL_BLACKLISTED Number

ProtocolHandler

Create protocol handler

Parameters

• options ProtocolHandlerOptions protocol handler options (optional, default {})
  • options.blacklist (optional, default [])

protocol

Registers protocol handler

Parameters

• scheme String protocol scheme
• handler 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

• protocols Set<String> registered protocols

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

• blacklist Array<String>? array of blacklisted schemes

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 error
• url 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);
}));