events

package
v1.7.2 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2026 License: AGPL-3.0 Imports: 25 Imported by: 1

Documentation

Overview

Package events implements the Lifecycle Control Plane.

It provides a reactive, event-driven orchestration layer that decouples event production (Sources) from business logic reactions (Handlers) using a centralized dispatcher (Router).

Core Concepts

  • Router: The central hub that collects events from multiple sources and dispatches them to matching handlers based on pattern matching (glob).
  • Source: Event producers that bridge external stimuli (OS Signals, Webhooks, File Changes, Tickers) into the lifecycle ecosystem.
  • Handler: Components that react to events to perform actions like reloading configuration, suspending workers, or initiating shutdown.
  • Event: A simple string-based stimulus that triggers reactions.

Usage Pattern 

router := events.NewRouter()

// 1. Add Sources
router.AddSource(events.NewWebhookSource(":8080"))
router.AddSource(events.NewFileWatchSource("config.yaml"))

// 2. Register Handlers
router.Handle("webhook/reload", events.NewReloadHandler(myReloadFunc))
router.HandleFunc("file/modified", func(ctx context.Context, e events.Event) error {
    return myCustomAction()
})

// 3. Run with Lifecycle
lifecycle.Run(router)

Design Philosophy

The Control Plane is designed to be "plug-and-play". By consolidating all event logic here, applications can easily swap a "Signal-based reload" for a "Webhook-based reload" without changing the core business logic.

Context-Aware Handlers

Handlers like NewShutdown and NewShutdownFunc are context-aware; they automatically discover the active signal.Context using signal.FromContext(ctx) and trigger its Shutdown() method. This ensures that even in complex interactive modes, the "Quit" command correctly exits the main Run loop.

Index

Constants

View Source 
const (
	// StatusUp indicates the component is healthy.
	StatusUp = "UP"
	// StatusDown indicates the component is unhealthy.
	StatusDown = "DOWN"
)

Variables

View Source 
var DefaultRouter = NewRouter()

DefaultRouter is the default instance for package-level helpers.

View Source 
var ErrNotHandled = errors.New("event not handled")

ErrNotHandled is a sentinel error that handlers can return to indicate they did not process the event, allowing the caller (e.g. SmartSignalHandler) to attempt a fallback action.

Functions

func Dispatch 

func Dispatch(ctx context.Context, e Event)

Dispatch finds the handler for an event on the DefaultRouter and executes it.

func Handle 

func Handle(pattern string, handler Handler)

Handle registers a handler on the Default

func HandleFunc 

func HandleFunc(pattern string, handler func(context.Context, Event) error)

HandleFunc registers a handler function on the Default

func Start 

func Start(ctx context.Context) error

Start begins the listening loop for the DefaultRouter.

func Use 

func Use(mw Middleware)

Use appends a middleware to the DefaultRouter.

Types

type BaseSource 

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

BaseSource provides default implementation for Source.Events() method. Embed this in your source types to avoid repeating the events channel boilerplate.

Example: 

type MySource struct {
    BaseSource
    // custom fields...
}

func NewMySource() *MySource {
    return &MySource{
        BaseSource: NewBaseSource("my-source", 10), // name and buffer size
    }
}

func (s *MySource) Start(ctx context.Context) error {
    for {
        event := // ... create event
        if err := s.Emit(ctx, event); err != nil {
            return err
        }
    }
}

The embedding provides Events() implementation automatically.

func NewBaseSource 

func NewBaseSource(name string, bufferSize int) BaseSource

NewBaseSource creates a BaseSource with the specified name and buffer size. A buffer of 10-100 is recommended for most sources to prevent blocking.

func (*BaseSource) Close 

func (b *BaseSource) Close()

Close closes the events channel. Call this when the source is done emitting

func (*BaseSource) Emit 

func (b *BaseSource) Emit(ctx context.Context, e Event) error

Emit sends an event to the events channel. This is a helper method for source implementations. It blocks if the channel buffer is full, providing backpressure. It returns an error if the context is cancelled while waiting.

