Skip to content
This repository was archived by the owner on Feb 12, 2024. It is now read-only.

Commit 689cfba

Browse files
daviddiasdaviddias
committedNov 1, 2016
docs: update readme, add examples, pointers to API docs and more
·
v0.41.20.24.1
1 parent 1b0b22d commit 689cfba

File tree

6 files changed

+272
-154
lines changed

6 files changed

+272
-154
lines changed
 

‎ARCHITECTURE.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Architecture
2+
3+
```
4+
┌───┐ ┌───────────────┐ ┌──────────────┐
5+
│CLI│───▶│ HTTP API ├───▶│IPFS Core Impl│
6+
└───┘ └───────────────┘ └──────────────┘
7+
△ △ △
8+
└──────────────└──────────┬─────────┘
9+
│
10+
┌─────┐
11+
│Tests│
12+
└─────┘
13+
```
14+
15+
## IPFS Core implementation architecture
16+
17+
IPFS Core is divided into separate subsystems, each of them exist in their own repo/module. The dependencies between each subsystem is assured by injection at the IPFS Core level. IPFS Core exposes an API, defined by the IPFS API spec. libp2p is the networking layer used by IPFS, but out of scope in IPFS core, follow that project [here](https://github.com/diasdavid/js-libp2p)
18+
19+
20+
```
21+
▶ ┌───────────────────────────────────────────────────────────────────────────────┐
22+
│ IPFS Core │
23+
│ └───────────────────────────────────────────────────────────────────────────────┘
24+
│
25+
│ │
26+
│
27+
│ ┌──────────────┬──────────────┼────────────┬─────────────────┐
28+
│ │ │ │ │
29+
│ │ │ │ │ │
30+
▼ │ ▼ │ ▼
31+
│ ┌──────────────────┐ │ ┌──────────────────┐ │ ┌──────────────────┐
32+
│ │ │ │ │ │ │ │
33+
│ │ Block Service │ │ │ DAG Service │ │ │ IPFS Repo │
34+
│ │ │ │ │ │ │ │
35+
│ └──────────────────┘ │ └──────────────────┘ │ └──────────────────┘
36+
│ │ │ │
37+
IPFS Core │ ▼ │ ┌────┴────┐ │
38+
┌────────┐ │ ▼ ▼ │
39+
│ │ Block │ │ ┌────────┐┌────────┐ │
40+
└────────┘ │ │DAG Node││DAG Link│ │
41+
│ │ └────────┘└────────┘ │
42+
┌──────────────────┐ │ │ ┌──────────────────┐
43+
│ │ │ │ │ │ │
44+
│ Bitswap │◀────┤ ├──────▶│ Importer │
45+
│ │ │ │ │ │ │
46+
└──────────────────┘ │ │ └──────────────────┘
47+
│ │ │ │
48+
│ │ ┌────┴────┐
49+
│ │ │ ▼ ▼
50+
│ │ ┌────────┐┌────────┐
51+
│ ┌──────────────────┐ │ │ │ layout ││chunker │
52+
│ │ │ ┌────────────┘ └────────┘└────────┘
53+
│ │ Files │◀────┘ │
54+
│ │ │
55+
│ └──────────────────┘ │
56+
▶ │
57+
▼
58+
┌───────────────────────────────────────────────────────────────────────────────┐
59+
│ │
60+
│ │
61+
│ │
62+
│ libp2p │
63+
│ │
64+
│ │
65+
└───────────────────────────────────────────────────────────────────────────────┘
66+
```
67+
68+
#### IPFS Core
69+
70+
IPFS Core is the entry point module for IPFS. It exposes an interface defined on [IPFS Specs.](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)
71+
72+
#### Block Service
73+
74+
Block Service uses IPFS Repo (local storage) and Bitswap (network storage) to store and fetch blocks. A block is a serialized MerkleDAG node.
75+
76+
#### DAG Service
77+
78+
DAG Service offers some graph language semantics on top of the MerkleDAG, composed by DAG Nodes (which can have DAG Links). It uses the Block Service as its storage and discovery service.
79+
80+
#### IPFS Repo
81+
82+
IPFS Repo is storage driver of IPFS, follows the [IPFS Repo Spec](https://github.com/ipfs/specs/tree/master/repo) and supports the storage of different types of files.
83+
84+
#### Bitswap
85+
86+
Bitswap is the exchange protocol used by IPFS to 'trade' blocks with other IPFS nodes.
87+
88+
#### Files
89+
90+
Files is the API that lets us work with IPFS objects (DAG Nodes) as if they were Unix Files.
91+
92+
#### Importer
93+
94+
Importer are a set of layouts (e.g. UnixFS) and chunkers (e.g: fixed-size, rabin, etc) that convert data to a MerkleDAG representation inside IPFS.
95+
96+

‎QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
hello world

‎README.md

+108-122
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,7 @@ This repo contains the JavaScript implementation of the IPFS protocol, with feat
2121

2222
### Project status
2323

24-
Consult the [Roadmap](/ROADMAP.md) for a complete state description of the project, or you can find `in process` updates in our [`Captain.log`](https://github.com/ipfs/js-ipfs/issues/30). A lot of components can be used currently, but it is a WIP, so beware of the Dragons.
25-
26-
[![](https://camo.githubusercontent.com/561516567e49f00b5a4f489e122ca9d22815b547/68747470733a2f2f6d656469612e67697068792e636f6d2f6d656469612f4965685335436f46667a5175512f67697068792e676966)](https://github.com/ipfs/js-ipfs/issues/30)
24+
Consult the [Roadmap](/ROADMAP.md) for a complete state description of the project, or you can find `in process` updates in our [`Captain.log`](https://github.com/ipfs/js-ipfs/issues/30). A lot of components can be used currently, but it is a WIP, so beware of the Dragons 🐉.
2725

2826
## Table of Contents
2927

@@ -37,15 +35,7 @@ Consult the [Roadmap](/ROADMAP.md) for a complete state description of the proje
3735
- [Examples](#examples)
3836
- [API](#api)
3937
- [Development](#development)
40-
- [Project structure](#project-structure)
41-
- [IPFS Core implementation architecture](#ipfs-core-implementation-architecture)
42-
- [IPFS Core](#ipfs-core)
43-
- [Block Service](#block-service)
44-
- [DAG Service](#dag-service)
45-
- [IPFS Repo](#ipfs-repo)
46-
- [Bitswap](#bitswap)
47-
- [Files](#files)
48-
- [Importer](#importer)
38+
- [Project Architecture](/ARCHITECTURE.md)
4939
- [Packages](#packages)
5040
- [Contribute](#contribute)
5141
- [Want to hack on IPFS?](#want-to-hack-on-ipfs)
@@ -97,155 +87,151 @@ Loading this module in a browser (using a `<script>` tag) makes the `Ipfs` ob
9787

9888
The last published version of the package become [available for download](https://unpkg.com/ipfs/dist/) from [unpkg](https://unpkg.com/) and thus you may use it as the source:
9989

100-
* loading the minified version
101-
102-
```html
103-
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
104-
```
10590

106-
* loading the human-readable (not minified) version
91+
```html
92+
<!-- loading the minified version -->
93+
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
10794

108-
```html
109-
<script src="https://unpkg.com/ipfs/dist/index.js"></script>
110-
```
95+
<!-- loading the human-readable (not minified) version -->
96+
<script src="https://unpkg.com/ipfs/dist/index.js"></script>
97+
```
11198

11299
## Usage
113100

114-
### Examples
101+
### CLI
115102

116-
> **Will come soon**
103+
The `jsipfs` CLI, available when `js-ipfs` is installed globably, follows(should, it is a WIP) the same interface defined by `go-ipfs`, you can always use the `help` command for help menus.
117104

118-
### API
105+
```
106+
# Install js-ipfs globally
107+
> npm install ipfs --global
108+
> jsipfs --help
109+
Commands:
110+
bitswap A set of commands to manipulate the bitswap agent.
111+
block Manipulate raw IPFS blocks.
112+
bootstrap Show or edit the list of bootstrap peers.
113+
commands List all available commands
114+
config <key> [value] Get and set IPFS config values
115+
daemon Start a long-running daemon process
116+
# ...
117+
```
119118

120-
A complete API definition will come, meanwhile, you can learn how to you use js-ipfs throught he standard interface at [![](https://img.shields.io/badge/interface--ipfs--core-API%20Docs-blue.svg)](https://github.com/ipfs/interface-ipfs-core)
119+
### HTTP-API
121120

122-
## Development
121+
The HTTP-API exposed by the js-ipfs daemon follows the [`http-api-spec`](https://github.com/ipfs/http-api-spec). You can use any of the IPFS HTTP-API client libraries with it, such as: [js-ipfs-api](https://github.com/ipfs/js-ipfs-api).
123122

124-
### Clone
125-
```
126-
git clone https://github.com/ipfs/js-ipfs.git
127-
cd js-ipfs
128-
```
123+
### IPFS Core examples (use IPFS as a module)
129124

130-
### Install Dependencies
131-
```
132-
npm install
133-
```
125+
#### Create a IPFS node instance
134126

135-
### Run Tests
136-
```
137-
npm test
138-
```
127+
```JavaScript
128+
// IPFS will need a repo, it can create one for you or you can pass
129+
// it a repo instance of the type IPFS Repo
130+
// https://github.com/ipfs/js-ipfs-repo
131+
const repo = <IPFS Repo instance or repo path>
139132

140-
### Lint
133+
// Create the IPFS node instance
134+
const node = new IPFS(repo)
Has conversations. Original line has conversations.
141135

142-
*Conforming to linting rules is a prerequisite to commit to js-ipfs.*
136+
// We need to init our repo, in this case the repo was empty
137+
// We are picking 2048 bits for the RSA key that will be our PeerId
138+
ipfs.init({ emptyRepo: true, bits: 2048 }, (err) => {
139+
if (err) { throw err }
143140

144-
```
145-
npm run lint
146-
```
141+
// Once the repo is initiated, we have to load it so that the IPFS
142+
// instance has its config values. This is useful when you have
143+
// previous created repos and you don't need to generate a new one
144+
ipfs.load((err) => {
145+
if (err) { throw err }
147146

148-
### Build
149-
```
150-
npm run build
147+
// Last but not the least, we want our IPFS node to use its peer
148+
// connections to fetch and serve blocks from.
149+
ipfs.goOnline((err) => {
150+
if (err) { throw err }
151+
// Here you should be good to go and call any IPFS function
152+
})
153+
})
151154
```
152155
153-
The ES5 distributable build will be located in `lib/`. The browser distributable will be located in `dist/index.js`.
156+
> We are working on making this init process better, see https://github.com/ipfs/js-ipfs/issues/556 for the discussion.
154157
155-
## Project structure
158+
#### More to come
156159
157-
```
158-
┌───┐ ┌───────────────┐ ┌──────────────┐
159-
│CLI│───▶│ HTTP API ├───▶│IPFS Core Impl│
160-
└───┘ └───────────────┘ └──────────────┘
161-
△ △ △
162-
└──────────────└──────────┬─────────┘
163-
│
164-
┌─────┐
165-
│Tests│
166-
└─────┘
167-
```
160+
> If you have built an example, please share it with the community by submitting a Pull Request to this repo!.
168161
169-
## IPFS Core implementation architecture
162+
### API
170163
171-
IPFS Core is divided into separate subsystems, each of them exist in their own repo/module. The dependencies between each subsystem is assured by injection at the IPFS Core level. IPFS Core exposes an API, defined by the IPFS API spec. libp2p is the networking layer used by IPFS, but out of scope in IPFS core, follow that project [here](https://github.com/diasdavid/js-libp2p)
164+
[![](https://github.com/ipfs/interface-ipfs-core/raw/master/img/badge.png)](https://github.com/ipfs/interface-ipfs-core)
172165
166+
A complete API definition will come, meanwhile, you can learn how to you use js-ipfs throught he standard interface at [![](https://img.shields.io/badge/interface--ipfs--core-API%20Docs-blue.svg)](https://github.com/ipfs/interface-ipfs-core).
173167
174-
```
175-
▶ ┌───────────────────────────────────────────────────────────────────────────────┐
176-
│ IPFS Core │
177-
│ └───────────────────────────────────────────────────────────────────────────────┘
178-
│
179-
│ │
180-
│
181-
│ ┌──────────────┬──────────────┼────────────┬─────────────────┐
182-
│ │ │ │ │
183-
│ │ │ │ │ │
184-
▼ │ ▼ │ ▼
185-
│ ┌──────────────────┐ │ ┌──────────────────┐ │ ┌──────────────────┐
186-
│ │ │ │ │ │ │ │
187-
│ │ Block Service │ │ │ DAG Service │ │ │ IPFS Repo │
188-
│ │ │ │ │ │ │ │
189-
│ └──────────────────┘ │ └──────────────────┘ │ └──────────────────┘
190-
│ │ │ │
191-
IPFS Core │ ▼ │ ┌────┴────┐ │
192-
┌────────┐ │ ▼ ▼ │
193-
│ │ Block │ │ ┌────────┐┌────────┐ │
194-
└────────┘ │ │DAG Node││DAG Link│ │
195-
│ │ └────────┘└────────┘ │
196-
┌──────────────────┐ │ │ ┌──────────────────┐
197-
│ │ │ │ │ │ │
198-
│ Bitswap │◀────┤ ├──────▶│ Importer │
199-
│ │ │ │ │ │ │
200-
└──────────────────┘ │ │ └──────────────────┘
201-
│ │ │ │
202-
│ │ ┌────┴────┐
203-
│ │ │ ▼ ▼
204-
│ │ ┌────────┐┌────────┐
205-
│ ┌──────────────────┐ │ │ │ layout ││chunker │
206-
│ │ │ ┌────────────┘ └────────┘└────────┘
207-
│ │ Files │◀────┘ │
208-
│ │ │
209-
│ └──────────────────┘ │
210-
▶ │
211-
▼
212-
┌───────────────────────────────────────────────────────────────────────────────┐
213-
│ │
214-
│ │
215-
│ │
216-
│ libp2p │
217-
│ │
218-
│ │
219-
└───────────────────────────────────────────────────────────────────────────────┘
168+
##### [Generic API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/generic)
169+
170+
##### [Block API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/block)
171+
172+
##### [Object API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/object)
173+
174+
##### [Config API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/config)
175+
176+
##### [Files API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/files)
177+
178+
##### [Swarm API](https://github.com/ipfs/interface-ipfs-core/tree/master/API/swarm)
179+
180+
##### [libp2p API](https://github.com/libp2p/interface-libp2p)
181+
182+
Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal interface for this API hasn't been defined by you can find documentation at its implementations:
183+
184+
- [libp2p-ipfs](https://github.com/ipfs/js-libp2p-ipfs)
185+
- [libp2p-ipfs-browser](https://github.com/ipfs/js-libp2p-ipfs-browser)
186+
187+
## Development
188+
189+
### Clone
190+
191+
```sh
192+
> git clone https://github.com/ipfs/js-ipfs.git
193+
> cd js-ipfs
220194
```
221195
222-
#### IPFS Core
196+
### Install Dependencies
223197
224-
IPFS Core is the entry point module for IPFS. It exposes an interface defined on [IPFS Specs.](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)
198+
```sh
199+
> npm install
200+
```
225201
226-
#### Block Service
202+
### Run Tests
227203
228-
Block Service uses IPFS Repo (local storage) and Bitswap (network storage) to store and fetch blocks. A block is a serialized MerkleDAG node.
204+
```sh
205+
> npm test
229206

230-
#### DAG Service
207+
# run just IPFS core tests
208+
> npm run test:node:core
231209

232-
DAG Service offers some graph language semantics on top of the MerkleDAG, composed by DAG Nodes (which can have DAG Links). It uses the Block Service as its storage and discovery service.
210+
# run just IPFS HTTP-API tests
211+
> npm run test:node:http
233212

234-
#### IPFS Repo
213+
# run just IPFS CLI tests
214+
> npm run test:node:cli
235215

236-
IPFS Repo is storage driver of IPFS, follows the [IPFS Repo Spec](https://github.com/ipfs/specs/tree/master/repo) and supports the storage of different types of files.
216+
# run just IPFS Browser tests
217+
> npm run test:browser
218+
```
237219
238-
#### Bitswap
220+
### Lint
239221
240-
Bitswap is the exchange protocol used by IPFS to 'trade' blocks with other IPFS nodes.
222+
*Conforming to linting rules is a prerequisite to commit to js-ipfs.*
241223
242-
#### Files
224+
```sh
225+
> npm run lint
226+
```
243227
244-
Files is the API that lets us work with IPFS objects (DAG Nodes) as if they were Unix Files.
228+
### Build a dist version
245229
246-
#### Importer
230+
```
231+
> npm run build
232+
```
247233
248-
Importer are a set of layouts (e.g. UnixFS) and chunkers (e.g: fixed-size, rabin, etc) that convert data to a MerkleDAG representation inside IPFS.
234+
The ES5 distributable build will be located in `lib/`. The browser distributable will be located in `dist/index.js`.
249235
250236
## Packages
251237

‎package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
"detect-node": "^2.0.3",
6969
"fs-pull-blob-store": "^0.3.0",
7070
"glob": "^7.0.6",
71-
"hapi": "^15.0.3",
71+
"hapi": "^15.2.0",
7272
"idb-pull-blob-store": "^0.5.1",
7373
"ipfs-api": "^10.0.0",
7474
"ipfs-bitswap": "^0.7.0",

‎src/cli/commands/object/patch/add-link.js

+63-30
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ const debug = require('debug')
55
const log = debug('cli:object')
66
const dagPB = require('ipld-dag-pb')
77
const DAGLink = dagPB.DAGLink
8+
const series = require('async/series')
89
log.error = debug('cli:object:error')
910

1011
module.exports = {
@@ -15,41 +16,73 @@ module.exports = {
1516
builder: {},
1617

1718
handler (argv) {
18-
utils.getIPFS(gotIPFS)
19+
let ipfs
20+
let node
21+
let nodeSize
22+
let nodeMultihash
23+
let nodePatched
24+
series([
25+
(cb) => {
26+
utils.getIPFS(gotIPFS)
1927

20-
function gotIPFS (err, ipfs) {
21-
if (err) {
22-
throw err
23-
}
28+
function gotIPFS (err, _ipfs) {
29+
if (err) {
30+
cb(err)
31+
}
32+
ipfs = _ipfs
33+
cb()
34+
}
35+
},
36+
(cb) => {
37+
ipfs.object.get(argv.ref, {enc: 'base58'}, (err, _node) => {
38+
if (err) {
39+
cb(err)
40+
}
41+
node = _node
42+
cb()
43+
})
44+
},
45+
(cb) => {
46+
node.size((err, size) => {
47+
if (err) {
48+
cb(err)
49+
}
50+
nodeSize = size
51+
cb()
52+
})
53+
},
54+
(cb) => {
55+
node.multihash((err, multihash) => {
56+
if (err) {
57+
cb(err)
58+
}
59+
nodeMultihash = multihash
60+
cb()
61+
})
62+
},
63+
(cb) => {
64+
const link = new DAGLink(argv.name, nodeSize, nodeMultihash)
2465

25-
ipfs.object.get(argv.ref, {enc: 'base58'}).then((linkedObj) => {
26-
linkedObj.size((err, size) => {
66+
ipfs.object.patch.addLink(argv.root, link, {enc: 'base58'}, (err, node) => {
2767
if (err) {
28-
throw err
68+
cb(err)
2969
}
30-
linkedObj.multihash((err, multihash) => {
31-
if (err) {
32-
throw err
33-
}
34-
35-
const link = new DAGLink(argv.name, size, multihash)
36-
37-
ipfs.object.patch.addLink(argv.root, link, {enc: 'base58'})
38-
.then((node) => {
39-
node.toJSON(gotJSON)
40-
41-
function gotJSON (err, nodeJSON) {
42-
if (err) {
43-
throw err
44-
}
45-
console.log(nodeJSON.Hash)
46-
}
47-
})
48-
})
70+
nodePatched = node
71+
cb()
4972
})
50-
}).catch((err) => {
73+
}
74+
], (err) => {
75+
if (err) {
5176
throw err
52-
})
53-
}
77+
}
78+
nodePatched.toJSON(gotJSON)
79+
80+
function gotJSON (err, nodeJSON) {
81+
if (err) {
82+
throw err
83+
}
84+
console.log(nodeJSON.Hash)
85+
}
86+
})
5487
}
5588
}

‎test/utils/ipfs-exec.js

+3-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,9 @@ module.exports = (repoPath, opts) => {
3434
}
3535

3636
return exec(args).then((res) => {
37-
expect(res.stderr).to.be.eql('')
37+
// We can't escape the os.tmpDir warning due to:
38+
// https://github.com/shelljs/shelljs/blob/master/src/tempdir.js#L43
39+
// expect(res.stderr).to.be.eql('')
3840

3941
return res.stdout
4042
})

0 commit comments

Comments
 (0)
This repository has been archived.