fileTransfer

package
v4.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2023 License: BSD-2-Clause, BSD-2-Clause Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// FileNameMaxLen is the maximum size, in bytes, for a file name. Currently,
	// it is set to 48 bytes.
	FileNameMaxLen = 48

	// FileTypeMaxLen is the maximum size, in bytes, for a file type. Currently,
	// it is set to 8 bytes.
	FileTypeMaxLen = 8

	// FileMaxSize is the maximum file size that can be transferred. Currently,
	// it is set to 250 kB.
	FileMaxSize = 250_000

	// PreviewMaxSize is the maximum size, in bytes, for a file preview.
	// Currently, it is set to 4 kB.
	PreviewMaxSize = 4_000
)

Variables

View Source 
var File_ftMessages_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type Cmix 

type Cmix interface {
	GetMaxMessageLength() int
	SendMany(messages []cmix.TargetedCmixMessage,
		p cmix.CMIXParams) (rounds.Round, []ephemeral.Id, error)
	AddFingerprint(identity *id.ID, fingerprint format.Fingerprint,
		mp message.Processor) error
	DeleteFingerprint(identity *id.ID, fingerprint format.Fingerprint)
	CheckInProgressMessages()
	IsHealthy() bool
	AddHealthCallback(f func(bool)) uint64
	RemoveHealthCallback(uint64)
	GetRoundResults(timeout time.Duration,
		roundCallback cmix.RoundEventCallback, roundList ...id.Round)
}

Cmix interface matches a subset of the cmix.Client methods used by the file transfer manager for easier testing.

type DelayedTimer 

type DelayedTimer struct {
	C *<-chan time.Time
	// contains filtered or unexported fields
}

The DelayedTimer type represents a single event manually started. When the DelayedTimer expires, the current time will be sent on C. A DelayedTimer must be created with NewDelayedTimer.

func NewDelayedTimer 

func NewDelayedTimer(d time.Duration) *DelayedTimer

NewDelayedTimer creates a new DelayedTimer that will send the current time on its channel after at least duration d once it is started.

func (*DelayedTimer) Start 

func (dt *DelayedTimer) Start()

Start starts the timer that will send the current time on its channel after at least duration d. If it is already running or stopped, it does nothing.

func (*DelayedTimer) Stop 

func (dt *DelayedTimer) Stop() bool

Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the timer has already expired, been stopped, or was never started.

type FilePartTracker 

type FilePartTracker interface {
	// GetPartStatus returns the status of the file part with the given part
	// number. The possible values for the status are:
	// 0 < Part does not exist
	// 0 = unsent
	// 1 = arrived (sender has sent a part, and it has arrived)
	// 2 = received (receiver has received a part)
	GetPartStatus(partNum uint16) FpStatus

	// GetNumParts returns the total number of file parts in the transfer.
	GetNumParts() uint16
}

FilePartTracker tracks the status of each file part in a sent or received file transfer.

type FileTransfer 

