wormhole

Documentation

Overview

Package wormhole provides a magic wormhole client implementation.

Index

• Variables
• 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) 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

Variables

var (
	// 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 occured.

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

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              string
	Type              TransferType
	TransferBytes     int
	UncompressedBytes int
	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 decripted contents sent to this client.

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.

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