Skip to content

Manifesto

Hao Tran edited this page Oct 16, 2024 · 3 revisions

Helia aims to be a next generation IPFS implementation that takes the learnings of js-ipfs and applies them to a modern, modular, and efficient codebase.

🧱 Modular

The use cases for a distributed filesystem are incredibly far reaching and the "bundle-everything" approach of js-ipfs/kubo does not suit every application.

For example:

  • Applications deployed to browsers may wish to limit the size of the final bundle by omitting features
  • Other applications may be deployed in extremely adversarial environments, and should limit the number of dependencies (throughout the dependency tree) to reduce the opportunities for supply chain attacks
  • The user should not have to include the code for features their application does not use

The core of Helia will be very focused on use as a library: just js-libp2p, a datastore, and a blockstore that transparently uses js-bitswap to load any requested blocks not already in the blockstore from the network and/or to transfer them to network peers.

Users are very much encouraged to bundle extra components with their version of Helia to suit their use case.

Extra components currently available are:

We hope there will be more soon!

πŸ“ BYO Filesystem

The default filesystem for IPFS is UnixFS, but UnixFS has several limitations. Support for some common Unix file attributes such as mode (permission bits) and mtime landed in UnixFSv1.5, but this has yet to make it to kubo.

Several features are still missing from 1.5, such as arbitrary metadata (extended attributes) or versioning, but they have been implemented by other filesystems such as WNFS.

The fact that at these missing features are being implemented by other filesystems is incredibly exciting and will unlock new use cases that are not possible today, so Helia will not bless any one filesystem as the One True Implementation, instead it is intended to provide the features required to implement these file systems in a network-aware way that allows pulling data from and sending data to peers.

Currently available filesystems are:

We hope there will be more soon!

βš—οΈ Isomorphic JavaScript

In the beginning there were Node.js streams. Then there were pull streams. And finally, browsers have native streams too.

Similarly, EventTargets can be used where EventEmitters were previously.

There are many other cases where primitives that existed only in Node.js or were provided by a popular library have now made it in to the language itself. These constructs should be preferred versus userland modules, in order to remove dependencies and make the API types more idiomatic and recognizable as modern JavaScript.

This also makes it easier to support other runtimes like deno or bun since runtime-specific code should be behind configuration such as the "browser" or "exports" fields in the package.json.

πŸš€ (runtime-specific code where it makes sense)

Some things are just faster in Node.js. The ability to run native code should not be underestimated so where the JS implementation of an algorithm is a proven performance bottleneck and a native version exists, it should be used.

Observability

An IPFS implementation typically contains a lot of moving parts all of which must move in perfect synchronicity for an operation to be successful.

When things do not go smoothly it's not always clear in which part of the system the fault has occurred.

Helia aims to alleviate some of this pain by exposing comprehensive progress handlers that give insight into specific calls and the components that are interacted with.

For example catting a file might involve requesting blocks from the blockstore, adding them to your bitswap want list, making DHT queries to find providers of that block, connecting to the provider and finally pulling the block down - any of these can go wrong but the user should be able to pinpoint where the problem lays.

In addition to this standard tools such as Prometheus should be usable with many metrics exposed to allow deep introspection of node behaviour and the debugging and isolatino of performance bottlenecks.

πŸ“œ ESM and TypeScript

Trying to write applications that scale has always been a challenge for JavaScript. Tools like TypeScript ease some of this pain, so Helia will be written in TypeScript and published as ESM-only to take advantage of modern runtimes and tooling.

β›” Non-goals

Helia is not attempting to reimplement layers beneath the top-level API so js-libp2p will remain as will js-bitswap and js-unixfs.

🌐 Networking

It will use js-libp2p and js-bitswap to ensure compatibility with existing IPFS clients.