Documentation
¶
Overview ¶
Package wittyconnect is the app's side of peer-to-peer connections, ready to use: it connects to a server by its connection ID and offers what an app already knows how to talk to, an HTTP address on this device. Whatever is sent to that address comes out at the server, encrypted to its key on the way, over whichever path the two could find.
The address is http://127.0.0.1:<port>, on a port picked at random, and it answers only requests that carry the session's secret (in a header or a cookie): other programs on the device can connect to the port, but not use it. The desktop app runs this as a helper program (cmd/wittyconnect); the phone and TV apps link it in (the mobile package beside this one).
docs/P2P.md describes the whole design.
Index ¶
- Constants
- func DeviceID(key string) (string, error)
- func NewJoinCode() (string, error)
- func NewKey() (key string, err error)
- func ParseInvite(link string) (p2p.Invite, error)
- type Config
- type Connector
- func (c *Connector) Close()
- func (c *Connector) DeviceID() string
- func (c *Connector) Enrol(ctx context.Context, secret, name, platform string) (p2p.EnrolResponse, error)
- func (c *Connector) KnownAddrs() []string
- func (c *Connector) NetworkChanged()
- func (c *Connector) Port() int
- func (c *Connector) Secret() string
- func (c *Connector) State() State
- func (c *Connector) URL() string
- type JoinConfig
- type JoinResult
- type State
Constants ¶
const ( SecretHeader = "X-Witty-Connect" SecretCookie = "wittyconnect" )
The names an app passes the secret under. The header suits an app's own HTTP client; the cookie suits a web view and media players, which send cookies by themselves with every request, sockets included.
Variables ¶
This section is empty.
Functions ¶
func NewJoinCode ¶
NewJoinCode makes the code a device with no keyboard shows, for someone signed in to type into the server: see Join.
Types ¶
type Config ¶
type Config struct {
// Key is this device's key, as NewKey made it. The app keeps it secret and
// keeps it: the server knows the device by it.
Key string `json:"key"`
// ServerID is the server's connection ID.
ServerID string `json:"serverId"`
// Hints are addresses the server had last time, or that an invite named.
Hints []string `json:"hints"`
// NoDHT, NoRelay and NoHolePunch turn layers off, for a person who wants
// fewer outside parties involved: see docs/P2P.md for what each costs.
NoDHT bool `json:"noDht"`
NoRelay bool `json:"noRelay"`
NoHolePunch bool `json:"noHolePunch"`
// StaticRelays are relays to use as well, as multiaddrs ending in /p2p/<id>.
StaticRelays []string `json:"staticRelays"`
// Port is the port to open the local address on, if it is free: the one
// used last time, so that what a web view stored for the address is still
// there. Otherwise, and when 0, one is picked.
Port int `json:"port"`
OnState func(State) `json:"-"`
Log *slog.Logger `json:"-"`
// Tune changes the node's configuration before it starts, for tests.
Tune func(*p2p.ClientConfig) `json:"-"`
}
Config is what a connection is made from.
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector is a running connection and its local address.
func Start ¶
Start connects and opens the local address. It returns as soon as the address is listening; requests wait while the server is being found.
func (*Connector) Close ¶
func (c *Connector) Close()
Close ends the connection and closes the local address.
func (*Connector) Enrol ¶
func (c *Connector) Enrol(ctx context.Context, secret, name, platform string) (p2p.EnrolResponse, error)
Enrol shows the server an invite's secret, which puts this device on its list. The answer may hold a sign-in code to redeem over the local address.
func (*Connector) KnownAddrs ¶
KnownAddrs are the server's addresses as last learnt, to keep as hints.
func (*Connector) NetworkChanged ¶
func (c *Connector) NetworkChanged()
NetworkChanged tells the connector the device moved to another network.
func (*Connector) Secret ¶
Secret is what requests to the address must carry, under SecretHeader or in a cookie named SecretCookie. It is new each time.
func (*Connector) URL ¶
URL is the local address: http://127.0.0.1:<port>.
type JoinConfig ¶
type JoinConfig struct {
// Key is this device's key, and Code what NewJoinCode made.
Key string `json:"key"`
Code string `json:"code"`
// Name and Platform are what the server's list will call the device.
Name string `json:"name"`
Platform string `json:"platform"`
// NoRelay and NoHolePunch turn layers off. The address book can't be: it
// is how a device that knows only a code finds the server.
NoRelay bool `json:"noRelay"`
NoHolePunch bool `json:"noHolePunch"`
StaticRelays []string `json:"staticRelays"`
// Tune changes the search before it starts, for tests.
Tune func(*p2p.JoinConfig) `json:"-"`
}
JoinConfig is what a device that shows a code looks for its server with.
type JoinResult ¶
type JoinResult = p2p.JoinResult
JoinResult is the server that took the code, and its answer: on OK, the server's connection ID and addresses to start a connection with, and a sign-in code to redeem over it.
func Join ¶
func Join(ctx context.Context, cfg JoinConfig) (JoinResult, error)
Join is for a device away from home that has never met its server and can't take an invite link in: a TV. It shows a code; this waits until someone signed in has typed that code into the server (POST /api/v1/p2p/join), finds the server through the address book, and has this device's key put on its list. Give ctx the fifteen minutes a code lasts. docs/P2P.md, "Joining by a code", is the design.