host

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package host owns the lifecycle of an Avero application.

New builds the application from a configuration and a set of options. Run performs the sequence that the SDD states in section 5.3: the boot checks, the migrations, the ordered start, the readiness gate, the wait, the drain and the reverse-ordered stop.

Avero owns lifecycle. Avero does not own semantics. A component decides what Start and Stop mean.

Index

Constants

View Source
const (
	// DoctorSchemaID names the schema that a JSON doctor report follows. See
	// host/doctor_schema.json.
	DoctorSchemaID = "https://avero.dev/schema/doctor-report/v1"
	// StatePass marks a check that holds.
	StatePass = "pass"
	// StateFail marks a check that does not hold.
	StateFail = "fail"
)

The names of the doctor report.

View Source
const (
	StageSetup   = "setup"
	StageMigrate = "migrate"
	StageStart   = "start"
	StageStop    = "stop"
)

The stages of the run sequence. A fault names the stage that raised it. See the SDD, section 5.3.

Variables

View Source
var DoctorSchema []byte

DoctorSchema holds host/doctor_schema.json. `avero doctor --json` emits a document that this schema accepts. See AN-3.

Functions

func Exit

func Exit(w io.Writer, err error) int

Exit writes err to w and returns the process exit code. It returns 0 for a nil error and 1 for any fault. The caller owns the call to os.Exit.

Types

type App

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

App is one Avero application. Build it with New. Run it one time.

func New

func New(cfg config.BaseConfig, opts ...Option) *App

New builds an application. Pass the BaseConfig that S1 loaded. An application configuration embeds it, so main.go passes cfg.BaseConfig.

func (*App) Addr

func (a *App) Addr() string

Addr returns the bound address. It is the empty string until the listener binds.

func (*App) Config

func (a *App) Config() config.BaseConfig

Config returns the configuration that New received.

func (*App) Run

func (a *App) Run(ctx context.Context) error

Run performs the run sequence of the SDD, section 5.3. It returns when the context is done, when a signal arrives, or when a fault stops the sequence. Call Exit with the result to get the process exit code.

func (*App) Signals

func (a *App) Signals() []os.Signal

Signals returns the signals that close the application.

type BootFault

type BootFault struct {
	// Check is the name of the check.
	Check string `json:"check"`
	// Repair states what to do. The check owns the sentence.
	Repair string `json:"repair"`
	// Err is the cause.
	Err error `json:"-"`
}

BootFault is the fault of one boot check. See DX-8.

func (*BootFault) Error

func (f *BootFault) Error() string

Error returns the message and the repair on two lines.

func (*BootFault) Unwrap

func (f *BootFault) Unwrap() error

Unwrap returns the cause.

type BootFaults

type BootFaults struct {
	Faults []*BootFault `json:"faults"`
}

BootFaults holds every boot check that failed. Avero runs every check. It does not stop at the first fault.

func (*BootFaults) Error

func (l *BootFaults) Error() string

Error returns a count and one entry for each fault.

func (*BootFaults) Unwrap

func (l *BootFaults) Unwrap() []error

Unwrap returns each fault so that errors.As reaches a single one.

type Check

type Check struct {
	// Name states what the check proves, such as "the database".
	Name string
	// Repair is one sentence that says what to do when the check fails.
	Repair string
	// Run performs the check. It returns nil when the check passes.
	Run func(ctx context.Context) error
}

Check is one boot check. Avero runs every check before it starts the first component, so that a fault appears before the process serves. See DX-8.

Name and Repair are mandatory. Avero refuses to run an application that carries a check with an empty field, because an error must state its repair. See DX-7.

type CheckResult

type CheckResult struct {
	// Name states what the check proves.
	Name string `json:"name"`
	// State is pass or fail.
	State string `json:"state"`
	// Message states the fault. It is empty for a check that holds.
	Message string `json:"message"`
	// Repair states what to do. It is empty for a check that holds.
	Repair string `json:"repair"`
}

CheckResult is one row of the doctor report.

type Component

