wormhole

Documentation

Overview

Package wormhole provides a magic wormhole client implementation.

Index

• Constants
• type Client
  • func (c *Client) Receive(ctx context.Context, code string) (fr *IncomingMessage, returnErr error)
  • func (c *Client) SendDirectory(ctx context.Context, directoryName string, entries []DirectoryEntry, ...) (string, chan SendResult, error)
  • func (c *Client) SendFile(ctx context.Context, fileName string, r io.ReadSeeker, opts ...SendOption) (string, chan SendResult, error)
  • func (c *Client) SendText(ctx context.Context, msg string, opts ...SendOption) (string, chan SendResult, error)
• type DirectoryEntry
• type IncomingMessage
  • func (f *IncomingMessage) Read(p []byte) (int, error)
  • func (f *IncomingMessage) ReadText() string
  • func (f *IncomingMessage) Reject() error
• type SendOption
  • func WithCode(code string) SendOption
  • func WithProgress(f func(sentBytes int64, totalBytes int64)) SendOption
• type SendResult
• type TransferType
  • func (tt TransferType) String() string

Constants

const (
	// WormholeCLIAppID is the AppID used by the python magic wormhole
	// client. In order to interoperate with that client you must use
	// the same AppID.
	WormholeCLIAppID = "lothar.com/wormhole/text-or-file-xfer"

	// DefaultRendezvousURL is the default Rendezvous server to use.
	DefaultRendezvousURL = "ws://relay.magic-wormhole.io:4000/v1"

	// DefaultTransitRelayAddress is the default transit server to ues.
	DefaultTransitRelayAddress = "transit.magic-wormhole.io:4001"
)

Types

type Client

type Client struct {
	// AppID is the identity string of the client sent to the rendezvous
	// server. Two clients can only communicate if they have the same
	// AppID. The AppID should be a domain name + path to make it
	// globally unique. If empty, WormholeCLIAppID will be used.
	AppID string
	// RendezvousURL is the url of the Rendezvous server. If empty,
	// DefaultRendezvousURL will be used.
	RendezvousURL string

	// TransitRelayAddress is the host:port address to offer
	// to use for file transfers where direct connections are unavailable.
	// If empty, DefaultTransitRelayAddress will be used.
	TransitRelayAddress string

	// PassPhraseComponentLength is the number of words to use
	// when generating a passprase. Any value less than 2 will
	// default to 2.
	PassPhraseComponentLength int

	// VerifierOk specifies an optional hook to be called before
	// transmitting/receiving the encrypted payload.
	//
	// If VerifierOk is non-nil it will be called after the PAKE
	// hand-shake has succeeded passing in the verifier code. Callers
	// can then prompt the user to confirm the code matches via an out
	// of band mechanism before proceeding with the file transmission.
	// If VerifierOk returns false the transmission will be aborted.
	VerifierOk func(verifier string) bool
}

A Client is wormhole client. Its zero value is a usable client.

func (*Client) Receive

func (c *Client) Receive(ctx context.Context, code string) (fr *IncomingMessage, returnErr error)

Receive receives a message sent by a wormhole client.

It returns an IncomingMessage with metadata about the payload being sent. To read the contents of the message call IncomingMessage.Read().

func (*Client) SendDirectory

func (c *Client) SendDirectory(ctx context.Context, directoryName string, entries []DirectoryEntry, opts ...SendOption) (string, chan SendResult, error)

SendDirectory sends a tree of files to a receiving client. Each DirectoryEntry Path must be prefixed by the directoryName provided to SendDirectory.

It returns a nameplate+passhrase code to give to the receiver, a result channel that will be written to after the receiver attempts to read (either successfully or not) and an error if one occurred.

func (*Client) SendFile

func (c *Client) SendFile(ctx context.Context, fileName string, r io.ReadSeeker, opts ...SendOption) (string, chan SendResult, error)

SendFile sends a single file via the wormhole protocol. It returns a nameplate+passhrase code to give to the receiver, a result channel that will be written to after the receiver attempts to read (either successfully or not) and an error if one occurred.

func (*Client) SendText

func (c *Client) SendText(ctx context.Context, msg string, opts ...SendOption) (string, chan SendResult, error)

SendText sends a text message via the wormhole protocol.

It returns the nameplate+passphrase code to give to the receiver, a result chan that gets written to once the receiver actually attempts to read the message (either successfully or not).

type DirectoryEntry

type DirectoryEntry struct {
	// Path is the relative path to the file from the top level directory.
	Path string

	// Mode controls the permission and mode bits for the file.
	Mode os.FileMode

	// Reader is a function that returns a ReadCloser for the file's content.
	Reader func() (io.ReadCloser, error)
}

A DirectoryEntry represents a single file to be sent by SendDirectory

type IncomingMessage

type IncomingMessage struct {
	// Name is the name of the file or directory being transferred.
	Name string
	// The type of file transfer being offered.
	Type TransferType
	// TransferBytes is the offered size of the file transfer from the peer.
	// This is expected to be the number of bytes sent over the network to
	// perform the file transfer, however a malicious client could lie about this.
	// The primary purpose of this field is to allow the user to choose to accept
	// or reject the transfer if the file size is unexpected.
	//
	// For client implementation convenience, TransferBytes is also set for text messages.
	// Note that the message has already been fully transferred by the time this value is known.
	TransferBytes int64
	// UncompressedBytes is the offered size of the files on disk post decompression.
	// This is sent from the peer as part of the offer and a malicious peer could lie
	// about this.
	// The primary purpose of this field is to allow the user to choose to accept
	// or reject the transfer if the file size is unexpected.
	//
	// For client implementation convenience, UncompressedBytes is also set for text messages.
	// Note that the message has already been fully transferred by the time this value is known.
	UncompressedBytes int64
	// FileCount is the number of files in a TransferDirectory offer. This is sent
	// as part of the offer from the peer and a malicious peer could lie about this.
	FileCount int
	// contains filtered or unexported fields
}

A IncomingMessage contains information about a payload sent to this wormhole client.

The Type field indicates if the sender sent a single file or a directory. If the Type is TransferDirectory then reading from the IncomingMessage will read a zip file of the contents of the directory.

func (*IncomingMessage) Read

func (f *IncomingMessage) Read(p []byte) (int, error)

Read the decrypted contents sent to this client.

func (*IncomingMessage) ReadText

func (f *IncomingMessage) ReadText() string

ReadText reads received text without nthe need for a buffer and the Read([]byte) method. This is more efficient but only works for text receives. File and directory transfers return an empty string.

func (*IncomingMessage) Reject

func (f *IncomingMessage) Reject() error

Reject an incoming file or directory transfer. This must be called before any calls to Read. This does nothing for text message transfers.

type SendOption

type SendOption interface {
	// contains filtered or unexported methods
}

func WithCode

func WithCode(code string) SendOption

WithCode returns a SendOption to use a specific nameplate+code instead of generating one dynamically.

func WithProgress

func WithProgress(f func(sentBytes int64, totalBytes int64)) SendOption

WithProgress returns a SendOption to track the progress of the data transfer. It takes a callback function that will be called for each chunk of data successfully written.

WithProgress is only minimally supported in SendText. SendText does not use the wormhole transit protocol so it is not able to detect the progress of the receiver. This limitation does not apply to SendFile or SendDirectory.

type SendResult

type SendResult struct {
	OK    bool
	Error error
}

SendResult has information about whether or not a Send command was successful.

type TransferType

type TransferType int

const (
	TransferFile TransferType = iota + 1
	TransferDirectory
	TransferText
)

func (TransferType) String

func (tt TransferType) String() string