Nexus Common

Nexus Common is a foundational crate that provides shared configuration, database connectors, data models and media processing utilities used throughout the Nexus indexer stack.

Overview

The nexus-common crate offers:

• Configuration Management: TOML-based loader with default file generation, home‑dir expansion, and asynchronous loading

• Database Connectivity:
  Connect to Neo4j and Redis using dedicated connectors. Use functions such as get_neo4j_graph() and get_redis_conn() to obtain connections for executing queries and handling errors.

• Data Models:
  Define core entities such as Files, Users, Posts, Tags, Notifications, and Follows. Each model provides functionality for caching, indexing, and graph operations.

• Indexing and Caching:
  Utilities to index and retrieve records from Redis. Includes support for pagination, lexicographical range queries, and sorted sets.

• Shared Types and Traits:
  Common types such as Pagination, Timeframe, and StreamSorting along with a collection of traits are provided to ensure a consistent interface across the Nexus backend.

• Media Processing:
  Process media files with support for image and video variant creation. The crate includes processors (like ImageProcessor and a prototype VideoProcessor) that generate different file variants (e.g. main, feed, small) and manage content types.

This crate is designed as a backbone for other services (e.g, homeserver watcher and API) crates in the Nexus stack, enabling consistent access to core functionalities and shared data structures.

Module Overview

Configuration Management

• Module: config/
• Features: ConfigLoader, default templates, home-dir expansion, async loading

Database Connectivity

• Module: db/
• Features: Neo4jConnector, RedisConnector, get_neo4j_graph(), get_redis_conn(), error handling

Data Models

The data models cover the core domain entities and their graph/cache operations:

• Files: Representing file details, blobs, and URLs
• Users: Including user details, counts, relationships, and search capabilities
• Posts: Covering post details, counts, relationships, bookmarks, and views
• Tags: Managing tag details, global taggers, and search operations
• Follows: Handling follower, following, and friends relationships
• Notifications: Representing user notifications

Shared Types

The crate provides common types and utilities (types/) that are used across different modules, such as:

• Pagination for paginated queries
• Timeframe for filtering data based on time ranges
• StreamSorting for ordering streams

Media Processing

• Module: media/
• Features: ImageProcessor, VideoProcessor, FileVariant, and VariantController for automated processing pipelines

MIME-type management and storage directory configuration

Getting Started

To add nexus-common to your project, include it in your Cargo.toml dependencies:

cargo add nexus-common

Quick Examples

Configuration Loading

Below is an example demonstrating how to load a configuration using the provided loader trait:

use nexus_common::config::{ConfigLoader, DaemonConfig};
use std::path::Path;
use nexus_common::types::DynError;

#[tokio::main]
async fn main() -> Result<(), DynError> {
    let cfg: DaemonConfig = DaemonConfig::read_config_file(
        config::expand_home_dir("~/.pubky-nexus".into())
    ).await?;
    println!("Loaded config: {:#?}", cfg);
    Ok(())
}

Database Connectivity

Below is an example demonstrating how to get the connectors of the data bases:

use nexus_common::db::{Neo4jConnector, RedisConnector, get_neo4j_graph, get_redis_conn};
use nexus_common::db::Neo4JConfig;
use nexus_common::types::DynError;

#[tokio::main]
async fn main() -> Result<(), DynError> {
    // Initialize connectors (once per app)
    Neo4jConnector::init(Neo4JConfig::default()).await?;
    RedisConnector::init("redis://127.0.0.1:6379").await?;

    // Use helper functions
    let graph = get_neo4j_graph()?;
    let mut redis_conn = get_redis_conn().await?;
    Ok(())
}

Data Models & Caching

Demonstrates cache-first retrieval of domain entities, attempting to load from Redis and falling back to Neo4j if not found

use nexus_common::models::user::UserDetails;
use nexus_common::types::DynError;
use nexus_common::{StackManager, StackConfig};

#[tokio::main]
async fn main() -> Result<(), DynError> {
    StackManager::setup("common-example", StackConfig::default()).await?
    // Cache-first: Redis -> Neo4j fallback
    if let Some(user) = UserDetails::get_by_id("some_user_id").await? {
        println!("User: {}", user.name);
    }
    Ok(())
}

Contributing

Contributions to nexus-common are welcome! Please open issues or submit pull requests on the project's repository. Follow the established coding conventions and include tests for new features.

License

This project is licensed under the MIT License.