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 of the module. |
|
public |
Version of the module. |
|
public |
The URL or absolute path of the JS file that defines custom banner element. |
|
public |
The URL or absolute path to link from the logo image in the banner. |
|
public |
The URL or absolute path of the logo image to appear in the banner. |
|
public |
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 |
Identifier of the module, sent to the server as X-ServiceWorker header. |
|
public |
Whether or not to show an archival banner. |
|
public |
The format of URI-Ms (e.g., http://example.com/archive/<datetime>/<urir>). |
Private Members | ||
private |
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 |
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 Members
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 urimPattern: string source
The format of URI-Ms (e.g., http://example.com/archive/<datetime>/<urir>).
Private Members
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 |
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 |
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 |
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 |
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 |
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 |
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 |