maintenance

package

v0.9.1 Latest Latest Go to latest Published: Sep 14, 2026 License: MIT Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/deploymenttheory/go-apple-dm

Links

Open Source Insights

Documentation ¶

Overview ¶

Package maintenance coordinates a pause in server writes before a checkpoint.

Processes register participants in shared SQL storage. When an operator requests a pause, participants stop accepting requests, cancel their workers and wait for existing writes to finish before acknowledging. The worker callback must honor cancellation and return only after its writes stop. WaitDrained succeeds only when every registered participant has acknowledged.

Participants never expire automatically: a missed heartbeat does not prove that a process stopped writing. Operators must stop an unreachable process before forgetting it. Cancellation leaves the persistent pause in place; resuming writes requires the matching ownership ticket.

See the recovery guide for the operator workflow: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/operations/recovery.md

Index ¶

Variables
func MigrationSet(d sqlcommon.Dialect) (sqlcommon.MigrationSet, error)
type Member
type Participant
type Status
- func (s Status) Ready() bool
type Store
- func Open(ctx context.Context, db *sql.DB, d sqlcommon.Dialect, initialize bool) (*Store, error)

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrInvalid     = errors.New("maintenance: invalid argument")
	ErrFenced      = errors.New("maintenance: writes paused")
	ErrOwner       = errors.New("maintenance: fence ownership changed")
	ErrParticipant = errors.New("maintenance: participant registration missing")
)

Functions ¶

func MigrationSet ¶

func MigrationSet(d sqlcommon.Dialect) (sqlcommon.MigrationSet, error)

MigrationSet exposes the compiled schema for coordinated recovery.

Types ¶

type Member ¶

type Member struct {
	ID      string `json:"id"`
	Label   string `json:"label"`
	Drained bool   `json:"drained"`
}

type Participant ¶

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

Participant covers a process's HTTP handlers and background workers. Setup clients register for their entire operation and Close when all writes finish.

func (*Participant) Close ¶

func (p *Participant) Close(ctx context.Context) error

Close is called after Run and all setup operations stop. A failed unregister deliberately leaves the member present, so recovery cannot assume it drained.

func (*Participant) ID ¶

func (p *Participant) ID() string

func (*Participant) Run ¶

func (p *Participant) Run(ctx context.Context, workers func(context.Context) error) error

Run supervises one worker bundle. A pause closes admission, cancels workers, and waits for both workers and admitted HTTP requests before acknowledging. The callback must honor cancellation and return only after its writes stop.

func (*Participant) Wrap ¶

func (p *Participant) Wrap(next http.Handler) http.Handler

Wrap rejects new requests during maintenance, including on a control-store failure. An admitted request finishes before the participant acknowledges.

type Status ¶

type Status struct {
	Token   string   `json:"token,omitempty"`
	Members []Member `json:"members"`
}

func (Status) Ready ¶

func (s Status) Ready() bool

type Store ¶

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

func Open ¶

func Open(ctx context.Context, db *sql.DB, d sqlcommon.Dialect, initialize bool) (*Store, error)

Open optionally initializes the schema. Recovery control clients use false: a server version without participation cannot safely be backed up online.

func (*Store) Forget ¶

func (s *Store) Forget(ctx context.Context, ticket, id string, processStopped bool) error

Forget requires an explicit assertion that the named process has stopped. Calling this on a running process invalidates the backup's consistency guarantee.

func (*Store) Register ¶

func (s *Store) Register(ctx context.Context, label string) (*Participant, error)

func (*Store) Request ¶

func (s *Store) Request(ctx context.Context, ticket string) error

Request pauses new registration. Persist the caller-generated ticket before requesting a fence, so an interrupted backup can be explicitly resumed.

func (*Store) Resume ¶

func (s *Store) Resume(ctx context.Context, ticket string) error

func (*Store) Status ¶

func (s *Store) Status(ctx context.Context) (Status, error)

func (*Store) WaitDrained ¶

func (s *Store) WaitDrained(ctx context.Context, ticket string) error

WaitDrained returns only after every registered process acknowledges this fence. Cancellation leaves the persistent fence in place for inspection and recovery.

Source Files ¶

View all Source files

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