hookstate

package
v0.0.0-...-20647f5 Latest Latest
Warning

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

 Go to latest Published: Nov 22, 2024 License: GPL-3.0 Imports: 28 Imported by: 125

Documentation

Overview

Package hookstate implements the manager and state aspects responsible for the running of hooks.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HookTask 

func HookTask(st *state.State, summary string, setup *HookSetup, contextData map[string]interface{}) *state.Task

HookTask returns a task that will run the specified hook. Note that the initial context must properly marshal and unmarshal with encoding/json.

func HookTaskWithUndo 

func HookTaskWithUndo(st *state.State, summary string, setup *HookSetup, undo *HookSetup, contextData map[string]interface{}) *state.Task

HookTaskWithUndo returns a task that will run the specified hook. On error the undo hook will be executed. Note that the initial context must properly marshal and unmarshal with encoding/json.

func MockRunHook 

func MockRunHook(hookInvoke func(c *Context, tomb *tomb.Tomb) ([]byte, error)) (restore func())

MockRunHook mocks the actual invocation of hooks for tests.

func NewGateAutoRefreshHookHandler 

func NewGateAutoRefreshHookHandler(context *Context) *gateAutoRefreshHookHandler

func SetupGateAutoRefreshHook 

func SetupGateAutoRefreshHook(st *state.State, snapName string) *state.Task

func SetupInstallComponentHook 

func SetupInstallComponentHook(st *state.State, snap, component string) *state.Task

func SetupInstallHook 

func SetupInstallHook(st *state.State, snapName string) *state.Task

func SetupPostRefreshComponentHook 

func SetupPostRefreshComponentHook(st *state.State, snap, component string) *state.Task

func SetupPostRefreshHook 

func SetupPostRefreshHook(st *state.State, snapName string) *state.Task

func SetupPreRefreshComponentHook 

func SetupPreRefreshComponentHook(st *state.State, snap, component string) *state.Task

func SetupPreRefreshHook 

func SetupPreRefreshHook(st *state.State, snapName string) *state.Task

func SetupRemoveComponentHook 

func SetupRemoveComponentHook(st *state.State, snap, component string) *state.Task

func SetupRemoveHook 

func SetupRemoveHook(st *state.State, snapName string) *state.Task

Types

type Context 

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

Context represents the context under which the snap is calling back into snapd. It is associated with a task when the callback is happening from within a hook, or otherwise considered an ephemeral context in that its associated data will be discarded once that individual call is finished.

func NewContext 

func NewContext(task *state.Task, state *state.State, setup *HookSetup, handler Handler, contextID string) (*Context, error)

NewContext returns a new context associated with the provided task or an ephemeral context if task is nil.

A random ID is generated if contextID is empty.

func (*Context) Cache 

func (c *Context) Cache(key, value interface{})

Cache associates value with key. The cached value is not persisted. Note that the context needs to be locked/unlocked by the caller.

func (*Context) Cached 

func (c *Context) Cached(key interface{}) interface{}

Cached returns the cached value associated with the provided key. It returns nil if there is no entry for key. Note that the context needs to be locked and unlocked by the caller.

func (*Context) ChangeID 

func (c *Context) ChangeID() string

ChangeID returns change ID for non-ephemeral context or empty string otherwise.

func (*Context) ComponentName 

func (c *Context) ComponentName() string

ComponentName returns the name of the component containing the hook. If the hook is not associated with a component, it returns an empty string.

func (*Context) ComponentRevision 

func (c *Context) ComponentRevision() snap.Revision

ComponentRevision returns the revision of the snap component containing the hook. This returned revision is only valid if the hook is a component hook.

func (*Context) Done 

func (c *Context) Done() error

Done is called to notify the context that its hook has exited successfully. It will call all of the functions added in OnDone (even if one of them returns an error) and will return the first error encountered. Note that the context needs to be locked/unlocked by the caller.

func (*Context) Errorf 

func (c *Context) Errorf(format string, args ...interface{})

Errorf logs errors to the context, either to the logger for ephemeral contexts or the task log.

Context must be locked.

func (*Context) Get 

func (c *Context) Get(key string, value interface{}) error

Get unmarshals the stored value associated with the provided key into the value parameter. Note that the context needs to be locked/unlocked by the caller.

func (*Context) Handler 

func (c *Context) Handler() Handler

Handler returns the handler for this context

func (*Context) HookName 

func (c *Context) HookName() string

HookName returns the name of the hook in this context.

func (*Context) HookSource 

func (c *Context) HookSource() string

HookSource returns a string that identifies the source of a hook. This could either be a snap or a component. Snaps will be in the form "<snap_instance>". Components will be in the form "<snap_instance>+<component_name>".

func (*Context) ID 

func (c *Context) ID() string

ID returns the ID of the context.

func (*Context) InstanceName 

func (c *Context) InstanceName() string

InstanceName returns the name of the snap instance containing the hook.

func (*Context) IsComponentHook 

func (c *Context) IsComponentHook() bool

IsComponentHook returns true if this context is associated with a component hook.

func (*Context) IsEphemeral 

func (c *Context) IsEphemeral() bool

func (*Context) IsSnapHook 

