hooks

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package hooks implements pre- and post snapshot hooks.

Plan is a generic executor for ExpectStepReports before and after an activity specified in a callback. It provides a reporting facility that can be polled while the plan is executing to gather progress information.

This package also provides all supported hook type implementations and abstractions around them.

Use For Other Kinds Of ExpectStepReports

This package REQUIRES REFACTORING before it can be used for other activities than snapshots, e.g. pre- and post-replication:

The Hook interface requires a hook to provide a Filesystems() filter, which doesn't make sense for all kinds of activities.

The hook implementations should move out of this package. However, there is a lot of tight coupling which to untangle isn't worth it ATM.

How This Package Is Used By Package Snapper

Deserialize a config.List using ListFromConfig(). Then it MUST filter the list to only contain hooks for a particular filesystem using hooksList.CopyFilteredForFilesystem(fs).

Then create a CallbackHook using NewCallbackHookForFilesystem().

Pass all of the above to NewPlan() which provides a Report() and Run() method:

Plan.Run(ctx context.Context,dryRun bool) executes the plan and take a context as argument that should contain a logger added using hooks.WithLogger()). The value of dryRun is passed through to the hooks' Run() method. Command hooks make it available in the environment variable ZREPL_DRYRUN.

Plan.Report() can be called while Plan.Run() is executing to give an overview of plan execution progress (future use in "zrepl status").

Index

Constants