type FileTransfer interface {

	// StartProcesses starts the sending threads that wait for file transfers to
	// send. Adheres to the xxdk.Service type.
	StartProcesses() (stoppable.Stoppable, error)

	// MaxFileNameLen returns the max number of bytes allowed for a file name.
	MaxFileNameLen() int

	// MaxFileTypeLen returns the max number of bytes allowed for a file type.
	MaxFileTypeLen() int

	// MaxFileSize returns the max number of bytes allowed for a file.
	MaxFileSize() int

	// MaxPreviewSize returns the max number of bytes allowed for a file
	// preview.
	MaxPreviewSize() int

	// Send initiates the sending of a file to the recipient and returns a
	// transfer ID that uniquely identifies this file transfer.
	//
	// In-progress transfers are restored when closing and reopening; however, a
	// SentProgressCallback must be registered again.
	//
	// Parameters:
	//  - recipient - ID of the receiver of the file transfer. The sender must
	//    have an E2E relationship with the recipient.
	//  - fileName - Human-readable file name. Max length defined by
	//    MaxFileNameLen.
	//  - fileType - Shorthand that identifies the type of file. Max length
	//    defined by MaxFileTypeLen.
	//  - fileData - File contents. Max size defined by MaxFileSize.
	//  - retry - The number of sending retries allowed on send failure (e.g.
	//    a retry of 2.0 with 6 parts means 12 total possible sends).
	//  - preview - A preview of the file data (e.g. a thumbnail). Max size
	//    defined by MaxPreviewSize.
	//  - progressCB - A callback that reports the progress of the file
	//    transfer. The callback is called once on initialization, on every
	//    progress update (or less if restricted by the period), or on fatal
	//    error.
	//  - period - The progress callback will be limited from triggering only
	//    once per period.
	//  - sendNew - Function that sends the file transfer information to the
	//    recipient.
	Send(recipient *id.ID, fileName, fileType string, fileData []byte,
		retry float32, preview []byte, progressCB SentProgressCallback,
		period time.Duration, sendNew SendNew) (*ftCrypto.TransferID, error)

	// RegisterSentProgressCallback allows for the registration of a callback to
	// track the progress of an individual sent file transfer.
	//
	// The callback will be called immediately when added to report the current
	// progress of the transfer. It will then call every time a file part
	// arrives, the transfer completes, or a fatal error occurs. It is called at
	// most once every period regardless of the number of progress updates.
	//
	// In the event that the client is closed and resumed, this function must be
	// used to re-register any callbacks previously registered with this
	// function or Send.
	RegisterSentProgressCallback(tid *ftCrypto.TransferID,
		progressCB SentProgressCallback, period time.Duration) error

	// CloseSend deletes a file from the internal storage once a transfer has
	// completed or reached the retry limit. If neither of those condition are
	// met, an error is returned.
	//
	// This function should be called once a transfer completes or errors out
	// (as reported by the progress callback).
	CloseSend(tid *ftCrypto.TransferID) error

	// HandleIncomingTransfer starts tracking the received file parts for the
	// given payload that contains the file transfer information and returns a
	// transfer ID that uniquely identifies this file transfer along with the
	// transfer information
	//
	// This function should be called once for every new file received on the
	// registered SendNew callback.
	//
	// In-progress transfers are restored when closing and reopening; however, a
	// ReceivedProgressCallback must be registered again.
	//
	//   payload - A marshalled payload container the file transfer information.
	//   progressCB - A callback that reports the progress of the file transfer.
	//      The callback is called once on initialization, on every progress
	//      update (or less if restricted by the period), or on fatal error.
	//   period - A progress callback will be limited from triggering only once
	//      per period.
	HandleIncomingTransfer(transferInfo []byte,
		progressCB ReceivedProgressCallback, period time.Duration) (
		*ftCrypto.TransferID, *TransferInfo, error)

	// RegisterReceivedProgressCallback allows for the registration of a
	// callback to track the progress of an individual received file transfer.
	//
	// The callback will be called immediately when added to report the current
	// progress of the transfer. It will then call every time a file part is
	// received, the transfer completes, or a fatal error occurs. It is called
	// at most once every period regardless of the number of progress updates.
	//
	// In the event that the client is closed and resumed, this function must be
	// used to re-register any callbacks previously registered.
	//
	// Once the callback reports that the transfer has completed, the recipient
	// can get the full file by calling Receive.
	RegisterReceivedProgressCallback(tid *ftCrypto.TransferID,
		progressCB ReceivedProgressCallback, period time.Duration) error

	// Receive returns the full file on the completion of the transfer. It
	// deletes internal references to the data and unregisters any attached
	// progress callback. Returns an error if the transfer is not complete, the
	// full file cannot be verified, or if the transfer cannot be found.
	//
	// Receive can only be called once the progress callback returns that the
	// file transfer is complete.
	Receive(tid *ftCrypto.TransferID) ([]byte, error)
}