func (*BaseSource) Events 

func (b *BaseSource) Events() <-chan Event

Events returns the read-only events channel. This method is automatically available via embedding.

func (*BaseSource) TryEmit 

func (b *BaseSource) TryEmit(e Event) bool

TryEmit attempts to send an event without blocking. Returns true if the event was sent, false if the buffer was full.

type ChannelSource 

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

ChannelSource adapts an external Go channel to the Source interface. Unlike other sources, it delegates Events() to the external channel rather than using BaseSource, since the channel is provided by the caller.

Use this to bridge async systems, testing, or internal event loops into the lifecycle Control Plane.

func NewChannelSource 

func NewChannelSource(ch <-chan Event) *ChannelSource

NewChannelSource returns a new source that reads from the given channel. The caller retains ownership of the channel and is responsible for closing it.

func (*ChannelSource) Events 

func (s *ChannelSource) Events() <-chan Event

Events returns the external channel for the router to consume. This source does NOT use BaseSource because the channel is externally managed.

func (*ChannelSource) Start 

func (s *ChannelSource) Start(ctx context.Context) error

Start blocks until the context is cancelled. Since the channel is external, we simply wait for the context to finish. The caller is responsible for managing the channel lifecycle.

type CheckFunc 

type CheckFunc func(ctx context.Context) error

CheckFunc is a function that checks the health of a component.

type ClearLineEvent 

type ClearLineEvent struct{}

ClearLineEvent is triggered when an interactive input is interrupted (e.g. Ctrl+C) but the process should NOT exit. Applications can use this to clear the current line and show a fresh prompt.

func (ClearLineEvent) String 

func (e ClearLineEvent) String() string

type DebounceOption added in v1.7.0 

type DebounceOption func(*debounce)

DebounceOption configures the DebounceHandler.

func WithMaxWait added in v1.7.0 

func WithMaxWait(maxWait time.Duration) DebounceOption

WithMaxWait sets a maximum duration that events can be delayed before a flush is forced. This prevents "starvation" when events arrive continuously at an interval shorter than the debounce window.

type Escalator 

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

Escalator is a handler that escalates from a Primary handler to a Fallback handler based on whether the Primary handler successfully handled the event.

Pattern: "Double-Tap" or "Try-Then-Force".

Logic: 1. If already escalating, call Fallback. 2. Call Primary. 3. If Primary returns ErrNotHandled, switch to escalating and call Fallback. 4. If Primary returns nil (handled), remain in Primary mode (reset). 5. If Primary returns other error, return it (stop).

func NewEscalator 

func NewEscalator(primary Handler, fallback Handler) *Escalator

NewEscalator creates a new Escalator handler. primary: The initial handler to try (e.g., "Interrupt", "Suspend", "Clear Line"). fallback: The handler to use if primary fails to handle or upon escalation (e.g., "Quit", "Force Exit").

func (*Escalator) HandleEvent 

func (h *Escalator) HandleEvent(ctx context.Context, e Event) error

HandleEvent implements the Handler interface.

func (*Escalator) Reset 

func (h *Escalator) Reset()

Reset resets the escalator to the primary state.

type Event 

type Event interface {
	String() string
}

Event is a stimulus that triggers a reaction. It can be a system signal, a webhook, a time tick, or a custom application event.

type FileOp 

type FileOp string

FileOp represents a file operation (preserved for backward compatibility). 

const (
	FileOpCreate FileOp = "CREATE"
	FileOpWrite  FileOp = "WRITE"
	FileOpRemove FileOp = "REMOVE"
	FileOpRename FileOp = "RENAME"
	FileOpChmod  FileOp = "CHMOD"
)

type FileWatchOption added in v1.7.0 

type FileWatchOption func(*FileWatchSource)

FileWatchOption configures the FileWatchSource

func WithFilter added in v1.7.0 

func WithFilter(filter func(path string) bool) FileWatchOption

WithFilter sets a function to ignore certain paths. If the filter returns false, the path is ignored. This is useful for omitting .git folders or locks.

