API Reference¶

This page provides a reference for the Blink API, including types, functions, and methods.

Package blink¶

import "github.com/TFMV/blink/pkg/blink"

Types¶

StreamMethod¶

type StreamMethod string

const (
    // StreamMethodSSE uses Server-Sent Events for streaming
    StreamMethodSSE StreamMethod = "sse"

    // StreamMethodWebSocket uses WebSockets for streaming
    StreamMethodWebSocket StreamMethod = "websocket"

    // StreamMethodBoth uses both SSE and WebSockets for streaming
    StreamMethodBoth StreamMethod = "both"
)

The StreamMethod type defines the method used for streaming events.

EventStreamer¶

type EventStreamer interface {
    // Start initializes and starts the streamer
    Start(ctx context.Context) error

    // Stop gracefully shuts down the streamer
    Stop() error

    // Send delivers an event to all connected clients
    Send(event fsnotify.Event) error
}

The EventStreamer interface defines the methods required for streaming events to clients.

StreamerOptions¶

type StreamerOptions struct {
    // Address to listen on ([host][:port])
    Address string

    // Path for the event stream
    Path string

    // AllowedOrigin for CORS (Access-Control-Allow-Origin)
    AllowedOrigin string

    // RefreshDuration for SSE events
    RefreshDuration time.Duration

    // Filter for events
    Filter *EventFilter
}

The StreamerOptions type contains configuration options for event streamers.

SSEStreamer¶

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

The SSEStreamer type implements the EventStreamer interface using Server-Sent Events (SSE).

WebSocketStreamer¶

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

The WebSocketStreamer type implements the EventStreamer interface using WebSockets.

MultiStreamer¶

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

The MultiStreamer type implements the EventStreamer interface by combining multiple streamers.

Watcher¶

type Watcher struct {
    // Underlying fsnotify watcher
    watcher *fsnotify.Watcher

    // Configuration
    config WatcherConfig

    // State management
    directories     map[string]bool
    watches         map[string]bool
    dirLock         sync.Mutex
    handlerLock     sync.Mutex

    // Event handling
    events          []fsnotify.Event
    lastHandlerTime time.Time

    // Control channels
    closeChan       chan bool
    errorChan       chan error
    eventChan       chan []fsnotify.Event

    // Polling for new files/directories
    pollInterval    time.Duration
}

The Watcher type provides file watching capabilities with event batching, separate file/directory handling, and periodic polling for new files.

WatcherConfig¶

type WatcherConfig struct {
    // Root directory to watch
    RootPath string

    // Patterns to include/exclude
    IncludePatterns []string
    ExcludePatterns []string

    // Event types to include/ignore
    IncludeEvents []string
    IgnoreEvents  []string

    // Whether to watch recursively
    Recursive bool

    // Delay before handling events (for batching)
    HandlerDelay time.Duration

    // Polling interval for checking new files
    PollInterval time.Duration
}

The WatcherConfig type holds configuration for the watcher.

EventBatcher¶

type EventBatcher struct {
    // Configuration
    handlerDelay time.Duration

    // State
    events          []fsnotify.Event
    lastHandlerTime time.Time
    handlerLock     sync.Mutex

    // Output channel
    eventChan chan []fsnotify.Event
}

The EventBatcher type batches file system events to reduce redundant processing.

RecursiveWatcher¶

type RecursiveWatcher struct {
 *fsnotify.Watcher
 Files   chan string // Channel for file events
 Folders chan string // Channel for folder events
 mu      sync.Mutex  // Mutex for thread-safe operations
}

The RecursiveWatcher type keeps the data for watching files and directories. It embeds fsnotify.Watcher and adds channels for tracking files and folders.

Event¶

type Event fsnotify.Event

The Event type represents a file system event. It's a type alias for fsnotify.Event.

TimeEventMap¶

type TimeEventMap map[time.Time]Event

The TimeEventMap type stores filesystem events with their timestamps.

EventFilter¶

