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
- Variables
- func DefaultListen() []string
- func DefaultRelays() []string
- func Dialable(a ma.Multiaddr) bool
- func FindInviteCode(text string) (string, error)
- func GenerateRelayKey(path string) (peer.ID, error)
- func LoadRelayID(path string) (peer.ID, error)
- func LoadRelayKey(path string) (crypto.PrivKey, error)
- func ParseRelay(s string) (ma.Multiaddr, peer.ID, error)
- func WriteFrame(w io.Writer, f Frame) error
- type Deliver
- type Frame
- type Host
- func (h *Host) AdvertiseAddrs(name string) []ma.Multiaddr
- func (h *Host) CircuitAddrs(team string) []ma.Multiaddr
- func (h *Host) Close() error
- func (h *Host) Connect(ctx context.Context, id peer.ID, addrs []string) error
- func (h *Host) Host() host.Host
- func (h *Host) ID() peer.ID
- func (h *Host) OnConnected(f func(peer.ID))
- func (h *Host) ProtectMembers()
- func (h *Host) SetRelays(lists map[string][]string)
- func (h *Host) WaitReserved(ctx context.Context) error
- type HostConfig
- type Invite
- type IsMember
- type JoinConfig
- type JoinService
- type MemberSync
- func (r *MemberSync) Changed(name string)
- func (r *MemberSync) Close()
- func (r *MemberSync) IsMember(id peer.ID) bool
- func (r *MemberSync) MemberOf(id peer.ID, name string) bool
- func (r *MemberSync) Receive(from peer.ID, f MembersFrame)
- func (r *MemberSync) Resend()
- func (r *MemberSync) SendLeft(t team.Team) int
- type MembersFrame
- type MessageFrame
- type MsgHandler
- type PresenceEntry
- type PresenceFrame
- type ReceiptFrame
- type Relay
- type RelayConfig
- type RelayStats
Constants ¶
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 )
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.
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.
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.
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.
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.
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.
const MsgProtocol protocol.ID = "/agent-courier/msg/1.0.0"
MsgProtocol carries frames between the daemons of members.
const ProjectRelayID = "12D3KooWEBZoLrJa7yXYJPH5SuHmwWtDCFA39ntvvp883rte7qde"
ProjectRelayID is the peer id of the project relay at relay.cappyt.sh.
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 ¶
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") )
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") )
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.
var ( // ErrFrameTooLarge comes from the reader and from the writer. ErrFrameTooLarge = fmt.Errorf("%w: a frame has at most %d bytes", ErrBadFrame, MaxFrame) )
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
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
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 ¶
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 ¶
LoadRelayID is the peer id of the key in path, for the relay list.
func LoadRelayKey ¶
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
ParseRelay parses a relay list entry: a multiaddr with a transport that ends with /p2p/<relay id> and has no /p2p-circuit.
Types ¶
type Deliver ¶
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.
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
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
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
Close stops the reservations and closes the host and its listeners.
func (*Host) Connect ¶ added in v0.5.0
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) OnConnected ¶ added in v0.5.0
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.
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
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
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 ¶
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:
- The joiner sends a join frame: team, secret, label.
- 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.
- The joiner checks the topics against its own teams, and sends join_accept, or closes the stream and the code stays valid.
- 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
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
MembersFrame carries member list entries of one team. A peer id is in at most one entry.
func PackMembers ¶ added in v0.5.0
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 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 ¶
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) Advertised ¶
Advertised are the addresses the relay tells its peers, without its peer id: the announce addresses when set, else the interface addresses.
func (*Relay) HasPublicAddr ¶
HasPublicAddr reports whether an advertised address is public. A relay without one gives members reservations with no address they can reach.
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.