func WithRecursive added in v1.7.0 

func WithRecursive(enabled bool) FileWatchOption

WithRecursive enables recursive watching of all subdirectories. WARNING: Operating systems have limits on the number of open file watches (e.g., fs.inotify.max_user_watches on Linux). Using WithRecursive on massive directories like node_modules or vendor without a proper WithFilter may exhaust OS resources and cause silent failures or system instability.

type FileWatchSource 

type FileWatchSource struct {
	BaseSource
	// contains filtered or unexported fields
}

FileWatchSource watches a file for changes and emits events when it is modified. This is useful for configuration hot-reloading without process restart.

This implementation uses fsnotify for efficient, event-driven file watching (supported on Linux, Windows, macOS, BSD).

Example: 

router := lifecycle.NewRouter()
AddSource(lifecycle.NewFileWatchSource("config.yaml"))
Handle("file/*", lifecycle.NewReloadHandler(loadConfig))

func NewFileWatchSource 

func NewFileWatchSource(path string, opts ...FileWatchOption) *FileWatchSource

NewFileWatchSource creates a new file watcher for the specified path. The path will be cleaned using filepath.Clean.

Unlike the legacy polling-based approach, this uses fsnotify for immediate event notification when files change.

func (*FileWatchSource) Start 

func (f *FileWatchSource) Start(ctx context.Context) error

Start begins watching the file for changes. It blocks until the context is cancelled or an unrecoverable error occurs.

type Handler 

type Handler interface {
	HandleEvent(ctx context.Context, e Event) error
}

Handler responds to an event.

func DebounceHandler added in v1.7.0 

func DebounceHandler(next Handler, window time.Duration, mergeFunc func(a, b Event) Event, opts ...DebounceOption) Handler

func NewReload 

func NewReload(onReload func(context.Context) error) Handler

func NewShutdown 

func NewShutdown(cancel context.CancelFunc) Handler

NewShutdown returns a handler that cancels context. It is automatically wrapped in Once to ensure idempotency.

func NewShutdownFunc 

func NewShutdownFunc(fn func()) Handler

NewShutdownFunc returns a handler that executes the given function once. Useful for wrapping generic close/cleanup operations as shutdown triggers.

func NewTerminate 

func NewTerminate(suspend Handler, shutdown Handler, opts ...TerminateOption) Handler

NewTerminate creates a new handler that chains suspension and shutdown.

func Notify added in v1.7.0 

func Notify(c chan<- Event) Handler

Notify returns a Handler that forwards received events to the provided channel. This is analogous to os/signal.Notify, giving consumers control over channel buffer size and blocking behavior.

The send is non-blocking. If the channel's buffer is full (or it is unbuffered and no goroutine is ready to receive), the event is dropped and ErrNotHandled is returned.

Example: 

ch := make(chan events.Event, 10)
events.Handle("file/*", events.Notify(ch))

for e := range ch {
	fmt.Println("Received:", e.String())
}

func Once 

func Once(h Handler) Handler

Once wraps a handler to ensure it only executes its logic exactly once. This is useful for shutdown or cleanup handlers that involve closing channels or other non-idempotent operations.

Example: 

Handle("command/quit", Once(HandlerFunc(func(ctx context.Context, _ Event) error {
    close(quitCh)
    return nil
})))

func WithFixedEvent 

func WithFixedEvent(h Handler, ev Event) Handler

WithFixedEvent wraps a handler and passes the specified event to it, ignoring the original event. Useful for adapting generic signals (SignalEvent) to specific domain events (SuspendEvent).

func WithStateCheck 

func WithStateCheck(h Handler, checker StateChecker) Handler

WithStateCheck wraps a handler and only executes it if the StateChecker reports valid state for handling.

Semantics: If checker.IsActive() returns TRUE, it means the state "Exists" (e.g. already Suspended). In the context of a "Start Operation" (like Suspend), this means we CANNOT start it again. So we return ErrNotHandled to allow escalation (e.g. to Quit).

