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
- func ExplainACME(raw string) string
- func IsApex(domain string) bool
- func IsCloudflareIP(ip string) bool
- type ACMEFailureFacts
- type Action
- type AppFacts
- type CAARecord
- type CertFacts
- type Check
- type DNSHint
- type DNSProbe
- type DNSVerdict
- type DNSVerdictInput
- type Facts
- type Fix
- type HTTPProbe
- type HTTPResult
- type NetDNS
- type NetHTTP
- type NetTLS
- type Options
- type PeerCert
- type PortHolder
- type Probes
- type Propagation
- type Record
- type Report
- type ResolverAnswer
- type State
- type TLSProbe
- type TargetFacts
Constants ¶
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.
const ( IDDNSProxied = "dns.proxied" IDDNSWildcard = "dns.wildcard" )
IDs for the checks that explain what sits between visitors and this server.
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.
const ( VerdictReady = "dns_ready" VerdictPublicReady = "public_ready" VerdictNotFound = "not_found" VerdictElsewhere = "points_elsewhere" VerdictUnknown = "unknown" )
DNS verdicts, computed from authoritative answers first.
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.
const ( StatusHealthy = "healthy" StatusWarnings = "warnings" StatusProblems = "problems" )
Overall report statuses.
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.
const ( ActionRequest = "request" ActionLink = "link" ActionCopy = "copy" )
Action kinds a fix can carry.
const ( PropagationSettled = "settled" PropagationPropagating = "propagating" PropagationWaiting = "waiting" )
Propagation states.
const ACMEActionFixDNSAccess = "fix_dns_access"
ACMEActionFixDNSAccess is reported when the DNS provider refused the _acme-challenge record the platform tried to create.
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 ¶
ExplainACME turns the certificate authority's raw error into one plain sentence an operator can act on.
func IsApex ¶
IsApex reports whether domain is a registrable domain (example.com, example.co.uk), where a CNAME is not allowed.
func IsCloudflareIP ¶
IsCloudflareIP reports whether ip is inside Cloudflare's proxy ranges.
Types ¶
type ACMEFailureFacts ¶
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 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 ¶
Prioritized returns the failing and warning checks, fails before warns, lower tier first, stable within a tier.
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 ¶
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.
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 ¶
PortHolder is a container publishing host port 80 or 443.
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 ¶
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 ¶
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 TargetFacts ¶
TargetFacts is a standalone domain's proxy target and whether this server could connect to it just now.