golive

package
v0.8.4 Latest Latest
Warning

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

 Go to latest Published: Oct 24, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package golive turns the platform's separate checks (app readiness, ports, host firewall, DNS, certificate, end-to-end HTTPS) into one ordered checklist for an app and a domain, each step with a status, evidence and one primary action. It does no I/O of its own except SelfCheck.

Index

Constants

View Source 
const (
	KindDNS       = "dns"
	KindPort      = "port"
	KindChallenge = "challenge"
	KindCert      = "certificate"
	KindRenewal   = "renewal"
	KindFailure   = "failure"
	KindLive      = "live"
)

Timeline event kinds.

View Source 
const (
	StepApp         = "app"
	StepPort        = "port"
	StepFirewall    = "firewall"
	StepDNS         = "dns"
	StepCertificate = "certificate"
	StepLive        = "live"
)

Step ids, in checklist order.

View Source 
const (
	ActionFix     = "fix"
	ActionRequest = "request"
	ActionRecheck = "recheck"
	ActionLink    = "link"
	ActionCopy    = "copy"
)

Action kinds.

View Source 
const ScopeControlPlane = "control_plane_host"

ScopeControlPlane labels a probe that ran on this server: it cannot prove the wider internet can reach it.

Variables

This section is empty.

Functions

func HashBody 

func HashBody(r io.Reader) string

HashBody fingerprints the first bytes of a response body.

Types

type Action 

type Action struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	// FixID names a typed fix applied through the fixit endpoints.
	FixID string `json:"fix_id,omitempty"`
	// API is "METHOD /path" for a request action.
	API   string         `json:"api,omitempty"`
	Body  map[string]any `json:"body,omitempty"`
	Href  string         `json:"href,omitempty"`
	Value string         `json:"value,omitempty"`
	// Blocked, when set, is why the action cannot run yet.
	Blocked string `json:"blocked,omitempty"`
}

Action is the one primary thing a step offers.

type AppInput 

type AppInput struct {
	Known         bool
	Running       bool
	Ready         bool
	Detail        string
	DiagnosisHref string
}

AppInput is the readiness of the app.

type CertInput 

type CertInput struct {
	Ready      bool
	Blocker    string
	BlockerFix string
	NextSafeAt *time.Time
	Status     CertStatus
	CertAPI    string
}

CertInput is what the certificate step decides from.

type CertStatus 

type CertStatus struct {
	State       string
	Staging     bool
	Trusted     bool
	Issuer      string
	NotBefore   time.Time
	NotAfter    time.Time
	RenewalAt   time.Time
	Error       string
	Explanation string
	Hint        string
	NextSafeAt  *time.Time
}

CertStatus is the certificate progress for the domain.

type Checklist 

type Checklist struct {
	App       string          `json:"app"`
	Domain    string          `json:"domain"`
	State     State           `json:"state"`
	Live      bool            `json:"live"`
	Next      string          `json:"next,omitempty"`
	URL       string          `json:"url,omitempty"`
	Steps     []Step          `json:"steps"`
	Timeline  []TimelineEvent `json:"timeline"`
	CheckedAt time.Time       `json:"checked_at"`
}

Checklist is the whole guided flow for one app and domain.

func Build 

func Build(in Input) Checklist

Build assembles the checklist. It is pure: every fact comes in through in.

type Evidence 

type Evidence struct {
	Label string `json:"label"`
	Value string `json:"value"`
	Copy  bool   `json:"copy,omitempty"`
}

Evidence is one fact behind a step status.

type Failure 

type Failure struct {
	At          time.Time
	Error       string
	Explanation string
	Renewal     bool
}

Failure is one recorded certificate error.

type FirewallInput 

type FirewallInput struct {
	Host     hostfw.Status
	Plan     hostfw.Plan
	FixID    string
	FixKind  fixit.Kind
	Provider *hostprovider.Guidance
}

FirewallInput is the host firewall state and the typed fix for it.

type FixPreview 

type FixPreview struct {
	FixID      string   `json:"fix_id"`
	Kind       string   `json:"kind"`
	Commands   []string `json:"commands"`
	Undo       []string `json:"undo"`
	Persistent bool     `json:"persistent"`
	Note       string   `json:"note,omitempty"`
	Refusal    string   `json:"refusal,omitempty"`
}

FixPreview is what an automatic fix would do, shown before it runs.

type Input 

type Input struct {
	App       string
	Domain    string
	Now       time.Time
	PollEvery time.Duration
	AppState  AppInput
	Port      PortInput
	Firewall  FirewallInput
	Report    *domaindoctor.Report
	Cert      CertInput
	Live      *SelfCheckResult
	Seen      *Seen
	// ChallengeStartedAt is when the certificate request began, zero when none.
	ChallengeStartedAt time.Time
	// Failure is the CA's last recorded error for the domain.
	Failure *Failure
	CLIName string
}

