channelsFileTransfer

package
v4.7.4 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2024 License: BSD-2-Clause, BSD-2-Clause Imports: 39 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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)
	AddIdentity(id *id.ID, validUntil time.Time, persistent bool,
		fallthroughProcessor message.Processor)
	RemoveIdentity(id *id.ID)
	AddFingerprint(identity *id.ID, fingerprint format.Fingerprint,
		mp message.Processor) error
	DeleteFingerprint(identity *id.ID, fingerprint format.Fingerprint)
	DeleteClientFingerprints(identity *id.ID)
	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 EventModel 

type EventModel interface {
	// ReceiveFile is called when a file upload or download beings.
	//
	// fileLink and fileData are nillable and may be updated based upon the UUID
	// or file ID later.
	//
	// fileID is always unique to the fileData. fileLink is the JSON of
	// FileLink.
	//
	// Returns any fatal errors.
	ReceiveFile(fileID ftCrypto.ID, fileLink, fileData []byte,
		timestamp time.Time, status Status) error

	// UpdateFile is called when a file upload or download completes or changes.
	//
	// fileLink, fileData, timestamp, and status are all nillable and may be
	// updated based upon the file ID at a later date. If a nil value is passed,
	// then make no update.
	//
	// Returns an error if the file cannot be updated. It must return
	// channels.NoMessageErr if the file does not exist.
	UpdateFile(fileID ftCrypto.ID, fileLink, fileData []byte,
		timestamp *time.Time, status *Status) error

	// GetFile returns the ModelFile containing the file data and download link
	// for the given file ID.
	//
	// Returns an error if the file cannot be retrieved. It must return
	// channels.NoMessageErr if the file does not exist.
	GetFile(fileID ftCrypto.ID) (ModelFile, error)

	// DeleteFile deletes the file with the given file ID.
	//
	// Returns fatal errors. It must return channels.NoMessageErr if the file
	// does not exist.
	DeleteFile(fileID ftCrypto.ID) error

	channels.EventModel
}

EventModel is an interface that allows the user to get channels messages and file transfers.

type FileInfo 

type FileInfo struct {
	// Name is the name of the file.
	Name string `json:"name"`

	// Type indicates what type of file is being transferred.
	Type string `json:"type"`

	// Preview contains a preview of the file.
	Preview []byte `json:"preview"`

	FileLink
}

FileInfo 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. 

type FileLink struct {
	// FileID is the file's ID.
	FileID ftCrypto.ID `json:"fileID"`

	// RecipientID is the ID to listen on to receive file.
	RecipientID *id.ID `json:"recipientID"`

	// SentTimestamp is the time when the file was first queued to send.
	SentTimestamp time.Time `json:"sentTimestamp"`

	// Key is the 256-bit encryption key.
	Key ftCrypto.TransferKey `json:"key"`

	// Mac is the transfer MAC (Message Authentication Code) for this file.
	Mac []byte `json:"mac"`

	// Size is the file size in bytes.
	Size uint32 `json:"size"`

	// NumParts is the number of file parts being transferred.
	NumParts uint16 `json:"numParts"`

	// Retry determines number of resends allowed on failure.
	Retry float32 `json:"retry"`
}

FileLink contains all the information required to download and decrypt a file.

func (*FileLink) Expired 

func (fl *FileLink) Expired() bool

Expired returns true if the file link is expired. A file link is expired when the sent timestamp (time that the first file part was sent) is greater than the max message life, meaning some or all the file parts no longer exist on the network for download.

func (*FileLink) GetFileID 

func (fl *FileLink) GetFileID() ftCrypto.ID

GetFileID returns the file's ID.

func (*FileLink) GetFileSize 

func (fl *FileLink) GetFileSize() uint32

GetFileSize returns the size of the entire file.

func (*FileLink) GetNumParts 

func (fl *FileLink) GetNumParts() uint16

GetNumParts returns the total number of file parts in the transfer.

func (*FileLink) GetRecipient 

func (fl *FileLink) GetRecipient() *id.ID

