Transport

Confidence Level:Draft/WIP

A transport is a mechanism for moving data over the wire with Data Transfer. Different transports provide different capabilities to data transfer. For example, some transports may have the ability to pause and resume requests, while others may not. Some may support incremental data events, while others may only support message events.

Dependencies

Name	Kind	APIs
Data Transfer	single	EventAPI

Roadmap

V0: Existing or 3 months

Currently, a single Transport interface is imported for Data Transfer: Graphsync. The interface does not look exactly like the API described below, and is somewhat Graphsync specific.

V0.5: 6 months

Team Ignite is implementing a second transport for data transfer as part of the F3 Project: STP, or simple transport protocol. To support both protocols, the Transport interface will need to be made fully protocol nuetral. The API below is a suggested revision to the interface.

Preliminary API

This is an extraction and revision of data transfer's Transport interface

package transport

import (
	"context"

	datatransfer "github.com/filecoin-project/retrieval-market-spec/docs/components/datatransfer"
	"github.com/ipld/go-ipld-prime"
	peer "github.com/libp2p/go-libp2p-peer"
)

// Capabilities describes what a transport can and cannot do
type Capabilities struct {
	DispatchesDataSentEvents     bool
	DispatchesDataQueuedEvents   bool
	DispatchesDataReceivedEvents bool
	DispatchesTimeoutsEvents     bool
	DispatchesDisconnectedEvents bool
	SupportsRestarts             bool
	SupportsPauseResume          bool
	Verifiable                   bool
	IncrementallyVerifiable      bool
}

type TransportAPI interface {
	Capabilities() Capabilities
	// OpenChannel initiates an outgoing request for the other peer to send data
	// to us on this channel
	OpenChannel(ctx context.Context,
		dataSender peer.ID,
		channelID datatransfer.ChannelID,
		root ipld.Link,
		stor ipld.Node,
		resumeState ipld.Node,
		msg datatransfer.Message) error
	// CloseChannel closes the given channel
	CloseChannel(ctx context.Context, chid datatransfer.ChannelID) error
	// CleanupChannel is called on the otherside of a cancel - removes any
	// associated
	// data for the channel
	CleanupChannel(chid datatransfer.ChannelID)
	PauseChannel(ctx context.Context,
		chid datatransfer.ChannelID,
	) error
	// ResumeChannel resumes the given channel
	ResumeChannel(ctx context.Context,
		msg datatransfer.Message,
		chid datatransfer.ChannelID,
	) error
	Shutdown(ctx context.Context) error
}