externalip

README

Go External IP

A Golang library to get your external ip from multiple services.

TODO

• Unit-Tests + CI (Travis);
• Design/Implement STUNSource, more info:
  • RFC 3489;
  • RFC 5389;

Docs

https://godoc.org/github.com/GlenDC/go-external-ip

Usage

Using the library can as simple as the following (runnable) example:

package main

import (
    "fmt"
    "github.com/glendc/go-external-ip"
)

func main() {
    // Create the default consensus,
    // using the default configuration and no logger.
    consensus := externalip.DefaultConsensus(nil, nil)
    // Get your IP,
    // which is never <nil> when err is <nil>.
    ip, err := consensus.ExternalIP()
    if err == nil {
        fmt.Println(ip.String()) // print IPv4/IPv6 in string format
    }
}

Please read the documentation for more information.

exip

This library also comes with a standalone command line application, which can be used to get your external IP, directly from your terminal.

install

$ go install github.com/glendc/go-external-ip/cmd/exip

usage

$ exip -h
Retrieve your external IP.

Usage:
    exip [flags]

Flags:
  -h help
    	show this usage message
  -t duration
    	consensus's voting timeout (default 5s)
  -v	log errors to STDERR, when defined

Documentation

Index

• Variables
• func NewLogger(w io.Writer) *log.Logger
• type Consensus
  • func DefaultConsensus(cfg *ConsensusConfig, logger *log.Logger) *Consensus
  • func NewConsensus(cfg *ConsensusConfig, logger *log.Logger) *Consensus
  • func (c *Consensus) AddVoter(source Source, weight uint) error
  • func (c *Consensus) ExternalIP() (net.IP, error)
• type ConsensusConfig
  • func DefaultConsensusConfig() *ConsensusConfig
  • func (cfg *ConsensusConfig) WithTimeout(timeout time.Duration) *ConsensusConfig
• type ContentParser
• type HTTPSource
  • func NewHTTPSource(url string) *HTTPSource
  • func (s *HTTPSource) IP(timeout time.Duration, logger *log.Logger) (net.IP, error)
  • func (s *HTTPSource) WithParser(parser ContentParser) *HTTPSource
• type InvalidIPError
  • func (err InvalidIPError) Error() string
• type Source

Variables

var (
	// ErrNoIP is returned by the Consensus when no vote was casted successfully
	ErrNoIP = errors.New("no IP could be found")
	// ErrInsufficientWeight is returned when a voter's weight is invalid
	ErrInsufficientWeight = errors.New("a voter's weight has to be at least 1")
	// ErrNoSource is returned when a voter is added,
	// which doesn't have a source specified
	ErrNoSource = errors.New("no voter's source given")
)

Functions

func NewLogger

func NewLogger(w io.Writer) *log.Logger

NewLogger returns a new standard logger, with a given writer. if w is <nil>, all logs will be discarded.

Types

type Consensus

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

Consensus the type at the center of this library, and is the main entry point for users. Its `ExternalIP` method allows you to ask for your ExternalIP, influenced by all its added voters.

func DefaultConsensus

func DefaultConsensus(cfg *ConsensusConfig, logger *log.Logger) *Consensus

DefaultConsensus returns a consensus filled with default and recommended HTTPSources. TLS-Protected providers get more power, compared to plain-text providers.

func NewConsensus

func NewConsensus(cfg *ConsensusConfig, logger *log.Logger) *Consensus

NewConsensus creates a new Consensus, with no sources. When the given cfg is <nil>, the `DefaultConsensusConfig` will be used.

func (*Consensus) AddVoter

func (c *Consensus) AddVoter(source Source, weight uint) error

AddVoter adds a voter to this consensus. The source cannot be <nil> and the weight has to be of a value of 1 or above.

func (*Consensus) ExternalIP

func (c *Consensus) ExternalIP() (net.IP, error)

ExternalIP requests asynchronously the externalIP from all added voters, returning the IP which received the most votes. The returned IP will always be valid, in case the returned error is <nil>.

type ConsensusConfig

type ConsensusConfig struct {
	Timeout time.Duration
}

ConsensusConfig is used to configure the Consensus, while creating it.

func DefaultConsensusConfig

func DefaultConsensusConfig() *ConsensusConfig

DefaultConsensusConfig returns the ConsensusConfig, with the default values:

• Timeout: 30 seconds;

func (*ConsensusConfig) WithTimeout

func (cfg *ConsensusConfig) WithTimeout(timeout time.Duration) *ConsensusConfig

WithTimeout sets the voting timeout of this config, returning the config itself at the end, to allow for chaining

type ContentParser

type ContentParser func(string) (string, error)

ContentParser can be used to add a parser to an HTTPSource to parse the raw content returned from a website, and return the IP. Spacing before and after the IP will be trimmed by the Consensus.

type HTTPSource

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

HTTPSource is the default source, to get the external IP from. It does so by requesting the IP from a URL, via an HTTP GET Request.

func NewHTTPSource

func NewHTTPSource(url string) *HTTPSource

NewHTTPSource creates a HTTP Source object, which can be used to request the (external) IP from. The Default HTTP Client will be used if no client is given.

func (*HTTPSource) IP

func (s *HTTPSource) IP(timeout time.Duration, logger *log.Logger) (net.IP, error)

IP implements Source.IP

func (*HTTPSource) WithParser

func (s *HTTPSource) WithParser(parser ContentParser) *HTTPSource

WithParser sets the parser value as the value to be used by this HTTPSource, and returns the pointer to this source, to allow for chaining.

type InvalidIPError

type InvalidIPError string

InvalidIPError is returned when an value returned is invalid. This error should be returned by the source itself.

func (InvalidIPError) Error

func (err InvalidIPError) Error() string

Error implements error.Error

type Source

type Source interface {
	// IP returns IPv4/IPv6 address in a non-error case
	// net.IP should never be <nil> when error is <nil>
	// It is recommended that the IP function times out,
	// if no result could be found, after the given timeout duration.
	IP(timeout time.Duration, logger *log.Logger) (net.IP, error)
}

Source defines the part of a voter which gives the actual voting value (IP).