domaincutover

package
v0.9.2 Latest Latest
Warning

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

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

Documentation

Overview

Package domaincutover turns the facts about a domain moving to this server into an ordered checklist with a downtime verdict. It does no I/O: the API layer gathers the facts (probes, DNS, certificate state) and calls Evaluate.

Index

Constants

View Source
const (
	StepApp           = "app"
	StepCertificate   = "certificate"
	StepCurrentDNS    = "current_dns"
	StepSwitch        = "switch_dns"
	StepAuthoritative = "authoritative"
	StepLive          = "live"
)

Step ids, in checklist order.

View Source
const (
	PointsNone       = "none"
	PointsThis       = "this_server"
	PointsElsewhere  = "previous_server"
	PointsCloudflare = "cloudflare_proxy"
)

Where current DNS points.

View Source
const (
	CertOff     = "off"
	CertPending = "pending"
	CertIssued  = "issued"
	CertFailed  = "failed"
)

Certificate progress, matching the guided certificate flow.

View Source
const (
	DNSConnected    = "connected"
	DNSPropagating  = "propagating"
	DNSNotResolving = "not_resolving"
	DNSElsewhere    = "resolves_elsewhere"
)

DNS check statuses the API layer already produces.

View Source
const (
	RunbookHref    = "/acme-verification-runbook"
	CloudflareDocs = "/cdn-and-caching"
	GuideHref      = "/move-a-domain-with-no-downtime"
)

Docs links used by the checklist.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	API   string `json:"api,omitempty"`
	Href  string `json:"href,omitempty"`
	CLI   string `json:"cli,omitempty"`
}

Action is the one thing a step offers.

type CertView

type CertView struct {
	State             string `json:"state"`
	Issuer            string `json:"issuer,omitempty"`
	Error             string `json:"error,omitempty"`
	Explanation       string `json:"explanation,omitempty"`
	ProviderConnected bool   `json:"provider_connected"`
	// Challenge is "dns01" while this host alone uses DNS-01, else empty.
	Challenge   string `json:"challenge,omitempty"`
	RunbookHref string `json:"runbook_href"`
}

CertView describes the certificate step for the dashboard action.

type DNSView

type DNSView struct {
	Points     string   `json:"points"`
	Status     string   `json:"status"`
	Resolved   []string `json:"resolved,omitempty"`
	TTLSeconds int      `json:"ttl_seconds,omitempty"`
	LowerTTLTo int      `json:"lower_ttl_to"`
	Records    []Record `json:"records,omitempty"`
}

DNSView describes where the name points now.

type Facts

type Facts struct {
	Domain string
	// App is the pre-flight probe against this server's own ingress.
	App Probe
	// UpstreamTLS is true when a proxy in front owns certificates.
	UpstreamTLS bool

	CertState         string
	CertIssuer        string
	CertError         string
	CertExplanation   string
	ProviderConnected bool
	// DNS01Host is true when this host alone was switched to DNS-01.
	DNS01Host bool

	DNSStatus    string
	Resolved     []string
	ExpectedIPv4 []string
	ExpectedIPv6 []string
	ExpectedHost string
	// Proxied is true when every resolved address is a Cloudflare proxy address.
	Proxied bool
	// TTLSeconds is the live record's TTL, 0 when unknown.
	TTLSeconds int
	// AuthKnown is true when the authoritative servers were asked.
	AuthKnown          bool
	AuthTotal, AuthHit int
	// Live is the end to end probe over the real name.
	Live Probe
}

Facts is everything Evaluate needs.

type Options

type Options struct {
	// LowTTL is the TTL at or below which a cutover is quick, and the value advised.
	LowTTL int
	// DefaultETA is the propagation estimate when the TTL is unknown, in seconds.
	DefaultETA int
	// CertETA is the usual time a DNS-01 certificate takes, in seconds.
	CertETA int
}

Options are the tunables, read from env by the caller.

type Probe

type Probe struct {
	// Done is false when the probe was not run (and why is in Err).
	Done        bool
	Status      int
	CertTrusted bool
	CertIssuer  string
	Err         string
}

Probe is one HTTPS probe outcome.

func (Probe) Answered

func (p Probe) Answered() bool

Answered is true when the app (not an error page of the proxy) replied.

type Record

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

Record is the exact DNS record to create or change.

type Result

type Result struct {
	Domain        string    `json:"domain"`
	Risk          Risk      `json:"risk"`
	ReadyToSwitch bool      `json:"ready_to_switch"`
	Summary       string    `json:"summary"`
	Proxied       bool      `json:"proxied"`
	ProxyDocs     string    `json:"proxy_docs,omitempty"`
	Steps         []Step    `json:"steps"`
	DNS           DNSView   `json:"dns"`
	Certificate   CertView  `json:"certificate"`
	CLI           []string  `json:"cli"`
	GuideHref     string    `json:"guide_href"`
	CheckedAt     time.Time `json:"checked_at"`
}

Result is the full checklist.

func Evaluate

func Evaluate(f Facts, o Options) Result

Evaluate builds the checklist and the downtime verdict.

type Risk

type Risk string

Risk is the downtime verdict.

const (
	RiskNone    Risk = "none"
	RiskLikely  Risk = "likely"
	RiskUnknown Risk = "unknown"
)

Risk values.

type State

type State string

State of one step.

const (
	StatePass State = "pass"
	StateWait State = "wait"
	StateFail State = "fail"
	StateSkip State = "skip"
)

State values.

type Step

type Step struct {
	ID         string  `json:"id"`
	State      State   `json:"state"`
	Title      string  `json:"title"`
	Detail     string  `json:"detail"`
	ETASeconds int     `json:"eta_seconds,omitempty"`
	Action     *Action `json:"action,omitempty"`
}

Step is one checklist row.

Jump to

Keyboard shortcuts

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