If checker.IsActive() returns FALSE, we proceed to call the handler.

type HandlerFunc 

type HandlerFunc func(ctx context.Context, e Event) error

HandlerFunc matches the signature of a Handler.

func (HandlerFunc) HandleEvent 

func (f HandlerFunc) HandleEvent(ctx context.Context, e Event) error

HandleEvent calls f(ctx, e).

type HealthCheckSource 

type HealthCheckSource struct {
	BaseSource
	Name     string
	Interval time.Duration
	Check    CheckFunc
	Strategy TriggerStrategy
}

HealthCheckSource runs a periodic health check.

func NewHealthCheckSource 

func NewHealthCheckSource(name string, check CheckFunc, opts ...HealthOption) *HealthCheckSource

NewHealthCheckSource creates a new health monitor.

func (*HealthCheckSource) Start 

func (s *HealthCheckSource) Start(ctx context.Context) error

type HealthEvent 

type HealthEvent struct {
	Name   string
	Status string // "UP", "DOWN", etc
	Error  error
}

HealthEvent represents a health probe status.

func (HealthEvent) String 

func (e HealthEvent) String() string

type HealthOption 

type HealthOption func(*HealthCheckSource)

HealthOption configures a HealthCheckSource.

func WithHealthInterval 

func WithHealthInterval(d time.Duration) HealthOption

WithHealthInterval sets the check interval. Default is 30 seconds.

func WithHealthStrategy 

func WithHealthStrategy(strategy TriggerStrategy) HealthOption

WithHealthStrategy sets the triggering strategy (Edge vs Level). Default is Edge.

type InputEvent 

type InputEvent struct {
	Command string
}

InputEvent is a generic input event for unmapped or custom commands.

func (InputEvent) String 

func (e InputEvent) String() string

type InputOption 

type InputOption func(*InputSource)

InputOption configures the InputSource.

func WithDefaultMappings 

func WithDefaultMappings() InputOption

WithDefaultMappings adds the standard lifecycle command mappings: suspend, resume, q, quit, exit, x, terminate.

func WithFallback 

func WithFallback(factory func(line string) Event) InputOption

WithFallback configures a factory to generate events for unknown commands. If set, this takes precedence over the default UnknownCommandEvent.

func WithInputBackoff 

func WithInputBackoff(d time.Duration) InputOption

WithInputBackoff configures the duration to wait before retrying interruptions or errors. Default: 100ms.

func WithInputBufferSize 

func WithInputBufferSize(size int) InputOption

WithInputBufferSize sets the size of the internal read buffer. Default: 1024 bytes.

func WithInputCommands 

func WithInputCommands(commands ...string) InputOption

WithInputCommands is a low-level helper to allowlist simple commands. It maps each string "cmd" to InputEvent{Command: "cmd"}. Use this if you want to define valid inputs without defining handlers here.

func WithInputEventBuffer 

func WithInputEventBuffer(size int) InputOption

WithInputEventBuffer sets the size of the event channel buffer. Default: 10.

func WithInputHandlers 

func WithInputHandlers(handlers map[string]Handler) InputOption

WithInputHandlers is a high-level helper to synchronize InputSource with Router. It extracts the keys from the handler map and allowlists them as valid commands. This ensures that any command you have a handler for is also a valid input.

func WithInputMapping 

func WithInputMapping(key string, event Event) InputOption

WithInputMapping adds a custom command mapping. Default mappings: "s", "suspend" -> SuspendEvent "r", "resume" -> ResumeEvent "q", "quit" -> InputEvent{Command: "quit"}

func WithInputMappings 

func WithInputMappings(mappings map[string]Event) InputOption

WithInputMappings adds multiple command mappings at once.

func WithInputReader 

func WithInputReader(r io.Reader) InputOption

WithInputReader sets the reader (default: os.Stdin).

func WithRawInput 

func WithRawInput(handler func(line string)) InputOption

WithRawInput configures the InputSource for "Data-Only" mode. It clears default mappings and sets a Fallback to capture everything.

