Add get_and_cache function (#19)

README.md

@@ -6,16 +6,20 @@ Native IPFS integration to Aqua language. Orchestrate IPFS file transfer with Aq
    - `@fluencelabs/aqua-ipfs`
    - `@fluencelabs/fluence` 
    - `@fluencelabs/fluence-network-environment`
+
 2. Import and call
 ```typescript
-import { put, get_from } from '@fluencelabs/aqua-ipfs';
+import { get_and_cache } from '@fluencelabs/aqua-ipfs';
 import { createClient } from "@fluencelabs/fluence";
 import { krasnodar } from "@fluencelabs/fluence-network-environment";
 
+// connect to the Fluence network
 const fluence = await createClient(krasnodar[1]);
+// get some file's or dir's IPFS CID
 let cid = "Qm...";
-let ipfs = "/ip4/x.x.x.x/tcp/5001/"
+let ipfsMultiaddr = "/ip4/x.x.x.x/tcp/5001/"
-let getResult = await get_from(fluence, fluence.relayPeerId, cid, ipfs, { ttl: 10000 });
+// And cache it on the IPFS node running along the Fluence node we've connected to
+let path = await get_and_cache(fluence, fluence.relayPeerId, cid, ipfs, { ttl: 10000 });
 ```
 
 ## Directory structure

aqua/ipfs-api.aqua

@@ -3,6 +3,46 @@ import "ipfs.aqua"
 
 alias Multiaddr: string
 alias PeerId: string
+alias CID: string
+alias Path: string
+
+-- Download file from remote IPFS node to Fluence node and then 
+-- put that file to local IPFS node, effectively caching it on the local IPFS node.
+--
+-- Arguments:
+--  node - PeerId of the node where execution should happen
+--  cid – IPFS Content ID to download
+--  from - Multiaddress of IPFS node to download `cid` from
+--  error - callback to notify function caller about errors
+--
+-- Returns:
+--  Path on the node's local filesystem. It will be available only during single particle execution.
+--
+-- Errors:
+--  If Ipfs.get_from or Ipfs.put fails, nil is returned. 
+--  Errors are reported to the `error` callback.
+func get_and_cache(
+    node: PeerId,
+    cid: CID,
+    from: Multiaddr,
+    error: string, string -> ()
+) -> ?Path:
+    path: *Path
+    on node:
+        -- Download file from remote IPFS to local filesystem
+        get <- Ipfs.get_from(cid, from)
+        if get.success:
+            -- Put file to local IPFS node
+            put <- Ipfs.put(get.path)
+            if put.success:
+                path <- put.path
+            else:
+                -- report error in background co-routine
+                co error("Ipfs.put failed", put.error)
+        else:
+            -- report error in background co-routine
+            co error("Ipfs.get failed", get.error)
+    <- path
 
 -- Upload file `path` to IPFS node running on `node`
 -- path should exist & be available to `ipfs-adapter`
@@ -11,10 +51,10 @@ func put(node: PeerId, path: string) -> IpfsPutResult:
         result <- Ipfs.put(path)
     <- result
 
--- Download file `hash` from IPFS node `from` and save it to `node`
+-- Download file `cid` from IPFS node `from` and save it to `node`
-func get_from(node: PeerId, hash: string, from: Multiaddr) -> IpfsGetResult:
+func get_from(node: PeerId, cid: CID, from: Multiaddr) -> IpfsGetResult:
     on node:
-        result <- Ipfs.get_from(hash, from)
+        result <- Ipfs.get_from(cid, from)
     <- result
 
 -- Set timeout for IPFS calls in `ipfs-adapter`
@@ -22,14 +62,20 @@ func set_timeout(node: PeerId, timeout_sec: u64):
     on node:
         Ipfs.set_timeout(timeout_sec)
 
--- Get multiaddress of IPFS's HTTP RPC endpoint (usually on port 5001)
+-- Get externally available multiaddress of IPFS's HTTP RPC endpoint (usually on port 5001)
 func get_external_api_multiaddr(node: PeerId) -> IpfsMultiaddrResult:
     on node:
         result <- Ipfs.get_external_api_multiaddr()
     <- result
 
--- Get multiaddress of IPFS's Swarm endpoint (usually on port 4001)
+-- Get externally available multiaddress of IPFS's Swarm endpoint (usually on port 4001)
 func get_external_swarm_multiaddr(node: PeerId) -> IpfsMultiaddrResult:
     on node:
         result <- Ipfs.get_external_swarm_multiaddr()
     <- result
+
+-- Get local multiaddress of IPFS's HTTP RPC endpoint (usually on port 5001)
+func get_local_api_multiaddr(node: PeerId) -> IpfsMultiaddrResult:
+    on node:
+        result <- Ipfs.get_local_api_multiaddr()
+    <- result