domaindoctor

package
v1.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package domaindoctor runs an ordered set of read-only checks against one domain (DNS, CAA, ports, TLS, HTTP, redirects, HSTS, platform state) and turns each result into a fix an operator can act on.

Index

Constants

View Source
const (
	IDDNSResolves   = "dns.resolves"
	IDDNSPointsHere = "dns.points_here"
	IDDNSAAAA       = "dns.aaaa_mismatch"
	IDDNSApexCNAME  = "dns.cname_apex"
	IDCAA           = "caa.blocks_issuer"
	IDAppRunning    = "app.running"
	IDHeldBack      = "domain.held_back"
	IDProxyPorts    = "proxy.ports"
	IDPort80        = "net.port80"
	IDTLS           = "tls.certificate"
	IDHTTPStatus    = "http.status"
	IDRedirects     = "redirect.chain"
	IDHSTS          = "hsts.risk"
	IDStoredCert    = "cert.renewal"
)

Check IDs, stable for the dashboard and alert prefills.

View Source
const (
	IDDNSProxied  = "dns.proxied"
	IDDNSWildcard = "dns.wildcard"
)

IDs for the checks that explain what sits between visitors and this server.

View Source
const (
	ACMEActionOpenPort80 = "open_port_80"
	ACMEActionFixDNS     = "fix_dns"
	ACMEActionWait       = "wait_rate_limit"
	ACMEActionFixCAA     = "fix_caa"
	ACMEActionOtherProxy = "other_proxy"
	ACMEActionCheckLogs  = "check_logs"
)

ACME next-action codes, matching the API's acme_failure.action values.

View Source
const (
	VerdictReady       = "dns_ready"
	VerdictPublicReady = "public_ready"
	VerdictNotFound    = "not_found"
	VerdictElsewhere   = "points_elsewhere"
	VerdictUnknown     = "unknown"
)

DNS verdicts, computed from authoritative answers first.

View Source
const (
	HintLocalStale      = "local_stale"
	HintWasCloudflare   = "was_cloudflare_proxy"
	HintCloudflareNow   = "cloudflare_proxied"
	HintWaiting         = "waiting"
	HintAAAAElsewhere   = "aaaa_elsewhere"
	HintNSMismatch      = "ns_mismatch"
	HintCheckZone       = "check_zone"
	HintCheckAAAA       = "check_aaaa"
	HintCheckCNAME      = "check_cname"
	HintCheckNameserver = "check_nameservers"
	HintLocalStaleLong  = "local_stale_long"
)

Hint codes; the dashboard translates them, Message is the English text.

View Source
const (
	StatusHealthy  = "healthy"
	StatusWarnings = "warnings"
	StatusProblems = "problems"
)

Overall report statuses.

View Source
const (
	TierTraffic     = 1
	TierCertificate = 2
	TierSoon        = 3
	TierHygiene     = 4
)

Tiers order fixes: traffic blockers first, then certificate blockers, then things that break soon, then hygiene.

View Source
const (
	ActionRequest = "request"
	ActionLink    = "link"
	ActionCopy    = "copy"
)

Action kinds a fix can carry.

View Source
const (
	PropagationSettled     = "settled"
	PropagationPropagating = "propagating"
	PropagationWaiting     = "waiting"
)

Propagation states.

View Source
const ACMEActionFixDNSAccess = "fix_dns_access"

ACMEActionFixDNSAccess is reported when the DNS provider refused the _acme-challenge record the platform tried to create.

View Source
const IDTimeout = "doctor.timeout"

IDTimeout is reported when the run budget ran out before every check ran.

Variables

This section is empty.

Functions

func ExplainACME

func ExplainACME(raw string) string

ExplainACME turns the certificate authority's raw error into one plain sentence an operator can act on.

func IsApex

func IsApex(domain string) bool

IsApex reports whether domain is a registrable domain (example.com, example.co.uk), where a CNAME is not allowed.

func IsCloudflareIP

func IsCloudflareIP(ip string) bool

IsCloudflareIP reports whether ip is inside Cloudflare's proxy ranges.

Types

type ACMEFailureFacts

type ACMEFailureFacts struct {
	Error   string
	Action  string
	Renewal bool
}

ACMEFailureFacts is the CA's last recorded error for the domain.

type Action

type Action struct {
	Kind  string            `json:"kind"`
	Label string            `json:"label"`
	API   string            `json:"api,omitempty"`
	Value string            `json:"value,omitempty"`
	Body  map[string]string `json:"body,omitempty"`
}

Action is the one primary thing a fix offers: an API request to run ("POST /api/v1/..." with an optional JSON Body), a page to open, or a Value to copy.

type AppFacts

type AppFacts struct {
	Known   bool
	Running bool
	Ready   bool
	Detail  string
}

AppFacts is the platform's view of the app serving the domain.

type CAARecord

type CAARecord struct {
	Name  string
	Flag  uint8
	Tag   string
	Value string
}

CAARecord is one CAA resource record and the name it was found at.

type CertFacts

