mesh

Documentation

Overview

Package mesh implements mesh related data structure conversions.

Index

• type AcceptInvitationRequest
• type DNS
• type Hosts
  • func (h Hosts) UnmarshalJSON(b []byte) error
• type Invitation
• type Invitations
• type Inviter
• type Machine
  • func (s Machine) EndpointsString() []string
  • func (s *Machine) IsEqual(b Machine) bool
  • func (s Machine) ToProtobuf() *pb.Peer
• type MachineCreateRequest
• type MachineCreateResponse
• type MachineMap
• type MachineMapResponse
• type MachinePeer
  • func (p MachinePeer) EndpointsString() []string
  • func (p MachinePeer) ToProtobuf() *pb.Peer
• type MachinePeerResponse
• type MachinePeers
• type MachineUpdateRequest
• type Machines
• type NotificationNewTransactionRequest
• type OperatingSystem
• type PeerUpdateRequest
  • func NewPeerUpdateRequest(peer MachinePeer) PeerUpdateRequest
• type Registry
• type SendInvitationRequest

Types

type AcceptInvitationRequest

type AcceptInvitationRequest struct {
	AllowInbound      bool `json:"allow_incoming_connections"`
	AllowRouting      bool `json:"allow_peer_traffic_routing"`
	AllowLocalNetwork bool `json:"allow_peer_local_network_access"`
	AllowFileshare    bool `json:"allow_peer_send_files"`
}

type DNS

type DNS struct {
	Hosts Hosts `json:"hosts"`
}

DNS defines mapping between peer name and ip used by magic DNS within the mesh network.

type Hosts

type Hosts map[string]netip.Addr

Hosts defines mapping between hostname an IP address.

func (Hosts) UnmarshalJSON

func (h Hosts) UnmarshalJSON(b []byte) error

UnmarshalJSON customizes json deserialization.

type Invitation

type Invitation struct {
	ID                uuid.UUID `json:"token"`
	Email             string    `json:"email"`
	OS                string    `json:"os"`
	AllowInbound      bool      `json:"allow_incoming_connections"`
	AllowRouting      bool      `json:"allow_peer_traffic_routing"`
	AllowLocalNetwork bool      `json:"allow_peer_local_network_access"`
}

Invitation to/from other user.

type Invitations

type Invitations []Invitation

Invitations to join other mesh networks.

type Inviter

type Inviter interface {
	// Invite to mesh network.
	Invite(
		token string,
		self uuid.UUID,
		email string,
		doIAllowInbound bool,
		doIAllowRouting bool,
		doIAllowLocalNetwork bool,
		doIAllowFileshare bool,
	) error
	// Sent invitations to other users.
	Sent(token string, self uuid.UUID) (Invitations, error)
	// Received invitations from other users.
	Received(token string, self uuid.UUID) (Invitations, error)
	// Accept an invitation.
	Accept(
		token string,
		self uuid.UUID,
		invitation uuid.UUID,
		doIAllowInbound bool,
		doIAllowRouting bool,
		doIAllowLocalNetwork bool,
		doIAllowFileshare bool,
	) error
	// Reject an invitation.
	Reject(token string, self uuid.UUID, invitation uuid.UUID) error
	// Revoke an invitation.
	Revoke(token string, self uuid.UUID, invitation uuid.UUID) error
}

Inviter defines a set of operations for managing personal mesh network.

type Machine

type Machine struct {
	// ID uniquely identifies the peer
	ID uuid.UUID
	// HardwareID uniquely identifies the physical machine,
	// without it, only one account can be used per machine.
	HardwareID uuid.UUID
	// Hostname to ping the peer by.
	Hostname string
	// OS where the peer is running on.
	OS OperatingSystem
	// PublicKey is a base64 encoded string.
	PublicKey string
	// Endpoints are used to reach the peer within meshnet.
	Endpoints []netip.AddrPort
	// Address is a meshnet IP address of a peer
	Address         netip.Addr
	SupportsRouting bool
	Nickname        string
}

Machine represents current device in meshnet.

func (Machine) EndpointsString

func (s Machine) EndpointsString() []string

EndpointsString could be replaced with slices.Map(p.Endpoints, func(s Stringer) string { return s.String() }) once we upgrade to Go 1.18

func (*Machine) IsEqual

func (s *Machine) IsEqual(b Machine) bool

func (Machine) ToProtobuf

func (s Machine) ToProtobuf() *pb.Peer

type MachineCreateRequest

