whois

README

Whois

go get github.com/domainr/whois

Whois client for Go (golang), inspired by Ruby Whois. Currently in production use at Domainr.

Design

func whois.Whois(query string) *whois.Record  // Fetches and returns a fully-parsed whois.Record

request = whois.NewRequest(query)             // Returns a prepared whois.Request
response = whois.DefaultClient.Fetch(request) // Fetches the request, returns a whois.Response
record = response.Parse()                     // (not implemented yet) Parses the response, returns a whois.Record

whois.Request  // represents a qualified whois request, including server, URL, and request body
whois.Response // intermediate record, raw response from a whois server for a given query
whois.Record   // parsed whois response; structured data

Logic

query := "domai.nr"
request, err := whois.NewRequest(query)
response, err := whois.DefaultClient.Fetch(request)
record, err := response.Parse() // not implemented yet
if record.Refer != "" {
  response = whois.FetchRefer(record)
}

TODO

• Create whois.Client
• Embed an http.Client in whois.Client to reuse state
• Implementations for known HTTP-based whois servers
• Parsers

Credits

This code is made available under an MIT license. See LICENSE for more information.

© 2014 nb.io, LLC

Documentation

Index

• Constants
• Variables
• func BindAdapter(s Adapter, names ...string)
• func Server(query string) (string, string, error)
• type Adapter
• type Client
  • func NewClient(timeout time.Duration) *Client
  • func (c *Client) Fetch(req *Request) (*Response, error)
  • func (c *Client) FetchContext(ctx context.Context, req *Request) (*Response, error)
• type FetchError
  • func (f *FetchError) Error() string
• type Record
• type Request
  • func NewRequest(query string) (*Request, error)
  • func (req *Request) Adapter() Adapter
  • func (req *Request) Prepare() error
• type Response
  • func Fetch(query string) (*Response, error)
  • func NewResponse(query, host string) *Response
  • func ReadMIME(r io.Reader) (*Response, error)
  • func ReadMIMEFile(path string) (*Response, error)
  • func (res *Response) Adapter() Adapter
  • func (res *Response) Checksum() string
  • func (res *Response) ContentType() string
  • func (res *Response) DetectCharset()
  • func (res *Response) DetectContentType(ct string)
  • func (res *Response) Encoding() (encoding.Encoding, error)
  • func (res *Response) Header() http.Header
  • func (res *Response) Reader() (io.Reader, error)
  • func (res *Response) String() string
  • func (res *Response) Text() ([]byte, error)
  • func (res *Response) WriteMIME(w io.Writer) error

Constants

const (
	// DefaultTimeout sets the maximum lifetime of whois requests.
	DefaultTimeout = 30 * time.Second

	// DefaultReadLimit sets the maximum bytes a client will attempt to read from a connection.
	DefaultReadLimit = 1 << 20 // 1 MB
)

const (
	// IANA is the default whois server for TLDs.
	IANA = "whois.iana.org"
)

Variables

var DefaultAdapter = &defaultAdapter{}

DefaultAdapter is the default Adapter for most whois servers.

var DefaultClient = NewClient(DefaultTimeout)

DefaultClient represents a shared whois client with a default timeout, HTTP transport, and dialer.

var ErrURLNotSupported = errors.New("URL not supported")

ErrURLNotSupported is returned when an adapter cannot support a given request.

Functions

func BindAdapter

func BindAdapter(s Adapter, names ...string)

BindAdapter globally associates an Adapter with given hostname(s).

func Server

func Server(query string) (string, string, error)

Server returns the whois server and optional URL for a given query. Returns an error if it cannot resolve query to any known host.

Types

type Adapter

type Adapter interface {
	// Prepare performs any server-specific modifications of the Request.
	Prepare(*Request) error

	// Text returns the UTF-8 text of the Response body, stripping off any
	// excess data, (e.g. HTML) from a web response.
	Text(*Response) ([]byte, error)
}

Adapter contains server-specific code for retrieving and parsing whois data.

type Client

