Event System

Spacedrive’s event system broadcasts real-time updates to all connected clients using a unified resource event architecture that eliminates per-resource event variants in favor of generic, horizontally-scalable events.

Overview

The event bus enables reactive UI updates by notifying clients when data changes. The system uses:

Generic Resource Events: A single event type (ResourceChanged) handles all database entities
Path-Scoped Subscriptions: Subscribe to events affecting specific directories or files
Infrastructure Events: Specialized events for jobs, sync, and system lifecycle
Automatic Emission: Events are emitted automatically by the TransactionManager - no manual calls needed

Event Types

Resource Events

Generic events that work for ALL resources (files, tags, albums, locations, etc.):

Event::ResourceChanged {
    resource_type: String,     // e.g., "file", "tag", "album", "location"
    resource: serde_json::Value, // Full resource data as JSON
    metadata: Option<ResourceMetadata>, // Cache hints and path scopes
}

Event::ResourceChangedBatch {
    resource_type: String,
    resources: serde_json::Value,  // Array of resources
    metadata: Option<ResourceMetadata>,
}

Event::ResourceDeleted {
    resource_type: String,
    resource_id: Uuid,
}

Supported Resources:

file - Files and directories (Entry entity)
tag - User tags
collection - File collections
location - Indexed locations
device - Devices in the network
volume - Storage volumes (replaces deprecated volume events)
sidecar - Generated thumbnails and metadata
user_metadata - User-added metadata (notes, favorites, etc.)
content_identity - Deduplicated content records

Volume events (VolumeAdded, VolumeUpdated, etc.) and indexing events (IndexingStarted, IndexingProgress, etc.) are deprecated. Use ResourceChanged for volumes and job events for indexing progress.

Infrastructure Events

Specialized events for system operations: Core Lifecycle:

CoreStarted, CoreShutdown - Daemon lifecycle

Library Management:

LibraryCreated, LibraryOpened, LibraryClosed, LibraryDeleted
Refresh - Invalidate all frontend caches

Jobs:

JobQueued, JobStarted, JobProgress, JobCompleted, JobFailed, JobCancelled

Sync:

SyncStateChanged - Sync state transitions
SyncActivity - Peer sync activity
SyncConnectionChanged - Peer connections
SyncError - Sync errors

Volumes (deprecated - use ResourceChanged with resource_type: "volume"):

~~VolumeAdded, VolumeRemoved, VolumeUpdated~~
~~VolumeMountChanged, VolumeSpeedTested~~

Indexing (deprecated - use job events):

~~IndexingStarted, IndexingProgress, IndexingCompleted, IndexingFailed~~

Filesystem:

FsRawChange - Raw filesystem watcher events (before database resolution)

Event Emission

Automatic Emission (Recommended)

Events are emitted automatically when using the TransactionManager:

// NO manual event emission needed!
pub async fn create_collection(
    tm: &TransactionManager,
    library: Arc<Library>,
    name: String,
) -> Result<Collection> {
    let model = collection::ActiveModel {
        id: NotSet,
        uuid: Set(Uuid::new_v4()),
        name: Set(name),
        // ...
    };

    // TM handles: DB write + sync log + event emission
    let collection = tm.commit::<collection::Model, Collection>(library, model).await?;

    Ok(collection) // ResourceChanged event already emitted!
}

The TransactionManager emits ResourceChanged after successful commits, ensuring:

✅ Events always match database state
✅ No forgotten emissions
✅ Automatic sync log integration

Manual Emission (Infrastructure Only)

Only use manual emission for infrastructure events:

// Jobs, sync, and system events
event_bus.emit(Event::JobStarted {
    job_id: job.id.to_string(),
    job_type: "IndexLocation".to_string(),
});

Path-Scoped Subscriptions

Subscribe to events affecting specific directories or files:

use sd_core::infra::event::SubscriptionFilter;

// Subscribe to changes in a specific directory
let filter = SubscriptionFilter::PathScoped {
    resource_type: "file".to_string(),
    path_scope: SdPath::physical(device_slug, "/Users/james/Photos"),
};

let mut subscriber = event_bus.subscribe_filtered(vec![filter]);

while let Ok(event) = subscriber.recv().await {
    // Only receives events affecting /Users/james/Photos
    println!("Event: {:?}", event);
}

The ResourceMetadata field includes affected_paths that indicate which directories/files changed:

pub struct ResourceMetadata {
    pub no_merge_fields: Vec<String>,  // Fields to replace, not merge
    pub alternate_ids: Vec<Uuid>,       // Alternate IDs for matching
    pub affected_paths: Vec<SdPath>,    // Paths affected by this event
}

Path matching supports:

Physical paths: Match by device slug + path prefix
Content IDs: Match by content identifier
Cloud paths: Match by service + bucket + path
Sidecar paths: Match by content ID

Client Integration

TypeScript (useNormalizedQuery)

The useNormalizedQuery hook automatically subscribes to resource events and updates the cache:

import { useNormalizedQuery } from '@sd/client';

// Automatically subscribes to ResourceChanged events for "tag"
const tags = useNormalizedQuery({
  resource_type: 'tag',
  query: api.tags.list(),
});

// UI automatically updates when tags change!

The normalized cache:

Subscribes to ResourceChanged events matching the resource type
Deserializes the JSON resource using generated TypeScript types
Updates the local cache
Triggers React re-renders