type MachineCreateRequest struct {
	// PublicKey is a WireGuard public key used to encrypt outgoing packets.
	PublicKey string `json:"public_key"`
	// HardwareID is used in combination with PublicKey to allow registering
	// multiple machines on the same hardware.
	HardwareID uuid.UUID `json:"hardware_identifier"`
	// OS is always 'linux'
	OS string `json:"os"`
	// Distro can be found in /etc/os-release
	Distro string `json:"os_version"`
	// Endpoints are publicly routable IP and port pairs.
	Endpoints       []netip.AddrPort `json:"endpoints"`
	SupportsRouting bool             `json:"traffic_routing_supported"`
}

type MachineCreateResponse

type MachineCreateResponse struct {
	// Identifier is an API generated unique identifier for a peer
	Identifier uuid.UUID `json:"identifier"`
	// PublicKey is a WireGuard public key used to encrypt outgoing packets.
	PublicKey string `json:"public_key"`
	// Hostname is a fully qualified domain name used to reach machine.
	// Also used as a human readable identifier.
	Hostname string `json:"hostname"`
	// OS is always 'linux'
	OS string `json:"os"`
	// Distro can be found in /etc/os-release
	Distro string `json:"os_version"`
	// Endpoints are publicly routable IP and port pairs.
	Endpoints []netip.AddrPort `json:"endpoints"`
	// Addresses belonging to 100.64.0.0/10 subnet.
	Addresses       []netip.Addr `json:"ip_addresses"`
	SupportsRouting bool         `json:"traffic_routing_supported"`
	Nickname        string       `json:"nickname"`
}

type MachineMap

type MachineMap struct {
	Machine
	Peers MachinePeers
	// Hosts maps hostnames to IP addresses
	Hosts
	// Raw is unprocessed API response passed directly to libtelio
	Raw []byte
}

MachineMap is used to refresh mesh.

type MachineMapResponse

type MachineMapResponse struct {
	ID        uuid.UUID `json:"identifier"`
	PublicKey string    `json:"public_key"`
	// Hostname is a fully qualified domain name used to reach machine.
	// Also used as a human readable identifier.
	Hostname string `json:"hostname"`
	// OS is always 'linux'
	OS string `json:"os"`
	// Distro can be found in /etc/os-release
	Distro string `json:"os_version"`
	// Endpoints are publicly routable IP and port pairs.
	Endpoints []netip.AddrPort `json:"endpoints"`
	// Addresses belonging to 100.64.0.0/10 subnet.
	Addresses       []netip.Addr          `json:"ip_addresses"`
	SupportsRouting bool                  `json:"traffic_routing_supported"`
	DNS             DNS                   `json:"dns"`
	Peers           []MachinePeerResponse `json:"peers"`
	Nickname        string                `json:"nickname"`
}

type MachinePeer

type MachinePeer struct {
	// ID uniquely identifies the peer
	ID uuid.UUID
	// Hostname to ping the peer by.
	Hostname string
	// OS where the peer is running on.
	OS OperatingSystem
	// PublicKey is a base64 encoded string.
	PublicKey string
	// Endpoints are used to reach the peer within meshnet.
	Endpoints []netip.AddrPort
	// Address is used to reach the peer outside meshnet.
	Address netip.Addr
	// Email of the owner.
	Email string
	// IsLocal to this meshnet. If not, it means invited.
	// Another way to represent this would be: enum Origin { Local, Invited }
	IsLocal bool
	// DoesPeerAllowRouting through it?
	DoesPeerAllowRouting bool
	// DoesPeerAllowInbound traffic to it?
	DoesPeerAllowInbound bool
	// DoesPeerAllowLocalNetwork access when routing through it?
	DoesPeerAllowLocalNetwork bool
	DoesPeerAllowFileshare    bool
	DoesPeerSupportRouting    bool
	// DoIAllowInbound traffic to this peer?
	DoIAllowInbound bool
	// DoIAllowRouting through this peer?
	DoIAllowRouting bool
	// DoIAllowLocalNetwork access when routing through me?
	DoIAllowLocalNetwork bool
	DoIAllowFileshare    bool
	AlwaysAcceptFiles    bool
	Nickname             string
}

MachinePeer represents someone else's device in meshnet.

func (MachinePeer) EndpointsString

func (p MachinePeer) EndpointsString() []string

EndpointsString could be replaced with slices.Map(p.Endpoints, func(s Stringer) string { return s.String() }) once we upgrade to Go 1.18

func (MachinePeer) ToProtobuf

func (p MachinePeer) ToProtobuf() *pb.Peer

type MachinePeerResponse

