icannclient

README

ICANN API Client for Go

Automates downloading zone files from the ICANN API site

Runs all needed to download zone-files periodically -- via one call.

Automation Features

Renews the OAuth 2.0 JWT

A new JWT token can be issued (per IP Addr) every 2 minutes; and each token is valid for 24 hours. A separate instance keeps track of the JWT token to ensure that no API request takes place with an expired token.

Downloads approved TLDs every 48 hours

According to ICANN terms, each tld must be downloaded no more than once in 24 hours. Considering the large amount of information to process + the time it takes to prepare the results for a purpose (i.e. indexing), 48 hours is deemed to be the minimum time between downloads.

Config

Required args

The following variables must be set via the environment variables:

SALT_PHRASE.................................... this can be any word or phrase
ICANN_ACCOUNT_USERNAME........ usually the email used to setup the ICANN account
ICANN_ACCOUNT_PASSWORD........ ICANN account password
USER_AGENT...................................... user-agent in format: <product name> / <version> <comment>
APPROVED_TLDS............................... approved tld names, separated by comma (e.g. com,net)
HOURS_TO_WAIT_BETWEEN_DOWNLOADS............. hours to wait to download the same type of file (default is 24)

Please, note that SALT_PHRASE is not required; if blank, an empty salt-phrase will be used.

Essential args using the icann.env file

If the icann.env file exists in the install-directory, it will be used to read required args into environment variables (otherwise the machine or user-profile env vars will be used).

If a plain-text value is detected in the icann.env file, it will be encrypted on the first-run -- including that of the SALT_PHRASE. Any key/value can be omitted from the icann.env, provided the equivalent exists in the machine or user-profile environment.

Essential args without using the icann.env file

If the icann.env file does not exist, then the env vars are still expected to exist via that of the system or user-profile.

Usage

package main
import (
	icann "github.com/kambahr/go-icann-client"
)
func main() {

	icn := icann.NewIcannAPIClient()

	icn.CzdsAPI.Run()
}

Documentation

Overview

(c) Kamiar Bahri

(c) Kamiar Bahri

(c) Kamiar Bahri

(c) Kamiar Bahri

(c) Kamiar Bahri

Index

• Constants
• func ConsoleClearLastLine()
• func CreateHash(key string) string
• func DecryptLight(data []byte, passphrase string) ([]byte, error)
• func EncryptLight(data []byte, passphrase string) ([]byte, error)
• func FileOrDirExists(path string) bool
• func RemoveItemFromIntArry(s []interface{}, i int) []interface{}
• func SetEnvFromFile(envFile string) error
• type CzdsAPI
  • func (c *CzdsAPI) DownloadZoneFile(localFilePath string, downloadLink string, wg *sync.WaitGroup) (int, error)
  • func (c *CzdsAPI) ICANN() *IcannAPI
  • func (c *CzdsAPI) Run()
• type HTTPResult
• type ICzdsAPI
• type IIcannAPI
• type IcannAPI
  • func (i *IcannAPI) Authenticate()
  • func (i *IcannAPI) GetCommonHeaders() http.Header
  • func (i *IcannAPI) HTTPExec(method string, urlx string, hd http.Header, data []byte) HTTPResult
  • func (i *IcannAPI) Run()
• type IcannClient
  • func NewIcannAPIClient() *IcannClient
• type JWT
• type TeeWriter
  • func (wm *TeeWriter) Write(p []byte) (int, error)
• type ZoneFileStatus

Constants

const (
	GET  = "GET"
	HEAD = "HEAD"
	POST = "POST"
)

Functions

func ConsoleClearLastLine

func ConsoleClearLastLine()

func CreateHash

func CreateHash(key string) string

CreateHash --

func DecryptLight

func DecryptLight(data []byte, passphrase string) ([]byte, error)

DecryptLight --d

func EncryptLight

func EncryptLight(data []byte, passphrase string) ([]byte, error)

func FileOrDirExists

func FileOrDirExists(path string) bool

FileOrDirExists checks to see if a file or dir exist. Note that os.Stat(path) works for any path (file or directory).

func RemoveItemFromIntArry