type InputSource 

type InputSource struct {
	BaseSource
	// contains filtered or unexported fields
}

InputSource reads commands from an io.Reader (like Stdin) and maps them to lifecycle It handles the "Detach" pattern to ensure shutdown is not blocked by read operations.

func NewInputSource 

func NewInputSource(opts ...InputOption) *InputSource

NewInputSource creates a new source for interactive commands.

func (*InputSource) Start 

func (s *InputSource) Start(ctx context.Context) error

type InterruptEvent 

type InterruptEvent struct{}

InterruptEvent is triggered when an interactive process should pause/intercept the current task. This is the default event for the first Interrupt signal (Ctrl+C) if configured via WithInterruptHandler. It can be transient (e.g., clearing a line in a REPL).

func (InterruptEvent) String 

func (e InterruptEvent) String() string

type Introspectable 

type Introspectable = introspection.Introspectable

Re-export introspection interfaces for backward compatibility

type LineEvent 

type LineEvent struct {
	Line string
}

LineEvent represents raw text input that didn't match a command. Topic: "input/line"

func (LineEvent) String 

func (e LineEvent) String() string

type Middleware 

type Middleware func(next Handler) Handler

Middleware wraps a Handler.

type ReloadEvent 

type ReloadEvent struct{}

ReloadEvent is triggered when the application should reload its configuration. It is intended for "Hot Reload" scenarios where a restart is not required.

func (ReloadEvent) String 

func (e ReloadEvent) String() string

type ReloadHandler 

type ReloadHandler struct {
	OnReload func(ctx context.Context) error
}

ReloadHandler handles configuration reload

func (*ReloadHandler) HandleEvent 

func (r *ReloadHandler) HandleEvent(ctx context.Context, e Event) error

type ResumeEvent 

type ResumeEvent struct{}

ResumeEvent is triggered when the application should resume processing.

func (ResumeEvent) String 

func (e ResumeEvent) String() string

type RouteInfo 

type RouteInfo struct {
	Pattern string
	Handler string // Name of the handler
}

RouteInfo describes a registered event route.

func Routes 

func Routes() []RouteInfo

Routes returns a snapshot of the currently registered routes on the DefaultRouter.

type Router 

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

Router routes events from sources to reactions using a ServeMux-style pattern.

func NewRouter 

func NewRouter(opts ...RouterOption) *Router

NewRouter creates a new control router with optional configuration.

func (*Router) AddSource 

func (r *Router) AddSource(s Source)

AddSource registers an event source.

func (*Router) Dispatch 

func (r *Router) Dispatch(ctx context.Context, e Event)

Dispatch finds the handler for an event and executes it.

func (*Router) Handle 

func (r *Router) Handle(pattern string, handler Handler)

Handle registers the handler for the given pattern. Patterns supports glob matching via path.Match.

func (*Router) HandleFunc 

func (r *Router) HandleFunc(pattern string, handler func(context.Context, Event) error)

HandleFunc registers the handler function for the given pattern.

func (*Router) Routes 

func (r *Router) Routes() []RouteInfo

Routes returns a snapshot of the currently registered routes.

func (*Router) Start 

func (r *Router) Start(ctx context.Context) error

Start runs the router loop.

func (*Router) State 

func (r *Router) State() any

State returns the current state of the

func (*Router) Use 

func (r *Router) Use(mw Middleware)

Use appends a middleware to the router stack.

type RouterOption 

type RouterOption func(*Router)

RouterOption configures a

func WithEventBuffer 

func WithEventBuffer(size int) RouterOption

WithEventBuffer sets the size of the event channel buffer. Default is 100.

func WithRouterHandlers 

func WithRouterHandlers(handlers map[string]Handler) RouterOption

WithRouterHandlers registers multiple command handlers at once. It maps each "cmd" key to the pattern "command/cmd". This is designed to be used with the same map passed to InputSource.WithCommandHandlers.

type RouterState 

