Home

Planktos API Documentation

Usage

Update planktos to the latest snapshot then fetch the file 'foobar.txt' inside the snapshot and get the file's blob.

const planktos = new Planktos()
planktos.startSeeder()

planktos.update('/url/to/planktos/root/directory')
.then(snapshot => planktos.fetch('foobar.txt'))
.then(response => response.blob())
.then(blob => console.log('Fetched blob', blob))

API

const planktos = new Planktos([opts])

Instantiates a new planktos instance. All instances share the same snapshots which are stored in IndexedDB. The reasoning for this is because planktos was made to work in service workers where the service worker context is routinely destroyed and recreated. Planktos can also be used in non-worker contexts like normal web pages. opts can have the following properties

opts.namespace - All instances with the same namespace share the same list of snapshots. Defaults to ''

planktos.getAllSnapshots().then(snapshots => {})

Retrieves the list of snapshots that planktos has stored locally. Snapshots a the saved files of a website at a given point in time. snapshots is an ordered array of Snapshot instances with the newer snapshots at higher indexes.

planktos.update(rootUrl).then(snapshot => {})

Checks to see if any new snapshots are found. rootUrl is the url to the directory that planktos was setup to serve. The planktos directory is inside the directory pointed to by rootUrl.

planktos.removeSnapshot(hash).then(() => {})

Removes the snapshot with the given hash then the returned promise resolves. Removing the snapshot does not remove it from other instances, only newly instantiated instances.

planktos.startSeeder()

This starts a WebTorrent instance that downloads and seeds the planktos snapshots to/from peers. This method can only be called within a web page and not web workers because WebTorrent uses the WebRTC api to download from peers. Since all planktos instances share the same snapshots, the snapshot data downloaded within a web page due to planktos.startSeeder() will be available to all planktos instances, even ones in web workers.

plantos.fetch(request, [opts]).then(response => {})

This is an alias for calling snapshot.fetch() on the latest snapshot.

Snapshot API

The list of snapshots a planktos instance holds can be retrieved with planktos.getAllSnapshots().then(snapshots => {})

snapshot.hash

A digest of the contents of the snapshot. This is used to uniquely identify a snapshot

snapshot.closed

Indicates if the internal resources of a snapshot have been freed. This will be true after planktos.removeSnapshot(...) is called

snapshot.fetch(request, [opts]).then(response => {})

The peer-to-peer version of fetch. This returns a Promise that resolves a Response for the requested file in the snapshot or the promise resolves to undefined if the file was not find in the snapshot. In browsers that support the WhatWG ReadableStream api, the response body can be streamed in while it is being downloaded from peers. Other browsers must download the file from peers in it's entirety before the responses body can be read.

It is important to note that the response body will be downloaded form peers so a webpage must call planktos.startSeeder() to initiate this seeder/downloader. If this method is not called then reading the body of the response will hang. planktos.fetch() takes care of explicity calling plankots.startSeeder() by automatically injecting the seeder script into the response body. This behavior can be disabled by setting opts.inject = false.

request can take many forms including FetchEvent, Request, URL, or a url string. If this method is being called from within a service worker, it is best to pass in the FetchEvent if available.

opts can have the following properties:

• opts.rootUrl - if the planktos root directory is not the websites root then a url to the directory will need to be passed in
• opts.stream - Use WhatWG Readable streams if supported. Defaults to true
• opts.inject - Inject the seeder script into the response body. Defaults to depends on the the properties of request

snapshot.getFile(filePath).then(file => {})

Returns a Promise that resolves to a File instance or undefined if the file was not found.

File API

file.path

The path of the file relative to the planktos root directory

file.length

The number of bytes in the file

file.getStream([opts]).then(stream => {})

Returns a Promise that resolves to a NodeJS ReadableStream.

file.getWebStream([opts]).then(webStream => {})

Returns a Promise that resolves to a WhatWG ReadableStream. If the browser does not have support for this type of stream then an error is thrown.

file.getBlob([opts]).then(blob => {})

Returns a Promise that resolves to a Blob