Notification System

How Xudanu delivers real-time events to clients: detector subscriptions, content watch, and CRDT collaborative relay.

1. Overview: Three Notification Channels

Xudanu implements three distinct notification mechanisms, each designed for a different use case. They share a common WebSocket transport but differ in delivery model, scope, and complexity.

2. Detector Events: Status, Revision, Fill

Detector events are the original notification mechanism, modelled after the Udanax-Gold observer pattern. A client subscribes to a specific work or edition and receives push events whenever that target changes.

Event Types

Subscription Flow

The key architectural insight: the server core is synchronous (Mutex-protected). The ChannelDetector bridges sync to async by pushing into an mpsc channel. A dedicated writer task on the async side drains the channel and writes to the WebSocket.

Code: Subscribing to Status Changes

// Subscribe to work status changes (grab/release)
ws.send(JSON.stringify({
  v: 2, type: 'subscribe', id: nextId(),
  payload: { detector_type: 'status', target_id: workId }
}));
// Response contains subscription_id

// Handle incoming events
ws.onmessage = function(msg) {
  var data = JSON.parse(msg.data);
  if (data.type === 'event') {
    var event = data.event;
    if (event.type === 'work_grabbed') {
      console.log('Work grabbed by session', event.payload.session_id);
    } else if (event.type === 'work_released') {
      console.log('Work released');
    }
  }
};

// Unsubscribe when done
ws.send(JSON.stringify({ v: 2, type: 'unsubscribe', id: subId }));

3. The ChannelDetector Bridge

The ChannelDetector is the sync-to-async bridge that makes detector events work. It implements the Detector trait but instead of processing the event itself, it wraps it in an EventMessage and sends it through a Tokio unbounded channel.

4. Content Watch: Cross-Document Transclusion Alerts

Content Watch is the newest notification channel. When a user clicks Watch on a document, the server monitors for any other documents that share content with it — both past matches that already exist and future matches that appear as documents are edited.

Why Content Watch Exists

Traditional hypertext systems require users to actively search for shared content. Content Watch inverts this: the server proactively notifies you when your content appears elsewhere. This is the Xanadu vision of automatic attribution and connection between documents.

Code: Setting Up Content Watch

var watchSubId = null;
var watchResults = [];

function startWatch(workId) {
  var id = nextId();
  ws.send(JSON.stringify({
    v: 2, type: 'subscribe', id: id,
    payload: {
      detector_type: 'content_transcluders',
      target_id: workId
    }
  }));
}

// Handle content_match events
if (msg.event && msg.event.type === 'content_match') {
  var p = msg.event.payload;
  watchResults.push({
    edition_be_id: p.edition_be_id,
    is_direct: p.is_direct
  });
  toast('Transclusion found in edition ' + p.edition_be_id.toString(16));
}

function stopWatch() {
  if (watchSubId) {
    ws.send(JSON.stringify({
      v: 2, type: 'unsubscribe', id: watchSubId
    }));
    watchSubId = null;
  }
}

5. The Fingerprint Reverse Index

The key data structure enabling Content Watch is fossil_by_fingerprint, a reverse index in the BackfollowEngine that maps content fingerprints to the fossil IDs watching for them.

When a recorder is planted during subscription, each content element's BLAKE3 fingerprint is mapped to the fossil ID. When any edition is revised, the new fingerprints are looked up in this index to find affected fossils in O(1) per element — no tree walk needed.

6. Per-Session Notification Drain

A critical design decision: content notifications are queued globally on the server, but drained per-session. Each client only receives notifications for its own fossils.

7. Subscription Lifecycle and Cleanup

The WS handler maintains three maps to track subscriptions across all notification types. Proper cleanup on both explicit unsubscribe and WebSocket disconnect is essential to avoid resource leaks.

8. CRDT Collaborative Relay

The CRDT system uses a fundamentally different notification model: relay. When one client edits a shared document, the server applies the change and returns a list of other subscribers who need to be notified. The receiving client then polls for the update.

How It Differs from Detectors

Relay Flow

CRDT Awareness

Beyond document content, the CRDT system also relays awareness state: cursor positions, text selections, and typing indicators. Each subscriber's awareness is stored in the WorkDoc and relayed to all other subscribers.

// Open CRDT sync
ws.send(JSON.stringify({
  v:2, type:'request', id:nextId(), op:'crdt_sync_open',
  payload: { work_id: workId }
}));
// Response: { state_vector: [...], current_text: "hello world" }

// Send edits
ws.send(JSON.stringify({
  v:2, type:'request', id:nextId(), op:'crdt_sync_update',
  payload: { work_id: workId, update: Array.from(updateBytes) }
}));
// Response: { relay_count: 2 }

// Poll for changes (every 50-100ms during active editing)
ws.send(JSON.stringify({
  v:2, type:'request', id:nextId(), op:'crdt_sync_diff',
  payload: { work_id: workId, state_vector: Array.from(mySV) }
}));
// Response: { update: [...] }

// Send awareness (cursor)
ws.send(JSON.stringify({
  v:2, type:'request', id:nextId(), op:'crdt_awareness_update',
  payload: {
    work_id: workId,
    state: { session_id: sid, user_name: "Alice",
             cursor: { index: 5 }, selection: null, is_typing: true }
  }
}));

9. Wire Protocol: Event Frames

All notification types share a common wire format. Events are delivered as WebSocket messages with the Event message type (0x04).

Binary Frame Layout

JSON Format

{
  "v": 2,
  "type": "event",
  "id": 42,
  "event": {
    "type": "content_match",
    "payload": {
      "fossil_id": 7,
      "edition_be_id": "0000000000abc123",
      "is_direct": true
    }
  }
}

Detector Type Codes

10. Enhancements and Fixes

The notification system was significantly improved during development. Here is a summary of all enhancements over the original design:

1. Per-Session Notification Drain

2. Complete Unsubscribe Cleanup

3. Fingerprint-Based Triggering

4. Content-Aware Past Match Search

Known Limitations

Key Source Files