GetRecipient returns the recipient ID to download the file from.

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

	// Upload starts uploading the file to a new ID that can be sent to the
	// specified channel when complete. To get progress information about the
	// upload, a SentProgressCallback must be registered. All errors returned on
	// the callback are fatal and the user must take action to either
	// RetryUpload or CloseSend.
	//
	// The file is added to the event model at the returned file ID with the
	// status Uploading. Once the upload is complete, the file link is added to
	// the event model with the status Complete.
	//
	// The SentProgressCallback only indicates the progress of the file upload,
	// not the status of the file in the event model. You must rely on updates
	// from the event model to know when it can be retrieved.
	//
	// Parameters:
	//   - 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).
	//   - progressCB - A callback that reports the progress of the file upload.
	//     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.
	//
	// Returns:
	//   - A file ID that uniquely identifies this file.
	Upload(fileData []byte, retry float32, progressCB SentProgressCallback,
		period time.Duration) (ftCrypto.ID, error)

	// Send sends the specified file info to the channel. Once a file is
	// uploaded via Upload, its file link (found in the event model) can be sent
	// to any channel.
	//
	// Parameters:
	//   - channelID - The ID of the channel to send the file to.
	//   - fileLink - JSON of FileLink stored in the event model.
	//   - fileName - Human-readable file name. Max length defined by
	//     MaxFileNameLen.
	//   - fileType - Shorthand that identifies the type of file. Max length
	//     defined by MaxFileTypeLen.
	//   - preview - A preview of the file data (e.g. a thumbnail). Max size
	//     defined by MaxPreviewSize.
	//   - validUntil - The duration that the file is available in the channel.
	//     For the maximum amount of time, use channels.ValidForever.
	//   - params - The xxdk.CMIXParams to send this.
	//   - pings - A list of Ed25519 public keys that will receive notifications
	//     for this message. They must be in the channel and have notifications
	//     enabled.
	Send(channelID *id.ID, fileLink []byte, fileName, fileType string,
		preview []byte, validUntil time.Duration, params xxdk.CMIXParams,
		pings []ed25519.PublicKey) (message.ID, rounds.Round, ephemeral.Id, error)

	// RegisterSentProgressCallback allows for the registration of a callback to
	// track the progress of an individual file upload. A SentProgressCallback
	// is auto-registered on Send; this function should be called when resuming
	// clients or registering extra callbacks.
	//
	// 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.
	//
	// The SentProgressCallback only indicates the progress of the file upload,
	// not the status of the file in the event model. You must rely on updates
	// from the event model to know when it can be retrieved.
	//
	// Parameters:
	//   - fileID - The unique ID of the file.
	//   - progressCB - A callback that reports the progress of the file upload.
	//     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.
	RegisterSentProgressCallback(fileID ftCrypto.ID,
		progressCB SentProgressCallback, period time.Duration) error

	// RetryUpload retries uploading a failed file upload. Returns an error if
	// the transfer has not failed.
	//
	// This function should be called once a transfer errors out (as reported by
	// the progress callback).
	//
	// A new progress callback must be registered on retry. Any previously
	// registered callbacks are defunct when the upload fails.
	RetryUpload(fileID ftCrypto.ID,
		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(fileID ftCrypto.ID) error

	// Download begins the download of the file described in the marshalled
	// FileInfo. The progress of the download is reported on the
	// ReceivedProgressCallback.
	//
	// Once the download completes, the file will be stored in the event model
	// with the given file ID and with the status
	// channels.ReceptionProcessingComplete.
	//
	// The ReceivedProgressCallback only indicates the progress of the file
	// download, not the status of the file in the event model. You must rely on
	// updates from the event model to know when it can be retrieved.
	//
	// Parameters:
	//   - fileInfo - The JSON of FileInfo received on a channel.
	//   - progressCB - A callback that reports the progress of the file
	//     download. 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.
	//
	// Returns:
	//   - A file ID that uniquely identifies this file.
	Download(fileInfo []byte, progressCB ReceivedProgressCallback,
		period time.Duration) (ftCrypto.ID, error)

	// RegisterReceivedProgressCallback allows for the registration of a
	// callback to track the progress of an individual file download.
	//
	// 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 download completes, the file will be stored in the event model
	// with the given file ID and with the status Complete.
	//
	// The ReceivedProgressCallback only indicates the progress of the file
	// download, not the status of the file in the event model. You must rely on
	// updates from the event model to know when it can be retrieved.
	//
	// Parameters:
	//   - fileID - The unique ID of the file.
	//   - progressCB - A callback that reports the progress of the file upload.
	//     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.
	RegisterReceivedProgressCallback(fileID ftCrypto.ID,
		progressCB ReceivedProgressCallback, period time.Duration) 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.

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 ModelFile 

type ModelFile struct {
	// ID is the unique identifier of this file.
	ID ftCrypto.ID `json:"id"`

	// Link contains all the information needed to download the file data.
	// It is the JSON of [FileLink].
	Link []byte `json:"link"`

	// Data is the contents of the file.
	Data []byte `json:"fileData"`

	// Timestamp is the last time the file data, link, or status was modified.
	Timestamp time.Time `json:"timestamp"`

	// The current status of the file in the event model.
	Status Status `json:"status"`
}

ModelFile contains a file and all of its information.

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 `json:"maxThroughput"`

	// 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 `json:"sendTimeout"`

	// ResendWait is the duration, in nanoseconds, to wait to receive a file
	// part before resending it.
	ResendWait time.Duration `json:"resendWait"`

	// Cmix are the parameters used when sending a cMix message.
	Cmix cmix.CMIXParams `json:"cmix"`
}

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 ReceivedProgressCallback 

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

