dbprovision

package
v0.8.1 Latest Latest
Warning

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

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

Documentation

Overview

Package dbprovision records and summarizes the steps of creating a database, so the dashboard, CLI and API all show the same truth.

Index

Constants

View Source 
const (
	CausePermission  = "permission"
	CauseOutOfMemory = "out_of_memory"
	CausePortInUse   = "port_in_use"
	CauseBadVolume   = "bad_volume"
	CauseBadConfig   = "bad_config"
)

Typed crash reasons.

View Source 
const (
	FixGrantCapabilities = "grant_capabilities"
	FixRaiseMemory       = "raise_memory"
	FixFreePort          = "free_port"
	FixResetVolume       = "reset_volume"
	FixReviewConfig      = "review_config"
)

Fix ids for crash causes. They are guided: the client shows the hint, none is applied server side.

View Source 
const (
	StepAccepted        = "accepted"
	StepDockerCheck     = "docker_check"
	StepPullImage       = "pull_image"
	StepCreateVolume    = "create_volume"
	StepCredentials     = "credentials_and_tls"
	StepCreateContainer = "create_container"
	StepStart           = "start"
	StepWaitReady       = "wait_ready"
	StepApplySettings   = "apply_settings"
	StepReady           = "ready"
)

Step names, in the order they run.

View Source 
const (
	StatusPending = "pending"
	StatusStarted = "started"
	StatusDone    = "done"
	StatusFailed  = "failed"
	StatusSkipped = "skipped"
)

Step statuses.

View Source 
const (
	AttemptInProgress = "in_progress"
	AttemptFailed     = "failed"
	AttemptReady      = "ready"
)

Attempt statuses.

View Source 
const (
	FixRecheckDocker = "recheck_docker"
	FixRetry         = "retry"
	FixRemoveVolume  = "remove_leftover_volume"
	FixFreeDisk      = "free_disk"
	FixReuseVolume   = "reuse_existing_volume"
	FixChooseName    = "choose_another_name"
)

Fix ids a client can act on.

View Source 
const (
	EnvKeepAttempts  = "APP_DB_PROVISION_KEEP_ATTEMPTS"
	EnvEventInterval = "APP_DB_PROVISION_EVENT_INTERVAL"
)

Environment variables.

View Source 
const ReasonCrashLoop = "CrashLoop"

ReasonCrashLoop is the Ready-condition reason when the container restarts repeatedly while starting.

View Source 
const ReasonLeftoverVolume = "LeftoverVolume"

ReasonLeftoverVolume is the Ready-condition reason of the create_volume stop.

View Source 
const StatusInfo = "info"

StatusInfo marks an event that records data rather than progress.

View Source 
const StepLogTail = "log_tail"

StepLogTail is the pseudo step that carries a crashed container's output; it is not a provisioning step.

Variables

View Source 
var Steps = []string{
	StepAccepted, StepDockerCheck, StepPullImage, StepCreateVolume, StepCredentials,
	StepCreateContainer, StepStart, StepWaitReady, StepApplySettings, StepReady,
}

Steps is the canonical order.

Functions

func EncodeCrash 

func EncodeCrash(info CrashInfo) string

EncodeCrash serializes info for a log_tail event, redacting the tail.

func FailStepForReason 

func FailStepForReason(reason string, pullFinished bool, errText string) string

FailStepForReason maps a reconciler Ready-condition reason to the step it belongs to; "" means the reason is not a provisioning failure.

func RedactTail 

func RedactTail(s string) string

RedactTail hides anything that looks like a password or token and keeps the last maxTailLines lines.

Types

type Attempt 

type Attempt struct {
	ID          string      `json:"attempt_id"`
	Status      string      `json:"status"`
	CurrentStep string      `json:"current_step,omitempty"`
	StartedAt   *time.Time  `json:"started_at,omitempty"`
	FinishedAt  *time.Time  `json:"finished_at,omitempty"`
	Steps       []StepView  `json:"steps"`
	Events      []EventView `json:"events"`
	Failure     *Failure    `json:"failure,omitempty"`
}

Attempt is the latest provisioning attempt of a database.

func View 

func View(id string, events []store.DatabaseProvisionEvent) Attempt

View folds an attempt's events into per-step state.

type Cause 

type Cause struct {
	Kind string `json:"kind"`
	Hint string `json:"hint"`
	Fix  *Fix   `json:"fix,omitempty"`
}

Cause is a classified reason a database container stopped, with a typed fix.

func Classify 

func Classify(tail string, exitCode int, oomKilled bool) *Cause

Classify maps a crashed container's output and exit facts to a typed cause, or nil when none matches.

type CrashInfo 

type CrashInfo struct {
	Tail      string `json:"tail"`
	ExitCode  int    `json:"exit_code"`
	OOMKilled bool   `json:"oom_killed,omitempty"`
	Restarts  int    `json:"restarts,omitempty"`
}

CrashInfo is the recorded output and exit facts of a crashed container.

type EventView 

type EventView struct {
	Step   string    `json:"step"`
	Status string    `json:"status"`
	Detail string    `json:"detail,omitempty"`
	At     time.Time `json:"at"`
}

EventView is one raw event for the Details log.

type Failure 

type Failure struct {
	Step   string `json:"step"`
	Reason string `json:"reason"`
	Fix    *Fix   `json:"fix,omitempty"`
	// Fixes lists every choice when the stop needs the owner to decide.
	Fixes  []Fix       `json:"fixes,omitempty"`
	Volume *VolumeInfo `json:"volume,omitempty"`
	// LogTail is the redacted last output of the crashed container.
	LogTail string `json:"log_tail,omitempty"`
	// Cause is the classified crash reason, when the output matched one.
	Cause *Cause `json:"cause,omitempty"`
}

Failure describes why an attempt stopped.

type Fix 

type Fix struct {
	ID      string `json:"id"`
	Label   string `json:"label"`
	Confirm bool   `json:"confirm,omitempty"`
}

Fix is a typed way to recover from a failed step.

func ClassifyFix 

func ClassifyFix(step, errText string) *Fix

ClassifyFix suggests a fix for a failure, or nil when none is known.

type LeftoverVolumeError 

type LeftoverVolumeError struct {
	Name      string
	SizeBytes int64
}

LeftoverVolumeError is the create_volume stop for a data volume a deleted database of the same name left behind.

func (*LeftoverVolumeError) Error 

func (e *LeftoverVolumeError) Error() string

type Recorder 

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

Recorder writes provisioning events.

func NewRecorder 

func NewRecorder(s Store) *Recorder

NewRecorder reads the attempt and throttle settings from the environment.

func (*Recorder) Begin 

func (r *Recorder) Begin(ctx context.Context, name string) (*Tracker, error)

Begin starts a new attempt and records the accepted step.

func (*Recorder) Open 

func (r *Recorder) Open(ctx context.Context, name string) *Tracker

Open returns a tracker for name's newest attempt unless it already reached ready, or nil when the database never had an attempt.

func (*Recorder) SetClock 

func (r *Recorder) SetClock(now func() time.Time)

SetClock replaces the time source, for tests.

type StepView 

type StepView struct {
	Step    string     `json:"step"`
	Status  string     `json:"status"`
	Detail  string     `json:"detail,omitempty"`
	Current int64      `json:"current,omitempty"`
	Total   int64      `json:"total,omitempty"`
	At      *time.Time `json:"at,omitempty"`
}

StepView is one step of an attempt as clients render it.

type Store 

type Store interface {
	AppendDatabaseProvisionEvent(ctx context.Context, e store.DatabaseProvisionEvent) error
	BeginDatabaseProvisionAttempt(ctx context.Context, name string, keep int) (string, error)
	LatestDatabaseProvisionAttempt(ctx context.Context, name string) (string, []store.DatabaseProvisionEvent, error)
}

Store is what the recorder needs; *store.DB satisfies it.

type Tracker 

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

Tracker writes one attempt's events. A nil Tracker ignores every call.

func (*Tracker) Done 

func (t *Tracker) Done(step, detail string)

Done marks step as finished.

func (*Tracker) Fail 

func (t *Tracker) Fail(step string, err error)

Fail marks step failed and every later step skipped.

func (*Tracker) Finish 

func (t *Tracker) Finish()

Finish marks every remaining step done and the attempt ready.

func (*Tracker) LogTail 

func (t *Tracker) LogTail(info CrashInfo)

LogTail records a crashed container's output on the current attempt. A nil Tracker ignores it.

func (*Tracker) Progress 

func (t *Tracker) Progress(step, detail string, cur, total int64)

Progress records progress for step, no more often than the throttle.

func (*Tracker) Pull 

func (t *Tracker) Pull(ev docker.PullEvent)

Pull converts a Docker pull report into pull_image events.

func (*Tracker) PullFinished 

func (t *Tracker) PullFinished() bool

PullFinished reports whether the pull step completed.

func (*Tracker) Skip 

func (t *Tracker) Skip(step, detail string)

Skip marks step as not needed.

func (*Tracker) Start 

func (t *Tracker) Start(step, detail string)

Start marks step as running.

type VolumeInfo 

type VolumeInfo struct {
	Name      string `json:"name"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
}

VolumeInfo names the leftover volume a failure is about.

func ParseLeftover 

func ParseLeftover(text string) (VolumeInfo, bool)

ParseLeftover extracts the volume name and size from a LeftoverVolumeError text.

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.