type MachinePeerResponse struct {
	ID        uuid.UUID        `json:"identifier"`
	PublicKey string           `json:"public_key"`
	Hostname  string           `json:"hostname"`
	OS        string           `json:"os"`
	Distro    string           `json:"os_version"`
	Endpoints []netip.AddrPort `json:"endpoints"`
	Addresses []netip.Addr     `json:"ip_addresses"`
	IsLocal   bool             `json:"is_local"`
	Email     string           `json:"user_email"`

	// MachinePeer settings
	DoesPeerAllowRouting      bool `json:"peer_allows_traffic_routing"`
	DoesPeerAllowInbound      bool `json:"allow_outgoing_connections"`
	DoesPeerAllowLocalNetwork bool `json:"peer_allows_local_network_access"`
	DoesPeerSupportRouting    bool `json:"traffic_routing_supported"`
	DoesPeerAllowFileshare    bool `json:"peer_allows_send_files"`

	// Machine settings
	DoIAllowInbound      bool   `json:"allow_incoming_connections"`
	DoIAllowRouting      bool   `json:"allow_peer_traffic_routing"`
	DoIAllowLocalNetwork bool   `json:"allow_peer_local_network_access"`
	DoIAllowFileshare    bool   `json:"allow_peer_send_files"`
	AlwaysAcceptFiles    bool   `json:"always_accept_files"`
	Nickname             string `json:"nickname"`
}

type MachinePeers

type MachinePeers []MachinePeer

type MachineUpdateRequest

type MachineUpdateRequest struct {
	// TODO: Endpoints doesn't exist in documentation, check if is needed
	Endpoints       []netip.AddrPort `json:"endpoints"`
	SupportsRouting bool             `json:"traffic_routing_supported"`
	Nickname        string           `json:"nickname"`
}

MachineUpdateRequest is used to update one's meshnet device.

type Machines

type Machines []Machine

type NotificationNewTransactionRequest

type NotificationNewTransactionRequest struct {
	ReceiverMachineIdentifier string `json:"receiver_machine_identifier"`
	FileName                  string `json:"file_name"`
	FileCount                 int    `json:"file_count"`
}

type OperatingSystem

type OperatingSystem struct {
	// Name is always 'linux' in our case.
	Name string
	// Distro can be found under the NAME key in /etc/os-release
	Distro string
}

OperatingSystem defines an operating system in use.

type PeerUpdateRequest

type PeerUpdateRequest struct {
	DoIAllowInbound      bool   `json:"allow_incoming_connections"`
	DoIAllowRouting      bool   `json:"allow_peer_traffic_routing"`
	DoIAllowLocalNetwork bool   `json:"allow_peer_local_network_access"`
	DoIAllowFileshare    bool   `json:"allow_peer_send_files"`
	AlwaysAcceptFiles    bool   `json:"always_accept_files"`
	Nickname             string `json:"nickname"`
}

PeerUpdateRequest is used to update one's peer.

func NewPeerUpdateRequest

func NewPeerUpdateRequest(peer MachinePeer) PeerUpdateRequest

type Registry

type Registry interface {
	// Register Self to mesh network.
	Register(token string, self Machine) (*Machine, error)
	// Update already registered peer.
	Update(token string, id uuid.UUID, info MachineUpdateRequest) error
	// Configure interaction with specific peer.
	Configure(
		token string,
		id uuid.UUID,
		peerID uuid.UUID,
		peerUpdateInfo PeerUpdateRequest,
	) error
	// Unregister Peer from the mesh network.
	Unregister(token string, self uuid.UUID) error
	// Local peers owned the same user.
	Local(token string) (Machines, error)
	// List given peer's neighbours in the mesh network.
	List(token string, self uuid.UUID) (MachinePeers, error)
	Map(token string, self uuid.UUID) (*MachineMap, error)
	// Unpair invited peer.
	Unpair(token string, self uuid.UUID, peer uuid.UUID) error
	// NotifyNewTransfer notifies a device about a new incoming transfer (outgoing from this
	// device perspective)
	NotifyNewTransfer(
		token string,
		self uuid.UUID,
		peer uuid.UUID,
		fileName string,
		fileCount int,
	) error
}

Registry defines a set of operations used to interact with the rest of the mesh.

type SendInvitationRequest

type SendInvitationRequest struct {
	Email             string `json:"email"`
	AllowInbound      bool   `json:"allow_incoming_connections"`
	AllowRouting      bool   `json:"allow_peer_traffic_routing"`
	AllowLocalNetwork bool   `json:"allow_peer_local_network_access"`
	AllowFileshare    bool   `json:"allow_peer_send_files"`
}