Documentation
¶
Overview ¶
Package events provides the /v1/events HTTP API endpoint for real-time Server-Sent Events (SSE). It exposes a Broadcaster that manages subscriber registration and event distribution, and a Handler that streams Watchtower operational events (scan_started, scan_failed, image_cleanup, scan_completed) to connected clients.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Broadcaster ¶
type Broadcaster struct {
// contains filtered or unexported fields
}
Broadcaster manages SSE subscriber registration and event distribution.
func NewBroadcaster ¶
func NewBroadcaster() *Broadcaster
NewBroadcaster creates a new event broadcaster for distributing Watchtower operational events to SSE subscribers.
func (*Broadcaster) Publish ¶
func (b *Broadcaster) Publish(event Event)
Publish sends an event to all registered subscribers. Subscribers that are full (backpressure) or have been unsubscribed have their event dropped.
func (*Broadcaster) Subscribe ¶
func (b *Broadcaster) Subscribe() <-chan Event
Subscribe registers a new subscriber and returns a channel for receiving events. Returns nil if the maximum number of subscribers has been reached.
func (*Broadcaster) SubscribeWithDone ¶
func (b *Broadcaster) SubscribeWithDone() (<-chan Event, <-chan struct{})
SubscribeWithDone registers a new subscriber and returns both the event channel and a done channel. The done channel is closed when the subscriber is unsubscribed, allowing the receiver to detect unsubscription even if no more events are sent. Returns nil, nil if the maximum number of subscribers has been reached.
func (*Broadcaster) SubscriberCount ¶
func (b *Broadcaster) SubscriberCount() int
SubscriberCount returns the current number of active subscribers.
func (*Broadcaster) Unsubscribe ¶
func (b *Broadcaster) Unsubscribe(ch <-chan Event) bool
Unsubscribe removes a subscriber and signals its goroutine to stop by closing the done channel. Returns true if the subscriber was found and removed, false if it was not found (which may indicate it was already unsubscribed).
type Event ¶
type Event struct {
Type string `json:"type"`
Timestamp time.Time `json:"timestamp"`
Data any `json:"data"`
}
Event represents a Watchtower operational event emitted to SSE subscribers.
type Handler ¶
type Handler struct {
Path string
Broadcaster *Broadcaster
AllowedOrigins []string
// contains filtered or unexported fields
}
Handler serves the /v1/events endpoint with Server-Sent Events.
func NewHandler ¶
func NewHandler(log *zerolog.Logger, b *Broadcaster, allowedOrigins []string) *Handler
NewHandler creates a new events handler backed by the given broadcaster.
Parameters:
- b: The event broadcaster for distributing events to subscribers.
- allowedOrigins: CORS origins permitted to connect to the SSE endpoint. Pass nil to allow all origins.
Returns:
- *Handler: The initialized events handler.
func (*Handler) Handle ¶
Handle streams Watchtower events to the client using Server-Sent Events.
Returns:
fiber.Handler: The registered route handler for SSE streaming.
@Summary Real-time events stream @Description Streams Watchtower operational events (scan started/completed, update started/completed/failed) via Server-Sent Events (SSE). @Description @Description **SSE is not supported by "Try it out"**. @Tags events @Produce text/event-stream @Success 200 {string} string "Event stream (SSE)" @Failure 401 {string} string "Missing or invalid events token" @Security EventsToken @Router /v1/events [get]
type ImageCleanupData ¶
type ImageCleanupData struct {
Images []ImageCleanupEntry `json:"images"`
}
ImageCleanupData carries details about images cleaned up after a scan.
type ImageCleanupEntry ¶
type ImageCleanupEntry struct {
ImageID string `json:"image_id"`
ImageName string `json:"image_name"`
ContainerID string `json:"container_id"`
ContainerName string `json:"container_name"`
}
ImageCleanupEntry represents a single cleaned-up image in an event.
type ScanCompletedData ¶
type ScanCompletedData struct {
Scanned int `json:"scanned"`
Updated int `json:"updated"`
Failed int `json:"failed"`
}
ScanCompletedData carries details about a scan that has finished.
type ScanFailedData ¶
type ScanFailedData struct {
Error string `json:"error"`
}
ScanFailedData carries details about a scan that encountered an error.
type ScanStartedData ¶
type ScanStartedData struct {
Cleanup bool `json:"cleanup"`
NoRestart bool `json:"no_restart"`
MonitorOnly bool `json:"monitor_only"`
LifecycleHooks bool `json:"lifecycle_hooks"`
RollingRestart bool `json:"rolling_restart"`
LabelPrecedence bool `json:"label_precedence"`
NoPull bool `json:"no_pull"`
RunOnce bool `json:"run_once"`
UseComposeDependsOn bool `json:"use_compose_depends_on"`
SkipSelfUpdate bool `json:"skip_self_update"`
EphemeralSelfUpdate bool `json:"ephemeral_self_update"`
ReviveStopped bool `json:"revive_stopped"`
}
ScanStartedData carries redacted scan policy flags for SSE subscribers. It intentionally omits filter functions, container IDs, and other internal fields from types.UpdateParams.
func NewScanStartedData ¶
func NewScanStartedData(updateParams types.UpdateParams) ScanStartedData
NewScanStartedData creates a redacted scan_started event payload from the full update configuration. It intentionally omits filter functions, container IDs, durations, and other internal fields from types.UpdateParams.
Source Files