campfire

Documentation

Overview

Package campfire implements the "camp fire" protocol.

Index

• Constants
• Variables
• func GeneratePSK() ([]byte, error)
• func Join(ctx context.Context, campfire *CampfireURI) (io.ReadWriteCloser, error)
• func MustGeneratePSK() []byte
• type CampfireChannel
  • func Wait(ctx context.Context, camp *CampfireURI) (CampfireChannel, error)
• type CampfireURI
  • func ParseCampfireURI(rawURL string) (*CampfireURI, error)
  • func (c *CampfireURI) EncodeURI() string
• type Location
  • func Find(psk []byte, turnServers []string) (*Location, error)
  • func (l *Location) Expired() <-chan struct{}
  • func (l *Location) LocalPwd() string
  • func (l *Location) LocalUfrag() string
  • func (l *Location) RemotePwd() string
  • func (l *Location) RemoteUfrag() string
  • func (l *Location) SessionID() int
  • func (l *Location) TURNSessionID() string
• type Options

Constants

const PSKSize = 32

PSKSize is the size of the PSK in bytes.

const Protocol = "/webmesh/campfire/1.0.0"

Protocol is the protocol name.

Variables

var (
	// ErrClosed is returned when the camp fire is closed.
	ErrClosed = net.ErrClosed
)

var Now = time.Now

Now is the current time. It is a variable so it can be mocked out in tests.

Functions

func GeneratePSK

func GeneratePSK() ([]byte, error)

GeneratePSK generates a random PSK of length PSKSize.

func Join

func Join(ctx context.Context, campfire *CampfireURI) (io.ReadWriteCloser, error)

Join will attempt to join the peer waiting at the given location.

func MustGeneratePSK

func MustGeneratePSK() []byte

MustGeneratePSK generates a random PSK of length PSKSize. It panics if an error occurs.

Types

type CampfireChannel

type CampfireChannel interface {
	// Accept returns a connection to a peer.
	Accept() (io.ReadWriteCloser, error)
	// Close closes the camp fire.
	Close() error
	// Errors returns a channel of errors.
	Errors() <-chan error
	// Expired returns a channel that is closed when the camp fire expires.
	Expired() <-chan struct{}
	// Opened returns true if the camp fire is open.
	Opened() bool
}

CampfireChannel is a connection to one or more peers sharing the same pre-shared key.

func Wait

func Wait(ctx context.Context, camp *CampfireURI) (CampfireChannel, error)

Wait will wait for peers to join at the given location.

type CampfireURI

type CampfireURI struct {
	TURNServers  []string // Username for TURN authentication
	TURNUsername string   // Username for TURN authentication
	TURNPassword string   // Password for TURN authentication
	StunHosts    []string // List of STUN server hosts
	StunPorts    []string // List of STUN server ports
	RemoteHosts  []string // List of remote hosts
	RemotePorts  []string // List of remote ports
	Fingerprint  string   // Raw query string, representing fingerprint
	PSK          []byte   // Pre-shared key
}

CampfireURI represents the components parsed from a camp URL.

func ParseCampfireURI

func ParseCampfireURI(rawURL string) (*CampfireURI, error)

ParseCampfireURI parses the given rawURL and returns a CampfireURI struct.

func (*CampfireURI) EncodeURI

func (c *CampfireURI) EncodeURI() string

EncodeURI encodes the CampfireURI into a string.

type Location

type Location struct {
	// PSK is the pre-shared key.
	PSK []byte
	// LocalSecret is the computed local secret from the PSK.
	LocalSecret string
	// RemoteSecret is the computed remote secret from the PSK.
	RemoteSecret string
	// TURNServer is the selected TURN server.
	TURNServer string
	// ExpiresAt is the time at which the campfire expires.
	ExpiresAt time.Time
}

Location is the secret and location of a campfire.

func Find

func Find(psk []byte, turnServers []string) (*Location, error)

Find finds a campfire using the given PSK and TURN servers. If turnServers is empty, a default list will be fetched from always-online-stun.

func (*Location) Expired

func (l *Location) Expired() <-chan struct{}

Expired returns a channel that is closed when the campfire expires.

func (*Location) LocalPwd

func (l *Location) LocalPwd() string

LocalPwd returns the local pwd.

func (*Location) LocalUfrag

func (l *Location) LocalUfrag() string

LocalUfrag returns the local ufrag.

func (*Location) RemotePwd

func (l *Location) RemotePwd() string

RemotePwd returns the remote pwd.

func (*Location) RemoteUfrag

func (l *Location) RemoteUfrag() string

RemoteUfrag returns the remote ufrag.

func (*Location) SessionID

func (l *Location) SessionID() int

SessionID returns the session ID.

func (*Location) TURNSessionID

func (l *Location) TURNSessionID() string

TURNSessionID returns the TURN session ID.

type Options

type Options struct {
	// PSK is the pre-shared key.
	PSK []byte
	// TURNServers is an optional list of turn servers to use.
	TURNServers []string
}

Options are options for creating or joining a new camp fire.