type RouterState struct {
	Routes      []RouteInfo `json:"routes"`
	Middlewares int         `json:"middlewares"`
	Sources     int         `json:"sources"`
	Running     bool        `json:"running"`
}

RouterState represents the serializable state of the

type ShutdownEvent 

type ShutdownEvent struct {
	Reason string
}

ShutdownEvent is triggered when the application should shut down gracefully. This is typically mapped to "exit" or "quit" commands.

func (ShutdownEvent) String 

func (e ShutdownEvent) String() string

type ShutdownHandler 

type ShutdownHandler struct {
	Cancel context.CancelFunc
}

ShutdownHandler creates a handler that cancels the given context (triggering shutdown). Since handlers receive a context, they can't cancel the *parent* unless they have access to the CancelFunc. We must provide the CancelFunc to the constructor.

func (*ShutdownHandler) HandleEvent 

func (r *ShutdownHandler) HandleEvent(ctx context.Context, e Event) error

type SignalEvent 

type SignalEvent struct {
	Signal os.Signal
}

SignalEvent represents an OS signal.

func (SignalEvent) String 

func (e SignalEvent) String() string

type SignalSource 

type SignalSource struct {
	BaseSource
	// contains filtered or unexported fields
}

SignalSource listens for OS signals and emits them as Events.

func NewOSSignalSource 

func NewOSSignalSource(sigs ...os.Signal) *SignalSource

NewOSSignalSource is an alias for NewSignalSource for backward compatibility.

func NewSignalSource 

func NewSignalSource(sigs ...os.Signal) *SignalSource

NewSignalSource creates a source that listens for the given signals.

func (*SignalSource) Start 

func (s *SignalSource) Start(ctx context.Context) error

type Source 

type Source interface {
	// Events returns a read-only channel where the source emits
	Events() <-chan Event

	// Start begins the listening process. It should be non-blocking or managed
	// by the caller (Control Router). The implementation should respect the context.
	Start(ctx context.Context) error
}

Source is a producer of It listens for external or internal triggers and emits them to the Events channel. The Start method should block until the context is done or a fatal error occurs.

type StateChecker 

type StateChecker interface {
	IsActive() bool
}

StateChecker is an optional interface for handlers that can report if they are in an "Active" (e.g. Suspended) state. This allows generic handlers like SmartSignalHandler to decide when to escalate a signal.

type StatusEvent 

type StatusEvent struct {
	Component string
	State     string
	Metadata  map[string]string
}

StatusEvent is an internal event for periodic status updates.

func (StatusEvent) String 

func (e StatusEvent) String() string

type SuspendEvent 

type SuspendEvent struct{}

SuspendEvent is triggered when the application should pause processing. This is typically used for "Durable Execution" where a process needs to be moved or upgraded without losing state.

func (SuspendEvent) String 

func (e SuspendEvent) String() string

type SuspendHandler 

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

SuspendHandler manages Suspend and Resume It allows registering hooks that are executed when these events occur.

func NewSuspendHandler 

func NewSuspendHandler() *SuspendHandler

NewSuspendHandler creates a new handler for suspend/resume

func (*SuspendHandler) HandleEvent 

func (h *SuspendHandler) HandleEvent(ctx context.Context, e Event) error

HandleEvent processes SuspendEvent and ResumeEvent.

func (*SuspendHandler) IsActive 

func (h *SuspendHandler) IsActive() bool

IsActive returns true if the system is currently suspended. Implements StateChecker interface.

func (*SuspendHandler) Manage 

func (h *SuspendHandler) Manage(s worker.Suspendable)

Manage registers a worker.Suspendable component to be managed by this handler. It automatically wires up the Suspend and Resume methods to the respective

func (*SuspendHandler) OnResume 

func (h *SuspendHandler) OnResume(fn SuspendHook)

OnResume adds a hook to be executed on resume.

func (*SuspendHandler) OnSuspend 

func (h *SuspendHandler) OnSuspend(fn SuspendHook)

OnSuspend adds a hook to be executed on suspend.

func (*SuspendHandler) State 

func (h *SuspendHandler) State() any

