Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs/code-flow : Add code flow documentation for add cmd. #5864

Merged
merged 6 commits into from
Jan 21, 2019
Merged

docs/code-flow : Add code flow documentation for add cmd. #5864

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
75d5e40
docs/code-flow : Add code flow documentation for add cmd.
Dec 20, 2018
e229bc2
Cleanup and resolve docs
Jan 6, 2019
9e08723
Updated the code reference links
Jan 11, 2019
d304a2f
Fixed the indentation of the sections
Jan 11, 2019
7dbdb0e
Document cleanup and additional references
Jan 15, 2019
269550b
Added link to doc in README.md
Jan 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/add-code-flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
# IPFS : The `Add` command demystified

https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/commands/add.go#L208-L213

The goal of this document is to capture the code flow for adding a file (see the `coreapi` package) using the IPFS CLI, in the process exploring some datastructures and packages like `ipld.Node` (aka `dagnode`, `FSNode`, `MFS`, etc.
The goal of this document is to capture the code flow for adding a file (see the `coreapi` package) using the IPFS CLI, in the process exploring some datastructures and packages like `ipld.Node` (aka `dagnode`), `FSNode`, `MFS`, etc.

**Try this yourself**
>
Expand Down Expand Up @@ -42,11 +40,11 @@ Within the function, a new `Adder` is created with the configured `Blockstore` a
- **[`adder.AddAllAndPin(files)`](https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L403)** - *Entrypoint to the `Add` logic*
encapsulates a lot of the underlying functionality that will be investigated in the following sections.

Our focus will be on the simplest case, a single file, handled by `Adder.addFileNode(path, file)` handled by `Adder.addFile(pathm files.File)`.
Our focus will be on the simplest case, a single file, handled by `Adder.addFile(file files.File)`.

- **[`adder.addFile(path, files.File)`](https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L450)** - *Create the _DAG_ and add to `MFS`*
- **[`adder.addFile(file files.File)`](https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L450)** - *Create the _DAG_ and add to `MFS`*

The `addFile(file)` method takes the data and converts it into a __DAG__ tree and adds the root of the tree in to the `MFS`.
The `addFile(file)` method takes the data and converts it into a __DAG__ tree and adds the root of the tree into the `MFS`.

https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L508-L521

Expand Down Expand Up @@ -80,18 +78,16 @@ Within the function, a new `Adder` is created with the configured `Blockstore` a

The node is then added as a child to the inner `UnixFS` directory using the `(BasicDirectory).AddChild()` method.

> NOTE: This is not to be confused with the `directory.AddChild(filename, ipld.Node)`, as this operates on the `UnixFS` `BasicDirectory` object only.
> NOTE: This is not to be confused with the `directory.AddChild(filename, ipld.Node)`, as this operates on the `UnixFS` `BasicDirectory` object.

- **[UnixFS] [`(BasicDirectory).AddChild(ctx, name, ipld.Node)`](https://github.com/ipfs/go-unixfs/blob/v1.1.16/io/directory.go#L137)** - *Add child to `BasicDirectory`*

> IMPORTANT: It should be noted that the `BasicDirectory` struct of the `UnixFS` package, encasulates a node object of type `ProtoNode`, which is a different format from the `ipld.Node` we have been working on throughout this document.
> IMPORTANT: It should be noted that the `BasicDirectory` object uses the `ProtoNode` type object which is an implementation of the `ipld.Node` interface, seen and used throughout this document. Ideally the `ipld.Node` should always be used, unless we need access tp specific functions from `ProtoNode` (like `Copy()`) that are not available in the interface.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: typo, tp -> to.


This method first attempts to remove any old links (`ProtoNode.RemoveNodeLink(name)`) to the `ProtoNode` prior to adding a link to the newly added `ipld.Node`, using `ProtoNode.AddNodeLink(name, ipld.Node)`.

- **[Merkledag] [`AddNodeLink()`](https://github.com/ipfs/go-merkledag/blob/v1.1.13/node.go#L99)**
- **[Merkledag] [`AddNodeLink()`](https://github.com/ipfs/go-merkledag/blob/v1.1.15/node.go#L99)**

**HELP: The go-merkledag version is supposed to v1.1.15 for this example, however that version has not been added to the [releases](https://github.com/ipfs/go-merkledag/releases)**

The `AddNodeLink()` method is where an `ipld.Link` is created with the `ipld.Node`'s `CID` and size in the `ipld.MakeLink(ipld.Node)` method, and is then appended to the `ProtoNode`'s links in the `ProtoNode.AddRawLink(name)` method.

- **[`adder.Finalize()`](https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L200)** - *Fetch and return the __DAG__ **root** from the `MFS` and `UnixFS` directory*
Expand All @@ -100,4 +96,8 @@ Within the function, a new `Adder` is created with the configured `Blockstore` a

- **[`adder.PinRoot()`](https://github.com/ipfs/go-ipfs/blob/v0.4.18/core/coreunix/add.go#L171)** - *Pin all files under the `MFS` **root***

The whole process ends with `PinRoot` recursively pinning all the files under the `MFS` **root**
The whole process ends with `PinRoot` recursively pinning all the files under the `MFS` **root**

# Also see
1. https://github.com/ipfs/go-ipfs/#development
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I probably wasn't very clear, I meant for you to add a link in the https://github.com/ipfs/go-ipfs/#development section pointing here, so this document wouldn't get lost in the docs directory.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh you meant only in the issue conversation space and not the actual doc?! Oops!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the actual entry-point README doc, but instead of pointing from here to there, point there to here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh dang. I completely misunderstood. I didn't realize the link was the the top README.md doc. Alright I will go ahead and add it to the README.md

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, you're right, sorry, I didn't realize the link was copied without the README.md path 😬

2. [Concept document about files](https://github.com/ipfs/docs/issues/133)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can probably move this to the introduction (before actually starting to talk about MFS/UnixFS).