type EventFilter struct {
    // Include/exclude patterns
    includePatterns []string
    excludePatterns []string

    // Event types to include/ignore
    includeEvents map[fsnotify.Op]bool
    ignoreEvents  map[fsnotify.Op]bool
}

The EventFilter type provides filtering capabilities for file system events.

WebhookConfig¶

type WebhookConfig struct {
 URL              string            // URL to send the webhook to
 Method           string            // HTTP method to use (GET, POST, PUT, etc.)
 Headers          map[string]string // Headers to include in the request
 Timeout          time.Duration     // Timeout for the HTTP request
 DebounceDuration time.Duration     // Debounce duration to avoid sending too many webhooks
 MaxRetries       int               // Maximum number of retries for failed requests
 Filter           *EventFilter      // Filter to apply to events before sending webhooks
}

The WebhookConfig type defines the configuration for a webhook.

WebhookManager¶

type WebhookManager struct {
 Config       WebhookConfig         // Configuration for the webhook
 client       *http.Client          // HTTP client for sending webhooks
 recentEvents map[string]time.Time  // Map to track recent events for debouncing
 mu           sync.Mutex            // Mutex to protect the recentEvents map
 eventChan    chan fsnotify.Event   // Channel to receive events
}

The WebhookManager type manages webhooks for file system events.

WebhookPayload¶

type WebhookPayload struct {
 Path      string    `json:"path"`       // Path of the file that changed
 EventType string    `json:"event_type"` // Type of event (create, write, remove, rename, chmod)
 Time      time.Time `json:"time"`       // Time the event occurred
}

The WebhookPayload type is the JSON payload sent to the webhook URL.

Options¶

type Options struct {
 Filter                  *EventFilter      // Filter to apply to events
 WebhookURL              string            // Webhook URL to send events to
 WebhookMethod           string            // HTTP method to use for webhooks
 WebhookHeaders          map[string]string // Headers to include in webhook requests
 WebhookTimeout          time.Duration     // Timeout for webhook requests
 WebhookDebounceDuration time.Duration     // Debounce duration for webhooks
 WebhookMaxRetries       int               // Maximum number of retries for webhook requests
}

The Options type contains all options for the EventServer.

Functions¶

NewWatcher¶

func NewWatcher(config WatcherConfig) (*Watcher, error)

NewWatcher creates a new file watcher with the specified configuration.

NewEventBatcher¶

func NewEventBatcher(handlerDelay time.Duration) *EventBatcher

NewEventBatcher creates a new event batcher with the specified handler delay.

NewRecursiveWatcher¶

func NewRecursiveWatcher(path string) (*RecursiveWatcher, error)

NewRecursiveWatcher creates a new RecursiveWatcher. It takes a path to a directory to watch recursively.

SetVerbose¶

func SetVerbose(enabled bool)

SetVerbose can be used to enable or disable logging of incoming events.

EventServer¶

func EventServer(path, allowed, eventAddr, eventPath string, refreshDuration time.Duration, options ...Option)

EventServer serves events on a dedicated port. It watches the specified path for changes and serves events via SSE.

NewEventFilter¶

func NewEventFilter() *EventFilter

NewEventFilter creates a new event filter.

NewWebhookManager¶

func NewWebhookManager(config WebhookConfig) *WebhookManager

NewWebhookManager creates a new webhook manager.

NewSSEStreamer¶

func NewSSEStreamer(opts StreamerOptions) *SSEStreamer

NewSSEStreamer creates a new SSE streamer with the given options.

NewWebSocketStreamer¶

func NewWebSocketStreamer(opts StreamerOptions) *WebSocketStreamer

NewWebSocketStreamer creates a new WebSocket streamer with the given options.

NewMultiStreamer¶

func NewMultiStreamer(streamers ...EventStreamer) *MultiStreamer

NewMultiStreamer creates a new multi-streamer that combines multiple streamers.

WithStreamMethod¶

func WithStreamMethod(method StreamMethod) Option

WithStreamMethod creates an Option that sets the stream method for the EventServer.

Methods¶

RecursiveWatcher.AddFolder¶