type Client struct {
	Dial        func(string, string) (net.Conn, error)                  // Deprecated, use DialContext instead
	DialContext func(context.Context, string, string) (net.Conn, error) // Only used for port 43 (whois) requests, not HTTP(S)
	HTTPClient  *http.Client                                            // If nil, http.DefaultClient will be used
	Timeout     time.Duration                                           // Deprecated (use a Context instead)
}

Client represents a whois client. It contains an http.Client, for executing some whois Requests.

func NewClient

func NewClient(timeout time.Duration) *Client

NewClient creates and initializes a new Client with the specified timeout.

func (*Client) Fetch

func (c *Client) Fetch(req *Request) (*Response, error)

Fetch sends the Request to a whois server.

func (*Client) FetchContext

func (c *Client) FetchContext(ctx context.Context, req *Request) (*Response, error)

FetchContext sends the Request to a whois server. If ctx cancels or times out before the request completes, it will return an error.

type FetchError

type FetchError struct {
	Err  error
	Host string
}

FetchError reports the underlying error and includes the target host of the fetch operation.

func (*FetchError) Error

func (f *FetchError) Error() string

Error implements the error interface.

type Record

type Record struct {
}

Record represents a parsed whois response.

type Request

type Request struct {
	Query string
	Host  string
	URL   string
	Body  []byte
}

Request represents a whois request.

func NewRequest

func NewRequest(query string) (*Request, error)

NewRequest returns a prepared Request ready to fetch. On error, returns a nil Request and the error.

func (*Request) Adapter

func (req *Request) Adapter() Adapter

Adapter returns an appropriate Adapter for the Request.

func (*Request) Prepare

func (req *Request) Prepare() error

Prepare prepares a Request with an appropriate Adapter. First resolves whois server in req.Host if not already set. Returns any errors.

type Response

type Response struct {
	// Query and Host are copied from the Request.
	Query string
	Host  string

	// FetchedAt is the date and time the response was fetched from the server.
	FetchedAt time.Time

	// MediaType and Charset hold the MIME-type and character set of the response body.
	MediaType string
	Charset   string

	// Body contains the raw bytes of the network response (minus HTTP headers).
	Body []byte
}

Response represents a whois response from a server.

func Fetch

func Fetch(query string) (*Response, error)

Fetch queries a whois server and returns a Response.

func NewResponse

func NewResponse(query, host string) *Response

NewResponse initializes a new whois response.

func ReadMIME

func ReadMIME(r io.Reader) (*Response, error)

ReadMIME reads a MIME-formatted representation of the response into a Response.

func ReadMIMEFile

func ReadMIMEFile(path string) (*Response, error)

ReadMIMEFile opens and reads a response MIME file at path. Returns any errors.

func (*Response) Adapter

func (res *Response) Adapter() Adapter

Adapter returns an appropriate Adapter for the Response.

func (*Response) Checksum

func (res *Response) Checksum() string

Checksum returns a hex-encoded SHA-1 checksum of the response Body.

func (*Response) ContentType

func (res *Response) ContentType() string

ContentType returns an RFC 2045 compatible internet media type string.

func (*Response) DetectCharset

func (res *Response) DetectCharset()

DetectCharset returns best guess for the reesponse body character set.

func (*Response) DetectContentType

func (res *Response) DetectContentType(ct string)

DetectContentType detects and sets the response content type and charset.

func (*Response) Encoding

func (res *Response) Encoding() (encoding.Encoding, error)

Encoding returns an Encoding for the response body.

func (*Response) Header

func (res *Response) Header() http.Header

Header returns a stringproto header representing the response.

func (*Response) Reader

func (res *Response) Reader() (io.Reader, error)

Reader returns a new UTF-8 io.Reader for the response body.

func (*Response) String

func (res *Response) String() string

String returns a string representation of the response text. Returns an empty string if an error occurs.

func (*Response) Text

func (res *Response) Text() ([]byte, error)

Text returns the UTF-8 text content from the response body or any errors that occur while decoding.

func (*Response) WriteMIME

func (res *Response) WriteMIME(w io.Writer) error

WriteMIME writes a MIME-formatted representation of the response to an io.Writer.