type CertFacts struct {
	Issuer   string
	NotAfter time.Time
	Status   string
	Renewal  string
	Source   string
}

CertFacts is the stored certificate for the domain.

type Check

type Check struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	State  State  `json:"state"`
	Tier   int    `json:"tier"`
	Detail string `json:"detail,omitempty"`
	// Cause is one plain sentence on what is wrong; Evidence lists the facts
	// that were observed.
	Cause    string   `json:"cause,omitempty"`
	Evidence []string `json:"evidence,omitempty"`
	Fix      *Fix     `json:"fix,omitempty"`
}

Check is one ordered result.

func Prioritized

func Prioritized(checks []Check) []Check

Prioritized returns the failing and warning checks, fails before warns, lower tier first, stable within a tier.

type DNSHint

type DNSHint struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

DNSHint is one piece of guidance.

type DNSProbe

type DNSProbe interface {
	Answers(ctx context.Context, host string) []ResolverAnswer
	CNAME(ctx context.Context, host string) (string, error)
	// CAA returns the CAA set that governs host: the records at the closest
	// name walking up from host, or none.
	CAA(ctx context.Context, host string) ([]CAARecord, error)
}

DNSProbe answers the DNS questions the doctor asks.

type DNSVerdict

type DNSVerdict struct {
	Verdict      string
	LocalStale   bool
	Escalated    bool
	RetryAt      time.Time
	FlushCommand string
	Hints        []DNSHint
}

DNSVerdict is the judged state of a domain's DNS.

func JudgeDNS

func JudgeDNS(in DNSVerdictInput) DNSVerdict

JudgeDNS decides readiness from authoritative answers, so a stale cache on this host can never hold a correctly configured domain back.

type DNSVerdictInput

type DNSVerdictInput struct {
	// Expected are this server's public addresses.
	Expected   []string
	Inspection dnsinspect.Inspection
	Local      dnsinspect.Source
	Now        time.Time
	// Waiting is how long this domain has been unsettled; Budget is when the
	// card stops reassuring and lists concrete checks.
	Waiting time.Duration
	Budget  time.Duration
	// FallbackWait is the cache wait assumed when the local TTL is unknown.
	FallbackWait time.Duration
	FlushCommand string
}

DNSVerdictInput is what JudgeDNS needs.

type Facts

type Facts struct {
	Domain    string
	App       string
	ServerIPs []string
	// HTTPPort and HTTPSPort are the ports clients use; 0 means 80 and 443.
	HTTPPort              int
	HTTPSPort             int
	TLSTerminatedUpstream bool
	ACMEEnabled           bool
	AppState              AppFacts
	HeldBack              bool
	PortHoldersKnown      bool
	PortHolders           []PortHolder
	Cert                  *CertFacts
	ACMEFailure           *ACMEFailureFacts
	// Target is set for a standalone domain, replacing the app check.
	Target *TargetFacts
	// ServerHost is the configured public hostname, used as a CNAME target.
	ServerHost string
	// DNSProvider and DNSZone describe the connected DNS provider that can
	// create records; empty means none.
	DNSProvider string
	DNSZone     string
	// CLIName is the command line tool's name for the secondary CLI hint.
	CLIName string
}

Facts is everything the API layer already knows from stored state.

type Fix

type Fix struct {
	Summary string     `json:"summary"`
	Kind    fixit.Kind `json:"kind"`
	Action  *Action    `json:"action,omitempty"`
	Records []Record   `json:"records,omitempty"`
	// CLI is the secondary, collapsed way to do the same from a terminal.
	CLI string `json:"cli,omitempty"`
	// ID names an existing fixit fix for the same problem, empty when none.
	ID    string `json:"id,omitempty"`
	Label string `json:"label,omitempty"`
	// Steps are plain instructions that need no terminal.
	Steps []string `json:"steps,omitempty"`
	Link  string   `json:"link,omitempty"`
	// CLIHint is an optional terminal shortcut, never the only content of a fix.
	CLIHint string `json:"cli_hint,omitempty"`
}

Fix is the remedy for a failed or warning check. Kind says how much the control plane can do: auto applies Action itself, guided shows exact Records or values, manual only explains. Every kind is followed by a re-check of the whole domain.

type HTTPProbe

type HTTPProbe interface {
	Get(ctx context.Context, addr, scheme, host, path string) (HTTPResult, error)
}

HTTPProbe sends one GET for scheme://host+path but always dials addr.

type HTTPResult

type HTTPResult struct {
	Status   int
	Location string
	HSTS     string
}

HTTPResult is one HTTP response, redirects not followed.

type NetDNS

type NetDNS struct {
	// Public lists resolver addresses (host:port); nil uses the list from
	// APP_DNS_PUBLIC_RESOLVERS (default 1.1.1.1, 8.8.8.8, 9.9.9.9).
	Public []string
}

NetDNS queries the system resolver, public resolvers and the zone's authoritative servers.

func (NetDNS) Answers

func (d NetDNS) Answers(ctx context.Context, host string) []ResolverAnswer

Answers implements DNSProbe.

func (NetDNS) CAA

