@default-js/defaultjs-httpinterceptor

defaultjs-httpinterceptor

• defaultjs-httpinterceptor
  • Intro
  • Install
    • npm
    • browser
  • Javascript API
    • Manager
      • Manager.setup(setup)
      • Manager.addInterceptor(interceptor)
      • Manager.ready
      • Manager.ignoreDocumentOrigin
      • Manager.addOriginToIgnore(origin)
      • Manager.addUrlToIgnore(urls = [array of strings | array of URL | string | URL])
      • Manager.uncheckedFetch(url, request)
      • Manager.doIntercept(data)
      • Manager.reset()
    • Interceptor
      • Interceptor.doAccept({url, metadata})
      • Interceptor.doHandle({url, metadata, request})
      • Interceptor.uncheckedFetch
    • TokenInterceptor
    • Object Metadata
    • How to implemente a custom Interceptor

Intro

This default-js modul provide functionality to intercept browser request and manipulate them. It's useful web pages with multi backend services on different domains or auhorization to provide the authorization to all requests.

The httpinterceptor works with XMLHttpRequest and fetch, but its supporting async requests only!

Install

npm

npm install @default-js/defaultjs-httpinterceptor

import {Manager} from "@default-js/defaultjs-httpinterceptor";
Manager.setup(async () => {
//setup your interceptor(s)
});

browser

<script type="application/javascript" src="/dist/defaultjs-httpinterceptor.min.js"></script>
<script type="application/javascript">

defaultjs.httpinterceptorManager.setup(async () => {
//setup your interceptor(s) -> see Javascript api
});
</script>

Include the javascript file and your setup script at head or as first script tags on your body!

Javascript API

Manager

This manager provides the main logic and optimized the request handling by caching the used interceptors by origin.

Manager.setup(setup)

Add your setup logic to the Manager instance and blocks all requests until all setup finished!

Param	Required	Default	Description
setup	X		function or Promise object

The result of the setup can be a single object of Interceptor, an array of Interceptor objects or nothing, but then you must be add your Interceptor object(s) by calling Manager.addInterceptor manualy.

import {Manager} from "@default-js/defaultjs-httpinterceptor";
Manager.setup(async () => {
//setup your interceptor(s)
});

Manager.addInterceptor(interceptor)

Add a Interceptor object.

Param	Required	Default	Description
interceptor	X		Interceptor or Array of Interceptor

Manager.addInterceptor(new MyInterceptor());
Manager.addInterceptor([new InterceptorA(), new InterceptorB(), new InterceptorC()]);

Every interceptor must be a instance of type Interceptor or an object with a function doAccept(data) and doHandle(data);

Manager.ready

This property is a Promise, that represented the current setup state.

Manager.ignoreDocumentOrigin

This property is tells the Manager to ignore all requests with the same origin as the current page.

Manager.addOriginToIgnore(origin)

Add origin to be ignored by Manager.

Param	Required	Default	Description
origin	X		string, URL, Array

Manager.addUrlToIgnore(urls = [array of strings | array of URL | string | URL])

Add url to be ignored by Manager.

Param	Required	Default	Description
url	X		string, URL, Array

Manager.uncheckedFetch(url, request)

This function make a unchecked fetch request. See default browser fetch api.

Param	Required	Default	Description
url	X		string or URL
request	X		object or Request object

Manager.doIntercept(data)

This function would be called automaticly by fetch and XMLHttpRequest to intercept the requests.

Param	Required	Default	Description
data	X		object

Manager.reset()

This function reset the interceptor-origin cache.

Interceptor

Basic class to extends by your own interceptor implementation.

Interceptor.doAccept({url, metadata})

This functions must be return true, if the interceptor apply to all requests by same origin.

Param	Default	Description
url		URL
metadata		Metadata

@return: true or false

Interceptor.doHandle({url, metadata, request})

This function would be called to maipulate the request.

Param	Default	Description
url		URL
metadata		Metadata
request		Object like fetch Request object

@return: a object of {url, metadata, request}

Interceptor.uncheckedFetch

This function make a unchecked fetch request. See default browser fetch api.

Param	Required	Default	Description
url	X		string or URL
request	X		object or Request object

TokenInterceptor

The TokenInterceptor extends Interceptor and provide logic to cache a auth token and make periodicly a refesh of auth token.

import TokenInterceptor from "@default-js/defaultjs-httpinterceptor/src/interceptors/TokenInterceptor";
new TokenInterceptor(setup)

Structur of setup

Property	Requiered	Description
condition	X	string, Array of string, function({url, metadata})
fetchToken	X	function({url, metadata})
appendToken		function({url, metadata, request}); default: add token as header Authorization=Bearer ${token}
refreshInterval		number for milliseconds. A number zero or below -> disable automatic token refesh; default: 6000
refreshToken		function({url, metadata})

Object Metadata

This object provide some meta infomation of request.

Property	Required	Description
method	X	string -> http verbs
origin	X	origin of request
hostname	X	hostname of request
protocol	X	protocol of request
port
query	X	query string of request

How to implemente a custom Interceptor

Create a new class and extend the class by Interceptor class. Impement the function doAccept(data) and doHandle(data).

import Manager from "@default-js/defaultjs-httpinterceptor";
import Interceptor from "@default-js/defaultjs-httpinterceptor";

class MyInterceptor extends Interceptor {
	#origin;

	constructor(origin){
		super();
		this.#origin = origin;
	}

	async doAccept({url, metadata}){
		return url.origin == this.#origin;
	}

	async doHandle({url, metadata, request}){
		const token = await this.uncheckedFetch("/url/to/token");
		request.headers["Authorization"] = `Bearer ${await token.text()}`;

		return {url, metadata, request};
	}
}

Manager.setup(async () => {
	const response = await Manager.uncheckedFetch("/request/for/all/origins.json");
	const origins = await response.json(); // response: ["example-a.com", "example-b.com", "example-c.com"]
	const interceptors = origins.map((origin) => new MyInterceptor(origin));

	return origins
});

await fetch("example-a.com");