entity

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MPL-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	InviteStatusActive  = "active"
	InviteStatusExpired = "expired"
	InviteStatusUsedUp  = "used_up"
	InviteStatusRevoked = "revoked"
)

Values of InviteResponse.Status.

View Source
const (
	InviteLinkScheme = "awl"
	InviteLinkHost   = "invite"
	// InviteLinkVersion is the newest format we understand. It is never written
	// into a link: adding a query parameter is backwards compatible on its own
	// (parsers ignore what they do not know), so a version only has to appear
	// the day something incompatible changes. Reading it is kept from day one,
	// so that such a link can be rejected with a comprehensible message instead
	// of a random parse failure.
	InviteLinkVersion = 1
)

Invite link format: awl://invite?p=<peer_id>&t=<token>&n=<name>

The peer ID lives in the query, not in the authority, on purpose: it is base58 and therefore case-sensitive, while hosts are historically case-insensitive and get lowercased by messenger linkifiers and Android intent matching, which would break peer.Decode. The authority is the fixed word "invite", leaving room for other awl:// URLs later.

The token is optional. With it the link is a capability — whoever presents it is added automatically; without it the link is just "here is me, with a name to fill in", the shareable form of a peer ID. One format covers both so that every consumer — the add form, the QR scanner, the CLI — has a single input to parse.

The same format has a second implementation in Dart (awl-flutter), so the format is a contract and both sides carry tests for it.

Variables

View Source
var ErrNotInviteLink = errors.New("not an awl invite link")

ErrNotInviteLink reports input that is not an awl invite link at all, as opposed to a malformed one. It lets a UI tell "this is a peer ID" from "this link is broken".

Functions

func BuildInviteLink(peerID, token, name string) string

BuildInviteLink renders a link; an empty token or name is left out. The query is assembled by hand rather than through url.Values, which sorts its keys: parameters stay in the p, t, n order the format is written in, so links read the same way everywhere they are shown.

Types

type AuthRequest

type AuthRequest struct {
	PeerID string
	protocol.AuthPeer
	// SuggestedIP is a free IP address generated for this peer
	SuggestedIP string
}

Responses

type AvailableProxy added in v0.12.0

type AvailableProxy struct {
	PeerID    string
	PeerName  string
	Connected bool
}

Responses

type AvailableVPNGateway added in v0.18.0

type AvailableVPNGateway struct {
	PeerID    string
	PeerName  string
	Connected bool
}

Responses

type BandwidthDebugInfo

type BandwidthDebugInfo struct {
	Total      BandwidthInfo
	ByProtocol map[string]BandwidthInfo
}

type BandwidthInfo

type BandwidthInfo struct {
	TotalIn  string
	TotalOut string
	RateIn   string
	RateOut  string
}

type ConnectionsDebugInfo

type ConnectionsDebugInfo struct {
	ConnectedPeersCount  int
	OpenConnectionsCount int
	OpenStreamsCount     int64
	LastTrimAgo          string
	TCPDials             p2p.TCPDialStats
}

type CreateInviteRequest added in v0.20.0

type CreateInviteRequest struct {
	// MaxUses: 0 means the default, 1 (single-use).
	MaxUses int `validate:"gte=0,lte=100"`
	// ExpiresInSeconds: 0 means the invite never expires. A number rather
	// than a duration string, as with ReconnectionIntervalSec; clients parse
	// "24h" on their side. Maximum is 365 days.
	ExpiresInSeconds int64 `validate:"gte=0,lte=31536000"`
	// Alias to give the peer that redeems the link. Single-use links only.
	Alias string `validate:"max=100,no_control_chars"`
	// AllowUsingAsExitNode lets the new peer use us as an exit node.
	AllowUsingAsExitNode bool
	Label                string `validate:"max=100,no_control_chars"`
}

Requests

type DhtDebugInfo

type DhtDebugInfo struct {
	RoutingTableSize    int
	RoutingTable        []kbucket.PeerInfo
	Reachability        string `enums:"Unknown,Public,Private"`
	ListenAddress       []string
	PeersWithAddrsCount int
	ReachableAddrs      []string
	UnreachableAddrs    []string
	UnknownAddrs        []string
	BootstrapPeers      map[string]p2p.BootstrapPeerDebugInfo
}

