Skip to content

Node library for creating custom protocol resolver; can be used as Express middleware.

License

Notifications You must be signed in to change notification settings

vladimyr/custom-protocol-handler

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

custom-protocol-handler

build status install size npm package version github license js semistandard style

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

Extends Error

Custom error indicating invalid, unknown or blacklisted protocol

Parameters

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
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
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

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

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

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);
}));

About

Node library for creating custom protocol resolver; can be used as Express middleware.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published