ipstack

README

ipstack

📡 ipstack is a helper package for calling the https://ipstack.com API. It includes type-safe response packets and a WorkerPool for asynchronous, once-only, lookup tasks

Installation

To install ipstack, simly run:

$ go get github.com/harwoeck/ipstack

Documentation

Overview

Package ipstack is a helper package for calling the https://ipstack.com API. It includes type-safe response packets and a WorkerPool for asynchronous, once-only, lookup tasks

Index

• Constants
• Variables
• type Client
  • func NewClient(accessKey string, httpsEnabled bool, timeout int) *Client
  • func (c *Client) Check(ip string) (r *Response, err error)
• type Logger
• type Response
• type WorkerFeedback
• type WorkerPool
  • func NewWorkerPool(config *WorkerPoolConfig, c *Client, fb WorkerFeedback) (wp *WorkerPool, err error)
  • func (wp *WorkerPool) Queue(ip string)
  • func (wp *WorkerPool) Shutdown()
• type WorkerPoolConfig
  • func NewDefaultWorkerPoolConfig() *WorkerPoolConfig

Constants

const (
	// DefaultClientTimeout is the recommended default for http timeouts, when
	// the external ipstack API is called
	DefaultClientTimeout = 5
)

Variables

var (
	// ErrFeedbackExistsFailed occurs when the provided implementation of
	// ipstack.WorkerFeedback.Exists returns an error.
	ErrFeedbackExistsFailed = "ipstack: WorkerPool: unable to check if ip already exists during feedback loop"
	// ErrAPIRequestFailed occurs when the external ipstack api returns an
	// error, or fails to meet the timeout requirements.
	ErrAPIRequestFailed = "ipstack: WorkerPool: error during api request"
	// ErrFeedbackCreateResponseFailed occurs when the provided implementation
	// of ipstack.WorkerFeedback.CreateResponse returns an error.
	ErrFeedbackCreateResponseFailed = "ipstack: WorkerPool: unable to create response during feedback loop"
)

Types

type Client

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

Client defines a single http client, which can be used to acces the external ipstack API

func NewClient

func NewClient(accessKey string, httpsEnabled bool, timeout int) *Client

NewClient initializes a new ipstack.Client which can access the external ipstack API in a typesafe way

func (*Client) Check

func (c *Client) Check(ip string) (r *Response, err error)

Check performs a single API call to the external ipstack API and returns the response object or any occurred errors

type Logger

type Logger interface {
	Info(msg string)
	Error(msg string, err error)
}

Logger defines a simple interface for logging info and error messages that occur during a Workers lifetime. The interface is chosen instead of a specific logging framework to decouple the package from other external dependencies and avoid stdout stderr logging

type Response

type Response struct {
	IP            string  `json:"ip"`
	Type          string  `json:"type"`
	ContinentCode string  `json:"continent_code"`
	ContinentName string  `json:"continent_name"`
	CountryCode   string  `json:"country_code"`
	CountryName   string  `json:"country_name"`
	RegionCode    string  `json:"region_code"`
	RegionName    string  `json:"region_name"`
	City          string  `json:"city"`
	ZIP           string  `json:"zip"`
	Latitude      float32 `json:"latitude"`
	Longitude     float32 `json:"longitude"`
	Location      struct {
		GeonameID int    `json:"geoname_id"`
		Capital   string `json:"capital"`
		Languages []struct {
			Code   string `json:"code"`
			Name   string `json:"name"`
			Native string `json:"native"`
		} `json:"languages"`
		CountryFlag             string `json:"country_flag"`
		CountryFlagEmoji        string `json:"country_flag_emoji"`
		CountryFlagEmojiUnicode string `json:"country_flag_emoji_unicode"`
		CallingCode             string `json:"calling_code"`
		IsEU                    bool   `json:"is_eu"`
	} `json:"location"`
	Timezone struct {
		ID               string `json:"id"`
		CurrentTime      string `json:"current_time"`
		GMTOffset        int    `json:"gmt_offset"`
		Code             string `json:"code"`
		IsDaylightSaving bool   `json:"is_daylight_saving"`
	} `json:"time_zone"`
	Currency struct {
		Code         string `json:"code"`
		Name         string `json:"name"`
		Plural       string `json:"plural"`
		Symbol       string `json:"symbol"`
		SymbolNative string `json:"symbol_native"`
	} `json:"currency"`
	Connection struct {
		ASN int    `json:"asn"`
		ISP string `json:"isp"`
	} `json:"connection"`
	Security struct {
		IsProxy     bool    `json:"is_proxy"`
		ProxyType   *string `json:"proxy_type"`
		IsCrawler   bool    `json:"is_crawler"`
		CrawlerName *string `json:"crawler_name"`
		CrawlerType *string `json:"crawler_type"`
		IsTor       bool    `json:"is_tor"`
		ThreatLevel string  `json:"threat_level"`
		ThreatType  *string `json:"threat_type"`
	}
}

Response defines a typesafe response object returned from the external ipstack API

type WorkerFeedback

type WorkerFeedback interface {
	Exists(ip string) (exists bool, err error)
	CreateResponse(ip string, r *Response) (err error)
}

WorkerFeedback is used to give single workers inside the ipstack.WorkerPool feedback about the way they should handle the ip address in question

type WorkerPool

type WorkerPool struct {
	Config *WorkerPoolConfig
	// contains filtered or unexported fields
}

WorkerPool represents a single ipstack.WorkerPool, which is able to perform ipstack IP Checks in a coordinated way across a fleet of goroutine workers. The pool increases performance and removes blocking calls to external APIs from your own goroutine

func NewWorkerPool

func NewWorkerPool(config *WorkerPoolConfig, c *Client, fb WorkerFeedback) (wp *WorkerPool, err error)

NewWorkerPool initializes a new WorkerPool instance. It performs runtime- checks for the passed arguments and starts all worker goroutines.

func (*WorkerPool) Queue

func (wp *WorkerPool) Queue(ip string)

Queue queues the passed ip into the internal buffered channel for unresolved IPs. Workers will dequeue it once they are ready. If a shutdown occurs before all IPs are dequeued, the shutdown caller will synchronously handle all remaining IPs

func (*WorkerPool) Shutdown

func (wp *WorkerPool) Shutdown()

Shutdown shutdowns all previously started workers and handles all remaining unresolved IPs synchronously before returing

type WorkerPoolConfig

type WorkerPoolConfig struct {
	QueueSize int
	Workers   int
	Log       Logger
}

WorkerPoolConfig represents a configuration for an ipstack.WorkerPool

func NewDefaultWorkerPoolConfig

func NewDefaultWorkerPoolConfig() *WorkerPoolConfig

NewDefaultWorkerPoolConfig returns a new ipstack.WorkerPoolConfig populated with default values and a dev/null logger implementation