express-protocol-handler

Resolve custom protocols using Express middleware.

Instalation

$ npm install express-protocol-handler

Usage

const app = require('express')();
const protocolHandler = require('express-protocol-handler')();

const port = 3000;
protocolHandler.protocol('s3://', url => 'https://example.com');

app.get('/resolve', protocolHandler.middleware());
app.listen(port, () => console.log('listening on port: %i!', port));

// Standalone usage
protocolHandler.resolve('s3://test').then(url => console.log(url));
//=> https://example.com

GET /resolve?url=s3://test HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:3000
User-Agent: HTTPie/0.9.9


HTTP/1.1 302 Found
Connection: keep-alive
Content-Length: 41
Content-Type: text/plain; charset=utf-8
Date: Thu, 20 Dec 2018 13:25:26 GMT
Location: https://example.com
Vary: Accept
X-Powered-By: Express

Found. Redirecting to https://example.com 

API

Table of Contents

• ProtocolHandler
  • Parameters
  • protocol
    • Parameters
    • Examples
  • protocols
    • Properties
    • Examples
  • resolve
    • Parameters
    • Examples
  • middleware
    • Examples
• module.exports
  • Parameters
  • Examples
• ProtocolHandlerOptions
  • Properties
• ProtocolCallback
  • Parameters
  • Examples
• IRequest
• IResponse

ProtocolHandler

Create protocol handler

Parameters

• param String name of query param containing target url (optional, default 'url')
• options ProtocolHandlerOptions protocol handler options (optional, default {})
  • options.blacklist (optional, default [])

protocol

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

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

Resolve 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

Returns Promise<String> resolved url, redirect location

middleware

Returns Express middleware

Examples

// create handler
const handler = new ProtocolHandler();
handler.protocol('s3://', resolve);
// attach to express app
app.use(handler.middleware());

Returns function (IRequest, IResponse) Express middleware

module.exports

Create new ProtocolHandler instance

Parameters

• param String name of query param containing target url (optional, default 'url')
• options ProtocolHandlerOptions protocol handler options (optional, default {})

Examples

const handler = require('express-protocol-handler')('query');

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

IRequest

• See: https://expressjs.com/en/4x/api.html#req

Express server request

IResponse

• See: https://expressjs.com/en/4x/api.html#res

Express server response