FileTransfer facilities the sending and receiving of large file transfers. It allows for progress tracking of both inbound and outbound transfers. FileTransfer handles the sending of the file data; however, the caller is responsible for communicating to the recipient of the incoming file transfer.

func NewManager 

func NewManager(params Params, user FtE2e) (FileTransfer, error)

NewManager creates a new file transfer manager object. If sent or received transfers already existed, they are loaded from storage and queued to resume once manager.startProcesses is called.

type FpStatus 

type FpStatus int

FpStatus is the file part status and indicates the status of individual file parts in a file transfer. 

const (
	// FpUnsent indicates that the file part has not been sent
	FpUnsent FpStatus = iota

	// FpSent indicates that the file part has been sent (sender has sent a
	// part, but it has not arrived)
	FpSent

	// FpArrived indicates that the file part has arrived (sender has sent a
	// part, and it has arrived)
	FpArrived

	// FpReceived indicates that the file part has been received (receiver has
	// received a part)
	FpReceived
)

Possible values for FpStatus.

func (FpStatus) String 

func (fps FpStatus) String() string

String returns the string representing of the FpStatus. This functions satisfies the fmt.Stringer interface.

type FtE2e 

type FtE2e interface {
	GetStorage() storage.Session
	GetReceptionIdentity() xxdk.ReceptionIdentity
	GetCmix() cmix.Client
	GetRng() *fastRNG.StreamGenerator
	GetE2E() e2e.Handler
}

FtE2e interface matches a subset of the xxdk.E2e methods used by the file transfer manager for easier testing.

type NewFileTransfer 

type NewFileTransfer struct {
	FileName    string  `protobuf:"bytes,1,opt,name=fileName,proto3" json:"fileName,omitempty"`       // Name of the file
	FileType    string  `protobuf:"bytes,2,opt,name=fileType,proto3" json:"fileType,omitempty"`       // String that indicates type of file
	TransferKey []byte  `protobuf:"bytes,3,opt,name=transferKey,proto3" json:"transferKey,omitempty"` // 256-bit encryption key
	TransferMac []byte  `protobuf:"bytes,4,opt,name=transferMac,proto3" json:"transferMac,omitempty"` // 256-bit MAC of the entire file
	NumParts    uint32  `protobuf:"varint,5,opt,name=numParts,proto3" json:"numParts,omitempty"`      // Number of file parts
	Size        uint32  `protobuf:"varint,6,opt,name=size,proto3" json:"size,omitempty"`              // The size of the file, in bytes
	Retry       float32 `protobuf:"fixed32,7,opt,name=retry,proto3" json:"retry,omitempty"`           // Determines how many times to retry sending
	Preview     []byte  `protobuf:"bytes,8,opt,name=preview,proto3" json:"preview,omitempty"`         // A preview of the file
	// contains filtered or unexported fields
}

NewFileTransfer is transmitted first on the initialization of a file transfer to inform the receiver about the incoming file.

func (*NewFileTransfer) Descriptor deprecated 

func (*NewFileTransfer) Descriptor() ([]byte, []int)

Deprecated: Use NewFileTransfer.ProtoReflect.Descriptor instead.

func (*NewFileTransfer) GetFileName 

func (x *NewFileTransfer) GetFileName() string

func (*NewFileTransfer) GetFileType 

func (x *NewFileTransfer) GetFileType() string

func (*NewFileTransfer) GetNumParts 

func (x *NewFileTransfer) GetNumParts() uint32

func (*NewFileTransfer) GetPreview 

func (x *NewFileTransfer) GetPreview() []byte

func (*NewFileTransfer) GetRetry 

func (x *NewFileTransfer) GetRetry() float32

func (*NewFileTransfer) GetSize 

func (x *NewFileTransfer) GetSize() uint32

func (*NewFileTransfer) GetTransferKey 

func (x *NewFileTransfer) GetTransferKey() []byte

func (*NewFileTransfer) GetTransferMac 

