wittyconnect

package
v0.8.0-alpha Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

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

View Source
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 DeviceID

func DeviceID(key string) (string, error)

DeviceID is the public name of a key.

func NewJoinCode

func NewJoinCode() (string, error)

NewJoinCode makes the code a device with no keyboard shows, for someone signed in to type into the server: see Join.

func NewKey

func NewKey() (key string, err error)

NewKey makes a device's key. ID says what the server will call it.

func ParseInvite

func ParseInvite(link string) (p2p.Invite, error)

ParseInvite reads an invite link.

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

func Start(cfg Config) (*Connector, error)

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) DeviceID

func (c *Connector) DeviceID() string

DeviceID is this device's ID, to enrol with the server.

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

func (c *Connector) KnownAddrs() []string

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) Port

func (c *Connector) Port() int

Port is its port.

func (*Connector) Secret

func (c *Connector) Secret() string

Secret is what requests to the address must carry, under SecretHeader or in a cookie named SecretCookie. It is new each time.

func (*Connector) State

func (c *Connector) State() State

State is how the server is reached right now.

func (*Connector) URL

func (c *Connector) URL() string

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.

type State

type State = p2p.State

State is how the server is reached right now: see p2p.State.

Directories

Path Synopsis
Package mobile is wittyconnect in the shape gomobile can bind for Kotlin and Swift: plain strings, numbers and one small interface.
Package mobile is wittyconnect in the shape gomobile can bind for Kotlin and Swift: plain strings, numbers and one small interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL