p2p

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 45 Imported by: 0

Documentation

Overview

Package p2p holds the libp2p side of agent-courier: the host, the wire protocol, the access rule, the member list sync, the join and the relay.

Index

Constants

View Source
const (
	// MaxJoinStreams is the most join streams an inviter serves at once, from
	// all peers, and MaxJoinStreamsPerPeer the most from one peer. Any peer
	// can open a join stream, so these caps bound the work of strangers.
	MaxJoinStreams        = 8
	MaxJoinStreamsPerPeer = 1
)
View Source
const (
	MaxRelayReservations   = 4096
	MaxRelayCircuits       = 64
	MaxRelayCircuitsTotal  = 32768 // MaxReservations x MaxCircuits
	MaxRelayDuration       = 24 * time.Hour
	MaxRelayReservationTTL = 24 * time.Hour
	MaxRelayData           = 1 << 30
)

Upper bounds of the limit flags. They keep the stream and memory sums of limits() far from overflow, and keep the memory that all circuits can hold under the resource manager's system memory limit.

View Source
const JoinProtocol protocol.ID = "/agent-courier/join/1.0.0"

JoinProtocol carries the join of a new machine. It is the only courier protocol without the member check, because a joining peer is in no member list yet: its handler accepts only a valid invite secret, and reads with readPayload so the frame cap holds there too.

View Source
const MaxFrame = 64 << 10

MaxFrame is the most bytes the JSON object of a frame can have. The 4-byte length in front of it does not count.

View Source
const MaxInviteCode = 2048

MaxInviteCode is the most characters an invite code has: version 1 with the longest team name, 4 addresses of team.MaxAddr bytes, and room to spare.

View Source
const MaxPresence = team.MaxTopics * 100

MaxPresence is the most entries a presence frame lists: 16 topics with 100 agents each, the most a sender has.

View Source
const MaxStreamsPerPeer = 4

MaxStreamsPerPeer is the most MsgProtocol streams that one peer can have open at once. A sender opens short streams, so a few are enough.

View Source
const MsgProtocol protocol.ID = "/agent-courier/msg/1.0.0"

MsgProtocol carries frames between the daemons of members.

View Source
const ProjectRelayID = "12D3KooWEBZoLrJa7yXYJPH5SuHmwWtDCFA39ntvvp883rte7qde"

ProjectRelayID is the peer id of the project relay at relay.cappyt.sh.

View Source
const StrangerGrace = 5 * time.Second

StrangerGrace is how long an inbound connection, direct or relayed, from a peer outside the member set may stay open without a join stream.

Variables

View Source
var (
	ErrInviterUnreachable = errors.New("the inviter is not reachable: its daemon must run during the join; the invite code stays valid")
	ErrJoinFailed         = errors.New("the join failed: the inviter answered against the join protocol, or sent a member list without the inviter and this machine")
)
View Source
var (
	// ErrBadInviteCode names the rule of a code and never quotes it.
	ErrBadInviteCode = errors.New("an invite code is the base32 text that agent-courier team invite prints on another member's machine")
	ErrInviteExpired = errors.New("the invite code expired: ask a member for a new one")
)
View Source
var ErrBadFrame = errors.New("bad frame")

ErrBadFrame is in the chain of every error for a frame that breaks the wire protocol. No such error quotes the frame.

View Source
var (
	// ErrFrameTooLarge comes from the reader and from the writer.
	ErrFrameTooLarge = fmt.Errorf("%w: a frame has at most %d bytes", ErrBadFrame, MaxFrame)
)
View Source
var ErrHostClosed = errors.New("the host is closed")

ErrHostClosed is the error of Connect on a closed host.

Functions

func DefaultListen added in v0.5.0

func DefaultListen() []string

DefaultListen are the addresses of a daemon in a team: every interface, QUIC and TCP, IPv4 and IPv6, on ports the system picks.

func DefaultRelays added in v0.5.0

func DefaultRelays() []string

DefaultRelays is the relay list of a team that sets none: the project relay over QUIC and TCP. Public relays found through the DHT come after it, when the DHT lookup exists.

func Dialable added in v0.5.0

func Dialable(a ma.Multiaddr) bool

Dialable reports whether a can name another machine. It is false for a /unix address, a loopback, unspecified, link-local or multicast IP address, and the DNS name localhost or a name under .localhost: in another machine's member list entry or invite code they name the dialing machine, its link, or a cloud metadata service such as 169.254.169.254. Private ranges are dialable, because members on one LAN use them.

func FindInviteCode added in v0.5.0

func FindInviteCode(text string) (string, error)

FindInviteCode finds the one invite code in text: a code alone, a code that a terminal or a chat app broke with spaces or line breaks, or the whole text that agent-courier team invite printed. A code is a run of words that DecodeInvite accepts once they are joined. FindInviteCode returns it joined and in lower case. Text with no such run, or with more than one, is ErrBadInviteCode.

func GenerateRelayKey

func GenerateRelayKey(path string) (peer.ID, error)

GenerateRelayKey writes a new ed25519 key to path with mode 0600. It fails when path exists, so it never replaces the identity of a running relay.

func LoadRelayID

func LoadRelayID(path string) (peer.ID, error)

LoadRelayID is the peer id of the key in path, for the relay list.

func LoadRelayKey

func LoadRelayKey(path string) (crypto.PrivKey, error)

LoadRelayKey reads a libp2p protobuf private key. The path may be a symlink, as a Kubernetes Secret volume mounts it. The file must not be readable by others or writable by the group: a Secret mounted at 0440 with an fsGroup passes.

func ParseRelay added in v0.5.0

func ParseRelay(s string) (ma.Multiaddr, peer.ID, error)

ParseRelay parses a relay list entry: a multiaddr with a transport that ends with /p2p/<relay id> and has no /p2p-circuit.

func WriteFrame

func WriteFrame(w io.Writer, f Frame) error

WriteFrame checks f and writes it to w with one Write. It writes nothing when f is not valid or its JSON is over MaxFrame.

Types

type Deliver

type Deliver func(ctx context.Context, from peer.ID, f Frame) (reply Frame, err error)

Deliver takes one valid frame from a member. from is the peer id of the connection, which Noise authenticates, never a field of the frame.

IsMember only says that from is in some member list this daemon shares. Deliver must accept a frame only when from is a member of the team the frame names: the team of a members frame, or the team that owns the topic of a message or of each presence entry.

ctx ends with the life of the stream, and Deliver must return when it ends. A non-nil reply goes back on the same stream. An error resets the stream.

type Frame

type Frame interface {
	// Validate checks every field against the rules of the wire protocol.
	Validate() error
	// contains filtered or unexported methods
}

Frame is one of MessageFrame, ReceiptFrame, MembersFrame and PresenceFrame.

func ReadFrame

func ReadFrame(r io.Reader) (Frame, error)

ReadFrame reads one frame from r and checks it. It returns io.EOF when r ends between two frames.

type Host added in v0.5.0

type Host struct {
	// contains filtered or unexported fields
}

Host is the libp2p host of a daemon in a team.

func StartHost added in v0.5.0

func StartHost(ctx context.Context, cfg HostConfig) (*Host, error)

StartHost starts the libp2p host of a daemon in a team, with the options of hostOptions. It keeps identify address discovery, because hole punching needs the addresses that peers observe, and serves no AutoNAT v2 dial request: it runs the client only. It holds a reservation on the first reachable relay of each list and renews it before it expires. ctx bounds only the start.

func (*Host) AdvertiseAddrs added in v0.5.0

func (h *Host) AdvertiseAddrs(name string) []ma.Multiaddr

AdvertiseAddrs are the addresses of this machine for an invite code or a member list entry of team, or of every team when team is empty, best first: the circuit addresses through the team's relays, then the dialable host addresses, public ones first. They carry no /p2p part, and there are at most team.MaxAddrs of them.

func (*Host) CircuitAddrs added in v0.5.0

func (h *Host) CircuitAddrs(team string) []ma.Multiaddr

CircuitAddrs are this machine's addresses through the relays of team where it holds a reservation: <relay list entry>/p2p-circuit/p2p/<own peer id>, built from the list entry and not from the host addresses, because the host publishes a circuit address only for a relay that announces a public address.

func (*Host) Close added in v0.5.0

func (h *Host) Close() error

Close stops the reservations and closes the host and its listeners.

func (*Host) Connect added in v0.5.0

func (h *Host) Connect(ctx context.Context, id peer.ID, addrs []string) error

Connect connects to the member id with the addresses of its member list entry. It waits first, at most until readyWait after the start, for the reservation and for a public observed address, so that DCUtR can upgrade a relayed connection. One dial then tries the direct addresses first and the circuit addresses after them: the member's own, and one through each relay of the teams this machine shares with the member. A relayed connection stays when hole punching fails. Connect drops the addresses that are not Dialable.

func (*Host) Host added in v0.5.0

func (h *Host) Host() host.Host

Host is the libp2p host, for the protocol handlers.

func (*Host) ID added in v0.5.0

func (h *Host) ID() peer.ID

ID is the peer id of this machine.

func (*Host) OnConnected added in v0.5.0

func (h *Host) OnConnected(f func(peer.ID))

OnConnected adds f to the functions that run, each in its own goroutine, when a peer goes from no connection to a direct or a relayed one. Every peer counts, relays and strangers too: f checks the member lists.

func (*Host) ProtectMembers added in v0.5.0

func (h *Host) ProtectMembers()

ProtectMembers protects the connections of the members in the connection manager, and unprotects those of peers that left the member set. The daemon calls it after each change of the member set.

func (*Host) SetRelays added in v0.5.0

func (h *Host) SetRelays(lists map[string][]string)

SetRelays replaces the relay lists, by team name. When a list changed, the host keeps the reservations that a list still names and reserves for the new lists at once; when none changed, it does nothing, so the backoff of a list without a reservation holds.

func (*Host) WaitReserved added in v0.5.0

func (h *Host) WaitReserved(ctx context.Context) error

WaitReserved waits until each relay list of the start made its first attempt, at most until readyWait after the start.

type HostConfig added in v0.5.0

type HostConfig struct {
	// Key is the machine key.
	Key crypto.PrivKey
	// Listen are the listen multiaddrs. Empty: the host listens on no
	// address, and peers reach it only through a relay.
	Listen []string
	// Relays holds the relay list of each team, by team name. Each entry is
	// a multiaddr that ends with /p2p/<relay id>. The host holds a
	// reservation on the first reachable relay of each list.
	Relays map[string][]string
	// IsMember is the member set of the daemon: whether a peer is a member
	// of a team this machine shares.
	IsMember IsMember
	// MemberOf says whether a peer is a member of the named team. A dial to
	// a member goes through the relays of the teams it shares.
	MemberOf func(id peer.ID, team string) bool
	// Log gets the host's log, and the libp2p log at debug level.
	Log *slog.Logger
	// contains filtered or unexported fields
}

HostConfig configures StartHost.

type Invite added in v0.5.0

type Invite struct {
	Team    string
	Inviter peer.ID
	// Addrs are addresses of the inviter without its /p2p part, at most
	// team.MaxAddrs.
	Addrs   []ma.Multiaddr
	Secret  []byte
	Expires time.Time
}

Invite is what an invite code carries: what the joiner needs to reach the inviter, and the secret of the invite.

func DecodeInvite added in v0.5.0

func DecodeInvite(code string) (Invite, error)

DecodeInvite parses an invite code. Case and the white space around it do not count. Every error is ErrBadInviteCode, which does not quote the code. An expired code decodes: the caller checks Expires. It drops the addresses that Dialable refuses: /unix, loopback, link-local and unspecified.

func (Invite) Encode added in v0.5.0

func (i Invite) Encode() (string, error)

Encode is the code of i. Version 1 is, in order: the version byte; the team name and the binary peer id of the inviter, each a 1-byte length and its bytes; the 16-byte secret; the expiry in Unix seconds, 8 bytes big-endian; the address count, 1 byte; and each address as a 2-byte big-endian length and its binary multiaddr. Integers are unsigned.

type IsMember

type IsMember func(id peer.ID) bool

IsMember reports whether id is a member of a team this daemon belongs to. It runs concurrently, for every stream and every frame. It must answer from memory, so a stranger's stream costs no database read.

type JoinConfig added in v0.5.0

type JoinConfig struct {
	// Set is the member set of the daemon.
	Set *team.Set
	// Addrs is the address source of invite codes and of this machine's own
	// member list entry, best first: the daemon puts its circuit address on
	// the relay there when it has one. Nil means the addresses of the host.
	Addrs func() []ma.Multiaddr
	// Changed runs after a join changed the member list of a team, on the
	// inviter and on the joiner, so the list goes out to the members.
	Changed func(team string)
	Log     *slog.Logger
}

JoinConfig is what a JoinService needs besides its host.

type JoinService added in v0.5.0

type JoinService struct {
	// contains filtered or unexported fields
}

JoinService serves JoinProtocol for the inviter and makes the joins of this machine. The protocol on one stream:

  1. The joiner sends a join frame: team, secret, label.
  2. The inviter checks the secret first, then the label and the member cap, without a change, and replies with an offer of the team's topics or a refusal.
  3. The joiner checks the topics against its own teams, and sends join_accept, or closes the stream and the code stays valid.
  4. The inviter checks again, marks the invite used and adds the joiner. It sends the member list in members frames, the joiner's entry and its own first, and closes. A check that fails now gets a refusal.