type Component interface {
	// Name identifies the component in a log line and in a fault.
	Name() string
	// Start brings the component up. A Start that returns an error stops the
	// run sequence. A panic in Start is a fault. Avero does not recover it.
	Start(ctx context.Context) error
	// Stop brings the component down. The context carries the SHUTDOWN_GRACE
	// deadline.
	Stop(ctx context.Context) error
}

Component is a part of the application that has a lifecycle. Avero starts components in registration order and stops them in reverse order. See the SDD, section 5.1.

type DoctorReport

type DoctorReport struct {
	// OK reports a report with no failed row.
	OK bool `json:"ok"`
	// Checks holds one row for each check, in the order that the
	// application registered them. The configuration rows stand first.
	Checks []CheckResult `json:"checks"`
	// Config lists every configuration field that the loader read.
	Config *config.Report `json:"config,omitempty"`
}

DoctorReport is the answer of `avero doctor`. It states one row for each configuration fault and one row for each boot check. See DX-8.

func Doctor

func Doctor(ctx context.Context, cfgReport *config.Report, cfgErr error, checks []Check) *DoctorReport

Doctor runs the boot checks and turns the configuration faults into rows.

The application calls it before it starts a component, and `avero doctor` calls it through the binary of the application. A fault therefore appears before the process serves. See DX-8.

func (*DoctorReport) MarshalJSON

func (r *DoctorReport) MarshalJSON() ([]byte, error)

MarshalJSON emits the report with a stable schema. See AN-3.

func (*DoctorReport) String

func (r *DoctorReport) String() string

String returns the table that `avero doctor` prints.

func (*DoctorReport) Write

func (r *DoctorReport) Write(w io.Writer, asJSON bool) error

Write prints the report to w. It writes the JSON document when asJSON is true, and the table when it is false.

type Fault

type Fault struct {
	// Stage is the step of the run sequence that raised the fault.
	Stage string `json:"stage"`
	// Subject is the component or the thing at fault.
	Subject string `json:"subject"`
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
	// Err is the cause. It can be nil.
	Err error `json:"-"`
}

Fault is one host fault. It names the stage and the subject, states what went wrong, and states the repair in one sentence. See DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the message and the repair on two lines.

func (*Fault) Unwrap

func (f *Fault) Unwrap() error

Unwrap returns the cause.

type Migrator

type Migrator interface {
	Migrate(ctx context.Context) error
}

Migrator applies the pending migrations. Avero calls it at boot when MIGRATE_ON_BOOT is true. See the SDD, section 5.3, step 3.

type Option

type Option func(*App)

Option configures an application. New applies each option in order.

func WithChecks

func WithChecks(cs ...Check) Option

WithChecks registers boot checks. Avero runs every check before it starts the first component. See DX-8.

func WithComponents

func WithComponents(cs ...Component) Option

WithComponents registers components. Avero starts them in this order and stops them in reverse order. Call it more than one time to append.

func WithHandler

func WithHandler(h http.Handler) Option

WithHandler mounts the application handler. Avero serves /readyz itself, so the handler never sees that path.

func WithListener

func WithListener(l net.Listener) Option

WithListener supplies the listener. Avero binds the port from the configuration when a test does not supply one.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger supplies the logger. The default logger reads LOG_LEVEL and LOG_FORMAT and writes to standard error.

func WithMigrator

func WithMigrator(m Migrator) Option

WithMigrator supplies the migrator. Avero calls it at boot when MIGRATE_ON_BOOT is true.

func WithSignals

func WithSignals(sig ...os.Signal) Option

WithSignals sets the signals that close the application. The default is interrupt and terminate.

func WithoutSignals

func WithoutSignals() Option

WithoutSignals installs no signal handler. A test uses it, so that a signal to the test binary does not reach the application. See the SDD, S2.

type Ready

type Ready interface {
	Ready(ctx context.Context) error
}

Ready is the optional readiness contract. A component that implements it gates /readyz. The endpoint answers 200 only when every implementation returns nil. See the SDD, section 5.1.

Jump to

Keyboard shortcuts

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