type EnableVPNGatewayClientRequest added in v0.18.0

type EnableVPNGatewayClientRequest struct {
	GatewayPeerID string `validate:"required"`
}

Responses

type FriendRequest

type FriendRequest struct {
	PeerID string `validate:"required"`
	Alias  string `validate:"required,trimmed_str_not_empty,max=100,no_control_chars"`
	// optional: specific IP address for the peer
	IPAddr string `validate:"omitempty,ipv4"`
	// optional: allow the peer to use us as an exit node
	AllowUsingAsExitNode bool
	// optional: token from an invite link (see InviteLink.Token). It is
	// stored with the peer and presented in every auth request until the
	// peer confirms us, which it then does without a manual accept.
	Token string
}

Requests

type FriendRequestReply

type FriendRequestReply struct {
	PeerID string `validate:"required"`
	// Alias is required to accept; declining takes none.
	Alias   string `validate:"required_if=Decline false,omitempty,trimmed_str_not_empty,max=100,no_control_chars"`
	Decline bool
	// optional: specific IP address for the peer
	IPAddr string `validate:"omitempty,ipv4"`
	// optional: allow the peer to use us as an exit node
	AllowUsingAsExitNode bool
}

Requests

type GeneralDebugInfo

type GeneralDebugInfo struct {
	Version string
	Uptime  string
}
type InviteLink struct {
	PeerID string
	// Token grants automatic acceptance to whoever presents it. Empty for a
	// link that only identifies its author, which is then added by hand as usual.
	Token string
	// Name is the creator's display name, used to prefill the add form so the
	// peer can be added before the creator ever comes online. Optional.
	Name string
}

InviteLink is the payload of an invite link: who invites, the bearer token granting automatic acceptance, and how the inviter calls itself.

func ParseInviteLink(rawLink string) (InviteLink, error)

ParseInviteLink parses a link, tolerating surrounding whitespace and newlines (links get copy-pasted out of messengers).

type InviteResponse added in v0.20.0

type InviteResponse struct {
	ID    string
	Label string
	// Link is rebuilt on every request from the current node name, so
	// renaming this node changes the link shown here while links already
	// handed out keep working — the name plays no part in validation.
	Link                 string
	Alias                string
	AllowUsingAsExitNode bool
	MaxUses              int
	UsedCount            int
	// ExpiresAt zero means the invite never expires.
	ExpiresAt time.Time
	CreatedAt time.Time
	Revoked   bool
	// Status is derived from the fields above for display.
	Status string `enums:"active,expired,used_up,revoked"`
}

InviteResponse describes one invite link. The token is never returned on its own — only inside Link, which is what the user shares.

type KnownPeerReconnectInfo added in v0.20.0

type KnownPeerReconnectInfo struct {
	p2p.ReconnectDebugInfo
	// Eager peers are tried every round, whatever NextAttemptIn says
	Eager bool
}

Responses

type KnownPeersResponse

type KnownPeersResponse struct {
	PeerID                        string
	Name                          string // Deprecated: use DisplayName instead
	DisplayName                   string // Deprecated: useless, equal to Alias all the time
	Alias                         string
	Version                       string
	IpAddr                        string
	IpAddrV6                      string
	DomainName                    string
	Connected                     bool
	Confirmed                     bool
	Declined                      bool
	WeAllowUsingAsExitNode        bool
	AllowedUsingAsExitNode        bool
	RemoteVPNGatewayServerEnabled bool
	// InviteID is set when we let this peer in through one of our invite
	// links; empty otherwise. Non-secret, see config.KnownPeer.InviteID.
	InviteID               string
	LastSeen               time.Time
	Connections            []p2p.ConnectionInfo
	NetworkStats           metrics.Stats
	NetworkStatsInIECUnits StatsInUnits
	Ping                   time.Duration `swaggertype:"primitive,integer"`
	// PeerstoreAddrs are the addresses a dial to the peer goes through.
	// There are none for a peer that has been away for a while.
	PeerstoreAddrs []string `json:",omitempty"`
	// Reconnect is set for a peer we fail to reach.
	Reconnect *KnownPeerReconnectInfo `json:",omitempty"`
}

Responses

type ListAvailableProxiesResponse added in v0.12.0