ReceivedProgressCallback is called when the progress on a received file changes or an error occurs in the transfer.

The FilePartTracker can be used to look up the status of individual file parts. Note, when completed == true, the FilePartTracker may be nil.

This callback only indicates the status of the file transfer, not the status of the file in the event model. Do NOT use this callback as an indicator of when the file is available in the event model.

type ReceivedTransfer 

type ReceivedTransfer interface {
	Transfer
}

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

type SentProgressCallback 

type SentProgressCallback func(completed bool, sent, received, total uint16,
	st SentTransfer, fpt FilePartTracker, err error)

SentProgressCallback is called when the progress on a sent file changes or an error occurs in the transfer.

The FilePartTracker can be used to look up the status of individual file parts. Note, when completed == true, the FilePartTracker may be nil.

Any error returned is fatal and the file must either be retried with [FileTransfer.RetryUpload] or canceled with [FileTransfer.CloseSend].

This callback only indicates the status of the file transfer, not the status of the file in the event model. Do NOT use this callback as an indicator of when the file is available in the event model.

type SentTransfer 

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

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

type Status 

type Status uint8

Status is the current status of a file stored in the event model. 

const (

	// Uploading indicates that the file is currently being uploaded. In this
	// state, the file data is accessible but the file link is not.
	Uploading Status = 10

	// Downloading indicates that the file is currently being downloaded. In
	// this state, the file link is accessible but the file data is not.
	Downloading Status = 20

	// Complete indicates that the file has successfully finished uploading or
	// downloading and the file is available to send/receive. In this state,
	// both the file data and file link are accessible.
	Complete Status = 30

	// Error indicates a fatal error occurred during upload or download.
	Error Status = 40
)

func (Status) String 

func (ft Status) String() string

String returns the human-readable form of the Status for logging and debugging. This function adheres to the fmt.Stringer interface.

type Transfer 

type Transfer interface {
	GetFileID() ftCrypto.ID
	GetFileSize() uint32
	GetNumParts() uint16
}

Transfer is the generic structure for a file transfer.

type Wrapper 

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

Wrapper facilitates the sending and receiving file over channels using the event model. It adheres to the FileTransfer interface.

func NewWrapper 

func NewWrapper(
	user FtE2e, params Params) (*Wrapper, channels.ExtensionBuilder, error)

NewWrapper generated a new file transfer wrapper for the channel manager and event model. It allows for sending and receiving of files over channels.

