feat: initial implementation

- Adds modules for a core library, a cli and an RPC client/server - Creates a `~/.helia` directory on startup - `helia daemon` starts a node with an RPC-over-libp2p server - `helia id` prints out node information online or offline
ipfs · Dec 22, 2022 · 20b0f35 · 20b0f35
1 parent 3321b3b
commit 20b0f35
Show file tree

Hide file tree

Showing 75 changed files with 3,690 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,45 +1,72 @@
-<h3 align="center">An implementation of IPFS in JavaScript.</h3>
+# helia-monorepo <!-- omit in toc -->
 
-### Project status
+[![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
+[![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
+[![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
+[![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
-This project is pre-alpha and is planned for development in late 2022, with an initial "v1" release in [late Q1 2023](/ROADMAP.md#late-q1-march). The project will be built in the open. Community contributors are welcome.
+> An implementation of IPFS in JavaScript
 
-## Table of Contents <!-- omit in toc -->
+## Table of contents <!-- omit in toc -->
 
-- [Name](#name)
+- [Structure](#structure)
+  - [Project status](#project-status)
+- [What's in a name?](#whats-in-a-name)
 - [Background](#background)
 - [Roadmap](#roadmap)
-- [Contribute](#contribute)
+- [API Docs](#api-docs)
 - [License](#license)
-  - [Contribution](#contribution)
+- [Contribute](#contribute)
+
+## Structure
 
-## Name
+- [`/packages/cli`](./packages/cli) Run a Helia node on the CLI
+- [`/packages/helia`](./packages/helia) An implementation of IPFS in JavaScript
+- [`/packages/interface`](./packages/interface) The Helia API
+- [`/packages/rpc-client`](./packages/rpc-client) An implementation of IPFS in JavaScript
+- [`/packages/rpc-protocol`](./packages/rpc-protocol) gRPC protocol for use by @helia/rpc-client and @helia/rpc-server
+- [`/packages/rpc-server`](./packages/rpc-server) An implementation of IPFS in JavaScript
+- [`/packages/unixfs`](./packages/unixfs) A Helia-compatible wrapper for UnixFS
+
+### Project status
+
+This project is pre-alpha and is planned for development in late 2022, with an initial "v1" release in [late Q1 2023](/ROADMAP.md#late-q1-march). The project will be built in the open. Community contributors are welcome.
 
-Helia (_HEE-lee-ah_) is the Latin spelling of Ἡλιη -- in Greek mythology, one of the [Heliades](https://www.wikidata.org/wiki/Q12656412): the daughters of the sun god Helios. When their brother Phaethon died trying to drive the sun chariot across the sky, their tears of mourning fell to earth as amber, which is yellow (sort of), and so is JavaScript. They were then turned into [poplar](https://en.wiktionary.org/wiki/poplar) trees and, well, JavaScript is quite popular.
+## What's in a name?
+
+Helia (*HEE-lee-ah*) is the Latin spelling of Ἡλιη -- in Greek mythology, one of the [Heliades](https://www.wikidata.org/wiki/Q12656412): the daughters of the sun god Helios. When their brother Phaethon died trying to drive the sun chariot across the sky, their tears of mourning fell to earth as amber, which is yellow (sort of), and so is JavaScript. They were then turned into [poplar](https://en.wiktionary.org/wiki/poplar) trees and, well, JavaScript is quite popular.
 
 In Oct–Dec 2022, IP Stewards [sought](https://github.com/ipfs/pomegranate/issues/3) community input for the name of this project. After considering 20 suggestions and holding a couple of polls, the name **Helia** was chosen. Here's [why it's not named IPFS](https://github.com/ipfs/ipfs/issues/470).
 
 ## Background
 
-This project aims to build a lean, modular, modern implementation of IPFS, the Interplanetary File System.
+This project aims to build a lean, modular, and modern implementation of IPFS, the Interplanetary File System.
 
 For more information, see the [State of IPFS in JS (blog post)](https://blog.ipfs.tech/state-of-ipfs-in-js/).
 
 ## Roadmap
 
-The roadmap can be found here: https://github.com/ipfs/pomegranate/issues/5
+The roadmap can be found here: <https://github.com/ipfs/helia/issues/5>
 
-## Contribute
+## API Docs
+
+- <https://ipfs.github.io/helia>
 
-This IPFS implementation in JavaScript is a work in progress. [Here are some ways you can help](https://blog.ipfs.tech/state-of-ipfs-in-js/#%F0%9F%A4%9D-ways-you-can-help).
-
 ## License
 
 Licensed under either of
 
- * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)
- * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
+
+## Contribute
+
+Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia/issues).
 
-### Contribution
+Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general.
+
+Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+
+[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
diff --git a/packages/cli/.aegir.js b/packages/cli/.aegir.js
@@ -0,0 +1,6 @@
+
+export default {
+  build: {
+    bundle: false
+  }
+}
diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
@@ -0,0 +1,4 @@
+This project is dual licensed under MIT and Apache-2.0.
+
+MIT: https://www.opensource.org/licenses/mit
+Apache-2.0: https://www.apache.org/licenses/license-2.0
diff --git a/packages/cli/LICENSE-APACHE b/packages/cli/LICENSE-APACHE
@@ -0,0 +1,5 @@
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
diff --git a/packages/cli/LICENSE-MIT b/packages/cli/LICENSE-MIT
@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -0,0 +1,44 @@
+# @helia/cli <!-- omit in toc -->
+
+[![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
+[![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
+[![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
+[![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
+
+> Run a Helia node on the CLI
+
+## Table of contents <!-- omit in toc -->
+
+- [Install](#install)
+- [API Docs](#api-docs)
+- [License](#license)
+- [Contribute](#contribute)
+
+## Install
+
+```console
+$ npm i @helia/cli
+```
+
+## API Docs
+
+- <https://ipfs.github.io/helia/modules/_helia_cli.html>
+
+## License
+
+Licensed under either of
+
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
+
+## Contribute
+
+Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia/issues).
+
+Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general.
+
+Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+
+[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -0,0 +1,171 @@
+{
+  "name": "@helia/cli",
+  "version": "0.0.0",
+  "description": "Run a Helia node on the CLI",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/ipfs/helia/tree/master/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipfs/helia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ipfs/helia/issues"
+  },
+  "keywords": [
+    "IPFS"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
+  "bin": {
+    "helia": "./dist/src/index.js"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "sourceType": "module"
+    }
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "breaking": true,
+              "release": "major"
+            },
+            {
+              "revert": true,
+              "release": "patch"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            },
+            {
+              "type": "deps",
+              "release": "patch"
+            },
+            {
+              "scope": "no-release",
+              "release": false
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "docs",
+                "section": "Documentation"
+              },
+              {
+                "type": "deps",
+                "section": "Dependencies"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      "@semantic-release/git"
+    ]
+  },
+  "scripts": {
+    "clean": "aegir clean",
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check",
+    "build": "aegir build",
+    "test": "aegir test",
+    "test:node": "aegir test -t node --cov",
+    "release": "aegir release"
+  },
+  "dependencies": {
+    "@chainsafe/libp2p-gossipsub": "^5.3.0",
+    "@chainsafe/libp2p-noise": "^10.2.0",
+    "@chainsafe/libp2p-yamux": "^3.0.3",
+    "@helia/interface": "~0.0.0",
+    "@helia/rpc-client": "~0.0.0",
+    "@helia/rpc-server": "~0.0.0",
+    "@helia/unixfs": "~0.0.0",
+    "@libp2p/kad-dht": "^6.1.1",
+    "@libp2p/logger": "^2.0.2",
+    "@libp2p/mplex": "^7.1.1",
+    "@libp2p/peer-id": "^1.1.18",
+    "@libp2p/peer-id-factory": "^1.0.20",
+    "@libp2p/prometheus-metrics": "1.1.3",
+    "@libp2p/tcp": "^6.0.8",
+    "@libp2p/websockets": "^5.0.2",
+    "@libp2p/webtransport": "^1.0.6",
+    "@multiformats/multiaddr": "^11.1.4",
+    "@ucans/ucans": "^0.11.0-alpha",
+    "blockstore-datastore-adapter": "^4.0.0",
+    "datastore-fs": "^8.0.0",
+    "helia": "~0.0.0",
+    "libp2p": "next",
+    "multiformats": "^10.0.3",
+    "strip-json-comments": "^5.0.0",
+    "uint8arrays": "^4.0.2"
+  },
+  "devDependencies": {
+    "aegir": "^37.7.5"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts"
+  }
+}
diff --git a/packages/cli/src/commands/cat.ts b/packages/cli/src/commands/cat.ts
@@ -0,0 +1,40 @@
+import { CID } from 'multiformats'
+import type { Command } from './index.js'
+
+interface CatArgs {
+  positionals?: string[]
+  offset?: string
+  length?: string
+}
+
+export const cat: Command<CatArgs> = {
+  description: 'Fetch and cat an IPFS path referencing a file',
+  example: '$ helia cat <CID>',
+  offline: true,
+  options: {
+    offset: {
+      description: 'Where to start reading the file from',
+      type: 'string',
+      short: 'o'
+    },
+    length: {
+      description: 'How many bytes to read from the file',
+      type: 'string',
+      short: 'l'
+    }
+  },
+  async execute ({ positionals, offset, length, helia, stdout }) {
+    if (positionals == null || positionals.length === 0) {
+      throw new TypeError('Missing positionals')
+    }
+
+    const cid = CID.parse(positionals[0])
+
+    for await (const buf of helia.cat(cid, {
+      offset: offset == null ? undefined : parseInt(offset),
+      length: length == null ? undefined : parseInt(length)
+    })) {
+      stdout.write(buf)
+    }
+  }
+}