View Source 
const (
	PhaseSnapshot = Phase("snapshot")
	PhaseTesting  = Phase("testing")
)
View Source 
const (
	Pre = Edge(1 << iota)
	Callback
	Post
)
View Source 
const (
	EnvType     = "ZREPL_HOOKTYPE"
	EnvDryRun   = "ZREPL_DRYRUN"
	EnvFS       = "ZREPL_FS"
	EnvSnapshot = "ZREPL_SNAPNAME"
	EnvTimeout  = "ZREPL_TIMEOUT"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CallbackHook 

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

func NewCallbackHook 

func NewCallbackHook(displayString string, cb HookJobCallback,
	filter zfs.DatasetFilter,
) *CallbackHook

func NewCallbackHookForFilesystem 

func NewCallbackHookForFilesystem(displayString string, fs *zfs.DatasetPath,
	cb HookJobCallback,
) *CallbackHook

func (*CallbackHook) ErrIsFatal 

func (h *CallbackHook) ErrIsFatal() bool

func (*CallbackHook) Filesystems 

func (h *CallbackHook) Filesystems() zfs.DatasetFilter

func (*CallbackHook) Run 

func (h *CallbackHook) Run(ctx context.Context, edge Edge, phase Phase,
	dryRun bool, extra map[string]string,
) HookReport

func (*CallbackHook) String 

func (h *CallbackHook) String() string

type CallbackHookReport 

type CallbackHookReport struct {
	Name string
	Err  error
}

func (*CallbackHookReport) Error 

func (r *CallbackHookReport) Error() string

func (*CallbackHookReport) HadError 

func (r *CallbackHookReport) HadError() bool

func (*CallbackHookReport) String 

func (r *CallbackHookReport) String() string

type Cmd added in v0.8.10 

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

func NewCommand added in v0.8.10 

func NewCommand(name string, arg ...string) *Cmd

func (*Cmd) CombinedOutput added in v0.8.10 

func (self *Cmd) CombinedOutput() []byte

func (*Cmd) Run added in v0.8.10 

func (self *Cmd) Run(ctx context.Context) error

func (*Cmd) String added in v0.8.10 

func (self *Cmd) String() string

func (*Cmd) WithEnv added in v0.8.10 

func (self *Cmd) WithEnv(envs ...map[string]string) *Cmd

func (*Cmd) WithTimeout added in v0.8.10 

func (self *Cmd) WithTimeout(t time.Duration) *Cmd

type CommandHook 

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

func NewCommandHook 

func NewCommandHook(in *config.HookCommand) (*CommandHook, error)

func (*CommandHook) ErrIsFatal 

func (self *CommandHook) ErrIsFatal() bool

func (*CommandHook) Filesystems 

func (self *CommandHook) Filesystems() zfs.DatasetFilter

func (*CommandHook) Run 

func (self *CommandHook) Run(ctx context.Context, edge Edge, phase Phase,
	dryRun bool, extra map[string]string,
) HookReport

func (*CommandHook) String 

func (self *CommandHook) String() string

func (*CommandHook) WithCombinedOutput added in v0.8.10 

func (self *CommandHook) WithCombinedOutput() *CommandHook

type CommandHookReport 

type CommandHookReport struct {
	Command string
	Args    []string // currently always empty
	Env     map[string]string
	Err     error

	CombinedOutput []byte
}

func (*CommandHookReport) Error 

func (r *CommandHookReport) Error() string

func (*CommandHookReport) HadError 

func (r *CommandHookReport) HadError() bool

func (*CommandHookReport) String 

func (r *CommandHookReport) String() string

type Edge 

type Edge uint

func (Edge) String 

func (i Edge) String() string

func (Edge) StringForPhase 

func (e Edge) StringForPhase(phase Phase) string

type Hook 

type Hook interface {
	String() string

	// If true and the Pre edge invocation of Run fails, Post edge will not run
	// and other Pre edges will not run.
	ErrIsFatal() bool

	// Run is invoked by HookPlan for a Pre edge. If HookReport.HadError() ==
	// false, the Post edge will be invoked, too.
	Run(ctx context.Context, edge Edge, phase Phase, dryRun bool,
		extra map[string]string,
	) HookReport
}

type HookJobCallback 

type HookJobCallback func(ctx context.Context) error

type HookReport 

type HookReport interface {
	String() string
	HadError() bool
	Error() string
}

type List 

type List []*CommandHook

func ListFromConfig 

func ListFromConfig(in []config.HookCommand) (List, error)

func (List) CopyFilteredForFilesystem 

func (self List) CopyFilteredForFilesystem(fs *zfs.DatasetPath) (List, error)

func (List) WithCombinedOutput added in v0.8.10 

func (self List) WithCombinedOutput() List

type Phase 

type Phase string

func (Phase) String 

func (p Phase) String() string

type Plan 

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

func NewPlan 

func NewPlan(hooks List, phase Phase, cb *CallbackHook, extra map[string]string,
) (*Plan, error)

func (*Plan) Report 

func (p *Plan) Report() PlanReport

func (*Plan) Run 

func (p *Plan) Run(ctx context.Context, dryRun bool)

type PlanReport 

type PlanReport []Step

func (PlanReport) HadError 

func (r PlanReport) HadError() bool

func (PlanReport) HadFatalError 

func (r PlanReport) HadFatalError() bool

func (PlanReport) String 

func (r PlanReport) String() string

type Step 

type Step struct {
	Hook       Hook
	Edge       Edge
	Status     StepStatus
	Begin, End time.Time
	// Report may be nil
	//
	// FIXME cannot serialize this for client status, but contains interesting
	// info (like what error happened)
	Report HookReport
}

func (Step) String 

func (s Step) String() (out string)

type StepStatus 

type StepStatus int
const (
	StepPending StepStatus = 1 << iota
	StepExec
	StepOk
	StepErr
	StepSkippedDueToFatalErr
	StepSkippedDueToPreErr
)

func StepStatusString 

func StepStatusString(s string) (StepStatus, error)

StepStatusString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func StepStatusValues 

func StepStatusValues() []StepStatus

StepStatusValues returns all values of the enum

func (StepStatus) IsAStepStatus 

func (i StepStatus) IsAStepStatus() bool

IsAStepStatus returns "true" if the value is listed in the enum definition. "false" otherwise

func (StepStatus) String 

func (i StepStatus) String() string

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.