Documentation
¶
Overview ¶
Package dns provides cached DNS resolution for scanorama.
It supports both forward lookups (hostname → []IP) and reverse lookups (IP → hostname) backed by the dns_cache database table. Every result — including negative ones — is stored so that repeated queries hit the database instead of the OS resolver.
TTL behavior ------------- Each cache row carries its own ttl_seconds value. Two TTLs are in play:
- TTL (default 1 h) — used for successful positive results.
- NegativeTTL (default 5 min) — used for NXDOMAIN / empty answers and resolver errors, so transient failures do not get pinned for an hour.
Both can be overridden at construction time via WithTTL / WithNegativeTTL.
Cache invalidation ------------------ Entries expire passively when their TTL window closes; the next lookup for that key then triggers a fresh network query. Two explicit invalidation methods are also provided:
- Invalidate(ctx, direction, key) — removes all rows for one key.
- InvalidateAll(ctx) — truncates the entire dns_cache table.
RefreshStale can be called from a background goroutine or scheduled job to proactively re-resolve entries whose TTL has already expired.
Concurrency ----------- Resolver is safe for concurrent use. A singleflight group ensures that simultaneous callers for the same key share one in-flight network lookup.
Index ¶
- Constants
- Variables
- type Direction
- type Option
- type Resolver
- func (r *Resolver) Invalidate(ctx context.Context, direction Direction, key string) error
- func (r *Resolver) InvalidateAll(ctx context.Context) error
- func (r *Resolver) LookupAddr(ctx context.Context, ip string) (string, error)
- func (r *Resolver) LookupHost(ctx context.Context, host string) ([]string, error)
- func (r *Resolver) RefreshStale(ctx context.Context) error
Constants ¶
const DefaultNegativeTTL = 5 * time.Minute
DefaultNegativeTTL is used for NXDOMAIN / empty-answer / resolver-error entries. It is intentionally short so transient failures resolve quickly.
const DefaultTTL = time.Hour
DefaultTTL is used for successful positive cache entries when the caller does not supply an explicit TTL via WithTTL.
Variables ¶
var ErrNoRecords = errors.New("dns: lookup returned no records")
ErrNoRecords is returned by a Lookup method when the resolver returned a successful response that contained no usable records (NXDOMAIN / empty answer section).
Functions ¶
This section is empty.
Types ¶
type Direction ¶
type Direction string
Direction distinguishes the two lookup directions stored in dns_cache.
type Option ¶
type Option func(*Resolver)
Option configures a Resolver.
func WithLogger ¶
WithLogger sets the structured logger used for warnings and debug output.
func WithNegativeTTL ¶
WithNegativeTTL overrides the default TTL used for NXDOMAIN / empty-answer / resolver-error cache entries.
func WithNetResolver ¶
WithNetResolver replaces the underlying net.Resolver (useful in tests that want to verify the Option wiring without injecting lookupHostFn directly).
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver performs cached DNS lookups.
func (*Resolver) Invalidate ¶
Invalidate removes all dns_cache entries for the given direction and key, forcing the next lookup to perform a fresh network query.
This is useful when an external event (e.g. a DHCP lease change or a manual host update) makes the cached value known-stale before its TTL expires.
func (*Resolver) InvalidateAll ¶
InvalidateAll truncates the entire dns_cache table. All subsequent lookups will hit the network until their results are re-cached.
Use with care — this is a heavy operation intended for administrative resets, not routine use.
func (*Resolver) LookupAddr ¶
LookupAddr performs a reverse PTR lookup for the given IP address and returns the first hostname (trailing dot stripped). Results are cached; ErrNoRecords is returned for empty / NXDOMAIN responses.
func (*Resolver) LookupHost ¶
LookupHost resolves a hostname to one or more IP address strings. The cache is consulted first; a live lookup is only performed when all cached entries are stale or absent.
On success the returned slice contains at least one element. ErrNoRecords is returned when the resolver returned an empty answer.
Source Files