From e1be257b289e674fa4659fb0566aaa009834fec5 Mon Sep 17 00:00:00 2001 From: hannahhoward Date: Fri, 25 Oct 2019 18:36:49 -0700 Subject: [PATCH] feat(datatransfer): add data transfer types Add types and interfaces for data transfer --- datatransfer/types.go | 139 ++++++++++++++++++++++++++++++++++++++++++ go.mod | 2 + go.sum | 2 + 3 files changed, 143 insertions(+) create mode 100644 datatransfer/types.go diff --git a/datatransfer/types.go b/datatransfer/types.go new file mode 100644 index 000000000..c05c6009d --- /dev/null +++ b/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 +} diff --git a/go.mod b/go.mod index 5197ee9df..5af683824 100644 --- a/go.mod +++ b/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 diff --git a/go.sum b/go.sum index e6ae50214..0760df709 100644 --- a/go.sum +++ b/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=