func (watcher *RecursiveWatcher) AddFolder(folder string) error

AddFolder adds a directory to watch, non-recursively.

RecursiveWatcher.Close¶

func (watcher *RecursiveWatcher) Close() error

Close properly closes the watcher and its channels.

EventFilter.SetIncludePatterns¶

func (f *EventFilter) SetIncludePatterns(patterns string)

SetIncludePatterns sets the include patterns.

EventFilter.SetExcludePatterns¶

func (f *EventFilter) SetExcludePatterns(patterns string)

SetExcludePatterns sets the exclude patterns.

EventFilter.SetIncludeEvents¶

func (f *EventFilter) SetIncludeEvents(events string)

SetIncludeEvents sets the include event types.

EventFilter.SetIgnoreEvents¶

func (f *EventFilter) SetIgnoreEvents(events string)

SetIgnoreEvents sets the ignore event types.

EventFilter.ShouldInclude¶

func (f *EventFilter) ShouldInclude(event fsnotify.Event) bool

ShouldInclude checks if an event should be included based on the filter.

WebhookManager.HandleEvent¶

func (m *WebhookManager) HandleEvent(event fsnotify.Event)

HandleEvent handles a file system event.

Option Functions¶

WithFilter¶

func WithFilter(filter *EventFilter) Option

WithFilter creates an Option that sets the event filter.

WithWebhook¶

func WithWebhook(url string, method string) Option

WithWebhook creates an Option that configures a webhook.

WithWebhookHeaders¶

func WithWebhookHeaders(headers map[string]string) Option

WithWebhookHeaders creates an Option that sets webhook headers.

WithWebhookTimeout¶

func WithWebhookTimeout(timeout time.Duration) Option

WithWebhookTimeout creates an Option that sets the webhook timeout.

WithWebhookDebounce¶

func WithWebhookDebounce(duration time.Duration) Option

WithWebhookDebounce creates an Option that sets the webhook debounce duration.

WithWebhookRetries¶

func WithWebhookRetries(maxRetries int) Option

WithWebhookRetries creates an Option that sets the maximum number of webhook retries.

WithIncludePatterns¶

func WithIncludePatterns(patterns string) FilterOption

WithIncludePatterns creates a FilterOption that sets the include patterns.

WithExcludePatterns¶

func WithExcludePatterns(patterns string) FilterOption

WithExcludePatterns creates a FilterOption that sets the exclude patterns.

WithIncludeEvents¶

func WithIncludeEvents(events string) FilterOption

WithIncludeEvents creates a FilterOption that sets the include event types.

WithIgnoreEvents¶

func WithIgnoreEvents(events string) FilterOption

WithIgnoreEvents creates a FilterOption that sets the ignore event types.

SSEStreamer.Start¶

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

Start initializes and starts the SSE streamer.

SSEStreamer.Stop¶

func (s *SSEStreamer) Stop() error

Stop gracefully shuts down the SSE streamer.

SSEStreamer.Send¶

func (s *SSEStreamer) Send(event fsnotify.Event) error

Send delivers an event to all connected SSE clients.

WebSocketStreamer.Start¶

func (ws *WebSocketStreamer) Start(ctx context.Context) error

Start initializes and starts the WebSocket streamer.

WebSocketStreamer.Stop¶

func (ws *WebSocketStreamer) Stop() error

Stop gracefully shuts down the WebSocket streamer.

WebSocketStreamer.Send¶

func (ws *WebSocketStreamer) Send(event fsnotify.Event) error

Send delivers an event to all connected WebSocket clients.

MultiStreamer.Start¶

func (m *MultiStreamer) Start(ctx context.Context) error

Start initializes and starts all streamers in the multi-streamer.

MultiStreamer.Stop¶

func (m *MultiStreamer) Stop() error

Stop gracefully shuts down all streamers in the multi-streamer.

MultiStreamer.Send¶

func (m *MultiStreamer) Send(event fsnotify.Event) error

Send delivers an event to all streamers in the multi-streamer.