Swift

// Generic event handler works for ALL resources
actor EventCacheUpdater {
    let cache: NormalizedCache

    func handleEvent(_ event: Event) async {
        switch event.kind {
        case .ResourceChanged(let resourceType, let resourceJSON):
            // Generic decode via type registry
            let resource = try ResourceTypeRegistry.decode(
                resourceType: resourceType,
                from: resourceJSON
            )
            await cache.updateEntity(resource)

        case .ResourceDeleted(let resourceType, let resourceId):
            await cache.deleteEntity(resourceType: resourceType, id: resourceId)

        default:
            break
        }
    }
}

CLI Event Monitoring

Monitor events in real-time using the CLI:

# Monitor all events
sd events monitor

# Filter by event type
sd events monitor --event-type JobProgress,JobCompleted

# Filter by library
sd events monitor --library-id <uuid>

# Filter by job
sd events monitor --job-id <id>

# Show timestamps
sd events monitor --timestamps

# Verbose mode (full JSON)
sd events monitor --verbose --pretty

Available Filters:

-t, --event-type - Comma-separated event types (e.g., ResourceChanged,JobProgress)
-l, --library-id - Filter by library UUID
-j, --job-id - Filter by job ID
-d, --device-id - Filter by device UUID
--timestamps - Show event timestamps
-v, --verbose - Show full event JSON
-p, --pretty - Pretty-print JSON output

Example Output:

Monitoring events - Press Ctrl+C to exit
═══════════════════════════════════════════════════════
Connected to event stream

JobStarted: Job started: IndexLocation (a1b2c3d4)
JobProgress: Job progress: IndexLocation (a1b2c3d4) - 45.2% - Scanning directory
ResourceChangedBatch: Resources changed: file (127 items)
JobCompleted: Job completed: IndexLocation (a1b2c3d4)

Implementation Reference

Event enum: core/src/infra/event/mod.rs

#[derive(Debug, Clone, Serialize, Deserialize, Type)]
pub enum Event {
    // Core lifecycle
    CoreStarted,
    CoreShutdown,

    // Library events
    LibraryOpened { id: Uuid, name: String, path: PathBuf },
    LibraryClosed { id: Uuid, name: String },

    // Generic resource events
    ResourceChanged {
        resource_type: String,
        resource: serde_json::Value,
        metadata: Option<ResourceMetadata>,
    },
    ResourceChangedBatch {
        resource_type: String,
        resources: serde_json::Value,
        metadata: Option<ResourceMetadata>,
    },
    ResourceDeleted {
        resource_type: String,
        resource_id: Uuid,
    },

    // Jobs, sync, volumes, indexing...
    // (See full enum in source)
}

Event bus: core/src/infra/event/mod.rs

pub struct EventBus {
    sender: broadcast::Sender<Event>,
    subscribers: Arc<RwLock<Vec<FilteredSubscriber>>>,
}

impl EventBus {
    // Subscribe to all events
    pub fn subscribe(&self) -> EventSubscriber;

    // Subscribe with path/resource filters
    pub fn subscribe_filtered(&self, filters: Vec<SubscriptionFilter>) -> EventSubscriber;

    // Emit an event
    pub fn emit(&self, event: Event);
}

Benefits

Backend

Zero Manual Emission: TransactionManager handles all resource events
Type Safety: Events always match actual resources
Centralized: Single point of emission prevents drift
Scalable: Adding new resources requires no event code

Frontend

Zero Boilerplate: One event handler for all resource types
Type Registry: Automatic deserialization via generated types
Path Scoping: Subscribe only to relevant directory changes
Cache Integration: useNormalizedQuery handles subscriptions automatically

Developer Experience

No Event Variants: ~40 variants eliminated → 3 generic events
No Manual Calls: Never call event_bus.emit() for resources
No Client Changes: Adding a 100th resource type = zero event handling updates
CLI Debugging: Monitor events in real-time with filtering

Sync System: See sync.md for event emission during sync
Normalized Cache: See normalized_cache.md for client-side event handling
TransactionManager: See transactions.md for automatic event emission

Architecture

File Management

Sync & Network

Development

Overview

Event Types

Resource Events

Infrastructure Events

Event Emission

Automatic Emission (Recommended)

Manual Emission (Infrastructure Only)

Path-Scoped Subscriptions

Client Integration

TypeScript (useNormalizedQuery)

Swift

CLI Event Monitoring

Implementation Reference

Benefits

Backend

Frontend

Developer Experience

​Overview

​Event Types

​Resource Events

​Infrastructure Events

​Event Emission

​Automatic Emission (Recommended)

​Manual Emission (Infrastructure Only)

​Path-Scoped Subscriptions

​Client Integration

​TypeScript (useNormalizedQuery)

​Swift

​CLI Event Monitoring

​Implementation Reference

​Benefits

​Backend

​Frontend

​Developer Experience

​Related Documentation

Overview

Event Types

Resource Events

Infrastructure Events

Event Emission

Automatic Emission (Recommended)

Manual Emission (Infrastructure Only)

Path-Scoped Subscriptions

Client Integration

TypeScript (useNormalizedQuery)

Swift

CLI Event Monitoring

Implementation Reference

Benefits

Backend

Frontend

Developer Experience

Related Documentation