type ListAvailableProxiesResponse struct {
	Proxies []AvailableProxy
}

Responses

type ListAvailableVPNGatewaysResponse added in v0.18.0

type ListAvailableVPNGatewaysResponse struct {
	VPNGateways []AvailableVPNGateway
}

Responses

type LogRequest

type LogRequest struct {
	StartFromHead bool `url:"from_head" query:"from_head"`
	LogsRows      int  `url:"logs" query:"logs" validate:"numeric,gte=0"`
}

Requests

type P2pDebugInfo

type P2pDebugInfo struct {
	General     GeneralDebugInfo
	DHT         DhtDebugInfo
	Connections ConnectionsDebugInfo
	Bandwidth   BandwidthDebugInfo
	KnownPeers  []KnownPeersResponse
}

type PeerIDRequest

type PeerIDRequest struct {
	PeerID string `validate:"required"`
}

Requests

type PeerInfo

type PeerInfo struct {
	PeerID                  string
	Name                    string
	Uptime                  time.Duration `swaggertype:"primitive,integer"`
	ServerVersion           string
	NetworkStats            metrics.Stats
	NetworkStatsInIECUnits  StatsInUnits
	TotalBootstrapPeers     int
	ConnectedBootstrapPeers int
	Reachability            string `enums:"Unknown,Public,Private"`
	AwlDNSAddress           string
	IsAwlDNSSetAsSystem     bool
	VPN                     VPNInfo
	SOCKS5                  SOCKS5Info
	VPNGateway              VPNGatewayInfo
}

Responses

type RevokeInviteRequest added in v0.20.0

type RevokeInviteRequest struct {
	ID string `validate:"required"`
}

Requests

type SOCKS5Info added in v0.12.0

type SOCKS5Info struct {
	// ListenAddress — address the local proxy listens on, empty if the proxy is off.
	ListenAddress   string
	ProxyingEnabled bool
	ListenerEnabled bool
	// Connected — current libp2p connectivity to the exit peer.
	Connected             bool
	UsingPeerID           string
	UsingPeerName         string
	UsingPeerPublicIP     string
	UsingPeerPing         time.Duration `swaggertype:"primitive,integer"`
	UsingPeerThroughRelay bool
}

Responses

type SetVPNGatewayServerEnabledRequest added in v0.18.0

type SetVPNGatewayServerEnabledRequest struct {
	Enabled bool
}

Responses

type StatsInUnits

type StatsInUnits struct {
	TotalIn  string
	TotalOut string
	RateIn   string
	RateOut  string
}

Responses

type UpdateMySettingsRequest

type UpdateMySettingsRequest struct {
	Name string `validate:"max=100,no_control_chars"`
}

Requests

type UpdatePeerSettingsRequest

type UpdatePeerSettingsRequest struct {
	PeerID     string `validate:"required"`
	Alias      string `validate:"required,trimmed_str_not_empty,max=100,no_control_chars"`
	DomainName string `validate:"required,trimmed_str_not_empty"`
	// TODO: support ipv6
	IPAddr               string `validate:"required,ipv4"`
	AllowUsingAsExitNode bool
}

Requests

type UpdateProxySettingsRequest added in v0.12.0

type UpdateProxySettingsRequest struct {
	UsingPeerID string
}

Requests

type VPNGatewayInfo added in v0.18.0

type VPNGatewayInfo struct {
	// ClientEnabled — VPN gateway client mode is on (we route via GatewayPeerID).
	ClientEnabled bool
	// GatewayPeerID — the peer we route through; empty when disabled.
	GatewayPeerID string
	// GatewayPeerName — display name of the gateway peer, populated when known.
	GatewayPeerName string
	// Connected — current libp2p connectivity to the gateway peer.
	Connected bool
	// ServerEnabled — this node currently offers VPN gateway server.
	ServerEnabled       bool
	GatewayPublicIP     string
	GatewayPing         time.Duration `swaggertype:"primitive,integer"`
	GatewayThroughRelay bool
}

Responses

type VPNInfo added in v0.16.0

type VPNInfo struct {
	VPNInterfaceEnabled bool
	InterfaceName       string
	IPNet               string
	IPv6Addr            string
}

Responses

Jump to

Keyboard shortcuts

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