Documentation
¶
Overview ¶
Package dns provides an embedded DNS server for Gopherstack that resolves synthetic AWS-style hostnames (e.g. my-cluster.abc.us-east-1.cache.amazonaws.com) back to a configured IP address (typically 127.0.0.1). It also supports per-record values for A, CNAME, and AAAA records via RegisterRecord.
Usage:
srv, err := dns.New(dns.Config{ListenAddr: ":10053", ResolveIP: "127.0.0.1"})
srv.Register("my-cluster.abc.us-east-1.cache.amazonaws.com")
srv.RegisterRecord("www.example.com", "A", []string{"1.2.3.4"})
if err := srv.Start(ctx); err != nil { ... }
defer srv.Stop()
Index ¶
- Constants
- Variables
- func DefaultTransparentSuffixes() []string
- func ResolvConfUpstreams(path string) []string
- func SyntheticHostname(resourceID, randomSuffix, region, serviceType string) string
- type Config
- type Interceptor
- type Server
- func (s *Server) Deregister(hostname string)
- func (s *Server) IsRegistered(hostname string) bool
- func (s *Server) Owns(hostname string) bool
- func (s *Server) Register(hostname string)
- func (s *Server) RegisterRecord(hostname, recordType string, values []string)
- func (s *Server) SetInterceptor(i Interceptor)
- func (s *Server) Start(ctx context.Context) error
- func (s *Server) Stop() error
- type TransparentConfig
Constants ¶
const DefaultListenAddr = ":10053"
DefaultListenAddr is the default UDP/TCP address the DNS server binds to.
const DefaultReadTimeout = 5 * time.Second
DefaultReadTimeout is the read timeout for the underlying DNS server.
const DefaultResolveIP = "127.0.0.1"
DefaultResolveIP is the IP address returned for every registered hostname.
const DefaultWriteTimeout = 5 * time.Second
DefaultWriteTimeout is the write timeout for the underlying DNS server.
Variables ¶
var ErrIPv4Required = errors.New("resolve IP must be an IPv4 address")
ErrIPv4Required is returned when the configured resolve IP is not an IPv4 address.
var ErrInvalidResolveIP = errors.New("invalid resolve IP")
ErrInvalidResolveIP is returned when the configured resolve IP cannot be parsed.
Functions ¶
func DefaultTransparentSuffixes ¶
func DefaultTransparentSuffixes() []string
DefaultTransparentSuffixes lists the real AWS endpoint zones answered in transparent mode.
func ResolvConfUpstreams ¶
ResolvConfUpstreams returns the nameservers (host:port) from a resolv.conf file.
func SyntheticHostname ¶
SyntheticHostname generates an AWS-style synthetic hostname for a resource. serviceType is one of: "cache", "rds", "redshift", "es".
Types ¶
type Config ¶
type Config struct {
// Logger is an optional structured logger.
Logger *slog.Logger
// ListenAddr is the host:port to bind (default ":10053").
ListenAddr string
// ResolveIP is the IP address returned for every registered name (default "127.0.0.1").
ResolveIP string
// Transparent enables real-AWS-endpoint interception and upstream forwarding.
Transparent TransparentConfig
}
Config holds the configuration for the embedded DNS server.
type Interceptor ¶
type Interceptor interface {
Intercept(src net.Addr, req *dns.Msg, local func() *dns.Msg) *dns.Msg
}
Interceptor sees every query before the static records do. local computes the static answer; returning nil falls back to it.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an embedded DNS server that answers A queries for registered synthetic hostnames with a fixed IP address.
func New ¶
New creates a new Server with the given config. Zero-value Config fields are filled with defaults.
func (*Server) Deregister ¶
Deregister removes a hostname from the set the server will resolve. It clears both simple registrations (Register) and typed records (RegisterRecord). Calls are safe for concurrent use.
func (*Server) IsRegistered ¶
IsRegistered reports whether the hostname is registered.
func (*Server) Register ¶
Register adds a hostname to the set of names the server will resolve. The trailing dot required by DNS is added automatically. Hostnames are stored in lower-case so lookups are case-insensitive. Calls are safe for concurrent use.
func (*Server) RegisterRecord ¶
RegisterRecord stores per-record typed values for a hostname. recordType must be one of "A", "CNAME", "AAAA", or "ALIAS". Multiple calls with the same hostname and recordType append values. Calls are safe for concurrent use.
func (*Server) SetInterceptor ¶
func (s *Server) SetInterceptor(i Interceptor)
SetInterceptor installs (or, with nil, removes) the query interceptor.
type TransparentConfig ¶
type TransparentConfig struct {
// Suffixes are zones whose names resolve to ResolveIP; empty disables the mode.
Suffixes []string
// Skip lists names (or zones) that always resolve upstream, e.g. "sts.amazonaws.com".
Skip []string
// Upstreams are host:port resolvers; empty means /etc/resolv.conf.
Upstreams []string
}
TransparentConfig makes the server answer real AWS endpoint names with ResolveIP and forward every other unowned name to an upstream resolver.
Source Files
Directories