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

    Constants

    This section is empty.

    Variables

    View Source
    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")
    
    	// IP4MappedIP6Loopback is the IPv4 Mapped IPv6 loopback address.
    	IP4MappedIP6Loopback = ma.StringCast("/ip6/::ffff:127.0.0.1")
    )

      Loopback Addresses

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

        Unspecified Addresses (used for )

        View Source
        var Private4, Private6 []*net.IPNet

          Private4 and Private6 are well-known private networks

          View Source
          var Unroutable4, Unroutable6 []*net.IPNet

            Unroutable4 and Unroutable6 are well known unroutable address ranges

            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 that returns network and address as expected by net.Dial. See https://godoc.org/net#Dial for an overview of possible return values (we do not support the unixpacket ones yet). Unix addresses do not, at present, compose.

                func FromIP

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

                  FromIP converts a net.IP type to a Multiaddr.

                  func FromIPAndZone

                  func FromIPAndZone(ip net.IP, zone string) (ma.Multiaddr, error)

                  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 whether a Multiaddr starts with an IPv6 link-local multiaddress (with zero or one leading zone). These addresses are non routable.

                        func IsIPLoopback

                        func IsIPLoopback(m ma.Multiaddr) bool

                          IsIPLoopback returns whether a Multiaddr starts with a "Loopback" IP address This means either /ip4/127.*.*.*/*, /ip6/::1/*, or /ip6/::ffff:127.*.*.*.*/*, or /ip6zone/<any value>/ip6/<one of the preceding ip6 values>/*

                          func IsIPUnspecified

                          func IsIPUnspecified(m ma.Multiaddr) bool

                            IsIPUnspecified returns whether a Multiaddr starts with an Unspecified IP address This means either /ip4/0.0.0.0/* or /ip6/::/*

                            func IsPrivateAddr

                            func IsPrivateAddr(a ma.Multiaddr) bool

                              IsPrivateAddr returns true if the IP part of the mutiaddr is in a private network

                              func IsPublicAddr

                              func IsPublicAddr(a ma.Multiaddr) bool

                                IsPublicAddr retruns true if the IP part of the multiaddr is a publicly routable address

                                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 NetListener

                                  func NetListener(l Listener) net.Listener

                                    NetListener turns this Listener into a net.Listener.

                                    * Connections returned from Accept implement multiaddr/net Conn. * Calling WrapNetListener on the net.Listener returned by this function will

                                    return the original (underlying) multiaddr/net Listener.
                                    

                                    func RegisterNetCodec

                                    func RegisterNetCodec(a *NetCodec)

                                      RegisterNetCodec adds a new NetCodec to the default codecs.

                                      func ToIP

                                      func ToIP(addr ma.Multiaddr) (net.IP, error)

                                        ToIP converts a Multiaddr to a net.IP when possible

                                        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) RegisterFromNetAddr

                                                func (cm *CodecMap) RegisterFromNetAddr(from FromNetAddrFunc, networks ...string)

                                                  RegisterFromNetAddr registers a conversion from net.Addr instances to multiaddrs

                                                  func (*CodecMap) RegisterNetCodec

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

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

                                                    func (*CodecMap) RegisterToNetAddr

                                                    func (cm *CodecMap) RegisterToNetAddr(to ToNetAddrFunc, protocols ...string)

                                                      RegisterToNetAddr registers a conversion from multiaddrs to net.Addr instances

                                                      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.

                                                              This function does it's best to avoid "hiding" methods exposed by the wrapped type. Guarantees:

                                                              * If the wrapped connection exposes the "half-open" closer methods

                                                              (CloseWrite, CloseRead), these will be available on the wrapped connection
                                                              via type assertions.
                                                              

                                                              * If the wrapped connection is a UnixConn, IPConn, TCPConn, or UDPConn, all

                                                              methods on these wrapped connections will be available via type assertions.
                                                              

                                                              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 {
                                                                      	// 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.

                                                                              Deprecated: Unfortunately, these mappings aren't one to one. This abstraction assumes that multiple "networks" can map to a single multiaddr protocol but not the reverse. For example, this abstraction supports `tcp6, tcp4, tcp -> /tcp/` really well but doesn't support `ip -> {/ip4/, /ip6/}`.

                                                                              Please use `RegisterFromNetAddr` and `RegisterToNetAddr` directly.

                                                                              type PacketConn

                                                                              type PacketConn interface {
                                                                              	net.PacketConn
                                                                              
                                                                              	LocalMultiaddr() ma.Multiaddr
                                                                              
                                                                              	ReadFromMultiaddr(b []byte) (int, ma.Multiaddr, error)
                                                                              	WriteToMultiaddr(b []byte, maddr ma.Multiaddr) (int, 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