From 1c4b9a62deda1b2fe54c0a7f8f842b1c8e390087 Mon Sep 17 00:00:00 2001 From: Hector Sanjuan Date: Thu, 16 Mar 2017 16:07:42 +0100 Subject: [PATCH] README/docs: Improved README, make golint happy License: MIT Signed-off-by: Hector Sanjuan --- README.md | 27 ++++++++++++++++++++++++--- convert.go | 10 ++++++---- ip.go | 3 ++- net.go | 6 ++++++ registry.go | 24 +++++++++++++++++++----- 5 files changed, 57 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 94885c7..15a8a99 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,12 @@ [![](https://img.shields.io/badge/project-multiformats-blue.svg?style=flat-square)](https://github.com/multiformats/multiformats) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](https://webchat.freenode.net/?channels=%23ipfs) [![](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) +[![GoDoc](https://godoc.org/github.com/multiformats/go-multiaddr-net?status.svg)](https://godoc.org/github.com/multiformats/go-multiaddr-net) [![Travis CI](https://img.shields.io/travis/multiformats/go-multiaddr-net.svg?style=flat-square&branch=master)](https://travis-ci.org/multiformats/go-multiaddr-net) -[![codecov.io](https://img.shields.io/codecov/c/github/multiformats/go-multiaddr-net.svg?style=flat-square&branch=master)](https://codecov.io/github/multiformats/go-multiaddr-net?branch=master) -> multiaddr net tools + + +> Multiaddress net tools This package provides [Multiaddr](https://github.com/multiformats/go-multiaddr) specific versions of common functions in [stdlib](https://github.com/golang/go/tree/master/src)'s `net` package. This means wrappers of standard net symbols like `net.Dial` and `net.Listen`, as well as conversion to and from `net.Addr`. @@ -22,13 +24,32 @@ as conversion to and from `net.Addr`. ## Install +`go-multiaddr-net` is a standard Go module which can be installed with: + ```sh go get github.com/multiformats/go-multiaddr-net ``` +Note that `go-multiaddr-net` is packaged with Gx, so it is recommended to use Gx to install and use it (see Usage section). + + ## Usage -See the docs: +This module is packaged with [Gx](https://github.com/whyrusleeping/gx). In order to use it in your own project do: + +```sh +go get -u github.com/whyrusleeping/gx +go get -u github.com/whyrusleeping/gx-go +cd +gx init +gx import github.com/multiformats/go-multiaddr-net +gx install --global +gx-go --rewrite +``` + +Please check [Gx](https://github.com/whyrusleeping/gx) and [Gx-go](https://github.com/whyrusleeping/gx-go) documentation for more information. + +For further usage, see the docs: - `multiaddr/net`: https://godoc.org/github.com/multiformats/go-multiaddr-net - `multiaddr`: https://godoc.org/github.com/multiformats/go-multiaddr diff --git a/convert.go b/convert.go index 0dfc258..973820c 100644 --- a/convert.go +++ b/convert.go @@ -15,6 +15,7 @@ func FromNetAddr(a net.Addr) (ma.Multiaddr, error) { return defaultCodecs.FromNetAddr(a) } +// FromNetAddr converts a net.Addr to Multiaddress. func (cm *CodecMap) FromNetAddr(a net.Addr) (ma.Multiaddr, error) { if a == nil { return nil, fmt.Errorf("nil multiaddr") @@ -34,6 +35,7 @@ func ToNetAddr(maddr ma.Multiaddr) (net.Addr, error) { return defaultCodecs.ToNetAddr(maddr) } +// ToNetAddr converts a Multiaddress to a standard net.Addr. func (cm *CodecMap) ToNetAddr(maddr ma.Multiaddr) (net.Addr, error) { protos := maddr.Protocols() final := protos[len(protos)-1] @@ -105,7 +107,7 @@ func DialArgs(m ma.Multiaddr) (string, string, error) { return network, host, nil } -func parseTcpNetAddr(a net.Addr) (ma.Multiaddr, error) { +func parseTCPNetAddr(a net.Addr) (ma.Multiaddr, error) { ac, ok := a.(*net.TCPAddr) if !ok { return nil, errIncorrectNetAddr @@ -127,7 +129,7 @@ func parseTcpNetAddr(a net.Addr) (ma.Multiaddr, error) { return ipm.Encapsulate(tcpm), nil } -func parseUdpNetAddr(a net.Addr) (ma.Multiaddr, error) { +func parseUDPNetAddr(a net.Addr) (ma.Multiaddr, error) { ac, ok := a.(*net.UDPAddr) if !ok { return nil, errIncorrectNetAddr @@ -149,7 +151,7 @@ func parseUdpNetAddr(a net.Addr) (ma.Multiaddr, error) { return ipm.Encapsulate(udpm), nil } -func parseIpNetAddr(a net.Addr) (ma.Multiaddr, error) { +func parseIPNetAddr(a net.Addr) (ma.Multiaddr, error) { ac, ok := a.(*net.IPAddr) if !ok { return nil, errIncorrectNetAddr @@ -157,7 +159,7 @@ func parseIpNetAddr(a net.Addr) (ma.Multiaddr, error) { return FromIP(ac.IP) } -func parseIpPlusNetAddr(a net.Addr) (ma.Multiaddr, error) { +func parseIPPlusNetAddr(a net.Addr) (ma.Multiaddr, error) { ac, ok := a.(*net.IPNet) if !ok { return nil, errIncorrectNetAddr diff --git a/ip.go b/ip.go index 71a2db6..aabbb56 100644 --- a/ip.go +++ b/ip.go @@ -70,7 +70,8 @@ func IsIPLoopback(m ma.Multiaddr) bool { return false } -// IP6 Link Local addresses are non routable. The prefix is technically +// 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. diff --git a/net.go b/net.go index fd39fc0..b747339 100644 --- a/net.go +++ b/net.go @@ -1,3 +1,8 @@ +// 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`. package manet import ( @@ -90,6 +95,7 @@ func (d *Dialer) Dial(remote ma.Multiaddr) (Conn, error) { return d.DialContext(context.Background(), remote) } +// DialContext allows to provide a custom context to Dial(). func (d *Dialer) DialContext(ctx context.Context, remote ma.Multiaddr) (Conn, error) { // if a LocalAddr is specified, use it on the embedded dialer. if d.LocalAddr != nil { diff --git a/registry.go b/registry.go index 0b86c05..696a953 100644 --- a/registry.go +++ b/registry.go @@ -8,7 +8,10 @@ import ( ma "github.com/multiformats/go-multiaddr" ) +// FromNetAddrFunc is a generic function which converts a net.Addr to Multiaddress type FromNetAddrFunc func(a net.Addr) (ma.Multiaddr, error) + +// ToNetAddrFunc is a generic function which converts a Multiaddress to net.Addr type ToNetAddrFunc func(ma ma.Multiaddr) (net.Addr, error) var defaultCodecs *CodecMap @@ -22,6 +25,10 @@ func init() { defaultCodecs.RegisterNetCodec(ipnetAddrSpec) } +// 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). type CodecMap struct { codecs map[string]*NetCodec addrParsers map[string]FromNetAddrFunc @@ -29,6 +36,7 @@ type CodecMap struct { lk sync.Mutex } +// NewCodecMap initializes and returns a CodecMap object. func NewCodecMap() *CodecMap { return &CodecMap{ codecs: make(map[string]*NetCodec), @@ -37,6 +45,9 @@ func NewCodecMap() *CodecMap { } } +// 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 NetCodec struct { // NetAddrNetworks is an array of strings that may be returned // by net.Addr.Network() calls on addresses belonging to this type @@ -55,10 +66,13 @@ type NetCodec struct { Protocol ma.Protocol } +// RegisterNetCodec adds a new NetCodec to the default codecs. func RegisterNetCodec(a *NetCodec) { defaultCodecs.RegisterNetCodec(a) } +// RegisterNetCodec adds a new NetCodec to the CodecMap. This function is +// thread safe. func (cm *CodecMap) RegisterNetCodec(a *NetCodec) { cm.lk.Lock() defer cm.lk.Unlock() @@ -73,35 +87,35 @@ func (cm *CodecMap) RegisterNetCodec(a *NetCodec) { var tcpAddrSpec = &NetCodec{ ProtocolName: "tcp", NetAddrNetworks: []string{"tcp", "tcp4", "tcp6"}, - ParseNetAddr: parseTcpNetAddr, + ParseNetAddr: parseTCPNetAddr, ConvertMultiaddr: parseBasicNetMaddr, } var udpAddrSpec = &NetCodec{ ProtocolName: "udp", NetAddrNetworks: []string{"udp", "udp4", "udp6"}, - ParseNetAddr: parseUdpNetAddr, + ParseNetAddr: parseUDPNetAddr, ConvertMultiaddr: parseBasicNetMaddr, } var ip4AddrSpec = &NetCodec{ ProtocolName: "ip4", NetAddrNetworks: []string{"ip4"}, - ParseNetAddr: parseIpNetAddr, + ParseNetAddr: parseIPNetAddr, ConvertMultiaddr: parseBasicNetMaddr, } var ip6AddrSpec = &NetCodec{ ProtocolName: "ip6", NetAddrNetworks: []string{"ip6"}, - ParseNetAddr: parseIpNetAddr, + ParseNetAddr: parseIPNetAddr, ConvertMultiaddr: parseBasicNetMaddr, } var ipnetAddrSpec = &NetCodec{ ProtocolName: "ip+net", NetAddrNetworks: []string{"ip+net"}, - ParseNetAddr: parseIpPlusNetAddr, + ParseNetAddr: parseIPPlusNetAddr, ConvertMultiaddr: func(ma.Multiaddr) (net.Addr, error) { return nil, fmt.Errorf("converting ip+net multiaddr not supported") },