func (c *Context) IsSnapHook() bool

IsSnapHook returns true if this context is associated with a snap hook.

func (*Context) Lock 

func (c *Context) Lock()

Lock acquires the lock for this context (required for Set/Get, Cache/Cached, Logf/Errorf), and OnDone/Done).

func (*Context) Logf 

func (c *Context) Logf(fmt string, args ...interface{})

Logf logs to the context, either to the logger for ephemeral contexts or the task log.

Context must be locked.

func (*Context) OnDone 

func (c *Context) OnDone(f func() error)

OnDone requests the provided function to be run once the context knows it's complete. This can be called multiple times; each function will be called in the order in which they were added. Note that the context needs to be locked and unlocked by the caller.

func (*Context) Set 

func (c *Context) Set(key string, value interface{})

Set associates value with key. The provided value must properly marshal and unmarshal with encoding/json. Note that the context needs to be locked and unlocked by the caller.

func (*Context) SnapRevision 

func (c *Context) SnapRevision() snap.Revision

SnapRevision returns the revision of the snap containing the hook.

func (*Context) State 

func (c *Context) State() *state.State

State returns the state contained within the context

func (*Context) Task 

func (c *Context) Task() (*state.Task, bool)

Task returns the task associated with the hook or (nil, false) if the context is ephemeral and task is not available.

func (*Context) Timeout 

func (c *Context) Timeout() time.Duration

Timeout returns the maximum time this hook can run

func (*Context) Unlock 

func (c *Context) Unlock()

Unlock releases the lock for this context.

type Handler 

type Handler interface {
	// Before is called right before the hook is to be run.
	Before() error

	// Done is called right after the hook has finished successfully.
	Done() error

	// Error is called if the hook encounters an error while running.
	// The returned bool flag indicates if the original hook error should be
	// ignored by hook manager.
	Error(hookErr error) (ignoreHookErr bool, err error)
}

Handler is the interface a client must satisfy to handle hooks.

type HandlerGenerator 

type HandlerGenerator func(*Context) Handler

HandlerGenerator is the function signature required to register for hooks.

type HookManager 

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

HookManager is responsible for the maintenance of hooks in the system state. It runs hooks when they're requested, assuming they're present in the given snap. Otherwise they're skipped with no error.

func Manager 

func Manager(s *state.State, runner *state.TaskRunner) (*HookManager, error)

Manager returns a new HookManager.

func (*HookManager) Context 

func (m *HookManager) Context(cookieID string) (*Context, error)

Context obtains the context for the given cookie ID.

func (*HookManager) Ensure 

func (m *HookManager) Ensure() error

Ensure implements StateManager.Ensure.

func (*HookManager) EphemeralRunHook 

func (m *HookManager) EphemeralRunHook(ctx context.Context, hooksup *HookSetup, contextData map[string]interface{}) (*Context, error)

func (*HookManager) GracefullyWaitRunningHooks 

func (m *HookManager) GracefullyWaitRunningHooks() bool

GracefullyWaitRunningHooks waits for currently running hooks to finish up to the default hook timeout. Returns true if there are no more running hooks on exit.

func (*HookManager) NumRunningHooks 

func (m *HookManager) NumRunningHooks() int

NumRunningHooks returns the number of hooks running at the moment.

func (*HookManager) Register 

func (m *HookManager) Register(pattern *regexp.Regexp, generator HandlerGenerator)

Register registers a function to create Handler values whenever hooks matching the provided pattern are run.

func (*HookManager) RegisterHijack 

func (m *HookManager) RegisterHijack(hookName, instanceName string, f hijackFunc)

func (*HookManager) StopHooks 

func (m *HookManager) StopHooks()

StopHooks kills all currently running hooks and returns after that's done.

type HookSetup 

type HookSetup struct {
	Snap     string        `json:"snap"`
	Revision snap.Revision `json:"revision"`
	Hook     string        `json:"hook"`
	Timeout  time.Duration `json:"timeout,omitempty"`

	// Optional is true if we should not error if the script is missing.
	Optional bool `json:"optional,omitempty"`

	// Always is true if we should run the handler even if the script is
	// missing.
	Always bool `json:"always,omitempty"`

	// IgnoreError is true if we should not run the handler's Error() on error.
	IgnoreError bool `json:"ignore-error,omitempty"`

	// Component is the component name that the hook is associated with. If the
	// hook is not associated with a component, the string will be empty.
	Component string `json:"component,omitempty"`

	// ComponentRevision is the revision of the component that the hook is
	// associated with. Only valid if Component is not empty.
	ComponentRevision snap.Revision `json:"component-revision"`
}

HookSetup is a reference to a hook within a specific snap.

type SnapHookHandler 

type SnapHookHandler struct{}

func (*SnapHookHandler) Before 

func (h *SnapHookHandler) Before() error

func (*SnapHookHandler) Done 

func (h *SnapHookHandler) Done() error

func (*SnapHookHandler) Error 

func (h *SnapHookHandler) Error(err error) (bool, error)

Source Files

View all Source files

Directories

Path Synopsis
Package ctlcmd contains the various snapctl subcommands.
 Package ctlcmd contains the various snapctl subcommands.

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.