manet

Documentation

Overview

Package manet provides Multiaddr specific versions of common functions in stdlib's net package. This means wrappers of standard net symbols like net.Dial and net.Listen, as well as conversion to/from net.Addr.

Package manet provides Multiaddr (https://github.com/multiformats/go-multiaddr) specific versions of common functions in Go's standard `net` package. This means wrappers of standard net symbols like `net.Dial` and `net.Listen`, as well as conversion to and from `net.Addr`.

Index

• Variables
• func AddrMatch(match ma.Multiaddr, addrs []ma.Multiaddr) []ma.Multiaddr
• func DialArgs(m ma.Multiaddr) (string, string, error)
• func FromIP(ip net.IP) (ma.Multiaddr, error)
• func FromNetAddr(a net.Addr) (ma.Multiaddr, error)
• func InterfaceMultiaddrs() ([]ma.Multiaddr, error)
• func IsIP6LinkLocal(m ma.Multiaddr) bool
• func IsIPLoopback(m ma.Multiaddr) bool
• func IsIPUnspecified(m ma.Multiaddr) bool
• func IsThinWaist(m ma.Multiaddr) bool
• func RegisterNetCodec(a *NetCodec)
• func ToNetAddr(maddr ma.Multiaddr) (net.Addr, error)
• type CodecMap
  • func NewCodecMap() *CodecMap
  • func (cm *CodecMap) FromNetAddr(a net.Addr) (ma.Multiaddr, error)
  • func (cm *CodecMap) RegisterNetCodec(a *NetCodec)
  • func (cm *CodecMap) ToNetAddr(maddr ma.Multiaddr) (net.Addr, error)
• type Conn
  • func Dial(remote ma.Multiaddr) (Conn, error)
  • func WrapNetConn(nconn net.Conn) (Conn, error)
• type Dialer
  • func (d *Dialer) Dial(remote ma.Multiaddr) (Conn, error)
  • func (d *Dialer) DialContext(ctx context.Context, remote ma.Multiaddr) (Conn, error)
• type FromNetAddrFunc
• type Listener
  • func Listen(laddr ma.Multiaddr) (Listener, error)
  • func WrapNetListener(nl net.Listener) (Listener, error)
• type NetCodec
• type PacketConn
  • func ListenPacket(laddr ma.Multiaddr) (PacketConn, error)
  • func WrapPacketConn(pc net.PacketConn) (PacketConn, error)
• type ToNetAddrFunc

Variables

var (
	// IP4Loopback is the ip4 loopback multiaddr
	IP4Loopback = ma.StringCast("/ip4/127.0.0.1")

	// IP6Loopback is the ip6 loopback multiaddr
	IP6Loopback = ma.StringCast("/ip6/::1")

	// IP6LinkLocalLoopback is the ip6 link-local loopback multiaddr
	IP6LinkLocalLoopback = ma.StringCast("/ip6/fe80::1")
)

Loopback Addresses

var (
	IP4Unspecified = ma.StringCast("/ip4/0.0.0.0")
	IP6Unspecified = ma.StringCast("/ip6/::")
)

Unspecified Addresses (used for )

Functions

func AddrMatch

func AddrMatch(match ma.Multiaddr, addrs []ma.Multiaddr) []ma.Multiaddr

AddrMatch returns the Multiaddrs that match the protocol stack on addr

func DialArgs

func DialArgs(m ma.Multiaddr) (string, string, error)

DialArgs is a convenience function returning arguments for use in net.Dial

func FromIP

func FromIP(ip net.IP) (ma.Multiaddr, error)

FromIP converts a net.IP type to a Multiaddr.

func FromNetAddr

func FromNetAddr(a net.Addr) (ma.Multiaddr, error)

FromNetAddr converts a net.Addr type to a Multiaddr.

func InterfaceMultiaddrs

func InterfaceMultiaddrs() ([]ma.Multiaddr, error)

InterfaceMultiaddrs will return the addresses matching net.InterfaceAddrs

func IsIP6LinkLocal

func IsIP6LinkLocal(m ma.Multiaddr) bool

IsIP6LinkLocal returns if a multiaddress is an IPv6 local link. These addresses are non routable. The prefix is technically fe80::/10, but we test fe80::/16 for simplicity (no need to mask). So far, no hardware interfaces exist long enough to use those 2 bits. Send a PR if there is.

func IsIPLoopback

func IsIPLoopback(m ma.Multiaddr) bool

IsIPLoopback returns whether a Multiaddr is a "Loopback" IP address This means either /ip4/127.0.0.1 or /ip6/::1 TODO: differentiate IsIPLoopback and OverIPLoopback

func IsIPUnspecified

func IsIPUnspecified(m ma.Multiaddr) bool

IsIPUnspecified returns whether a Multiaddr is am Unspecified IP address This means either /ip4/0.0.0.0 or /ip6/::

func IsThinWaist

func IsThinWaist(m ma.Multiaddr) bool

IsThinWaist returns whether a Multiaddr starts with "Thin Waist" Protocols. This means: /{IP4, IP6}[/{TCP, UDP}]

func RegisterNetCodec

func RegisterNetCodec(a *NetCodec)

RegisterNetCodec adds a new NetCodec to the default codecs.

func ToNetAddr

func ToNetAddr(maddr ma.Multiaddr) (net.Addr, error)

ToNetAddr converts a Multiaddr to a net.Addr Must be ThinWaist. acceptable protocol stacks are: /ip{4,6}/{tcp, udp}

Types

type CodecMap

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

CodecMap holds a map of NetCodecs indexed by their Protocol ID along with parsers for the addresses they use. It is used to keep a list of supported network address codecs (protocols which addresses can be converted to and from multiaddresses).

func NewCodecMap

func NewCodecMap() *CodecMap

NewCodecMap initializes and returns a CodecMap object.

func (*CodecMap) FromNetAddr

func (cm *CodecMap) FromNetAddr(a net.Addr) (ma.Multiaddr, error)

FromNetAddr converts a net.Addr to Multiaddress.

func (*CodecMap) RegisterNetCodec

func (cm *CodecMap) RegisterNetCodec(a *NetCodec)

RegisterNetCodec adds a new NetCodec to the CodecMap. This function is thread safe.

func (*CodecMap) ToNetAddr

func (cm *CodecMap) ToNetAddr(maddr ma.Multiaddr) (net.Addr, error)

ToNetAddr converts a Multiaddress to a standard net.Addr.

type Conn

type Conn interface {
	net.Conn

	// LocalMultiaddr returns the local Multiaddr associated
	// with this connection
	LocalMultiaddr() ma.Multiaddr

	// RemoteMultiaddr returns the remote Multiaddr associated
	// with this connection
	RemoteMultiaddr() ma.Multiaddr
}

Conn is the equivalent of a net.Conn object. It is the result of calling the Dial or Listen functions in this package, with associated local and remote Multiaddrs.

func Dial

func Dial(remote ma.Multiaddr) (Conn, error)

Dial connects to a remote address. It uses an underlying net.Conn, then wraps it in a Conn object (with local and remote Multiaddrs).

func WrapNetConn

func WrapNetConn(nconn net.Conn) (Conn, error)

WrapNetConn wraps a net.Conn object with a Multiaddr friendly Conn.

type Dialer

type Dialer struct {

	// Dialer is just an embedded net.Dialer, with all its options.
	net.Dialer

	// LocalAddr is the local address to use when dialing an
	// address. The address must be of a compatible type for the
	// network being dialed.
	// If nil, a local address is automatically chosen.
	LocalAddr ma.Multiaddr
}

Dialer contains options for connecting to an address. It is effectively the same as net.Dialer, but its LocalAddr and RemoteAddr options are Multiaddrs, instead of net.Addrs.

func (*Dialer) Dial

func (d *Dialer) Dial(remote ma.Multiaddr) (Conn, error)

Dial connects to a remote address, using the options of the Dialer. Dialer uses an underlying net.Dialer to Dial a net.Conn, then wraps that in a Conn object (with local and remote Multiaddrs).

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, remote ma.Multiaddr) (Conn, error)

