Merge pull request #46 from richardschneider/basic-articles

richardschneider · web-flow · commit 1a19259d62a4 · 2018-11-07T14:16:21.000+13:00
docs: improve articles
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![build status](https://ci.appveyor.com/api/projects/status/github/richardschneider/net-ipfs-api?branch=master&svg=true)](https://ci.appveyor.com/project/richardschneider/net-ipfs-api) 
 [![Coverage Status](https://coveralls.io/repos/github/richardschneider/net-ipfs-api/badge.svg?branch=master)](https://coveralls.io/github/richardschneider/net-ipfs-api?branch=master)
 [![Version](https://img.shields.io/nuget/v/Ipfs.Api.svg)](https://www.nuget.org/packages/Ipfs.Api)
-[![docs](https://cdn.rawgit.com/richardschneider/net-ipfs-api/master/doc/images/docs-latest-green.svg)](https://richardschneider.github.io/net-ipfs-api)
+[![docs](https://cdn.rawgit.com/richardschneider/net-ipfs-api/master/doc/images/docs-latest-green.svg)](https://richardschneider.github.io/net-ipfs-api/articles/client.html)
 
 
 A .Net client library for the IPFS HTTP API, implemented in C#. 
@@ -17,7 +17,7 @@ More information, including the Class Reference, is on the [Project](https://ric
 - [Asynchronous I/O](https://richardschneider.github.io/net-ipfs-api/articles/async.html) to an IPFS server
 - Supports [cancellation](https://richardschneider.github.io/net-ipfs-api/articles/cancellation.html) of all requests to the IPFS Server
 - Requests that all responses are compressed
-- Comprehensive [documentation](https://richardschneider.github.io/net-ipfs-api)
+- Comprehensive [documentation](https://richardschneider.github.io/net-ipfs-api/articles/client.html)
 - C# style access to the [ipfs core interface](https://richardschneider.github.io/net-ipfs-core/api/Ipfs.CoreApi.html)
   - [Bitswap API](https://richardschneider.github.io/net-ipfs-core/api/Ipfs.CoreApi.IBitswapApi.html)
   - [Block API](https://richardschneider.github.io/net-ipfs-core/api/Ipfs.CoreApi.IBlockApi.html)
@@ -45,7 +45,7 @@ For the latest build or older non-released builds see [Continuous Integration](h
 
 Every IPFS Api is a property of the [IpfsClient](https://richardschneider.github.io/net-ipfs-api/api/Ipfs.Api.IpfsClient.html).  The following example reads a text file
 
-```
+```csharp
 var ipfs = new IpfsClient();
 
 const string filename = "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about";
diff --git a/doc/Documentation.csproj b/doc/Documentation.csproj
@@ -88,9 +88,11 @@
     <Content Include="template\fonts\Lato-Regular.ttf" />
     <Content Include="template\fonts\Lato-Regular.woff" />
     <Content Include="template\fonts\Lato-Regular.woff2" />
-    <Content Include="articles\cancellation.md" />
     <Content Include="articles\async.md" />
     <Content Include="articles\envvars.md" />
+    <Content Include="articles\client.md" />
+    <Content Include="articles\daemon.md" />
+    <Content Include="articles\filesystem.md" />
     <None Include="Web.Debug.config">
       <DependentUpon>Web.config</DependentUpon>
     </None>
diff --git a/doc/api/.manifest b/doc/api/.manifest
diff --git a/doc/articles/async.md b/doc/articles/async.md
@@ -1,24 +1,45 @@
-﻿# Asynchronous I/O
-
-All requests to the IPFS server are [asynchronous](https://docs.microsoft.com/en-us/dotnet/csharp/async),
-which does not block current thread.
-
-This means that callers should **normally** use the `async/await` paradigm
-
-```cs
-async Task<string> AddText()
-{
-	var result = await ipfs.FileSystem.AddTextAsync("I am pinned");
-	return result.Hash;
-}
-```
-
-If a synchronous operation is required, then this can work
-
-```cs
-string AddText()
-{
-	var result = ipfs.FileSystem.AddTextAsync("I am pinned").Result;
-	return result.Hash;
-}
-```
+﻿# Asynchronous I/O
+
+All requests to the IPFS server are [asynchronous](https://docs.microsoft.com/en-us/dotnet/csharp/async),
+which does not block current thread.
+
+This means that callers should **normally** use the `async/await` paradigm
+
+```cs
+var result = await ipfs.FileSystem.AddTextAsync("I am pinned");
+```
+
+## Synchronous
+
+If a synchronous operation is required, then this can work
+
+```cs
+var result = ipfs.FileSystem.AddTextAsync("I am pinned").Result;
+```
+
+## Cancelling a request
+
+All requests to the IPFS server can be cancelled by supplying 
+an optional [CancellationToken](xref:System.Threading.CancellationToken).  When 
+the token is cancelled, 
+a [TaskCanceledException](xref:System.Threading.Tasks.TaskCanceledException) 
+will be `thrown`.
+
+Here's a contrived example ([unit test](https://github.com/richardschneider/net-ipfs-api/blob/cancellation/test/CoreApi/CancellationTest.cs)) 
+that forces the getting of info on the local IPFS server to be cancelled
+
+```csharp
+var cts = new CancellationTokenSource(500);
+try
+{
+	await Task.Delay(1000);
+	var peer = await ipfs.IdAsync(cts.Token);
+	Assert.Fail("Did not throw TaskCanceledException");
+}
+catch (TaskCanceledException)
+{
+	return;
+}
+```
+
+See also [Task Cancellation](https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/task-cancellation)
diff --git a/doc/articles/cancellation.md b/doc/articles/cancellation.md
diff --git a/doc/articles/client.md b/doc/articles/client.md
@@ -0,0 +1,52 @@
+﻿# Accessing IPFS
+
+IPFS is a distributed peer to peer system.  There is no central server!  Typically, each machine (peer) runs 
+a [daemon](daemon.md) that communicates with other peers.
+
+The [IpfsClient](xref:Ipfs.Api.IpfsClient) provides a simple way for your program to access the daemon 
+via the [IPFS HTTP API](https://docs.ipfs.io/reference/api/http/) protocol. The client 
+should be used as a shared object in your program, much like [HttpClient](xref:System.Net.Http.HttpClient).  It is 
+thread safe (re-entrant) and conserves sockets and TCP connections when only one instance is used.
+
+```csharp
+public class Program
+{
+  static readonly IpfsClient ipfs = new IpfsClient();
+  public async Task Main(string[] args) 
+  {
+	// Get the Peer info of the daemon
+	var peer = await ipfs.IdAsync();
+  }
+}
+```
+
+## Core API
+
+The [Core API](xref:Ipfs.CoreApi.ICoreApi) is a set of interfaces to IPFS features and is implemented by the client.  The 
+[FileSystem](filesystem.md) and [PubSub]() features are most often used.
+
+```csharp
+const string filename = "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about";
+string text = await ipfs.FileSystem.ReadAllTextAsync(filename);
+```
+
+### Features
+
+| Feature | Purpose |
+| ------- | ------- |
+| [Bitswap](xref:Ipfs.CoreApi.IBitswapApi) | Data trading module for IPFS; requests blocks from and sends blocks to other peers |
+| [Block](xref:Ipfs.CoreApi.IBlockApi) | Manages the blocks |
+| [Bootstrap](xref:Ipfs.CoreApi.IBootstrapApi) | Trusted peers |
+| [Config](xref:Ipfs.CoreApi.IConfigApi) | Manages the configuration of the local peer |
+| [Dag](xref:Ipfs.CoreApi.IDagApi) | Manages the IPLD (linked data) Directed Acrylic Graph |
+| [Dht](xref:Ipfs.CoreApi.IDhtApi) | Manages the Distributed Hash Table |
+| [Dns](xref:Ipfs.CoreApi.IDhtApi) | DNS mapping to IPFS |
+| [Misc](xref:Ipfs.CoreApi.IGenericApi) | Some miscellaneous methods |
+| [FileSystem](xref:Ipfs.CoreApi.IFileSystemApi) | Manages the files/directories in IPFS |
+| [Key](xref:Ipfs.CoreApi.IKeyApi) | Manages the cryptographic keys |
+| [Name](xref:Ipfs.CoreApi.INameApi) | Manages the Interplanetary Name Space (IPNS) |
+| [Object](xref:Ipfs.CoreApi.IObjectApi) | Manages the IPFS Directed Acrylic Graph |
+| [Pin](xref:Ipfs.CoreApi.IPinApi) | Manage objects that are locally stored and permanent |
+| [PubSub](xref:Ipfs.CoreApi.IPubSubApi) | Publish and subscribe to topic messages |
+| [Swarm](xref:Ipfs.CoreApi.ISwarmApi) | Manages the swarm of peers |
+
diff --git a/doc/articles/daemon.md b/doc/articles/daemon.md
@@ -0,0 +1,32 @@
+﻿# IPFS Daemon
+
+The IPFS daemon is a service that runs on a machine and allows access to other peers on the network. This 
+is what the [IPFS client](client.md) manages.
+
+## Installing
+
+The authoritive documentmenation is at [https://docs.ipfs.io/introduction/install/](https://docs.ipfs.io/introduction/install/) which 
+describes the `go-ipfs` implementation. 
+There is also [js-ipfs](https://docs.ipfs.io/reference/js/overview/) for NodeJS fans.
+
+### Windows
+
+For Windows using [chocolatey](https://chocolatey.org/)
+
+```
+> choco install go-ipfs
+> ipfs init
+> ipfs daemon
+```
+
+## Locating the daemon
+
+By default the client looks for a deamon at `http://localhost:5001`.  This can be overriden by either 
+setting the environment variable [IpfsHttpUrl](envvars.md) or initialising the client with an URL.
+
+```csharp
+// js-ipfs likes this address
+static readonly IpfsClient ipfs = new IpfsClient("http://127.0.0.1:5002");
+```
+
+
diff --git a/doc/articles/envvars.md b/doc/articles/envvars.md
@@ -1,8 +1,8 @@
 ﻿# Environment variables
 
 The following [environment variables](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682653.aspx) 
-are used  to control the behaviour of the library
+are used  to control the behaviour of the library.  They override the default value.
 
 | Name | Description |
 | --- | --- |
-| IpfsHttpUrl | The default URL to the IPFS HTTP API server. See [DefaultApiUri](xref:Ipfs.Api.IpfsClient.DefaultApiUri) for more details. |
+| IpfsHttpUrl | The [default URL](xref:Ipfs.Api.IpfsClient.DefaultApiUri) to the IPFS HTTP API [daemon](daemon.md).
diff --git a/doc/articles/filesystem.md b/doc/articles/filesystem.md
@@ -0,0 +1,63 @@
+﻿# IPFS file system
+
+The official name is [UnixFS](https://docs.ipfs.io/guides/concepts/unixfs/).  It allows files and directories of any size 
+to be added and retrieved from IPFS via the [FileSystem](xref:Ipfs.CoreApi.IFileSystemApi) 
+and [Object](xref:Ipfs.CoreApi.IObjectApi) API.  
+
+## Files
+
+A file has a unique [content id (CID)](xref:Ipfs.Cid) which is the cryptographic hash of the content; see
+[CID concept](https://docs.ipfs.io/guides/concepts/cid/) for background information.  The file's content is not just the file's 
+data but is encapsulated with a [protocol buffer](https://en.wikipedia.org/wiki/Protocol_Buffers) encoding of the 
+[PBNode](https://github.com/ipfs/go-ipfs/blob/0cb22ccf359e05fb5b55a9bf2f9c515bf7d4dba7/merkledag/pb/merkledag.proto#L31-L39) 
+and [UnixFS Data](https://github.com/ipfs/go-ipfs/blob/0cb22ccf359e05fb5b55a9bf2f9c515bf7d4dba7/unixfs/pb/unixfs.proto#L3-L20).
+
+Where
+- `PBNode.Data` contains unixfs message Data
+- unixfs `Data.Data` contans file's data
+
+When the file's data exceeds the [chunking size](xref:Ipfs.CoreApi.AddFileOptions.ChunkSize), multiple [blocks](xref:Ipfs.CoreApi.IBlockApi) 
+are generated.  The returned CID points to a block that has `PBNode.Links` and no `PBNode.Data`.
+
+### Adding a file
+
+[AddAsync](xref:Ipfs.CoreApi.IFileSystemApi.AddAsync*) is used to add a stream of data to IPFS.  It returns a 
+[FileSystemNode](xref:Ipfs.IFileSystemNode) which 
+describes the added the data.  Of particular import is its [CID](xref:Ipfs.IDataBlock.Id).  The helper methods 
+[AddTextAsync](xref:Ipfs.CoreApi.IFileSystemApi.AddTextAsync*) and [AddFileAsync](xref:Ipfs.CoreApi.IFileSystemApi.AddFileAsync*) are also available.
+
+All the Add methods accept [options](xref:Ipfs.CoreApi.AddFileOptions) to control how the data is added to IPFS.
+
+```csharp
+var fsn = await ipfs.FileSystem.AddTextAsync("hello world");
+Console.WriteLine((string)fsn.Id)
+
+// Qmf412jQZiuVUtdgnB36FXFX7xg5V6KEbSJ4dpQuhkLyfD
+```
+
+### Reading a file
+
+[ReaFileAsync](xref:Ipfs.CoreApi.IFileSystemApi.ReadFileAsync*) is used to read a stream of data from IPFS.  It returns a 
+[Stream](xref:System.IO.Stream) containing just the file's data NOT the protocol buffer encoded data.
+
+```csharp
+string path = "Qmf412jQZiuVUtdgnB36FXFX7xg5V6KEbSJ4dpQuhkLyfD";
+using (var stream = await ipfs.FileSystem.ReadFileAsyc(path))
+{
+	// Do something with the data
+}
+```
+
+### Getting a CID
+
+Normally, you get the CID by [adding](xref:Ipfs.CoreApi.IFileSystemApi.AddAsync*) the file to IPFS.  You can avoid adding it 
+to IPFS by using the [OnlyHash option](xref:Ipfs.CoreApi.AddFileOptions.OnlyHash).
+
+```csharp
+var options = new AddFileOptions { OnlyHash = true };
+var fsn = await ipfs.FileSystem.AddTextAsync("hello world", options);
+Console.WriteLine((string)fsn.Id)
+
+// Qmf412jQZiuVUtdgnB36FXFX7xg5V6KEbSJ4dpQuhkLyfD
+```
+
diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml
@@ -1,9 +1,14 @@
 - name: Introduction
   href: intro.md
+- name: Accessing IPFS
+  href: client.md
+- name: File system
+  href: filesystem.md
 - name: Asynchronous I/O
   href: async.md
-  items:
-    - name: Cancellation
-      href: cancellation.md
 - name: Environment variables
-  href: envvars.md
+  href: envvars.md
+- name: IPFS daemon
+  href: daemon.md
+- name: Class Reference
+  href: ../api/Ipfs.Api.yml