func (d NetDNS) CAA(ctx context.Context, host string) ([]CAARecord, error)

CAA implements DNSProbe, walking up to (not including) the TLD.

func (NetDNS) CNAME

func (d NetDNS) CNAME(ctx context.Context, host string) (string, error)

CNAME implements DNSProbe.

type NetHTTP

type NetHTTP struct{}

NetHTTP sends single requests that never follow redirects.

func (NetHTTP) Get

func (NetHTTP) Get(ctx context.Context, addr, scheme, host, path string) (HTTPResult, error)

Get implements HTTPProbe.

type NetTLS

type NetTLS struct{}

NetTLS dials and handshakes for real.

func (NetTLS) Handshake

func (NetTLS) Handshake(ctx context.Context, addr, sni string) (PeerCert, error)

Handshake implements TLSProbe. Verification runs separately so an untrusted certificate is still described rather than just rejected.

type Options

type Options struct {
	Timeout        time.Duration
	ProbeTimeout   time.Duration
	ExpiryWarnDays int
	MaxRedirects   int
	Now            func() time.Time
}

Options bound the run.

type PeerCert

type PeerCert struct {
	Subject     string
	Issuer      string
	DNSNames    []string
	NotAfter    time.Time
	Verified    bool
	VerifyError string
}

PeerCert is the leaf certificate a TLS handshake presented.

type PortHolder

type PortHolder struct {
	Port      int
	Container string
	Kind      string
}

PortHolder is a container publishing host port 80 or 443.

type Probes

type Probes struct {
	DNS  DNSProbe
	TLS  TLSProbe
	HTTP HTTPProbe
}

Probes are the network seams; tests replace each one.

func DefaultProbes

func DefaultProbes() Probes

DefaultProbes are the real network probes.

type Propagation

type Propagation struct {
	State            string    `json:"state"`
	Detail           string    `json:"detail"`
	NextCheckSeconds int       `json:"next_check_seconds,omitempty"`
	NextCheckAt      time.Time `json:"next_check_at,omitzero"`
}

Propagation tells the dashboard whether DNS has caught up and when to look again.

type Record

type Record struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
}

Record is one DNS record an operator or the connected DNS provider creates.

func PlanRecords

func PlanRecords(domain string, serverIPs []string, serverHost string) []Record

PlanRecords returns the one record domain needs to reach this server: an address record at an apex, a CNAME to serverHost for a subdomain when the server has a public hostname, an address record otherwise. It returns nil when nothing is known about this server's address.

type Report

type Report struct {
	Domain    string    `json:"domain"`
	App       string    `json:"app,omitempty"`
	CheckedAt time.Time `json:"checked_at"`
	Status    string    `json:"status"`
	// Probed is false when the doctor refused to connect to the domain
	// (it does not resolve to this server), with ProbeNote saying why.
	Probed    bool    `json:"probed"`
	ProbeNote string  `json:"probe_note,omitempty"`
	Checks    []Check `json:"checks"`
	// Records are the DNS records this domain needs, inferred from apex versus
	// subdomain and this server's address.
	Records     []Record     `json:"records,omitempty"`
	Propagation *Propagation `json:"propagation,omitempty"`
	// GoLive is the dashboard path of the guided checklist for this app and domain.
	GoLive string `json:"go_live,omitempty"`
}

Report is the doctor's full answer for one domain.

func Run

func Run(ctx context.Context, facts Facts, probes Probes, opts Options) Report

Run executes every check and never returns an error: a check that cannot run reports unavailable or skipped instead.

func RunStream

func RunStream(ctx context.Context, facts Facts, probes Probes, opts Options, emit func(Check)) Report

RunStream is Run that also calls emit with each check as soon as it finishes, so a caller can show first results before the slow probes end. emit calls are serialized but arrive in completion order; the returned report is in canonical order.

type ResolverAnswer

type ResolverAnswer struct {
	Resolver string   `json:"resolver"`
	IPv4     []string `json:"ipv4,omitempty"`
	IPv6     []string `json:"ipv6,omitempty"`
	Error    string   `json:"error,omitempty"`
	// TTL is the longest record TTL the resolver reported, in seconds.
	TTL uint32 `json:"ttl,omitempty"`
	// Authoritative marks an answer from the zone's own name server, which is
	// never cached and is the source of truth.
	Authoritative bool `json:"authoritative,omitempty"`
}

ResolverAnswer is what one resolver answered for the domain.

type State

type State string

State is the outcome of one check.

const (
	StatePass        State = "pass"
	StateWarn        State = "warn"
	StateFail        State = "fail"
	StateSkipped     State = "skipped"
	StateUnavailable State = "unavailable"
)

The five check outcomes.

type TLSProbe

type TLSProbe interface {
	Handshake(ctx context.Context, addr, sni string) (PeerCert, error)
}

TLSProbe performs a handshake against addr with the given SNI.

type TargetFacts

type TargetFacts struct {
	Display   string
	Reachable bool
	Detail    string
}

TargetFacts is a standalone domain's proxy target and whether this server could connect to it just now.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL