hooks

package
v0.85.0-pre.2 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Overview

Package hooks normalizes and executes configured dev-server on-change hooks.

The package isolates hook matching and execution policy so watcher/runloop code can remain focused on orchestration instead of hook internals.

Index

Constants

View Source 
const (
	// MaxConcurrentNoWaitHookExecutions bounds background hook concurrency.
	MaxConcurrentNoWaitHookExecutions = 8
)

Variables

This section is empty.

Functions

func ApplyHookStageActionsToWorkSet 

func ApplyHookStageActionsToWorkSet(
	work *eventpipeline.WorkSet,
	actions []wavewatch.RefreshAction,
) eventpipeline.RefreshActionApplicationResult

ApplyHookStageActionsToWorkSet mutates workset based on hook refresh actions.

func BuildEventHooksForProcessing 

func BuildEventHooksForProcessing(
	classifiedEvents []eventpipeline.ClassifiedEvent,
) []eventpipeline.EventWithHooks

BuildEventHooksForProcessing builds stage-partitioned hook entries per event.

func BuildNormalizedChangedFilePathsByWatchedPatternForHookContexts 

func BuildNormalizedChangedFilePathsByWatchedPatternForHookContexts(
	classifiedEvents []eventpipeline.ClassifiedEvent,
) map[string][]string

BuildNormalizedChangedFilePathsByWatchedPatternForHookContexts batches changed paths by pattern.

func BuildSkipDuplicateHooksByClassifiedEventIndex 

func BuildSkipDuplicateHooksByClassifiedEventIndex(
	classifiedEvents []eventpipeline.ClassifiedEvent,
) []bool

BuildSkipDuplicateHooksByClassifiedEventIndex returns per-event duplicate hook policy.

func CloneHookContextForExecution 

func CloneHookContextForExecution(
	hookContext *wavewatch.HookContext,
	executionContext context.Context,
) *wavewatch.HookContext

CloneHookContextForExecution creates a context copy for execution.

func DeriveBuildHookCommandTimeoutDuration 

func DeriveBuildHookCommandTimeoutDuration(
	coreConfig *waveconfig.CoreConfig,
	isDev bool,
) time.Duration

DeriveBuildHookCommandTimeoutDuration resolves build-hook command timeout.

func DeriveEventsWithHooksForExecution 

func DeriveEventsWithHooksForExecution(
	eventsWithHooks []eventpipeline.EventWithHooks,
	appStopStrategy eventpipeline.AppStopStrategy,
) []eventpipeline.EventWithHooks

DeriveEventsWithHooksForExecution resolves events to execute from app-stop strategy.

func DeriveExecutableHooksForStage 

func DeriveExecutableHooksForStage(
	watcher *watch.Watcher,
	eventWithHooks eventpipeline.EventWithHooks,
	stageType HookStageType,
) []wavewatch.OnChangeHook

DeriveExecutableHooksForStage filters hooks for current path and stage semantics.

func DeriveExecutionContextWithOptionalTimeout 

func DeriveExecutionContextWithOptionalTimeout(
	parentExecutionContext context.Context,
	timeoutDuration time.Duration,
) (context.Context, context.CancelFunc)

DeriveExecutionContextWithOptionalTimeout derives child context only when timeout is set.

func DeriveHookCallbackStageTimeoutMilliseconds 

func DeriveHookCallbackStageTimeoutMilliseconds(
	watchConfig *waveconfig.WatchConfig,
	stageType HookStageType,
) int

DeriveHookCallbackStageTimeoutMilliseconds resolves stage callback timeout override.

func DeriveHookCallbackTimeoutDurationForExecutionPlan 

func DeriveHookCallbackTimeoutDurationForExecutionPlan(
	watchConfig *waveconfig.WatchConfig,
	stageType HookStageType,
	executionPlan HookExecutionPlan,
) time.Duration

DeriveHookCallbackTimeoutDurationForExecutionPlan resolves callback timeout for plan.

func DeriveHookCommandStageTimeoutMilliseconds 

func DeriveHookCommandStageTimeoutMilliseconds(
	watchConfig *waveconfig.WatchConfig,
	stageType HookStageType,
) int

DeriveHookCommandStageTimeoutMilliseconds resolves stage command timeout override.

func DeriveHookCommandTimeoutDurationForExecutionPlan 

func DeriveHookCommandTimeoutDurationForExecutionPlan(
	watchConfig *waveconfig.WatchConfig,
	stageType HookStageType,
	executionPlan HookExecutionPlan,
) time.Duration

DeriveHookCommandTimeoutDurationForExecutionPlan resolves command timeout for plan.

func DeriveHookExecutionContext 

func DeriveHookExecutionContext(
	executionContext context.Context,
) context.Context

DeriveHookExecutionContext returns context or background fallback.

func DeriveHookExecutionContextError 

func DeriveHookExecutionContextError(executionContext context.Context) error

DeriveHookExecutionContextError derives context cancellation reason for hook execution.

func DeriveHookStageLabel 

func DeriveHookStageLabel(stageType HookStageType) string

DeriveHookStageLabel returns stable label for logs.

func DeriveResolvedTimeoutDurationFromStageAndExecutionPolicy 

func DeriveResolvedTimeoutDurationFromStageAndExecutionPolicy(
	stageTimeoutMilliseconds int,
	executionTimeoutMilliseconds int,
	disableStageTimeout bool,
) time.Duration

DeriveResolvedTimeoutDurationFromStageAndExecutionPolicy resolves timeout duration.

func DeriveStageHooksAndRunOnChangePolicyForEvent 

func DeriveStageHooksAndRunOnChangePolicyForEvent(
	eventWithHooks eventpipeline.EventWithHooks,
	stageType HookStageType,
) ([]wavewatch.OnChangeHook, bool)

DeriveStageHooksAndRunOnChangePolicyForEvent resolves stage hooks for one event.

func ExecuteHookCallbackSafely 

func ExecuteHookCallbackSafely(
	callback func(*wavewatch.HookContext) (*wavewatch.RefreshAction, error),
	hookContext *wavewatch.HookContext,
) (callbackAction *wavewatch.RefreshAction, callbackError error)

ExecuteHookCallbackSafely executes callback with panic-to-error conversion.

func ExecuteHookCommandWithContext 

func ExecuteHookCommandWithContext(
	executionContext context.Context,
	command string,
) error

ExecuteHookCommandWithContext executes a shell command under provided context.

func HookHasCommandAction 

func HookHasCommandAction(hook wavewatch.OnChangeHook) bool

HookHasCommandAction reports whether hook has command-side behavior.

func JoinHookExecutionErrorsInOrder 

func JoinHookExecutionErrorsInOrder(executionErrors []error) error

JoinHookExecutionErrorsInOrder joins non-nil errors preserving order.

func NormalizeHookContextPathShape 

func NormalizeHookContextPathShape(path string) string

NormalizeHookContextPathShape normalizes path formatting for hook contexts.

func PrepareHookForExecutionWithRunOnChangeOnlyRules 

func PrepareHookForExecutionWithRunOnChangeOnlyRules(
	isRunOnChangeOnly bool,
	hook wavewatch.OnChangeHook,
) (wavewatch.OnChangeHook, bool)

PrepareHookForExecutionWithRunOnChangeOnlyRules strips command behavior when policy requires callback-only execution.

func ResolveHookForStageExecution 

func ResolveHookForStageExecution(
	watcher *watch.Watcher,
	classifiedEvent eventpipeline.ClassifiedEvent,
	hook wavewatch.OnChangeHook,
) bool

ResolveHookForStageExecution returns true when hook should run for event path.

func ResolveHookForStageExecutionWithRunOnChangeOnlyPolicy 

func ResolveHookForStageExecutionWithRunOnChangeOnlyPolicy(
	watcher *watch.Watcher,
	classifiedEvent eventpipeline.ClassifiedEvent,
	isRunOnChangeOnly bool,
	shouldApplyRunOnChangeOnlyRules bool,
	hook wavewatch.OnChangeHook,
) (wavewatch.OnChangeHook, bool)

ResolveHookForStageExecutionWithRunOnChangeOnlyPolicy filters and rewrites one hook for execution.

func ResolveSequentialShellCommands 

func ResolveSequentialShellCommands(commands ...string) string

ResolveSequentialShellCommands joins non-empty commands into one shell expression.

func ShouldContinueConcurrentHookExecution 

func ShouldContinueConcurrentHookExecution(
	concurrentHookExecutionContext context.Context,
) bool

ShouldContinueConcurrentHookExecution reports whether context still allows work.

func ShouldExecuteBrowserPhaseAfterHookStageResults 

func ShouldExecuteBrowserPhaseAfterHookStageResults(
	preHookStageResult HookStageResult,
	concurrentHookStageResult HookStageResult,
	postHookStageResult HookStageResult,
) bool

ShouldExecuteBrowserPhaseAfterHookStageResults resolves browser phase execution.

func ShouldShortCircuitPipelineForHookStageResult 

func ShouldShortCircuitPipelineForHookStageResult(
	hookStageResult HookStageResult,
	configuredFailurePolicy HookStageFailurePolicy,
) bool

ShouldShortCircuitPipelineForHookStageResult returns true when stage should stop pipeline.

func ShouldStartAppAfterImplicitBuild 

func ShouldStartAppAfterImplicitBuild(
	runImplicitBuild bool,
	restartDecision eventpipeline.RestartPhaseDecision,
) bool

ShouldStartAppAfterImplicitBuild resolves whether app should restart after build.

func SortActionsByRestartPriority 

func SortActionsByRestartPriority(actions []wavewatch.RefreshAction)

SortActionsByRestartPriority sorts actions so restart actions are applied last.

func WrapHookExecutionErrorWithStageAndPath 

func WrapHookExecutionErrorWithStageAndPath(
	stageType HookStageType,
	path string,
	hookExecutionError error,
) error

WrapHookExecutionErrorWithStageAndPath adds stage/path context to hook errors.

Types

type HookExecutionPlan 

type HookExecutionPlan struct {
	Callback func(*wavewatch.HookContext) (*wavewatch.RefreshAction, error)
	Command  string

	CommandTimeoutMilliseconds  int
	DisableStageCommandTimeout  bool
	CallbackTimeoutMilliseconds int
	DisableStageCallbackTimeout bool
}

HookExecutionPlan is one executable hook plan after policy derivation.

func DeriveHookExecutionPlanFromHook 

func DeriveHookExecutionPlanFromHook(
	hook wavewatch.OnChangeHook,
	commandResolver func(wavewatch.OnChangeHook) string,
) HookExecutionPlan

DeriveHookExecutionPlanFromHook converts hook configuration into executable plan.

func DeriveHookExecutionPlansForEventStage 

func DeriveHookExecutionPlansForEventStage(
	watcher *watch.Watcher,
	eventWithHooks eventpipeline.EventWithHooks,
	stageType HookStageType,
	planResolver func(wavewatch.OnChangeHook) HookExecutionPlan,
) []HookExecutionPlan

DeriveHookExecutionPlansForEventStage builds executable plans for one stage.

type HookStageContinuationDecision 

type HookStageContinuationDecision struct {
	ShouldContinue      bool
	StopReason          HookStageContinuationStopReason
	RestartActionResult eventpipeline.RefreshActionApplicationResult
}

HookStageContinuationDecision resolves whether pipeline should continue.

func DeriveHookStageContinuationDecision 

func DeriveHookStageContinuationDecision(
	hookStageResult HookStageResult,
) HookStageContinuationDecision

DeriveHookStageContinuationDecision derives continuation for default policy.

func DeriveHookStageContinuationDecisionWithFailurePolicy 

func DeriveHookStageContinuationDecisionWithFailurePolicy(
	hookStageResult HookStageResult,
	hookStageFailurePolicy HookStageFailurePolicy,
) HookStageContinuationDecision

DeriveHookStageContinuationDecisionWithFailurePolicy applies explicit failure policy.

type HookStageContinuationStopReason 