func NewJoinService added in v0.5.0

func NewJoinService(h host.Host, cfg JoinConfig) (*JoinService, error)

NewJoinService sets the JoinProtocol handler of h. The deadlines of a join stream bound the work of the handler.

func (*JoinService) Handle added in v0.5.0

func (j *JoinService) Handle(s network.Stream)

Handle is the network.StreamHandler of JoinProtocol. It is the only courier handler without the member check, so it caps the streams before it reads a byte, and takes the joiner's peer id only from the connection, which Noise authenticates.

func (*JoinService) Join added in v0.5.0

func (j *JoinService) Join(ctx context.Context, code, label string) (team.Team, error)

Join joins this machine with label to the team of an invite code. It fails before it dials with ErrBadInviteCode, ErrInviteExpired, or an error of team.Set.CheckJoin, and then with ErrInviterUnreachable, a refusal of the inviter (team.ErrInviteRefused, team.ErrLabelTaken, team.ErrTeamFull), team.ErrTopicTaken, or ErrJoinFailed. None of them quotes the code or the inviter's frames.

type MemberSync added in v0.5.0

type MemberSync struct {
	// contains filtered or unexported fields
}

MemberSync keeps the member lists of the teams of this machine in step with the other members. It sends every list a member shares on each new connection to that member, and the list of a team to its members after a local change or a received change, and every list again on Resend. It merges a received list only from a member of that team. Members frames have no budget: they never reach a session, and members are trusted. The member set it reads and changes is the daemon's team.Set.

func NewMemberSync added in v0.5.0

func NewMemberSync(ctx context.Context, h host.Host, set *team.Set, changed func(name string), log *slog.Logger) *MemberSync

NewMemberSync starts to watch the connections of h. changed runs after a received frame changed the list of a team; nil means nothing. ctx bounds every send.

func (*MemberSync) Changed added in v0.5.0

func (r *MemberSync) Changed(name string)

Changed sends the list of team name to each member of the team, after a local change, in the background.

func (*MemberSync) Close added in v0.5.0

func (r *MemberSync) Close()

Close stops the sends and waits for the running ones.

func (*MemberSync) IsMember added in v0.5.0

func (r *MemberSync) IsMember(id peer.ID) bool

IsMember is the IsMember of MsgHandler: id is a member of a team of this machine.

func (*MemberSync) MemberOf added in v0.5.0

func (r *MemberSync) MemberOf(id peer.ID, name string) bool

MemberOf reports whether id is a member of team name: the rule of Deliver for a frame that names a team.

func (*MemberSync) Receive added in v0.5.0

func (r *MemberSync) Receive(from peer.ID, f MembersFrame)

Receive merges a members frame from the peer from. team.Set.Merge is the one check that from is a member of the team the frame names. When the frame changed the list, Receive runs changed and sends the list on to the other members.

func (*MemberSync) Resend added in v0.5.0

func (r *MemberSync) Resend()

Resend sends every list to every member, in the background, so a member that missed a change learns it without a new connection.

func (*MemberSync) SendLeft added in v0.5.0

func (r *MemberSync) SendLeft(t team.Team) int

SendLeft sends t, the list of a team this machine left with its own entry marked left, to each other member of t, in parallel, and waits for the sends. No member set holds t any more, so no other send reaches them. It returns how many of the other members it did not reach.

type MembersFrame added in v0.5.0

type MembersFrame struct {
	Team    string       `json:"team"`
	Entries []team.Entry `json:"entries"`
}

MembersFrame carries member list entries of one team. A peer id is in at most one entry.

func PackMembers added in v0.5.0

func PackMembers(name string, entries []team.Entry) (frames []MembersFrame, skipped int, err error)

PackMembers splits the member list entries of team name into members frames, in order, each within MaxFrame and the entry cap of a frame. It skips an entry that fails the frame check, so one bad entry does not stop the rest of the list, and returns how many it skipped.

func (MembersFrame) Validate added in v0.5.0

func (f MembersFrame) Validate() error

type MessageFrame

type MessageFrame struct {
	ID message.ID `json:"id"`
	// Sender is the agent name on the sending machine.
	Sender         string `json:"sender"`
	message.Fields `json:",embed"`
}

MessageFrame carries one message. The receiver takes the member label of the sender from the connection: no field of the frame names it.

func (MessageFrame) Validate

func (f MessageFrame) Validate() error

Validate refuses kind online, because onlines travel in presence frames, and a recipient on a third machine: To names an agent of the receiver.

