Blink Documentation¶

What is Blink?¶

Blink is a high-performance file system watcher that monitors directories for changes and provides events through real-time streaming protocols. It's designed to be fast, efficient, and easy to use, with a focus on real-time notifications and integration with other systems.

Key Features¶

• Watcher: High-performance file system monitoring with batched events and separate file/directory handling
• Recursive Directory Watching: Monitor entire directory trees for changes
• Symbolic Link Support: Properly follows symbolic links for comprehensive monitoring
• Real-time Event Streaming: Choose between WebSockets, Server-Sent Events (SSE), or both
• WebSocket Support: Bidirectional communication with JSON-formatted events
• Server-Sent Events (SSE): Standard SSE protocol for compatibility with older systems
• Cross-Origin Resource Sharing: Configurable CORS support for web applications
• Event Filtering: Focus on specific files or event types with improved pattern matching
• Webhooks: Send HTTP requests when file changes occur
• High-Performance Design:
• Event batching for improved performance with editors like Vim
• Separate processing for file and directory events
• Configurable batching delay for different workflows
• Periodic polling for new files
• Parallel directory scanning
• Non-blocking channel operations
• Efficient memory usage with periodic cleanup

Quick Example¶

# Install Blink
go install github.com/TFMV/blink/cmd/blink@latest

# Start watching the current directory
blink

# In another terminal, make some changes to files
touch test.txt

Connect to the event stream from any language:

const socket = new WebSocket('ws://localhost:12345/events/ws');

socket.onopen = () => {
  console.log('Connected to Blink WebSocket server');
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`File ${data.operation}: ${data.path}`);
};

const eventSource = new EventSource('http://localhost:12345/events');
eventSource.onmessage = function(event) {
  console.log('File changed:', event.data);
};

import sseclient
import requests

url = 'http://localhost:12345/events'
headers = {'Accept': 'text/event-stream'}
response = requests.get(url, headers=headers, stream=True)
client = sseclient.SSEClient(response)
for event in client.events():
    print(f"File changed: {event.data}")

import (
    "fmt"
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Create watcher configuration
    config := blink.WatcherConfig{
        RootPath:        ".",
        Recursive:       true,
        HandlerDelay:    100 * time.Millisecond,
        PollInterval:    4 * time.Second,
    }

    // Create watcher
    watcher, err := blink.NewWatcher(config)
    if err != nil {
        panic(err)
    }

    // Start the watcher
    watcher.Start()

    // Process events
    for {
        select {
        case eventBatch := <-watcher.Events():
            for _, event := range eventBatch {
                fmt.Println("Event:", event)
            }
        case err := <-watcher.Errors():
            fmt.Println("Error:", err)
        }
    }
}

Getting Started¶

Check out the Installation guide to get started with Blink, or dive into the Quick Start guide to see it in action.