type HookStageContinuationStopReason int

HookStageContinuationStopReason explains why stage continuation halted. 

const (
	// HookStageContinuationStopReasonNone means pipeline should continue.
	HookStageContinuationStopReasonNone HookStageContinuationStopReason = iota
	// HookStageContinuationStopReasonRestartRequested means hook action requested restart.
	HookStageContinuationStopReasonRestartRequested
	// HookStageContinuationStopReasonStageFailure means hook stage failure policy stopped execution.
	HookStageContinuationStopReasonStageFailure
)

type HookStageExecutionDescriptor 

type HookStageExecutionDescriptor struct {
	DescriptorIndex int
	EventWithHooks  eventpipeline.EventWithHooks
}

HookStageExecutionDescriptor binds deterministic event order to stage execution.

func DeriveHookStageExecutionDescriptors 

func DeriveHookStageExecutionDescriptors(
	eventsWithHooks []eventpipeline.EventWithHooks,
) []HookStageExecutionDescriptor

DeriveHookStageExecutionDescriptors returns deterministic execution descriptors.

type HookStageFailurePolicy 

type HookStageFailurePolicy int

HookStageFailurePolicy controls pipeline behavior after hook errors. 

const (
	// HookStageFailurePolicyContinue keeps pipeline moving despite stage errors.
	HookStageFailurePolicyContinue HookStageFailurePolicy = iota
	// HookStageFailurePolicyStop stops pipeline after stage errors.
	HookStageFailurePolicyStop
)

func DeriveHookStageFailurePolicy 

func DeriveHookStageFailurePolicy(
	configuredValue string,
) HookStageFailurePolicy

DeriveHookStageFailurePolicy resolves stage failure policy from config value.

func DeriveHookStageFailurePolicyFromConfiguredValue 

func DeriveHookStageFailurePolicyFromConfiguredValue(
	configuredValue string,
) HookStageFailurePolicy

DeriveHookStageFailurePolicyFromConfiguredValue parses failure policy text.

type HookStageResult 

type HookStageResult struct {
	Actions             []wavewatch.RefreshAction
	RefreshActionResult eventpipeline.RefreshActionApplicationResult
	StageType           HookStageType
	ExecutionErrors     []error
}

HookStageResult captures actions and errors produced by one stage.

func RunAndApplyHookStageActionsAndErrorsToWorkSet 

func RunAndApplyHookStageActionsAndErrorsToWorkSet(
	stageType HookStageType,
	runStage func() ([]wavewatch.RefreshAction, []error),
	work *eventpipeline.WorkSet,
) HookStageResult

RunAndApplyHookStageActionsAndErrorsToWorkSet runs stage producer and applies actions.

func RunAndApplyHookStageActionsToWorkSet 

func RunAndApplyHookStageActionsToWorkSet(
	stageType HookStageType,
	runStage func() []wavewatch.RefreshAction,
	work *eventpipeline.WorkSet,
) HookStageResult

RunAndApplyHookStageActionsToWorkSet runs actions producer and applies actions.

type HookStageType 

type HookStageType int

HookStageType identifies one hook execution stage. 

const (
	// HookStageTypePre executes before build work starts.
	HookStageTypePre HookStageType = iota
	// HookStageTypeConcurrent executes in parallel with build stage.
	HookStageTypeConcurrent
	// HookStageTypeConcurrentNoWait executes detached from cycle completion.
	HookStageTypeConcurrentNoWait
	// HookStageTypePost executes after build and concurrent stages complete.
	HookStageTypePost
)

type ImplicitBuildExecutionDecision 

type ImplicitBuildExecutionDecision struct {
	ShouldRunImplicitBuild    bool
	SkipImplicitBuildLogEntry string
}

ImplicitBuildExecutionDecision resolves whether implicit build should execute.

func DeriveImplicitBuildExecutionDecision 

func DeriveImplicitBuildExecutionDecision(
	shouldRunImplicitBuild bool,
	eventCount int,
) ImplicitBuildExecutionDecision

DeriveImplicitBuildExecutionDecision resolves implicit build behavior.

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.