datatransfer

Documentation

Index

• type Channel
  • func (c Channel) BaseCID() cid.Cid
  • func (c Channel) Recipient() peer.ID
  • func (c Channel) Selector() ipld.Node
  • func (c Channel) Sender() peer.ID
  • func (c Channel) TotalSize() uint64
  • func (c Channel) TransferID() TransferID
  • func (c Channel) Voucher() Voucher
• type ChannelID
• type ChannelState
  • func (c ChannelState) Received() uint64
  • func (c ChannelState) Sent() uint64
• type Event
• type Manager
  • func NewDAGServiceDataTransfer(dag ipldformat.DAGService) Manager
• type RequestValidator
• type Status
• type Subscriber
• type TransferID
• type Voucher

Types

type Channel

type Channel struct {
	// contains filtered or unexported fields
}

Channel represents all the parameters for a single data transfer

func (Channel) BaseCID

func (c Channel) BaseCID() cid.Cid

BaseCID returns the CID that is at the root of this data transfer

func (Channel) Recipient

func (c Channel) Recipient() peer.ID

Recipient returns the peer id for the node that is receiving data

func (Channel) Selector

func (c Channel) Selector() ipld.Node

Selector returns the IPLD selector for this data transfer (represented as an IPLD node)

func (Channel) Sender

func (c Channel) Sender() peer.ID

Sender returns the peer id for the node that is sending data

func (Channel) TotalSize

func (c Channel) TotalSize() uint64

TotalSize returns the total size for the data being transferred

func (Channel) TransferID

func (c Channel) TransferID() TransferID

TransferID returns the transfer id for this channel

func (Channel) Voucher

func (c Channel) Voucher() Voucher

Voucher returns the voucher for this data transfer

type ChannelID

type ChannelID struct {
	// contains filtered or unexported fields
}

ChannelID is a unique identifier for a channel, distinct by both the other party's peer ID + the transfer ID

type ChannelState

type ChannelState struct {
	Channel
	// contains filtered or unexported fields
}

ChannelState is immutable channel data plus mutable state

func (ChannelState) Received

func (c ChannelState) Received() uint64

Received returns the number of bytes received

func (ChannelState) Sent

func (c ChannelState) Sent() uint64

Sent returns the number of bytes sent

type Event

type Event int

Event is a name for an event that occurs on a data transfer channel

const (
	// Open is an event occurs when a channel is first opened
	Open Event = iota

	// Progress is an event that gets emitted every time more data is transferred
	Progress

	// Error is an event that emits when an error occurs in a data transfer
	Error

	// Complete is emitted when a data transfer is complete
	Complete
)

type Manager

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(ctx context.Context, to peer.ID, voucher Voucher, baseCid cid.Cid, selector ipld.Node) (ChannelID, error)

	// open a data transfer that will request data from the sending peer and
	// transfer parts of the piece that match the selector
	OpenPullDataChannel(ctx context.Context, to peer.ID, voucher Voucher, baseCid cid.Cid, selector ipld.Node) (ChannelID, error)

	// 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
}

Manager is the core interface presented by all implementations of of the data transfer sub system

func NewDAGServiceDataTransfer

func NewDAGServiceDataTransfer(dag ipldformat.DAGService) Manager

NewDAGServiceDataTransfer returns a data transfer manager based on an IPLD DAGService

type RequestValidator

type RequestValidator interface {
	// ValidatePush validates a push request received from the peer that will send data
	ValidatePush(
		sender peer.ID,
		voucher Voucher,
		baseCid cid.Cid,
		selector ipld.Node) error
	// ValidatePull validates a pull request received from the peer that will receive data
	ValidatePull(
		receiver peer.ID,
		voucher Voucher,
		baseCid cid.Cid,
		selector ipld.Node) error
}

RequestValidator is an interface implemented by the client of the data transfer module to validate requests

type Status

type Status int

Status is the status of transfer for a given channel

const (
	// Ongoing means the data transfer is in progress
	Ongoing Status = iota

	// Completed means the data transfer is completed successfully
	Completed

	// Failed means the data transfer failed
	Failed

	// ChannelNotFoundError means the searched for data transfer does not exist
	ChannelNotFoundError
)

type Subscriber

type Subscriber func(event Event, channelState ChannelState)

Subscriber is a callback that is called when events are emitted

type TransferID

type TransferID uint64

TransferID is an identifier for a data transfer, shared between request/responder and unique to the requester

type Voucher

type Voucher interface {
	// ToBytes converts the Voucher to raw bytes
	ToBytes() ([]byte, error)
	// FromBytes reads a Voucher from raw bytes
	FromBytes([]byte) error
	// Identifier is a unique string identifier for this voucher type
	Identifier() string
}

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, and has a string identifier type