func (x *NewFileTransfer) GetTransferMac() []byte

func (*NewFileTransfer) ProtoMessage 

func (*NewFileTransfer) ProtoMessage()

func (*NewFileTransfer) ProtoReflect 

func (x *NewFileTransfer) ProtoReflect() protoreflect.Message

func (*NewFileTransfer) Reset 

func (x *NewFileTransfer) Reset()

func (*NewFileTransfer) String 

func (x *NewFileTransfer) String() string

type Params 

type Params struct {
	// MaxThroughput is the maximum data transfer speed to send file parts (in
	// bytes per second). If set to 0, rate limiting will be disabled.
	MaxThroughput int

	// SendTimeout is the duration, in nanoseconds, before sending on a round
	// times out. It is recommended that SendTimeout is not changed from its
	// default.
	SendTimeout time.Duration

	// Cmix are the parameters used when sending a cMix message.
	Cmix cmix.CMIXParams
}

Params contains parameters used for file transfer.

func DefaultParams 

func DefaultParams() Params

DefaultParams returns a Params object filled with the default values.

func GetParameters 

func GetParameters(params string) (Params, error)

GetParameters returns the default network parameters, or override with given parameters, if set. Returns an error if provided invalid JSON. If the JSON is valid but does not match the Params structure, the default parameters will be returned.

type ReceiveCallback 

type ReceiveCallback func(tid *ftCrypto.TransferID, fileName, fileType string,
	sender *id.ID, size uint32, preview []byte)

ReceiveCallback is a callback function that notifies the receiver of an incoming file transfer.

type ReceivedProgressCallback 

type ReceivedProgressCallback func(completed bool, received, total uint16,
	rt ReceivedTransfer, t FilePartTracker, err error)

ReceivedProgressCallback is a callback function that tracks the progress of receiving a file.

type ReceivedTransfer 

type ReceivedTransfer interface {
	Transfer
}

ReceivedTransfer tracks the information and individual parts of a received file transfer.

type SendNew 

type SendNew func(transferInfo []byte) error

SendNew handles the sending of the initial message informing the recipient of the incoming file transfer parts. SendNew should block until the send completes and return an error only on failed sends.

type SentProgressCallback 

type SentProgressCallback func(completed bool, arrived, total uint16,
	st SentTransfer, t FilePartTracker, err error)

SentProgressCallback is a callback function that tracks the progress of sending a file.

type SentTransfer 

type SentTransfer interface {
	Recipient() *id.ID
	Transfer
}

SentTransfer tracks the information and individual parts of a sent file transfer.

type Storage 

type Storage interface {
	GetKV() versioned.KV
	GetCmixGroup() *cyclic.Group
}

Storage interface matches a subset of the storage.Session methods used by the manager for easier testing.

type Transfer 

type Transfer interface {
	TransferID() *ftCrypto.TransferID
	FileName() string
	FileSize() uint32
	NumParts() uint16
}

Transfer is the generic structure for a file transfer.

type TransferInfo 

type TransferInfo struct {
	FileName string               // Name of the file
	FileType string               // String that indicates type of file
	Key      ftCrypto.TransferKey // 256-bit encryption key
	Mac      []byte               // 256-bit MAC of the entire file
	NumParts uint16               // Number of file parts
	Size     uint32               // The size of the file, in bytes
	Retry    float32              // Determines how many times to retry sending
	Preview  []byte               // A preview of the file
}

TransferInfo contains all the information for a new transfer. This is the information sent in the initial file transfer so the recipient can prepare for the incoming file transfer parts.

func UnmarshalTransferInfo 

func UnmarshalTransferInfo(data []byte) (*TransferInfo, error)

UnmarshalTransferInfo deserializes the TransferInfo.

func (*TransferInfo) Marshal 

func (ti *TransferInfo) Marshal() ([]byte, error)

Marshal serialises the TransferInfo for sending over the network.

Source Files

View all Source files

Directories

Path Synopsis
cypher
fileMessage

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.