451-tools v2.0.3

451 Tools

Censorship resilient and distributed publishing. This repository contains a collection of scripts and tools to help you run your own censorship resilient web services. We mostly use Service Workers to achieve this.

451 Tools started as a censorship circumvention technology that we were developing for RadioZamaneh.com which is permanently blocked in Iran. We just wanted to make our own content accessible even during shutdowns. However, we realised that it had potential for others as well, so we eventually turned it into a NPM package. So it really has a bottom up origin story.

Installation

npm install 451-tools

Table of contents

• Getting started
• Bookmarking
• Fallback pages
• Fallback assets
• Content bundles
• Fallback image
• Mirroring
• UI components

Getting started

To ensure smooth integration between our modules it is necessary to use the registerServiceWorkerController function. Ensure serviceWorkerController is included within the options parameter when calling the module, as shown in the example below.

Inside your service worker:

import { registerBookmarkApi, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerBookmarkApi({ serviceWorkerController });

Individual modules can be configured from a configuration file. You need to host that file on your server and pass the path of the file as a url parameter to your service worker registration path, as illustrated below.

From the client:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    const configurationVersion = 1;
    const serviceWorkerUrl = `/service-worker.js?configuration=${encodeURIComponent(`/static/service-worker-configuration.json?v=${configurationVersion}`)}`;
    navigator.serviceWorker
      .register(serviceWorkerUrl)
      .then((registration) => registration.update())
  });
}

Make sure to revision hash or version the configuration file, so that you can update it without having to update your service worker.

The configuration file should look like this, all modules are optional.

{
  "fallbackPages": {},
  "fallbackAssets": {},
  "contentBundles": {},
  "mirroring": {}
}

For additional logging, you can enable debug mode by setting the debugMode flag to true in your configuration.

{
  ...
  "debugMode": true,
}

For more information about the configuration options, see the documentation of the individual modules.

API endpoint: PUT /451-tools/configuration/

Overwrites the current configuration with a new one. ⚠️ Warning: This is an advanced feature. Ensure you understand the implications of changing the configuration before using this endpoint.

Example

fetch('/451-tools/configuration/', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "fallbackPages": {
      "customProperties": {
        "primary-color": "darkblue"
      }
    },
  }),
});

Bookmarking

Your readers can bookmark content for offline reading.

We provide some API endpoints defined in the service worker to save pages for offline availability.

Inside your service worker:

import { registerBookmarkApi, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerBookmarkApi({ serviceWorkerController });

When your service worker is installed, you can now call the bookmark API, which is available at /451-tools/bookmark/.

GET /451-tools/bookmark/

Get all pages from the bookmark cache.

Response

An array of bookmarked pages.

Example

fetch('/451-tools/bookmark/', { method: 'GET' })
  .then(response => response.json())
  .then(pages => {
    console.log(pages);
  });

GET /451-tools/bookmark/{path}

Get a single page from the bookmark cache. Where the path is a url encoded path.

Response

200: A single bookmarked page.

404: The page was not found in the bookmark cache.

400: The path is not a valid url encoded path.

Example

fetch('/451-tools/bookmark/%2Fpath%2Fto%2Fthe%2Fpage%2F', { method: 'GET' })
  .then(response => response.json())
  .then(page => {
    console.log(page);
  });

POST /451-tools/bookmark/{path}

Add a page to the bookmark cache. Where the path is a url encoded path.

Request body

Example

fetch('/451-tools/bookmark/%2Fpath%2Fto%2Fthe%2Fpage%2F', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ metadata: { title: 'Page title' } }),
});

DELETE /451-tools/bookmark/{path}

Delete a page from the bookmark cache. Where the path is a url encoded path.

Example

fetch('/451-tools/bookmark/%2Fpath%2Fto%2Fthe%2Fpage%2F', { method: 'DELETE' });

Fallback pages

Instead of seeing a 404 or a No internet page, your users will see a custom page with information that you want to communicate to them (great during shutdowns, if censored, and when they are offline). When visitors find you through a search engine, on social media, or other places, you can have a different, custom fallback page for each of these referrers.

Inside your service worker:

import { registerFallbackPages, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackPages({ serviceWorkerController });

Calling registerFallbackPages is enough to get you started. It will render a default offline page whenever the network is not available. By default, it looks like this:

This page is somewhat customizable, it has support for basic theming and the default UI texts can be overwritten. However, in case this is not enough, we also support custom offline pages.

import { registerFallbackPages, registerFallbackHandlersPlugin } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackPages({ serviceWorkerController });

And the configuration for the custom offline page:

{
  "fallbackPages": {
    "pages": [
      {
        "url": "/my-offline-page/",
        "revision": "1"
      }
    ]
  }
}

revision is not required, but it is highly recommended. Changing this value will cause a cache invalidation, which means we will re-cache the latest version.

⚠️ Please note that this module takes over the /451-tools/dashboard/ route regardless of the user's online status. The route is used to make the default offline page available for online users.

See below the possible options for the configuring the fallback pages:

customProperties

A list of all the over writable custom properties and their default values.

templateStrings

A list of all the over writable UI text strings and their default values.

Default offline page with customization

import { registerFallbackPages, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackPages({ serviceWorkerController });

And the configuration for the default offline page with customization:

{
  "fallbackPages": {
    "customProperties": {
      "primary-color": "blue"
    },
    "templateStrings": {
      "pageTitle": "My Offline Page"
    }
  }
}

Custom offline page

import { registerFallbackPages, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackPages({ serviceWorkerController });

And the configuration for the custom offline page:

{
  "fallbackPages": {
    "pages": [
      {
        "url": "/my-offline-page/",
        "revision": "1"
      }
    ]
  }
}

Multiple offline pages

For most cases, a single fallback is enough. However, we support an optional refererRegex property. This can, for example, be used to render a different fallback page for users who came from a search engine:

import { registerFallbackPages, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackPages({ serviceWorkerController });

And the configuration for multiple offline pages:

{
  "fallbackPages": {
    "pages": [
      {
        "url": "/my-offline-page/",
        "revision": "1"
      },
      {
        "url": "/google-search-offline-page/",
        "revision": "1",
        "refererRegex": "https://(www.)?(google).com/"
      }
    ]
  }
}

Fallback assets

We provide a fallback strategy for assets to use when the network is not available.

Inside your service worker:

import { registerFallbackAssets, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackAssets({ serviceWorkerController });

And the configuration for the fallback assets:

{
  "fallbackAssets": {
    "assets": [
      {
        "url": "/main.css",
        "revision": "1"
      },
      {
        "url": "/main.js",
        "revision": "1"
      }
    ]
  }
}

revision is not required, but it is highly recommended. Changing this value will cause a cache invalidation, which means we will re-cache the latest version.

See below the possible options for the configuring the fallback assets:

Content bundles

You can mark articles for precaching so your readers always have access to them (great for evergreen articles or ones with particularly important information in case of a shutdown).

You can define a list of pages as content bundles to be cached by the service worker.

Inside your service worker:

import { registerContentBundles, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerContentBundles({ serviceWorkerController });

And the configuration for the content bundles:

{
  "contentBundles": {
    "pages": [
      {
        "url": "/content-bundle-1/",
        "revision": "1"
      },
      {
        "url": "/content-bundle-2/",
        "revision": "1"
      }
    ]
  }
}

revision is not required, but it is highly recommended. Changing this value will cause a cache invalidation, which means we will re-cache the latest version.

A page object can have the following properties:

GET /451-tools/content-bundles/

Get all content from the content bundles cache.

Response

An array of content.

Example

fetch('/451-tools/content-bundles/', { method: 'GET' })
  .then(response => response.json())
  .then(content => {
    console.log(content);
  });

Fallback image

We provide a fallback strategy for images, it returns a fallback SVG for uncached images, when the network is not available.

Inside your service worker:

import { registerFallbackImage, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerFallbackImage({ serviceWorkerController });

Mirroring

In order to keep a website more available you can configure alternative mirrors where the website is hosted.

You can feed the URLs for your mirrors as configuration and it will fetch content for your readers from the mirror if the primary website is unavailable. This way your readers do not have to go looking for your mirrors and you do not have to separately communicate them to your readers.

The service worker will always try to get resources from the primary domain. But once the primary domain fails and mirrors are configured content will be fetched from one of the configured mirrors. By default, we will timeout and cancel a request after 3 seconds.

We mark a mirror and its status, which means that for subsequent requests a mirror that was marked as up will be used for the next 10 minutes. We feel that this leads to a faster user experience because we will not encounter the timeout for every request that is done. When all mirrors are marked as down we will reset the status of the mirrors and try the primary domain again on the next document request.

If all mirrors fail the offline fallback pages strategy as defined in fallback pages will be used. If the offline fallback page is not configured the request will simply fail.

Inside your service worker:

import { registerMirroring, registerServiceWorkerController } from '451-tools';

const serviceWorkerController = registerServiceWorkerController();
registerMirroring({ serviceWorkerController });

⚠️ Please note that the order of registering modules is important. Especially with mirroring. Since it will match all document requests and same origin requests it is important to register it last.

Once the service worker is installed, you can call the mirror status API endpoint, which is available at /451-tools/mirror-status/. It will return the status of where the content is coming from. The response looks like this:

{
  "status": "up" // or "unknown", "down", "low" 
}

Pass an object with the following properties to the registerMirroring function:

{
  "mirroring": {
    "urls": [
      "https://mirror1.com/",
      "https://mirror2.com/"
    ],
    "excludeByPath": [
      "^/wp-admin/?.*",   // Matches any path starting with "/wp-admin".
      "^/wp-login\\.php$" // Matches exactly "/wp-login.php".
    ]
  }
}

UI components

In addition to our modules, we offer a set of UI components that come in the form of web components. While these components may offer added functionality, their primary function is to provide an alternative approach to implementing our modules without requiring any JavaScript coding.

Bookmark button

The button displays the bookmark status of the related page - whether it is currently bookmarked or not. In addition, it enables users to bookmark or unbookmark the page with just a click. Please note that this button requires the bookmarking module to function properly.

Usage

Inside your HTML:

<bookmark-button
  path="/my-page"
  bookmark-text="Bookmark"
  remove-bookmark-text="Remove Bookmark"
>
</bookmark-button>

Attributes

Pass the following attributes to the bookmark-button component:

Styling

Use the following selector:

bookmark-button::part(button) {
  background-color: rebeccapurple;
  color: white;
}

Traffic light

A traffic light component that indicates to the user whether they are accessing the primary website (green), a mirror (yellow) or cached content (red).

Usage

Inside your HTML:

<traffic-light
  href="/offline/"
  unknown-text="The status of the main site is currently unknown."
  up-text="The main site is online and accessible."
  low-text="The main site is unavailable; a mirror site is being used."
  down-text="The main site is currently inaccessible."
>
</traffic-light>

Attributes

Pass the following attributes to the traffic-light component:

Styling

Use the following selectors:

traffic-light::part(button) {
  /* General button selector. */
}

traffic-light::part(online) {
  /* Online button selector. */
}

traffic-light::part(offline) {
  /* Offline button selector. */
}