func RemoveItemFromIntArry(s []interface{}, i int) []interface{}

func SetEnvFromFile

func SetEnvFromFile(envFile string) error

SetEnvFromFile read target key/val from the icann.env file. It encrypts plain-text values before returning.

Types

type CzdsAPI

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

CzdsAPI implements the ICzdsAPI interface.

func (*CzdsAPI) DownloadZoneFile

func (c *CzdsAPI) DownloadZoneFile(localFilePath string, downloadLink string, wg *sync.WaitGroup) (int, error)

DownloadZoneFile downloads a zone file from an assigned link.

func (*CzdsAPI) ICANN

func (c *CzdsAPI) ICANN() *IcannAPI

ICANN exposes the IcannAPI to outside callers (public).

func (*CzdsAPI) Run

func (c *CzdsAPI) Run()

Run will download the authorized zone files once every >24 hours.

type HTTPResult

type HTTPResult struct {
	StatusCode      int
	Error           error
	ResponseBody    []byte
	ResponseHeaders http.Header
}

type ICzdsAPI

type ICzdsAPI interface {
	DownloadZoneFile(localFilePath string, downloadLink string, wg *sync.WaitGroup) (int, error)
	ICANN() *IcannAPI
	Run()
}

ICzdsAPI is the interface for CzdsAPI.

type IIcannAPI

type IIcannAPI interface {
	Authenticate()
	HTTPExec(method string, url string, hd http.Header, data []byte) HTTPResult
	GetCommonHeaders() http.Header
	Run()
	// contains filtered or unexported methods
}

ICannAPI interface performs the basic funtions to interact with the ICANN's API.

type IcannAPI

type IcannAPI struct {

	// AppDataDir is the directory (on the volume) that zone files will be downloaded to.
	AppDataDir string

	// UserAgent is required for all ICANN API calls; its format is:
	// <name of you product> / <version> <comment about your product>
	UserAgent string

	// ICANN person account username.
	UserName string

	// Password is the ICANN person account password.
	Password string

	// ApprovedTLD is an array of TLDs e.g. com, net.
	ApprovedTLD []string

	// Authenticated is used by callers to get the status of the authentication.
	Authenticated bool

	// AccessToken is available to callers to use for Bearer in the Authorization header.
	AccessToken JWT

	HoursToWaitBetweenDownloads int
	// contains filtered or unexported fields
}

IcannAPI defines the structure of the IIcannAPI interface.

func (*IcannAPI) Authenticate

func (i *IcannAPI) Authenticate()

Authenticate calls the authenticate and retreives an access code, which can be used by the ICzdsAPI interface.

func (*IcannAPI) GetCommonHeaders

func (i *IcannAPI) GetCommonHeaders() http.Header

GetCommonHeaders gets the headers required by icann api.

func (*IcannAPI) HTTPExec

func (i *IcannAPI) HTTPExec(method string, urlx string, hd http.Header, data []byte) HTTPResult

HTTPExec is wrappter to make http calls.

func (*IcannAPI) Run

func (i *IcannAPI) Run()

Run renews the access token every 23 hours

type IcannClient

type IcannClient struct {
	IcannAPI IIcannAPI
	CzdsAPI  ICzdsAPI
}

func NewIcannAPIClient

func NewIcannAPIClient() *IcannClient

NewIcannAPIClient creates a new instance of the icann interface. It runs the authentication immediately.

type JWT

type JWT struct {
	Token           string
	DateTimeIssued  time.Time
	DateTimeExpires time.Time
}

type TeeWriter

type TeeWriter struct {
	TotalDownloaded uint64
	File            *os.File
	TempFilePath    string
	FileName        string
	TLDType         string
	StartTime       time.Time
}

TeeWriter defines the structure of the callback, to get status of the download in porgress.

func (*TeeWriter) Write

func (wm *TeeWriter) Write(p []byte) (int, error)

Write keeps track of the number of bytes written + the elapsed time; and writes the status to the console.

type ZoneFileStatus

type ZoneFileStatus struct {
	HTTPResult       HTTPResult
	OriginalFileName string // e.g. com.txt.gz
	FileLength       uint64
	TLDType          string // e.g. com
}