endpoint_cache

Documentation

Overview

Package endpoint_cache implements a database-backed endpoint override cache.

When resolving a domain or IP for outbound mail delivery, the cache is consulted first. If a matching EndpointOverride row exists in the database, its TargetHost is returned without performing any real DNS lookup.

For IP addresses without an override, the IP itself is returned (an IP is already a concrete endpoint — no resolution needed).

For domain names without an override, an empty string is returned so that the caller falls through to OS DNS resolution.

This allows operators to:

• Route mail destined for a domain to a specific IP (e.g., during migration).
• Override IP-literal destinations (e.g., a@[1.1.1.1] → deliver to 2.2.2.2).
• Test mail flows against staging servers without touching system DNS.

Index

• type Cache
  • func New(db *gorm.DB, logger log.Logger) (*Cache, error)
  • func (c *Cache) Delete(lookupKey string) error
  • func (c *Cache) Get(lookupKey string) (*mdb.EndpointOverride, error)
  • func (c *Cache) List() ([]mdb.EndpointOverride, error)
  • func (c *Cache) Resolve(ctx context.Context, key string) (string, error)
  • func (c *Cache) ResolveMX(ctx context.Context, domain string) (records []*net.MX, cacheHit bool, err error)
  • func (c *Cache) Set(lookupKey, targetHost, comment string) error

Types

type Cache

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

Cache wraps a GORM database to provide endpoint resolution with local overrides.

func New

func New(db *gorm.DB, logger log.Logger) (*Cache, error)

New creates an endpoint_cache.Cache from the given GORM database connection. It automatically runs AutoMigrate for the EndpointOverride table.

func (*Cache) Delete

func (c *Cache) Delete(lookupKey string) error

Delete removes an endpoint override entry.

func (*Cache) Get

func (c *Cache) Get(lookupKey string) (*mdb.EndpointOverride, error)

Get retrieves a single endpoint override entry.

func (*Cache) List

func (c *Cache) List() ([]mdb.EndpointOverride, error)

List returns all endpoint override entries.

func (*Cache) Resolve

func (c *Cache) Resolve(ctx context.Context, key string) (string, error)

Resolve looks up the target host for the given key (domain name or IP).

Behaviour:

• If an explicit override exists in the database, its TargetHost is returned.
• If key is an IP address (bare or bracketed) with NO override, the IP itself is returned — an IP is already a concrete endpoint.
• If key is a domain name with NO override, an empty string is returned so the caller uses the original hostname for DNS resolution (which preserves proper TLS certificate verification and MTA-STS compatibility).

func (*Cache) ResolveMX

func (c *Cache) ResolveMX(ctx context.Context, domain string) (records []*net.MX, cacheHit bool, err error)

ResolveMX resolves the MX host for a domain. It first checks the local override database. If an override exists for the domain, it returns a single synthetic MX record pointing to the override target with cacheHit=true. Otherwise it performs a standard MX lookup via the OS resolver and returns cacheHit=false.

func (*Cache) Set

func (c *Cache) Set(lookupKey, targetHost, comment string) error

Set creates or updates an endpoint override entry.