Input is everything Build decides from.

type Match 

type Match string

Match says how strongly the HTTPS response was tied to this app. 

const (
	MatchBody       Match = "body"
	MatchHeaders    Match = "headers"
	MatchUnverified Match = "unverified"
	MatchNone       Match = "none"
)

Match values.

type PortInput 

type PortInput struct {
	ZeroConfigURL string
	DirectURL     string
	// DirectAllowed is true when the app exposure feature can publish a direct port.
	DirectAllowed bool
	Probe         *PortProbe
	NetworkHref   string
}

PortInput is how the app is reachable before any domain exists.

type PortProbe 

type PortProbe struct {
	OK      bool
	Status  int
	Failure string
}

PortProbe is a loopback request to the container's published port.

type Reference 

type Reference struct {
	Status      int
	ContentType string
	Server      string
	BodyHash    string
}

Reference is what the app itself answers when asked directly, used to tell it apart from another server behind the same address.

type Seen 

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

Seen remembers when each milestone was first observed, for the lifetime of the process, so the timeline keeps its times across page reloads.

func NewSeen 

func NewSeen() *Seen

NewSeen returns an empty memory.

func (*Seen) Forget 

func (s *Seen) Forget(key string)

Forget drops key, so a milestone that regressed is observed again.

func (*Seen) Mark 

func (s *Seen) Mark(key string, now time.Time) time.Time

Mark records now for key the first time and returns the recorded time.

type SelfCheckInput 

type SelfCheckInput struct {
	Domain string
	// Addr is the host:port to dial, normally this server's own address.
	Addr      string
	Path      string
	Reference *Reference
	// RootCAs replaces the system roots; tests only.
	RootCAs *x509.CertPool
	Timeout time.Duration
}

SelfCheckInput is one end-to-end check of https://domain.

type SelfCheckResult 

type SelfCheckResult struct {
	Reached   bool      `json:"reached"`
	TLSValid  bool      `json:"tls_valid"`
	TLSError  string    `json:"tls_error,omitempty"`
	Issuer    string    `json:"issuer,omitempty"`
	NotAfter  time.Time `json:"not_after,omitzero"`
	Status    int       `json:"status,omitempty"`
	Match     Match     `json:"match"`
	Error     string    `json:"error,omitempty"`
	Scope     string    `json:"scope"`
	CheckedAt time.Time `json:"checked_at"`
}

SelfCheckResult is the outcome, with the TLS and HTTP facts behind it.

func SelfCheck 

func SelfCheck(ctx context.Context, in SelfCheckInput) SelfCheckResult

SelfCheck dials addr, verifies the certificate chain for domain against the system roots, requests path and compares the answer with the reference.

type State 

type State string

State is the one-word summary used by badges. 

const (
	StateNotLive            State = "not_live"
	StateWaitingDNS         State = "waiting_dns"
	StateWaitingCertificate State = "waiting_certificate"
	StateLive               State = "live"
	StateNeedsAttention     State = "needs_attention"
)

State values.

func StateOf 

func StateOf(steps []Step) State

StateOf collapses the steps into the badge state.

type Status 

type Status string

Status of one step. 

const (
	StatusPending Status = "pending"
	StatusOK      Status = "ok"
	StatusWarn    Status = "warn"
	StatusFail    Status = "fail"
	StatusUnknown Status = "unknown"
)

Status values.

type Step 

type Step struct {
	ID       string     `json:"id"`
	Title    string     `json:"title"`
	Status   Status     `json:"status"`
	Summary  string     `json:"summary"`
	Evidence []Evidence `json:"evidence"`
	Primary  *Action    `json:"primary,omitempty"`
	// CLI is the secondary, collapsed way to do the same from a terminal.
	CLI         string     `json:"cli,omitempty"`
	NextCheckAt *time.Time `json:"next_check_at,omitempty"`
	DocsURL     string     `json:"docs_url,omitempty"`

	Records     []domaindoctor.Record  `json:"records,omitempty"`
	FirewallFix *FixPreview            `json:"firewall_fix,omitempty"`
	Provider    *hostprovider.Guidance `json:"provider,omitempty"`
	// Scope says where a probe ran, so a control plane check is never read as proof from the internet.
	Scope string `json:"scope,omitempty"`
}

Step is one checklist row.

type TimelineEvent 

type TimelineEvent struct {
	ID     string    `json:"id"`
	At     time.Time `json:"at"`
	Kind   string    `json:"kind"`
	Title  string    `json:"title"`
	Detail string    `json:"detail,omitempty"`
	Failed bool      `json:"failed,omitempty"`
	// Future marks something scheduled, such as a renewal.
	Future bool `json:"future,omitempty"`
}

TimelineEvent is one entry in a domain's go live history.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.