public class | source

Reconstructive

Reconstructive is a ServiceWorker module for client-side reconstruction of composite mementos. It reroutes embedded resource requests to their appropriate archival version without any URL rewriting. It also provides functionality to add custom archival banners or rewrite hyperlinks on the client-side. Use it in a ServiceWorker as illustrated below:

importScripts('reconstructive.js');
const rc = new Reconstructive();
self.addEventListener('fetch', rc.reroute);

Constructor Summary

Public Constructor
public	constructor(config: {id: string, urimPattern: string, bannerElementLocation: string, bannerLogoLocation: string, showBanner: boolean, debug: boolean}) Creates a new Reconstructive instance with optional configurations.

Member Summary

Public Members
public	NAME: string Name of the module.
public	VERSION: string Version of the module.
public	bannerElementLocation: string The URL or absolute path of the JS file that defines custom banner element.
public	bannerLogoHref: string The URL or absolute path to link from the logo image in the banner.
public	bannerLogoLocation: string The URL or absolute path of the logo image to appear in the banner.
public	debug: boolean Whether or not to show debug messages in the console.
public	exclusions: function(event: FetchEvent): boolean, bannerElement An object of functions to check whether the request should be excluded from being rerouted.
public	id: string Identifier of the module, sent to the server as X-ServiceWorker header.
public	showBanner: boolean Whether or not to show an archival banner.
public	urimPattern: string The format of URI-Ms (e.g., http://example.com/archive/<datetime>/<urir>).

Private Members
private	_regexps: {urimPattern: RegExp, absoluteReference: RegExp, bodyEnd: RegExp} A private object with various RegExp properties (possibly derived from other properties) for internal use.

Method Summary

Public Methods
public	cloneHeaders(original: Headers): Headers Clones provided request or response headers.
public	createBanner(response: Response, event: FetchEvent): string Creates a string representing an HTML block to be injected in the response's HTML body.
public	createRequest(event: FetchEvent): Request Creates a new request based on the original.
public	createUrim(event: FetchEvent): string Creates a potential URI-M based on the requested URL and the referrer URL for request rerouting.
public	extractDatetimeUrir(urim: string): string[] Extracts datetime and URI-R from a URI-M.
public	fetchFailure(error: Error): Response The callback function on network failure of the server fetch.
public	fetchSuccess(response: Response, event: FetchEvent): Promise<Response> The callback function on a successful fetch from the server.
public	localRedirect(urim: string): Promise<Response> Redirects a non-URI-M request to its potentially URI-M locally.
public	reroute(event: FetchEvent) The callback function on the fetch event.
public	rewrite(response: Response, event: FetchEvent): Promise<Response> Rewrites the fetched response when necessary.
public	shouldExclude(event: FetchEvent): boolean Iterates over all the members of the exclusions object and returns true if any of the members return true, otherwise returns false.

Public Constructors

public constructor(config: {id: string, urimPattern: string, bannerElementLocation: string, bannerLogoLocation: string, showBanner: boolean, debug: boolean}) source

Creates a new Reconstructive instance with optional configurations.

Params:

Name	Type	Attribute	Description
config	{id: string, urimPattern: string, bannerElementLocation: string, bannerLogoLocation: string, showBanner: boolean, debug: boolean}	optional	Configuration options

Public Members

public NAME: string source

Name of the module. Treated as a constant.

public VERSION: string source

Version of the module. Treated as a constant.

public bannerElementLocation: string source

The URL or absolute path of the JS file that defines custom banner element. Only necessary if showBanner is set to true.

public bannerLogoHref: string source

The URL or absolute path to link from the logo image in the banner. This should generally be set to the address of the homepage. Only necessary if showBanner is set to true.

public bannerLogoLocation: string source

The URL or absolute path of the logo image to appear in the banner. An empty value will render the default Reconstructive logo as inline SVG. Only necessary if showBanner is set to true.

public debug: boolean source

Whether or not to show debug messages in the console. Defaults to false.

public exclusions: function(event: FetchEvent): boolean, bannerElement source

An object of functions to check whether the request should be excluded from being rerouted. Add more members to the object to add more exclusions or modify/delete existing ones. The property name can be anything descriptive of the particular exclusion, which will be shown in debug logs. Each member function is called with the fetch event as parameters. If any member returns true, the fetch event is excluded from being rerouted.

public id: string source

Identifier of the module, sent to the server as X-ServiceWorker header. Defaults to the name and version of the module.

public showBanner: boolean source

Whether or not to show an archival banner. Defaults to false.

public urimPattern: string source

The format of URI-Ms (e.g., http://example.com/archive/<datetime>/<urir>).

Private Members

private _regexps: {urimPattern: RegExp, absoluteReference: RegExp, bodyEnd: RegExp} source

A private object with various RegExp properties (possibly derived from other properties) for internal use.

Public Methods

public cloneHeaders(original: Headers): Headers source

Clones provided request or response headers.

Params:

Name	Type	Attribute	Description
original	Headers		Original request or response headers

Return:

Headers

A clone of the supplied headers

public createBanner(response: Response, event: FetchEvent): string source

Creates a string representing an HTML block to be injected in the response's HTML body.

Params:

Name	Type	Attribute	Description
response	Response		Original response object
event	FetchEvent		The fetch event

Return:

string

The banner markup

public createRequest(event: FetchEvent): Request source

Creates a new request based on the original. Copies all the headers from the original request. Adds X-ServiceWorker header with the id of the module. Sets the redirect mode to manual to ensure proper origin boundaries.

Params:

Name	Type	Attribute	Description
event	FetchEvent		The fetch event

Return:

Request

A new request object

public createUrim(event: FetchEvent): string source

Creates a potential URI-M based on the requested URL and the referrer URL for request rerouting.

Params:

Name	Type	Attribute	Description
event	FetchEvent		The fetch event

Return:

string

A potential URI-M

public extractDatetimeUrir(urim: string): string[] source

Extracts datetime and URI-R from a URI-M.

Params:

Name	Type	Attribute	Description
urim	string		A URI-M

Return:

string[]

An array of datetime and URI-R

public fetchFailure(error: Error): Response source

The callback function on network failure of the server fetch. Logs the failure reason for debugging. Returns a synthetic 503 Service Unavailable response.

Params:

Name	Type	Attribute	Description
error	Error		The exception raised on fetching from the server

Return:

Response

A 503 Service Unavailable response

public fetchSuccess(response: Response, event: FetchEvent): Promise<Response> source

The callback function on a successful fetch from the server. Calls the rewrite() function if the response code is 2xx. Logs the response for debugging. Resolves to a potentially modified response.

Params:

Name	Type	Attribute	Description
response	Response		Original response object
event	FetchEvent		The fetch event

Return:

Promise<Response>

Potentially modified response

public localRedirect(urim: string): Promise<Response> source

Redirects a non-URI-M request to its potentially URI-M locally. The potential URI-M is generated using createUrim(). This function only returns a synthetic redirection response.

Params:

Name	Type	Attribute	Description
urim	string		A potential URI-M

Return:

Promise<Response>

A 302 redirection response to the potential URI-M

public reroute(event: FetchEvent) source

The callback function on the fetch event. Logs the fetch event for debugging. Checks for any rerouting exclusions. If the request URL is a URI-M then creates a new request with certain modifications in the original request and fetches it from the server. Otherwise, responds with a redirect to the potential URI-M. Both success and failure responses are dealt with appropriately.

Params:

Name	Type	Attribute	Description
event	FetchEvent		The fetch event

public rewrite(response: Response, event: FetchEvent): Promise<Response> source

Rewrites the fetched response when necessary. Potential uses are to fix certain replay issues, adding an archival banner, or modifying hyperlinks. When the showBanner config is set to true, it tries to add a banner in navigational HTML pages. Resolves to a potentially modified response.

Params:

Name	Type	Attribute	Description
response	Response		Original response object
event	FetchEvent		The fetch event

Return:

Promise<Response>

Potentially modified response

public shouldExclude(event: FetchEvent): boolean source

Iterates over all the members of the exclusions object and returns true if any of the members return true, otherwise returns false. Logs the first matching exclusion for debugging, if any.

Params:

Name	Type	Attribute	Description
event	FetchEvent		The fetch event

Return:

boolean

Should the request be rerouted?