Documentation
¶
Overview ¶
Package appready defines what "app-ready" means for a bundle install (P7-PLUG-19, cap:cli.bundle-app-ready) and runs the steps after the plugin files are on disk.
Purpose: `nself bundle install` used to end at one build. This package names the nine steps (licence, fetch, install, ledger, reconcile, start, readiness, tracking, health), records each one with its result and duration, stops at the first failure and says which step and which plugin failed. Inputs: Hooks (cmd-supplied reconcile / start / Hasura / service-health functions, injected because this package may not import those layers) and the Members read from the installed plugin.json files. Outputs: a Report (human text through Render, JSON through the struct tags). Constraints: nothing here applies SQL or touches a database; HTTP goes through internal/plugin/readiness (internal/httptimeout); the dry run only prints.
Index ¶
- Constants
- Variables
- func DefaultHealthURL(m Member) string
- func Missing(members []Member, tracked map[string]bool) (string, []string)
- func PrintPlan(w io.Writer, bundle string, members []string)
- func Render(w io.Writer, r Report)
- func TrackedTables(raw []byte) (map[string]bool, error)
- type Failure
- type Hooks
- type Member
- type Outcome
- type Report
- type Runner
- type StepError
- type StepResult
Constants ¶
const ( StepLicence = "licence" StepFetch = "fetch" StepInstall = "install" StepLedger = "ledger" StepReconcile = "reconcile" StepStart = "start" StepReadiness = "readiness" StepTracking = "tracking" StepHealth = "health" )
Step names, in the order they run. These exact strings are used in the human output, in the JSON and in E135 messages.
const ( ResultOK = "ok" ResultFailed = "failed" ResultSkipped = "skipped" ResultPlanned = "planned" // dry run )
Step results.
const NotVerifiedV15 = "not verified (v1.5 behaviour, NSELF_V15=1)"
NotVerifiedV15 is the detail of every step that did not run because the install built no start hook (v1.4 default mode).
Variables ¶
var ErrNoProject = errors.New("not in an nSelf project")
ErrNoProject is what Hooks.Reconcile returns outside an nSelf project: the plugins are installed, but there is no stack to reconcile, start or check.
var Order = []string{ StepLicence, StepFetch, StepInstall, StepLedger, StepReconcile, StepStart, StepReadiness, StepTracking, StepHealth, }
Order is the fixed step order.
Functions ¶
func DefaultHealthURL ¶
DefaultHealthURL is where the member's container publishes /health on the host.
func Missing ¶
Missing returns, for the first member (in order) that has untracked tables, that member's name and the sorted missing tables.
func Render ¶
Render writes one line per step, then the verdict line: APP-READY, or NOT APP-READY naming the step and plugin, or the Note.
func TrackedTables ¶
TrackedTables parses an export_metadata response into the set of tracked postgres tables, keyed "schema.name". It reads sources[].tables[].table and, for older metadata, a top-level tables array. Only postgres-kind sources count (kind "postgres", "citus", "cockroach", or no kind); a data-connector or BigQuery source is ignored. A table entry counts only in the {schema,name} object form (schema defaults to public); any other shape is skipped.
Types ¶
type Hooks ¶
type Hooks struct {
// Reconcile regenerates project files for the new membership.
Reconcile func(ctx context.Context) error
// Start boots the stack (the in-process `nself start`).
Start func(ctx context.Context) error
// ExportMetadata returns Hasura's export_metadata response.
ExportMetadata func(ctx context.Context) ([]byte, error)
// ServiceHealth returns an error listing unhealthy services.
ServiceHealth func(ctx context.Context) error
// HealthURL is the plugin's /health URL; default http://127.0.0.1:<port><endpoint>.
HealthURL func(m Member) string
// Timeout bounds each waiting step; default readiness.TimeoutFromEnv().
Timeout time.Duration
// Interval is the poll interval; tests set milliseconds.
Interval time.Duration
}
Hooks are the project-level operations the post-install steps call. A nil function skips its step and marks the report unverified.
type Member ¶
type Member struct {
Name string
Dir string
Port int
HealthEndpoint string
Tables []string
BootMigrations bool // manifest declares migrations.apply: boot
HasMigrationsDir bool // a migrations directory exists on disk
}
Member is one installed plugin of the bundle.
type Outcome ¶
type Outcome struct {
// Reconciled is true once the Reconcile hook ran, success or not.
Reconciled bool
}
Outcome tells the caller what Run did beyond the Report.
type Report ¶
type Report struct {
Bundle string `json:"bundle"`
AppReady bool `json:"app_ready"`
Steps []StepResult `json:"steps"`
Failed string `json:"failed_step,omitempty"`
FailedFor string `json:"failed_plugin,omitempty"`
// Note explains a report that is neither app-ready nor failed (for example
// the install ran outside an nSelf project).
Note string `json:"note,omitempty"`
}
Report is the outcome of one bundle install.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner times each step and stops at the first failure: once a step has failed, every later step is recorded as skipped.
func (*Runner) Record ¶
Record stores a step that already ran outside the Runner (the fetch step runs before the plan is printed). A failed result makes it the run's first failure unless one is already set.
func (*Runner) Report ¶
Report assembles the report in canonical order. A step that never ran is listed as skipped. AppReady is true only when no step failed and nothing marked the run Unverified, so a run that could not check a step is never called ready.
func (*Runner) Step ¶
Step runs fn as the named step. After a failure it does not run fn and records the step as skipped. fn returns a detail text and an error; wrap the error in *StepError to name the plugin.
func (*Runner) Unverified ¶
Unverified marks the run as not proven app-ready without failing it (the first reason is kept).
Source Files