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
- Variables
- func Exit(w io.Writer, err error) int
- type App
- type BootFault
- type BootFaults
- type Check
- type CheckResult
- type Component
- type DoctorReport
- type Fault
- type Migrator
- type Option
- func WithChecks(cs ...Check) Option
- func WithComponents(cs ...Component) Option
- func WithHandler(h http.Handler) Option
- func WithListener(l net.Listener) Option
- func WithLogger(l *slog.Logger) Option
- func WithMigrator(m Migrator) Option
- func WithSignals(sig ...os.Signal) Option
- func WithoutSignals() Option
- type Ready
Constants ¶
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.
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 ¶
var DoctorSchema []byte
DoctorSchema holds host/doctor_schema.json. `avero doctor --json` emits a document that this schema accepts. See AN-3.
Functions ¶
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) Config ¶
func (a *App) Config() config.BaseConfig
Config returns the configuration that New received.
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.
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.
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.
type Migrator ¶
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 ¶
WithChecks registers boot checks. Avero runs every check before it starts the first component. See DX-8.
func WithComponents ¶
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 ¶
WithHandler mounts the application handler. Avero serves /readyz itself, so the handler never sees that path.
func WithListener ¶
WithListener supplies the listener. Avero binds the port from the configuration when a test does not supply one.
func WithLogger ¶
WithLogger supplies the logger. The default logger reads LOG_LEVEL and LOG_FORMAT and writes to standard error.
func WithMigrator ¶
WithMigrator supplies the migrator. Avero calls it at boot when MIGRATE_ON_BOOT is true.
func WithSignals ¶
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.