Documentation
¶
Index ¶
- Constants
- Variables
- func BuildInviteLink(peerID, token, name string) string
- type AuthRequest
- type AvailableProxy
- type AvailableVPNGateway
- type BandwidthDebugInfo
- type BandwidthInfo
- type ConnectionsDebugInfo
- type CreateInviteRequest
- type DhtDebugInfo
- type EnableVPNGatewayClientRequest
- type FriendRequest
- type FriendRequestReply
- type GeneralDebugInfo
- type InviteLink
- type InviteResponse
- type KnownPeerReconnectInfo
- type KnownPeersResponse
- type ListAvailableProxiesResponse
- type ListAvailableVPNGatewaysResponse
- type LogRequest
- type P2pDebugInfo
- type PeerIDRequest
- type PeerInfo
- type RevokeInviteRequest
- type SOCKS5Info
- type SetVPNGatewayServerEnabledRequest
- type StatsInUnits
- type UpdateMySettingsRequest
- type UpdatePeerSettingsRequest
- type UpdateProxySettingsRequest
- type VPNGatewayInfo
- type VPNInfo
Constants ¶
const ( InviteStatusActive = "active" InviteStatusExpired = "expired" InviteStatusUsedUp = "used_up" InviteStatusRevoked = "revoked" )
Values of InviteResponse.Status.
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 ¶
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 ¶ added in v0.20.0
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
Responses
type AvailableVPNGateway ¶ added in v0.18.0
Responses
type BandwidthDebugInfo ¶
type BandwidthDebugInfo struct {
Total BandwidthInfo
ByProtocol map[string]BandwidthInfo
}
type BandwidthInfo ¶
type ConnectionsDebugInfo ¶
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 InviteLink ¶ added in v0.20.0
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 ¶ added in v0.20.0
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 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 ¶
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