ara

README

ara

Package ara provides a dialer with customizable resolver.

It can be used with http.Client and http.Transport to alter host lookups. For example, with a custom resolver that maps google.com to 127.0.0.1, you can get httpClient.Get("http://google.com") to connect the localhost.

Example

server := &http.Server{
    Addr: "127.0.0.1:80",
    Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Alo?"))
    })
}
go server.ListenAndServe()
client := ara.NewClient(ara.NewCustomResolver(map[string][]string{"example.com": {"127.0.0.1"}}))
res, _ := client.Get("http://example.com")
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
// Output: Alo?

Documentation

Overview

Package ara provides a dialer with customizable resolver.

It can be used with http.Client and http.Transport to alter host lookups. For example, with a custom resolver that maps google.com to 127.0.0.1, you can get httpClient.Get("http://google.com") to connect the localhost.

Index

• func NewClient(r Resolver) *http.Client
• func NewTransport(r Resolver) *http.Transport
• type Dialer
  • func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)
• type Resolver
  • func NewCustomResolver(hosts map[string][]string) Resolver

Examples

• Dialer
• NewClient
• NewTransport

Functions

func NewClient

func NewClient(r Resolver) *http.Client

NewClient returns a *http.Client that uses the given resolver while dialing.

Example

package main

import (
	"context"
	"fmt"
	"github.com/cevatbarisyilmaz/ara"
	"io/ioutil"
	"log"
	"net/http"
)

func main() {
	server := &http.Server{Addr: "127.0.0.1:80", Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_, err := w.Write([]byte("Alo?"))
		if err != nil {
			log.Fatal(err)
		}
	})}
	go func() {
		_ = server.ListenAndServe()
	}()
	defer func() {
		err := server.Shutdown(context.Background())
		if err != nil {
			log.Fatal(err)
		}
	}()
	client := ara.NewClient(ara.NewCustomResolver(map[string][]string{"example.com": {"127.0.0.1"}}))
	res, _ := client.Get("http://example.com")
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(string(body))
}

Output:

Alo?

func NewTransport

func NewTransport(r Resolver) *http.Transport

NewTransport returns a *http.Transport that uses the given resolver while dialing.

Example

package main

import (
	"context"
	"fmt"
	"github.com/cevatbarisyilmaz/ara"
	"io/ioutil"
	"log"
	"net/http"
)

func main() {
	server := &http.Server{Addr: "127.0.0.1:80", Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_, err := w.Write([]byte("Alo?"))
		if err != nil {
			log.Fatal(err)
		}
	})}
	go func() {
		_ = server.ListenAndServe()
	}()
	defer func() {
		err := server.Shutdown(context.Background())
		if err != nil {
			log.Fatal(err)
		}
	}()
	client := &http.Client{
		Transport: ara.NewTransport(ara.NewCustomResolver(map[string][]string{"example.com": {"127.0.0.1"}})),
	}
	res, _ := client.Get("http://example.com")
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(string(body))
}

Output:

Alo?

Types

type Dialer

type Dialer struct {
	// Timeout is the maximum amount of time a dial will wait for
	// a connect to complete. If Deadline is also set, it may fail
	// earlier.
	//
	// The default is no timeout.
	//
	// When using TCP and dialing a host name with multiple IP
	// addresses, the timeout may be divided between them.
	//
	// With or without a timeout, the operating system may impose
	// its own earlier timeout. For instance, TCP timeouts are
	// often around 3 minutes.
	Timeout time.Duration

	// Deadline is the absolute point in time after which dials
	// will fail. If Timeout is set, it may fail earlier.
	// Zero means no deadline, or dependent on the operating system
	// as with the Timeout option.
	Deadline time.Time

	// LocalAddr is the local address to use when dialing an
	// address. The address must be of a compatible type for the
	// network being dialed.
	// If nil, a local address is automatically chosen.
	LocalAddr net.Addr

	// FallbackDelay specifies the length of time to wait before
	// spawning a RFC 6555 Fast Fallback connection. That is, this
	// is the amount of time to wait for IPv6 to succeed before
	// assuming that IPv6 is misconfigured and falling back to
	// IPv4.
	//
	// If zero, a default delay of 300ms is used.
	// A negative value disables Fast Fallback support.
	FallbackDelay time.Duration

	// KeepAlive specifies the interval between keep-alive
	// probes for an active network connection.
	// If zero, keep-alive probes are sent with a default value
	// (currently 15 seconds), if supported by the protocol and operating
	// system. Network protocols or operating systems that do
	// not support keep-alives ignore this field.
	// If negative, keep-alive probes are disabled.
	KeepAlive time.Duration

	// Resolver optionally specifies an alternate resolver to use.
	Resolver Resolver

	// If Control is not nil, it is called after creating the network
	// connection but before actually dialing.
	//
	// Network and address parameters passed to Control method are not
	// necessarily the ones passed to Dial. For example, passing "tcp" to Dial
	// will cause the Control function to be called with "tcp4" or "tcp6".
	Control func(network, address string, c syscall.RawConn) error
	// contains filtered or unexported fields
}

Dialer is a partial replacement for net.Dialer but it still uses net.Dialer internally.

Unlike net.Dialer, it accepts an actual customizable Resolver.

A Dialer contains options for connecting to an address.

The zero value for each field is equivalent to dialing without that option.

Example

package main

import (
	"context"
	"fmt"
	"github.com/cevatbarisyilmaz/ara"
	"io/ioutil"
	"log"
	"net"
)

func main() {
	go func() {
		listener, err := net.Listen("tcp", "127.0.0.1:1919")
		if err != nil {
			log.Fatal(err)
		}
		conn, err := listener.Accept()
		if err != nil {
			log.Fatal(err)
		}
		_, err = conn.Write([]byte("Alo?"))
		if err != nil {
			log.Fatal(err)
		}
		err = conn.Close()
		if err != nil {
			log.Fatal(err)
		}
		err = listener.Close()
		if err != nil {
			log.Fatal(err)
		}
	}()
	dialer := ara.Dialer{
		Resolver: ara.NewCustomResolver(map[string][]string{"example.com": {"127.0.0.1"}}),
	}
	conn, err := dialer.DialContext(context.Background(), "tcp", "example.com:1919")
	if err != nil {
		log.Fatal(err)
	}
	res, err := ioutil.ReadAll(conn)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(res))
}

Output:

Alo?

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext connects to the address on the named network using the provided context.

The provided Context must be non-nil. If the context expires before the connection is complete, an error is returned. Once successfully connected, any expiration of the context will not affect the connection.

When using TCP, and the host in the address parameter resolves to multiple network addresses, any dial timeout (from d.Timeout or ctx) is spread over each consecutive dial, such that each is given an appropriate fraction of the time to connect. For example, if a host has 4 IP addresses and the timeout is 1 minute, the connect to each single address will be given 15 seconds to complete before trying the next one.

See func net.Dial for a description of the network and address parameters.

type Resolver

type Resolver interface {
	LookupHost(ctx context.Context, host string) ([]string, error)
}

A Resolver looks up hosts.

func NewCustomResolver

func NewCustomResolver(hosts map[string][]string) Resolver

NewCustomResolver returns a resolver that will give priority to given host/ip mappings on lookups.

If a host is not part of the given mapping, it will use the net.DefaultResolver.

hosts is a map of addresses for a host name, like map[host][]address.