Event Streaming¶

Blink provides real-time file system events through multiple streaming protocols. You can choose between WebSockets, Server-Sent Events (SSE), or both, depending on your application's needs.

Streaming Methods¶

WebSockets¶

WebSockets provide a bidirectional communication channel between the client and server, allowing for more interactive applications. Benefits include:

• Bidirectional communication
• Better support across browsers and platforms
• Lower overhead for high-frequency events
• Support for binary data

Server-Sent Events (SSE)¶

Server-Sent Events (SSE) is a standard for pushing notifications from a server to a browser client in the form of DOM events. Benefits include:

• Simpler protocol
• Automatic reconnection
• Built-in event IDs
• Better compatibility with older systems

Configuring Streaming Method¶

You can configure the streaming method using the --stream-method flag:

# Use WebSockets only
blink --stream-method websocket

# Use Server-Sent Events (SSE) only (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)

WebSocket Event Format¶

WebSocket events are sent as JSON objects with the following structure:

{
  "type": "event",
  "timestamp": 1615123456789,
  "path": "/path/to/file.txt",
  "operation": "write"
}

The operation field can be one of:

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

Client Examples¶

WebSocket Client (JavaScript)¶

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}`);
};

socket.onclose = () => {
  console.log('Disconnected from Blink WebSocket server');
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

SSE Client (JavaScript)¶

const eventSource = new EventSource('http://localhost:12345/events');

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

eventSource.onmessage = (event) => {
  console.log('File changed:', event.data);
};

eventSource.onerror = () => {
  console.log('Error or disconnected from Blink SSE server');
};

Python SSE Client¶

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}")

Python WebSocket Client¶

import websocket
import json

def on_message(ws, message):
    data = json.loads(message)
    print(f"File {data['operation']}: {data['path']}")

def on_error(ws, error):
    print(f"Error: {error}")

def on_close(ws, close_status_code, close_msg):
    print("Connection closed")

def on_open(ws):
    print("Connection opened")

ws = websocket.WebSocketApp("ws://localhost:12345/events/ws",
                          on_open=on_open,
                          on_message=on_message,
                          on_error=on_error,
                          on_close=on_close)
ws.run_forever()

Performance Considerations¶

WebSockets generally have better performance than SSE for high-frequency events, but they also require more resources on the server side. If you're monitoring a large number of files with frequent changes, WebSockets may be the better choice.

For simpler use cases or when compatibility with older browsers is important, SSE may be sufficient.

Security Considerations¶

WebSockets use the same-origin policy by default, but you can configure CORS using the --allowed-origin flag:

blink --allowed-origin "https://example.com" --stream-method websocket

This will only allow connections from the specified origin.

Example Applications¶

Blink includes example clients for both WebSocket and SSE 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.