blink

Blink

Blink is a high-performance file system watcher that monitors directories for changes and provides events through real-time streaming protocols.

Features

Core Capabilities

• 🔍 File System Monitoring

  • Recursive directory watching
  • Symbolic link support
  • Real-time change detection

• 📡 Event Delivery

  • WebSocket support for bidirectional communication
  • Server-sent events (SSE) for real-time notifications
  • Configurable streaming method (WebSocket, SSE, or both)
  • Cross-origin resource sharing (CORS) support
  • JSON-formatted event data

Performance Optimizations

• ⚡ High-Performance Design
  • Parallel directory scanning with worker pools
  • Non-blocking channel operations
  • Efficient memory usage with periodic cleanup
  • Event debouncing to reduce duplicate events
  • Watcher: Advanced file system monitoring with batched events
  • Smart Event Handling: Separate processing for file and directory events
  • Configurable Batching: Adjustable delay for grouping related events

Integration & Configuration

• 🔧 Flexible Configuration

  • Command-line interface
  • Environment variables
  • YAML configuration files
  • Dynamic configuration management
  • Polling Support: Periodic scanning for new files
  • Customizable Delays: Fine-tune event batching for your workflow

• 🔌 Integration Options

  • Webhook support with retry logic
  • Custom HTTP headers
  • Configurable timeouts and debouncing
  • Filterable events and patterns
  • Improved Pattern Matching: Better file filtering with glob patterns

Monitoring & Debugging

• 📊 Observability
  • Prometheus metrics integration
  • Health check endpoints
  • Verbose logging option
  • Kubernetes-ready deployment

Installation

go install github.com/TFMV/blink/cmd/blink@latest

Or clone the repository and build manually:

git clone https://github.com/TFMV/blink.git
cd blink
go build -o blink ./cmd/blink

Kubernetes Deployment

Please see the Kubernetes deployment guide for detailed instructions on deploying Blink to Kubernetes.

Benchmarks

Blink is optimized for high-performance. Here are some benchmark results from our test suite. For detailed performance metrics, memory analysis, and race condition testing, see our comprehensive benchmarks report.

Filter Performance

Usage

Basic usage:

# Watch the current directory
blink

# Watch a specific directory
blink --path /path/to/watch

# Customize the event server
blink --path /path/to/watch --event-addr :12345 --event-path /events

Command-line Options

Event Streaming

Blink supports multiple methods for streaming file system events:

# Use WebSockets for event streaming
blink --stream-method websocket

# Use Server-Sent Events (SSE) for event streaming (default)
blink --stream-method sse

# Use both WebSockets and SSE simultaneously
blink --stream-method both

When using --stream-method both, Blink will serve:

• SSE events at the path specified by --event-path (default: /events)
• WebSocket events at the same path with /ws appended (default: /events/ws)

Event Filtering

Blink supports filtering capabilities to focus on specific files or event types:

# Only watch for changes to JavaScript, CSS, and HTML files
blink --include "*.js,*.css,*.html"

# Ignore node_modules directory and temporary files
blink --exclude "node_modules,*.tmp"

# Only trigger on write and create events
blink --events "write,create"

# Ignore chmod events
blink --ignore "chmod"

# Combine multiple filters
blink --include "*.js,*.css" --exclude "node_modules" --events "write,create"

Available event types:

• create: File or directory creation
• write: File modification
• remove: File or directory removal
• rename: File or directory renaming
• chmod: Permission changes

Webhooks

Blink can send webhooks when file changes occur, allowing integration with other systems:

# Send webhooks to a URL
blink --webhook-url "https://example.com/webhook"

# Use a specific HTTP method
blink --webhook-method "POST"

# Add custom headers
blink --webhook-headers "Authorization:Bearer token,Content-Type:application/json"

# Set timeout and retry options
blink --webhook-timeout 10s --webhook-max-retries 5

# Debounce webhooks to reduce the number of requests
blink --webhook-debounce-duration 500ms

# Combine with filters to only send webhooks for specific events
blink --include "*.js" --events "write" --webhook-url "https://example.com/webhook"

Client Examples

Example clients for both WebSocket and SSE are available in the examples directory:

• WebSocket client: examples/websocket-client/index.html
• SSE client: examples/sse-client/index.html

These examples demonstrate how to connect to Blink and receive real-time file system events.