hookstate

Documentation

Index

• func Hook(st *state.State, sdk string, timeout time.Duration, hook WorkshopHookType) *state.Task
• type Context
  • func NewContext(task *state.Task, state *state.State, setup *HookSetup, handler Handler, ...) (*Context, error)
  • func (c *Context) Cache(key, value any)
  • func (c *Context) Cached(key any) any
  • func (c *Context) ChangeID() string
  • func (c *Context) Done() error
  • func (c *Context) Errorf(format string, args ...any)
  • func (c *Context) Get(key string, value any) error
  • func (c *Context) Handler() Handler
  • func (c *Context) HookName() string
  • func (c *Context) ID() string
  • func (c *Context) IsEphemeral() bool
  • func (c *Context) Lock()
  • func (c *Context) Logf(fmt string, args ...any)
  • func (c *Context) OnDone(f func() error)
  • func (c *Context) Sdk() string
  • func (c *Context) Set(key string, value any)
  • 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 HookLog
  • func NewHookLog() *HookLog
  • func (h *HookLog) Output() *bytes.Buffer
  • func (h *HookLog) Write(buf []byte) (n int, err error)
• type HookLogKey
• type HookManager
  • func New(s *state.State, runner *state.TaskRunner) *HookManager
  • func (m *HookManager) Context(cookieID string) (*Context, error)
  • func (w *HookManager) Ensure() error
  • func (m *HookManager) Register(pattern *regexp.Regexp, generator HandlerGenerator)
• type HookSetup
  • func (h *HookSetup) Type() string
• type WorkshopHookType
  • func (s WorkshopHookType) String() string

Functions

func Hook

func Hook(st *state.State, sdk string, timeout time.Duration, hook WorkshopHookType) *state.Task

Types

type Context

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

Context represents the context under which the workshop is calling back into workshopd. 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 any)

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 any) any

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) 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 ...any)

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 any) 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) 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, Logf/Errorf), and OnDone/Done).

func (*Context) Logf

func (c *Context) Logf(fmt string, args ...any)

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) Sdk

func (c *Context) Sdk() string

Sdk returns the name of the SDK in this context.

func (*Context) Set

func (c *Context) Set(key string, value any)

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) 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 HookLog

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

func NewHookLog

func NewHookLog() *HookLog

func (*HookLog) Output

func (h *HookLog) Output() *bytes.Buffer

func (*HookLog) Write

func (h *HookLog) Write(buf []byte) (n int, err error)

type HookLogKey

type HookLogKey string

type HookManager

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

func New

func New(s *state.State, runner *state.TaskRunner) *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 (w *HookManager) Ensure() error

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.

type HookSetup

type HookSetup struct {
	Sdk         string           `json:"sdk"`
	HookType    WorkshopHookType `json:"type"`
	Timeout     time.Duration    `json:"timeout"`
	IgnoreError bool             `json:"bool"`
}

func (*HookSetup) Type

func (h *HookSetup) Type() string

type WorkshopHookType

type WorkshopHookType int

const (
	SetupBase WorkshopHookType = iota
	SetupProject
	SaveState
	RestoreState
	CheckHealth
)

func (WorkshopHookType) String

func (s WorkshopHookType) String() string