State returns the current state of the handler.

type SuspendHook 

type SuspendHook func(ctx context.Context) error

SuspendHook is a function called when a suspend/resume event occurs.

type SuspendableHandler 

type SuspendableHandler interface {
	Handler
	IsActive() bool
}

SuspendableHandler is an optional interface for handlers that support the full Suspend/Resume lifecycle (Suspend, Intercept, Resume).

type TerminateEvent 

type TerminateEvent struct{}

TerminateEvent is a high-level event that chains Suspend and Shutdown. It represents a graceful exit that preserves system state.

func (TerminateEvent) String 

func (e TerminateEvent) String() string

type TerminateHandler 

type TerminateHandler struct {
	Suspend           Handler
	Shutdown          Handler
	ContinueOnFailure bool
}

TerminateHandler chains a SuspendEvent (to save state) with a Shutdown. This implements the "Power Command" pattern: Composing primitives to create rich behaviors.

Mindset: High-level operations should be composed from smaller, specialized handlers rather than hard-coding complexity.

func (*TerminateHandler) HandleEvent 

func (h *TerminateHandler) HandleEvent(ctx context.Context, e Event) error

HandleEvent processes the terminate request by chaining suspend and shutdown phases. It collects errors from both phases and returns them joined.

type TerminateOption 

type TerminateOption func(*TerminateHandler)

TerminateOption configures the TerminateHandler.

func WithContinueOnFailure 

func WithContinueOnFailure(continueOnFailure bool) TerminateOption

WithContinueOnFailure configures whether to proceed with shutdown even if suspension fails. Default is true.

type TickEvent 

type TickEvent struct {
	Time time.Time
}

TickEvent represents a periodic time tick.

func (TickEvent) String 

func (e TickEvent) String() string

type TickerSource 

type TickerSource struct {
	BaseSource
	// contains filtered or unexported fields
}

TickerSource emits events at a regular interval.

func NewTickerSource 

func NewTickerSource(interval time.Duration) *TickerSource

NewTickerSource creates a new source that emits tick

func (*TickerSource) Start 

func (s *TickerSource) Start(ctx context.Context) error

Start begins the ticker loop.

type TriggerStrategy 

type TriggerStrategy string

TriggerStrategy defines when events are emitted. 

const (
	// TriggerEdge emits events only when the status changes.
	TriggerEdge TriggerStrategy = "EDGE"
	// TriggerLevel emits events on every check interval (Heartbeat).
	TriggerLevel TriggerStrategy = "LEVEL"
)

type UnknownCommandEvent 

type UnknownCommandEvent struct {
	Command string
	Known   []string
}

UnknownCommandEvent is emitted when a command is not found in the mappings and no fallback is configured. Topic: "input/unknown"

func (UnknownCommandEvent) String 

func (e UnknownCommandEvent) String() string

type WebhookEvent 

type WebhookEvent struct {
	Method  string
	Path    string
	Payload []byte
}

WebhookEvent represents an HTTP triggering event.

func (WebhookEvent) String 

func (e WebhookEvent) String() string

type WebhookOption 

type WebhookOption func(*WebhookSource)

WebhookOption configures a WebhookSource.

func WithMaxPayloadBytes added in v1.6.5 

func WithMaxPayloadBytes(n int64) WebhookOption

WithMaxPayloadBytes configures the maximum request body size in bytes. Default is 1MB to prevent OOM attacks.

type WebhookSource 

type WebhookSource struct {
	BaseSource
	// contains filtered or unexported fields
}

WebhookSource listens for HTTP requests and converts them into lifecycle events.

func NewWebhookSource 

func NewWebhookSource(addr string, opts ...WebhookOption) *WebhookSource

NewWebhookSource creates a new source listening on the given address (e.g., ":8080").

func (*WebhookSource) Addr 

func (s *WebhookSource) Addr() string

Addr returns the address the source is listening on. This is useful when using dynamic ports (":0").

func (*WebhookSource) Start 

func (s *WebhookSource) Start(ctx context.Context) error

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.