type MsgHandler

type MsgHandler struct {
	// contains filtered or unexported fields
}

MsgHandler serves MsgProtocol. A connection gater lets any peer connect, because DHT and relay traffic need it, so the member check is here, before the handler reads a byte. The per-peer stream cap is a counter keyed by the authenticated peer id, so it holds whatever resource manager the host has.

func NewMsgHandler

func NewMsgHandler(ctx context.Context, isMember IsMember, deliver Deliver, log *slog.Logger) *MsgHandler

NewMsgHandler returns a handler that passes the frames of members to deliver. ctx bounds every deliver call.

func (*MsgHandler) Handle

func (m *MsgHandler) Handle(s network.Stream)

Handle is the network.StreamHandler of MsgProtocol. Before it reads a byte, it resets the stream of a peer outside the member lists with StreamGated, and the stream of a peer with MaxStreamsPerPeer streams open with StreamResourceLimitExceeded. It resets with StreamProtocolViolation a stream that breaks the wire protocol or a deadline, and with StreamGated a stream whose peer leaves the member lists: its next frame is not delivered.

type PresenceEntry

type PresenceEntry struct {
	Topic string `json:"topic"`
	Agent string `json:"agent"`
}

type PresenceFrame

type PresenceFrame struct {
	Agents []PresenceEntry `json:"agents"`
}

PresenceFrame lists the agents online on the topics both members share. An empty list means none. A topic and agent pair is in at most one entry.

func (PresenceFrame) Validate

func (f PresenceFrame) Validate() error

type ReceiptFrame

type ReceiptFrame struct {
	ID message.ID `json:"id"`
}

ReceiptFrame acknowledges the message with the id ID.

func (ReceiptFrame) Validate

func (f ReceiptFrame) Validate() error

type Relay

type Relay struct {
	// contains filtered or unexported fields
}

Relay is a running circuit relay v2 node.

func StartRelay

func StartRelay(key crypto.PrivKey, cfg RelayConfig) (*Relay, error)

StartRelay starts a libp2p host that serves circuit relay v2 and identify only: QUIC and TCP, Noise, no ping, no relay client, no DHT, no AutoNAT.

func (*Relay) Addrs

func (r *Relay) Addrs() []ma.Multiaddr

Addrs are the relay's listen addresses, without its peer id.

func (*Relay) Advertised

func (r *Relay) Advertised() []ma.Multiaddr

Advertised are the addresses the relay tells its peers, without its peer id: the announce addresses when set, else the interface addresses.

func (*Relay) Close

func (r *Relay) Close() error

Close stops the relay service, then the host.

func (*Relay) HasPublicAddr

func (r *Relay) HasPublicAddr() bool

HasPublicAddr reports whether an advertised address is public. A relay without one gives members reservations with no address they can reach.

func (*Relay) ID

func (r *Relay) ID() peer.ID

ID is the relay's peer id.

func (*Relay) Stats

func (r *Relay) Stats() RelayStats

Stats are the current counts of the relay.

type RelayConfig

type RelayConfig struct {
	// Listen are the multiaddrs the relay listens on.
	Listen []string
	// Announce, when set, replaces the listen addresses that the relay
	// tells its peers, for a relay behind a load balancer. Each address
	// must be public and carry no /p2p or /p2p-circuit.
	Announce []string
	// MaxReservations caps the reservations the relay holds at once.
	MaxReservations int
	// MaxReservationsPerIP caps the reservations from one IP address.
	MaxReservationsPerIP int
	// MaxCircuits caps the relayed connections of one peer.
	MaxCircuits int
	// ReservationTTL is how long a reservation lasts before the peer renews it.
	ReservationTTL time.Duration
	// MaxDuration ends a relayed connection after this time.
	MaxDuration time.Duration
	// MaxData ends a relayed connection after this many bytes in one direction.
	MaxData int64
}

RelayConfig holds the limits and addresses of the relay node.

func DefaultRelayConfig

func DefaultRelayConfig() RelayConfig

DefaultRelayConfig has the limits of the design: 10 minutes and 1 MiB per relayed connection, 1024 reservations, 8 per IP and 16 circuits per peer.

type RelayStats

type RelayStats struct {
	Peers               int
	Reservations        int64
	Circuits            int64
	ReservationsRefused map[string]int64
	CircuitsRefused     map[string]int64
}

RelayStats are the counts the relay logs. They hold no peer ids. The refusal maps count requests by circuit relay status name.

Jump to

Keyboard shortcuts

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