feat(datatransfer): add data transfer types

Add types and interfaces for data transfer

datatransfer/types.go

@@ -0,0 +1,139 @@
+package datatransfer
+
+import (
+	"reflect"
+
+	"github.com/ipfs/go-cid"
+	selector "github.com/ipld/go-ipld-prime/traversal/selector"
+	"github.com/libp2p/go-libp2p-core/peer"
+)
+
+// Voucher is used to validate
+// a data transfer request against the underlying storage or retrieval deal
+// that precipitated it. The only requirement is a voucher can read and write
+// from bytes
+type Voucher interface {
+	ToBytes() []byte
+	FromBytes([]byte) (Voucher, error)
+	Identifier() string
+}
+
+// Status is the status of transfer for a given channel
+type Status string
+
+const (
+	// Ongoing means the data transfer is in progress
+	Ongoing = Status("Ongoing")
+
+	// Completed means the data transfer is completed successfully
+	Completed = Status("Completed")
+
+	// Failed means the data transfer failed
+	Failed = Status("Failed")
+
+	// ChannelNotFoundError means the searched for data transfer does not exist
+	ChannelNotFoundError = Status("ChannelNotFoundError")
+)
+
+// TransferID is an identifier for a data transfer, shared between
+// request/responder and unique to the requestor
+type TransferID uint64
+
+// ChannelID is a unique identifier for a channel, distinct by both the other
+// party's peer ID + the transfer ID
+type ChannelID struct {
+	to peer.ID
+	id TransferID
+}
+
+// Channel represents all the parameters for a single data transfer
+type Channel struct {
+	// an identifier for this channel shared by request and responder, set by requestor through protocol
+	transferID TransferID
+	// base CID for the piece being transferred
+	PieceRef cid.Cid
+	// portion of Piece to return, spescified by an IPLD selector
+	Selector selector.Selector
+	// used to verify this channel
+	voucher Voucher
+	// the party that is sending the data (not who initiated the request)
+	sender peer.ID
+	// the party that is receiving the data (not who initiated the request)
+	recipient peer.ID
+	// expected amount of data to be transferred
+	totalSize uint64
+}
+
+// ChannelState is immutable channel data plus mutable state
+type ChannelState struct {
+	Channel
+	// total bytes sent from this node (0 if receiver)
+	sent uint64
+	// total bytes received by this node (0 if sender)
+	received uint64
+}
+
+// Event is a name for an event that occurs on a data transfer channel
+type Event string
+
+const (
+	// Open is an event occurs when a channel is first opened
+	Open = Event("Open")
+
+	// Progress is an event that gets emitted every time more data is transferred
+	Progress = Event("Progress")
+
+	// Error is an event that emits when an error occurs in a data transfer
+	Error = Event("Error")
+
+	// Complete is emitted when a data transfer is complete
+	Complete = Event("Complete")
+)
+
+// Subscriber is a callback that is called when events are emitted
+type Subscriber func(event Event, channelState ChannelState)
+
+// RequestValidator is an interface implemented by the client of the
+// data transfer module to validate requests
+type RequestValidator interface {
+	ValidatePush(
+		sender peer.ID,
+		voucher Voucher,
+		PieceRef cid.Cid,
+		Selector selector.Selector) error
+	ValidatePull(
+		receiver peer.ID,
+		voucher Voucher,
+		PieceRef cid.Cid,
+		Selector selector.Selector) error
+}
+
+// Manager is the core interface presented by all implementations of
+// of the data transfer sub system
+type Manager interface {
+	// RegisterVoucherType registers a validator for the given voucher type
+	// will error if voucher type does not implement voucher
+	// or if there is a voucher type registered with an identical identifier
+	RegisterVoucherType(voucherType reflect.Type, validator RequestValidator) error
+
+	// open a data transfer that will send data to the recipient peer and
+	// open a data transfer that will send data to the recipient peer and
+	// transfer parts of the piece that match the selector
+	OpenPushDataChannel(to peer.ID, voucher Voucher, PieceRef cid.Cid, Selector selector.Selector) ChannelID
+
+	// open a data transfer that will request data from the sending peer and
+	// transfer parts of the piece that match the selector
+	OpenPullDataChannel(to peer.ID, voucher Voucher, PieceRef cid.Cid, Selector selector.Selector) ChannelID
+
+	// close an open channel (effectively a cancel)
+	CloseDataTransferChannel(x ChannelID)
+
+	// get status of a transfer
+	TransferChannelStatus(x ChannelID) Status
+
+	// get notified when certain types of events happen
+	SubscribeToEvents(subscriber Subscriber)
+
+	// get all in progress transfers
+	InProgressChannels() map[ChannelID]ChannelState
+}

go.mod

@@ -28,6 +28,7 @@ require (
 	github.com/ipfs/go-fs-lock v0.0.1
 	github.com/ipfs/go-hamt-ipld v0.0.12-0.20190910032255-ee6e898f0456
 	github.com/ipfs/go-ipfs-blockstore v0.1.0
+	github.com/ipfs/go-ipfs-blocksutil v0.0.1
 	github.com/ipfs/go-ipfs-chunker v0.0.1
 	github.com/ipfs/go-ipfs-ds-help v0.0.1
 	github.com/ipfs/go-ipfs-exchange-interface v0.0.1
@@ -39,6 +40,7 @@ require (
 	github.com/ipfs/go-log v0.0.2-0.20190920042044-a609c1ae5144
 	github.com/ipfs/go-merkledag v0.2.3
 	github.com/ipfs/go-unixfs v0.2.2-0.20190827150610-868af2e9e5cb
+	github.com/ipld/go-ipld-prime v0.0.1
 	github.com/ipsn/go-secp256k1 v0.0.0-20180726113642-9d62b9f0bc52
 	github.com/libp2p/go-libp2p v0.3.0
 	github.com/libp2p/go-libp2p-circuit v0.1.1

go.sum

@@ -231,6 +231,8 @@ github.com/ipfs/go-unixfs v0.2.2-0.20190827150610-868af2e9e5cb h1:tmWYgjltxwM7PD
 github.com/ipfs/go-unixfs v0.2.2-0.20190827150610-868af2e9e5cb/go.mod h1:IwAAgul1UQIcNZzKPYZWOCijryFBeCV79cNubPzol+k=
 github.com/ipfs/go-verifcid v0.0.1 h1:m2HI7zIuR5TFyQ1b79Da5N9dnnCP1vcu2QqawmWlK2E=
 github.com/ipfs/go-verifcid v0.0.1/go.mod h1:5Hrva5KBeIog4A+UpqlaIU+DEstipcJYQQZc0g37pY0=
+github.com/ipld/go-ipld-prime v0.0.1 h1:ZTjkYODUmJAca7w5hfzP9emyJfUxTy/Xi4zsUoqHggQ=
+github.com/ipld/go-ipld-prime v0.0.1/go.mod h1:bDDSvVz7vaK12FNvMeRYnpRFkSUPNQOiCYQezMD/P3w=
 github.com/ipsn/go-secp256k1 v0.0.0-20180726113642-9d62b9f0bc52 h1:QG4CGBqCeuBo6aZlGAamSkxWdgWfZGeE49eUOWJPA4c=
 github.com/ipsn/go-secp256k1 v0.0.0-20180726113642-9d62b9f0bc52/go.mod h1:fdg+/X9Gg4AsAIzWpEHwnqd+QY3b7lajxyjE1m4hkq4=
 github.com/jackpal/gateway v1.0.5 h1:qzXWUJfuMdlLMtt0a3Dgt+xkWQiA5itDEITVJtuSwMc=