{"id":16616168,"url":"https://github.com/vladimyr/custom-protocol-handler","last_synced_at":"2025-07-14T22:38:33.939Z","repository":{"id":33794306,"uuid":"162580245","full_name":"vladimyr/custom-protocol-handler","owner":"vladimyr","description":"Node library for creating custom protocol resolver; can be used as Express middleware.","archived":false,"fork":false,"pushed_at":"2023-01-23T21:58:18.000Z","size":1281,"stargazers_count":6,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-09T05:40:23.156Z","etag":null,"topics":["express","middleware","nodejs","protocol-handler"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladimyr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-20T13:01:13.000Z","updated_at":"2023-03-25T11:16:08.000Z","dependencies_parsed_at":"2023-02-13T04:00:38.022Z","dependency_job_id":null,"html_url":"https://github.com/vladimyr/custom-protocol-handler","commit_stats":null,"previous_names":["vladimyr/express-protocol-handler"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/vladimyr/custom-protocol-handler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimyr%2Fcustom-protocol-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimyr%2Fcustom-protocol-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimyr%2Fcustom-protocol-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimyr%2Fcustom-protocol-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladimyr","download_url":"https://codeload.github.com/vladimyr/custom-protocol-handler/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimyr%2Fcustom-protocol-handler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265362419,"owners_count":23753139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","middleware","nodejs","protocol-handler"],"created_at":"2024-10-12T02:12:07.478Z","updated_at":"2025-07-14T22:38:33.918Z","avatar_url":"https://github.com/vladimyr.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# custom-protocol-handler\n[![build status](https://badgen.net/travis/vladimyr/custom-protocol-handler)](https://travis-ci.com/vladimyr/custom-protocol-handler/) [![install size](https://badgen.net/packagephobia/install/custom-protocol-handler)](https://packagephobia.now.sh/result?p=custom-protocol-handler) [![npm package version](https://badgen.net/npm/v/custom-protocol-handler)](https://npm.im/custom-protocol-handler) [![github license](https://badgen.net/github/license/vladimyr/custom-protocol-handler)](https://github.com/vladimyr/custom-protocol-handler/blob/master/LICENSE) [![js semistandard style](https://badgen.net/badge/code%20style/semistandard/pink)](https://github.com/Flet/semistandard)\n\n\u003e Resolve custom protocols using registered handlers.\n\n## Instalation\n\n    $ npm install custom-protocol-handler\n\n## Usage\n\nThis module can be used either in standalone mode or as [Express](https://expressjs.com) middleware.\n\n```js\nconst protocolHandler = require('custom-protocol-handler')();\nprotocolHandler.protocol('s3://', url =\u003e 'https://example.com');\n\n// Standalone usage\nprotocolHandler.resolve('s3://test').then(url =\u003e console.log(url));\n//=\u003e https://example.com\n\n// Using as Express middleware\nconst port = 3000;\nconst app = require('express')();\napp.get('/resolve', protocolHandler.middleware());\napp.listen(port, () =\u003e console.log('listening on port: %i!', port));\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to open HTTP log\u003c/summary\u003e\n\n    $ ./example.sh\n\n    # resolve registered protocol: `s3:`\n\n    GET /resolve?url=s3://test HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip, deflate\n    Connection: keep-alive\n    Host: localhost:3000\n    User-Agent: HTTPie/1.0.2\n\n\n\n    HTTP/1.1 302 Found\n    Connection: keep-alive\n    Content-Length: 41\n    Content-Type: text/plain; charset=utf-8\n    Date: Sat, 12 Jan 2019 16:55:26 GMT\n    Location: https://example.com\n    Vary: Accept\n    X-Powered-By: Express\n\n    Found. Redirecting to https://example.com\n\n    # resolve standard protocol: `https:`\n\n    GET /resolve?url=https://google.com HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip, deflate\n    Connection: keep-alive\n    Host: localhost:3000\n    User-Agent: HTTPie/1.0.2\n\n\n\n    HTTP/1.1 302 Found\n    Connection: keep-alive\n    Content-Length: 40\n    Content-Type: text/plain; charset=utf-8\n    Date: Sat, 12 Jan 2019 16:55:26 GMT\n    Location: https://google.com\n    Vary: Accept\n    X-Powered-By: Express\n\n    Found. Redirecting to https://google.com\n\n    # resolve unknown protocol: `gdrive:`\n\n    GET /resolve?url=gdrive://test HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip, deflate\n    Connection: keep-alive\n    Host: localhost:3000\n    User-Agent: HTTPie/1.0.2\n\n\n\n    HTTP/1.1 400 Bad Request\n    Connection: keep-alive\n    Content-Length: 83\n    Content-Type: application/json; charset=utf-8\n    Date: Sat, 12 Jan 2019 16:55:27 GMT\n    ETag: W/\"53-Z2BGf/llR30GzNCkJLqNslE8IJ4\"\n    X-Powered-By: Express\n\n    {\n        \"error\": {\n            \"code\": 1,\n            \"message\": \"Unknown protocol: `gdrive:`\",\n            \"name\": \"ProtocolError\"\n        }\n    }\n\u003c/details\u003e\n\n## API\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n#### Table of Contents\n\n-   [ProtocolError](#protocolerror)\n    -   [Parameters](#parameters)\n-   [ProtocolError.code](#protocolerrorcode)\n    -   [Properties](#properties)\n-   [ProtocolHandler](#protocolhandler)\n    -   [Parameters](#parameters-1)\n    -   [protocol](#protocol)\n        -   [Parameters](#parameters-2)\n        -   [Examples](#examples)\n    -   [protocols](#protocols)\n        -   [Properties](#properties-1)\n        -   [Examples](#examples-1)\n    -   [resolve](#resolve)\n        -   [Parameters](#parameters-3)\n        -   [Examples](#examples-2)\n    -   [middleware](#middleware)\n        -   [Parameters](#parameters-4)\n        -   [Examples](#examples-3)\n-   [module.exports](#moduleexports)\n    -   [Parameters](#parameters-5)\n    -   [Examples](#examples-4)\n-   [ProtocolHandlerOptions](#protocolhandleroptions)\n    -   [Properties](#properties-2)\n-   [ProtocolCallback](#protocolcallback)\n    -   [Parameters](#parameters-6)\n    -   [Examples](#examples-5)\n-   [ProtocolErrorCallback](#protocolerrorcallback)\n    -   [Parameters](#parameters-7)\n    -   [Examples](#examples-6)\n\n### ProtocolError\n\n**Extends Error**\n\nCustom error indicating invalid, unknown or blacklisted protocol\n\n#### Parameters\n\n-   `code` **[ProtocolError.code](#protocolerrorcode)** Error code\n-   `message` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Error message\n\n### ProtocolError.code\n\nType: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)\n\n#### Properties\n\n-   `ERR_PROTOCOL_INVALID` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** \n-   `ERR_PROTOCOL_UNKNOWN` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** \n-   `ERR_PROTOCOL_BLACKLISTED` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** \n\n### ProtocolHandler\n\nCreate protocol handler\n\n#### Parameters\n\n-   `options` **[ProtocolHandlerOptions](#protocolhandleroptions)** protocol handler options (optional, default `{}`)\n    -   `options.blacklist`   (optional, default `[]`)\n\n#### protocol\n\nRegisters protocol handler\n\n##### Parameters\n\n-   `scheme` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** protocol scheme\n-   `handler` **[ProtocolCallback](#protocolcallback)** protocol handler\n\n##### Examples\n\n```javascript\n// register multiple handlers\nconst handler = new ProtocolHandler();\nhandler\n  .protocol('s3://', resolve)\n  .protocol('gdrive://', resolve);\n```\n\n-   Throws **[ProtocolError](#protocolerror)** throws if protocol scheme is invalid or blacklisted\n\nReturns **[ProtocolHandler](#protocolhandler)** instance to allow chaining\n\n#### protocols\n\n##### Properties\n\n-   `protocols` **[Set](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set)\u0026lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e** registered protocols\n\n##### Examples\n\n```javascript\n// check if protocol is registered\nconst handler = new ProtocolHandler();\nhandler.protocol('s3://', resolve);\nconsole.log(handler.protocols.has('s3:'));\n//=\u003e true\n```\n\n#### resolve\n\nAsynchronously resolves url with registered protocol handler\n\n##### Parameters\n\n-   `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url\n\n##### Examples\n\n```javascript\n// create handler\nconst handler = new ProtocolHandler();\nhandler.protocol('s3://', url =\u003e 'https://example.com');\n// resolve url\nhandler.resolve('s3://test').then(url =\u003e console.log(url));\n//=\u003e https://example.com\nhandler.resolve('file:///local/file.txt').then(url =\u003e console.log(url));\n//=\u003e file:///local/file.txt\nhandler.resolve('dummy://unknown/protocol');\n//=\u003e throws ProtocolError\n```\n\n-   Throws **[ProtocolError](#protocolerror)** throws if url contains invalid or unknown protocol\n\nReturns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\u0026lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e** resolved url, redirect location\n\n#### middleware\n\nReturns [Express](https://expressjs.com) middleware\n\n##### Parameters\n\n-   `param` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** name of query param containing target url (optional, default `'url'`)\n-   `cb` **[ProtocolErrorCallback](#protocolerrorcallback)?** custom error handling callback\n\n##### Examples\n\n```javascript\n// create handler\nconst handler = new ProtocolHandler();\nhandler.protocol('s3://', resolve);\n// attach to express app\napp.use(handler.middleware());\n```\n\n### module.exports\n\nCreate new ProtocolHandler instance\n\n#### Parameters\n\n-   `options` **[ProtocolHandlerOptions](#protocolhandleroptions)** protocol handler options (optional, default `{}`)\n\n#### Examples\n\n```javascript\nconst handler = require('custom-protocol-handler')();\n```\n\nReturns **[ProtocolHandler](#protocolhandler)** instance\n\n### ProtocolHandlerOptions\n\nType: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)\n\n#### Properties\n\n-   `blacklist` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\u0026lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e?** array of blacklisted schemes\n\n### ProtocolCallback\n\nResolver function for specific protocol\n\nType: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)\n\n#### Parameters\n\n-   `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url\n\n#### Examples\n\n```javascript\n// Resolve gdrive urls\nconst { fetchInfo } = require('gdrive-file-info');\n\nasync function resolve(url) {\n  const itemId = new URL(url).pathname;\n  const fileInfo = await fetchInfo(itemId);\n  return fileInfo.downloadUrl;\n}\n```\n\nReturns **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \\| [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\u0026lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e)** resolved url _redirect location_\n\n### ProtocolErrorCallback\n\nCustom error calback for Express middleware\n\nType: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)\n\n#### Parameters\n\n-   `err` **[ProtocolError](#protocolerror)** protocol error\n-   `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** target url\n\n#### Examples\n\n```javascript\nconst handler = new ProtocolHandler();\nhandler.protocol('s3://', resolve);\n// Redirect ONLY registered protocols\napp.use(handler.middleware('url', (err, url, res) =\u003e {\n  if (!err) res.redirect(url);\n  return res.sendStatus(400);\n}));\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimyr%2Fcustom-protocol-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladimyr%2Fcustom-protocol-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimyr%2Fcustom-protocol-handler/lists"}