feat: use error channels

block.go

@@ -2,10 +2,10 @@ package iface
 
 import (
 	"context"
-	path "github.com/ipfs/interface-go-ipfs-core/path"
 	"io"
 
 	"github.com/ipfs/interface-go-ipfs-core/options"
+	path "github.com/ipfs/interface-go-ipfs-core/path"
 )
 
 // BlockStat contains information about a block

dht.go

@@ -19,6 +19,9 @@ type DhtAPI interface {
 
 	// FindProviders finds peers in the DHT who can provide a specific value
 	// given a key.
+	//
+	// The returned channel will be closed when the request completes or is
+	// canceled.
 	FindProviders(context.Context, path.Path, ...options.DhtFindProvidersOption) (<-chan peer.AddrInfo, error)
 
 	// Provide announces to the network that you are providing given values

name.go

@@ -18,11 +18,6 @@ type IpnsEntry interface {
 	Value() path.Path
 }
 
-type IpnsResult struct {
-	path.Path
-	Err error
-}
-
 // NameAPI specifies the interface to IPNS.
 //
 // IPNS is a PKI namespace, where names are the hashes of public keys, and the
@@ -43,5 +38,9 @@ type NameAPI interface {
 	//
 	// Note: by default, all paths read from the channel are considered unsafe,
 	// except the latest (last path in channel read buffer).
-	Search(ctx context.Context, name string, opts ...options.NameResolveOption) (<-chan IpnsResult, error)
+	//
+	// Both returned channels will be closed when the request completes or is
+	// canceled. The error channel will yield at most one error and should
+	// be read after the path channel is closed.
+	Search(ctx context.Context, name string, opts ...options.NameResolveOption) (<-chan path.Path, <-chan error)
 }

name_test.go

@@ -0,0 +1,20 @@
+package iface
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/ipfs/interface-go-ipfs-core/path"
+)
+
+func ExampleNameAPI_Search() {
+	var api CoreAPI
+
+	_ = func(ctx context.Context) (result path.Path, err error) {
+		results, errC := api.Name().Search(ctx, "foobar")
+		for result = range results {
+			fmt.Println(result)
+		}
+		return result, <-errC
+	}
+}

pin.go

@@ -14,9 +14,6 @@ type Pin interface {
 
 	// Type of the pin
 	Type() string
-
-	// if not nil, an error happened. Everything else should be ignored.
-	Err() error
 }
 
 // PinStatus holds information about pin health
@@ -43,8 +40,12 @@ type PinAPI interface {
 	// tree
 	Add(context.Context, path.Path, ...options.PinAddOption) error
 
-	// Ls returns list of pinned objects on this node
-	Ls(context.Context, ...options.PinLsOption) (<-chan Pin, error)
+	// Ls returns list of pinned objects on this node.
+	//
+	// Both returned channels will be closed when the request completes or is
+	// canceled. The error channel will yield at most one error and should
+	// be read after the path channel is closed.
+	Ls(context.Context, ...options.PinLsOption) (<-chan Pin, <-chan error)
 
 	// IsPinned returns whether or not the given cid is pinned
 	// and an explanation of why its pinned
@@ -57,6 +58,14 @@ type PinAPI interface {
 	// the old tree
 	Update(ctx context.Context, from path.Path, to path.Path, opts ...options.PinUpdateOption) error
 
-	// Verify verifies the integrity of pinned objects
-	Verify(context.Context) (<-chan PinStatus, error)
+	// Verify verifies the integrity of pinned objects.
+	//
+	// Both returned channels will be closed when the request completes or is
+	// canceled. The error channel will yield at most one error and should
+	// be read after the path channel is closed.
+	//
+	// The error channel will only yield an error if the verification
+	// process itself fails or is canceled. It will not yield an error when
+	// we fail to verify a pin.
+	Verify(context.Context) (<-chan PinStatus, <-chan error)
 }

pin_test.go

@@ -0,0 +1,40 @@
+package iface
+
+import (
+	"context"
+	"fmt"
+)
+
+func ExamplePinAPI_Ls() {
+	var api CoreAPI
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	pins, errC := api.Pin().Ls(ctx)
+	for pin := range pins {
+		fmt.Println(pin.Path())
+	}
+	if err := <-errC; err != nil {
+		fmt.Printf("error: %s\n", err)
+	}
+}
+
+func ExamplePinAPI_Verify() {
+	var api CoreAPI
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	status, errC := api.Pin().Verify(ctx)
+	for pin := range status {
+		if !pin.Ok() {
+			for _, missing := range pin.BadNodes() {
+				fmt.Printf("missing node %s: %s\n", missing.Path().Cid(), missing.Err())
+			}
+		}
+	}
+	if err := <-errC; err != nil {
+		fmt.Printf("failed to complete pin verification request: %s\n", err)
+	}
+}

tests/pin.go

@@ -192,17 +192,17 @@ func (tp *TestSuite) TestPinRecursive(t *testing.T) {
 		t.Errorf("unexpected path, %s != %s", list[0].Path().Cid().String(), p0.Cid().String())
 	}
 
-	res, err := api.Pin().Verify(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
+	res, errCh := api.Pin().Verify(ctx)
 	n := 0
 	for r := range res {
 		if !r.Ok() {
 			t.Error("expected pin to be ok")
 		}
 		n++
 	}
+	if err := <-errCh; err != nil {
+		t.Fatal(err)
+	}
 
 	if n != 1 {
 		t.Errorf("unexpected verify result count: %d", n)
@@ -583,19 +583,10 @@ func assertNotPinned(t *testing.T, ctx context.Context, api iface.CoreAPI, p pat
 	}
 }
 
-func accPins(pins <-chan iface.Pin, err error) ([]iface.Pin, error) {
-	if err != nil {
-		return nil, err
-	}
-
+func accPins(pins <-chan iface.Pin, err <-chan error) ([]iface.Pin, error) {
 	var result []iface.Pin
-
 	for pin := range pins {
-		if pin.Err() != nil {
-			return nil, pin.Err()
-		}
 		result = append(result, pin)
 	}
-
-	return result, nil
+	return result, <-err
 }

tests/unixfs.go

@@ -681,15 +681,9 @@ func (tp *TestSuite) TestLs(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	entries, err := api.Unixfs().Ls(ctx, p)
-	if err != nil {
-		t.Fatal(err)
-	}
+	entries, errCh := api.Unixfs().Ls(ctx, p)
 
 	entry := <-entries
-	if entry.Err != nil {
-		t.Fatal(entry.Err)
-	}
 	if entry.Size != 15 {
 		t.Errorf("expected size = 15, got %d", entry.Size)
 	}
@@ -703,9 +697,6 @@ func (tp *TestSuite) TestLs(t *testing.T) {
 		t.Errorf("expected cid = QmX3qQVKxDGz3URVC3861Z3CKtQKGBn6ffXRBBWGMFz9Lr, got %s", entry.Cid)
 	}
 	entry = <-entries
-	if entry.Err != nil {
-		t.Fatal(entry.Err)
-	}
 	if entry.Type != coreiface.TSymlink {
 		t.Errorf("wrong type %s", entry.Type)
 	}
@@ -716,11 +707,11 @@ func (tp *TestSuite) TestLs(t *testing.T) {
 		t.Errorf("expected symlink target to be /foo/bar, got %s", entry.Target)
 	}
 
-	if l, ok := <-entries; ok {
+	if _, ok := <-entries; ok {
 		t.Errorf("didn't expect a second link")
-		if l.Err != nil {
-			t.Error(l.Err)
-		}
+	}
+	if err := <-errCh; err != nil {
+		t.Error(err)
 	}
 }
 
@@ -784,14 +775,20 @@ func (tp *TestSuite) TestLsEmptyDir(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	links, err := api.Unixfs().Ls(ctx, path.IpfsPath(emptyDir.Cid()))
-	if err != nil {
-		t.Fatal(err)
+	links, errCh := api.Unixfs().Ls(ctx, path.IpfsPath(emptyDir.Cid()))
+	count := 0
+	for range links {
+		count++
 	}
 
-	if len(links) != 0 {
+	if count != 0 {
 		t.Fatalf("expected 0 links, got %d", len(links))
 	}
+
+	err = <-errCh
+	if err != nil {
+		t.Fatal(err)
+	}
 }
 
 // TODO(lgierth) this should test properly, with len(links) > 0
@@ -813,14 +810,21 @@ func (tp *TestSuite) TestLsNonUnixfs(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	links, err := api.Unixfs().Ls(ctx, path.IpfsPath(nd.Cid()))
-	if err != nil {
-		t.Fatal(err)
+	links, errCh := api.Unixfs().Ls(ctx, path.IpfsPath(nd.Cid()))
+
+	count := 0
+	for range links {
+		count++
 	}
 
-	if len(links) != 0 {
+	if count != 0 {
 		t.Fatalf("expected 0 links, got %d", len(links))
 	}
+
+	err = <-errCh
+	if err != nil {
+		t.Fatal(err)
+	}
 }
 
 type closeTestF struct {

unixfs.go

@@ -55,8 +55,6 @@ type DirEntry struct {
 	Size   uint64   // The size of the file in bytes (or the size of the symlink).
 	Type   FileType // The type of the file.
 	Target string   // The symlink target (if a symlink).
-
-	Err error
 }
 
 // UnixfsAPI is the basic interface to immutable files in IPFS
@@ -75,5 +73,5 @@ type UnixfsAPI interface {
 
 	// Ls returns the list of links in a directory. Links aren't guaranteed to be
 	// returned in order
-	Ls(context.Context, path.Path, ...options.UnixfsLsOption) (<-chan DirEntry, error)
+	Ls(context.Context, path.Path, ...options.UnixfsLsOption) (<-chan DirEntry, <-chan error)
 }