func (*Wrapper) CloseSend 

func (w *Wrapper) CloseSend(fileID ftCrypto.ID) 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).

func (*Wrapper) Download 

func (w *Wrapper) Download(fileInfo []byte, progressCB ReceivedProgressCallback,
	period time.Duration) (ftCrypto.ID, error)

Download beings the download of the file described in the marshalled FileInfo. The progress of the download is reported on the progress callback.

func (*Wrapper) GetNotificationTags added in v4.7.1 

func (w *Wrapper) GetNotificationTags(_ *id.ID, level channels.NotificationLevel) (
	asymmetric, symmetric channels.AllowLists)

GetNotificationTags is called to get the symmetric and asymmetric allow lists for the given channel at the specified level that are appended to the [NotificationFilter].

func (*Wrapper) GetProperties 

func (w *Wrapper) GetProperties() (
	name string, userSpace, adminSpace, mutedSpace bool)

GetProperties returns debugging and pre-filtering information.

func (*Wrapper) GetType 

func (w *Wrapper) GetType() channels.MessageType

GetType returns the channels.FileTransfer message type.

func (*Wrapper) Handle 

func (w *Wrapper) Handle(channelID *id.ID, messageID message.ID,
	messageType channels.MessageType, nickname string, content, _ []byte,
	pubKey ed25519.PublicKey, dmToken uint32, codeset uint8, timestamp,
	_ time.Time, lease time.Duration, _ id.Round, round rounds.Round,
	_ channels.SentStatus, _, hidden bool) uint64

Handle handles the file transfer file info message.

func (*Wrapper) MaxFileNameLen 

func (w *Wrapper) MaxFileNameLen() int

MaxFileNameLen returns the max number of bytes allowed for a file name.

func (*Wrapper) MaxFileSize 

func (w *Wrapper) MaxFileSize() int

MaxFileSize returns the max number of bytes allowed for a file.

func (*Wrapper) MaxFileTypeLen 

func (w *Wrapper) MaxFileTypeLen() int

MaxFileTypeLen returns the max number of bytes allowed for a file type.

func (*Wrapper) MaxPreviewSize 

func (w *Wrapper) MaxPreviewSize() int

MaxPreviewSize returns the max number of bytes allowed for a file preview.

func (*Wrapper) RegisterReceivedProgressCallback 

func (w *Wrapper) RegisterReceivedProgressCallback(fileID ftCrypto.ID,
	progressCB ReceivedProgressCallback, period time.Duration) error

RegisterReceivedProgressCallback registers the callback to the given file ID.

func (*Wrapper) RegisterSentProgressCallback 

func (w *Wrapper) RegisterSentProgressCallback(fileID ftCrypto.ID,
	progressCB SentProgressCallback, period time.Duration) error

RegisterSentProgressCallback registers the callback to the given file described in the marshalled FileInfo.

func (*Wrapper) RetryUpload 

func (w *Wrapper) RetryUpload(fileID ftCrypto.ID,
	progressCB SentProgressCallback, period time.Duration) error

RetryUpload retries uploading a failed file upload. Returns an error if the transfer has not run out of retries.

This function should be called once a transfer errors out (as reported by the progress callback).

func (*Wrapper) Send 

func (w *Wrapper) Send(channelID *id.ID, fileLink []byte, fileName,
	fileType string, preview []byte, validUntil time.Duration,
	params xxdk.CMIXParams, pings []ed25519.PublicKey) (
	message.ID, rounds.Round, ephemeral.Id, error)

Send sends the specified file info to the channel.

func (*Wrapper) StartProcesses 

func (w *Wrapper) StartProcesses() (stoppable.Stoppable, error)

StartProcesses starts the sending threads. Adheres to the xxdk.Service type.

func (*Wrapper) Upload 

func (w *Wrapper) Upload(fileData []byte, retry float32,
	progressCB SentProgressCallback, period time.Duration) (ftCrypto.ID, error)

Upload starts uploading the file to a new ID that can be sent to the specified channel when complete. To get progress information about the upload a SentProgressCallback must be registered.

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.