DialContext allows to provide a custom context to Dial().

type FromNetAddrFunc

type FromNetAddrFunc func(a net.Addr) (ma.Multiaddr, error)

FromNetAddrFunc is a generic function which converts a net.Addr to Multiaddress

type Listener

type Listener interface {

	// NetListener returns the embedded net.Listener. Use with caution.
	NetListener() net.Listener

	// Accept waits for and returns the next connection to the listener.
	// Returns a Multiaddr friendly Conn
	Accept() (Conn, error)

	// Close closes the listener.
	// Any blocked Accept operations will be unblocked and return errors.
	Close() error

	// Multiaddr returns the listener's (local) Multiaddr.
	Multiaddr() ma.Multiaddr

	// Addr returns the net.Listener's network address.
	Addr() net.Addr
}

A Listener is a generic network listener for stream-oriented protocols. it uses an embedded net.Listener, overriding net.Listener.Accept to return a Conn and providing Multiaddr.

func Listen

func Listen(laddr ma.Multiaddr) (Listener, error)

Listen announces on the local network address laddr. The Multiaddr must be a "ThinWaist" stream-oriented network: ip4/tcp, ip6/tcp, (TODO: unix, unixpacket) See Dial for the syntax of laddr.

func WrapNetListener

func WrapNetListener(nl net.Listener) (Listener, error)

WrapNetListener wraps a net.Listener with a manet.Listener.

type NetCodec

type NetCodec struct {
	// NetAddrNetworks is an array of strings that may be returned
	// by net.Addr.Network() calls on addresses belonging to this type
	NetAddrNetworks []string

	// ProtocolName is the string value for Multiaddr address keys
	ProtocolName string

	// ParseNetAddr parses a net.Addr belonging to this type into a multiaddr
	ParseNetAddr FromNetAddrFunc

	// ConvertMultiaddr converts a multiaddr of this type back into a net.Addr
	ConvertMultiaddr ToNetAddrFunc

	// Protocol returns the multiaddr protocol struct for this type
	Protocol ma.Protocol
}

NetCodec is used to identify a network codec, that is, a network type for which we are able to translate multiaddresses into standard Go net.Addr and back.

type PacketConn

type PacketConn interface {
	Connection() net.PacketConn

	Multiaddr() ma.Multiaddr

	ReadFrom(b []byte) (int, ma.Multiaddr, error)
	WriteTo(b []byte, maddr ma.Multiaddr) (int, error)

	Close() error
}

A PacketConn is a generic packet oriented network connection which uses an underlying net.PacketConn, wrapped with the locally bound Multiaddr.

func ListenPacket

func ListenPacket(laddr ma.Multiaddr) (PacketConn, error)

ListenPacket announces on the local network address laddr. The Multiaddr must be a packet driven network, like udp4 or udp6. See Dial for the syntax of laddr.

func WrapPacketConn

func WrapPacketConn(pc net.PacketConn) (PacketConn, error)

WrapPacketConn wraps a net.PacketConn with a manet.PacketConn.

type ToNetAddrFunc

type ToNetAddrFunc func(ma ma.Multiaddr) (net.Addr, error)

ToNetAddrFunc is a generic function which converts a Multiaddress to net.Addr