hookstate

Documentation

Overview

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

Index

• func HookTask(st *state.State, summary string, setup *HookSetup, ...) *state.Task
• func HookTaskWithUndo(st *state.State, summary string, setup *HookSetup, undo *HookSetup, ...) *state.Task
• func MockRunHook(hookInvoke func(c *Context, tomb *tomb.Tomb) ([]byte, error)) (restore func())
• func SetupInstallHook(st *state.State, snapName string) *state.Task
• func SetupPostRefreshHook(st *state.State, snapName string) *state.Task
• func SetupPreRefreshHook(st *state.State, snapName string) *state.Task
• func SetupRemoveHook(st *state.State, snapName string) *state.Task
• type Context
  • func NewContext(task *state.Task, state *state.State, setup *HookSetup, handler Handler, ...) (*Context, error)
  • func (c *Context) Cache(key, value interface{})
  • func (c *Context) Cached(key interface{}) interface{}
  • func (c *Context) Done() error
  • func (c *Context) Get(key string, value interface{}) error
  • func (c *Context) Handler() Handler
  • func (c *Context) HookName() string
  • func (c *Context) ID() string
  • func (c *Context) InstanceName() string
  • func (c *Context) IsEphemeral() bool
  • func (c *Context) Lock()
  • func (c *Context) OnDone(f func() error)
  • func (c *Context) Set(key string, value interface{})
  • func (c *Context) SnapRevision() snap.Revision
  • func (c *Context) State() *state.State
  • func (c *Context) Task() (*state.Task, bool)
  • func (c *Context) Timeout() time.Duration
  • func (c *Context) Unlock()
• type Handler
• type HandlerGenerator
• type HookManager
  • func Manager(s *state.State, runner *state.TaskRunner) (*HookManager, error)
  • func (m *HookManager) Context(cookieID string) (*Context, error)
  • func (m *HookManager) Ensure() error
  • func (m *HookManager) GracefullyWaitRunningHooks() bool
  • func (m *HookManager) NumRunningHooks() int
  • func (m *HookManager) Register(pattern *regexp.Regexp, generator HandlerGenerator)
  • func (m *HookManager) RegisterHijack(hookName, instanceName string, f hijackFunc)
  • func (m *HookManager) StopHooks()
• type HookSetup

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 SetupInstallHook

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

func SetupPostRefreshHook

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

func SetupPreRefreshHook

func SetupPreRefreshHook(st *state.State, snapName 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) 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) 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) 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) IsEphemeral

func (c *Context) IsEphemeral() bool

func (*Context) Lock

func (c *Context) Lock()

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

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.
	Error(err error) error
}

Handler is the interface a client must satify 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) 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    bool          `json:"optional,omitempty"`     // do not error if script is missing
	Always      bool          `json:"always,omitempty"`       // run handler even if script is missing
	IgnoreError bool          `json:"ignore-error,omitempty"` // do not run handler's Error() on error
	TrackError  bool          `json:"track-error,omitempty"`  // report hook error to oopsie
}

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