custom-protocol-handler

    3.0.0 • Public • Published

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

    Install

    npm i custom-protocol-handler@3.0.0

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    20.3 kB

    Total Files

    4

    Last publish

    Collaborators

    • vladimyr