rsfulmen

Curated Libraries for Scale

Rust Fulmen helper library for enterprise-scale development.

Lifecycle Phase: alpha | Version: 0.1.0

📖 Read the complete rsfulmen overview for comprehensive documentation including module catalog and roadmap.

Overview

rsfulmen provides consistent, high-quality implementations of common functionality across the FulmenHQ ecosystem. Built on Crucible's schemas and standards, it ensures uniformity and reliability with idiomatic Rust APIs.

Alpha Status: Early adopters; API may evolve before 1.0. See Repository Lifecycle Standard.

Crucible Integration

What is Crucible?

Crucible is the FulmenHQ single source of truth (SSOT) for schemas, standards, and configuration templates. It ensures consistent APIs, documentation structures, and behavioral contracts across all language foundations (gofulmen, pyfulmen, tsfulmen, rsfulmen).

Why rsfulmen?

Rather than copying Crucible assets into every Rust project, rsfulmen provides idiomatic access through type-safe APIs. This keeps your application lightweight, versioned correctly, and aligned with ecosystem-wide standards.

Where to Learn More:

• Crucible Repository — SSOT schemas, docs, and configs
• Fulmen Technical Manifesto — Philosophy and design principles
• gofulmen — Go reference implementation

Modules

Config (config)

Configuration path utilities following the Fulmen Config Path Standard.

• XDG Base Directory compliance (Linux, macOS, Windows)
• Application-specific config/data/cache directories
• Fulmen ecosystem directory helpers
• Legacy config path fallback support

use rsfulmen::config::{get_fulmen_config_dir, get_app_config_dir, get_xdg_base_dirs};

// Get Fulmen ecosystem config directory
let fulmen_config = get_fulmen_config_dir();
// Linux: ~/.config/fulmen
// macOS: ~/Library/Application Support/Fulmen
// Windows: %APPDATA%\Fulmen

// Get app-specific directories
let app_config = get_app_config_dir("myapp");
let xdg = get_xdg_base_dirs();
println!("Config home: {:?}", xdg.config_home);

Foundry (foundry)

Enterprise-grade foundation utilities providing consistent cross-language implementations from Crucible catalogs. All data is embedded at compile time — no network dependencies required.

Country Codes

ISO 3166-1 country code lookups with triple-index support.

use rsfulmen::foundry::country_codes::{lookup_by_alpha2, lookup_by_alpha3, lookup_by_numeric};

let usa = lookup_by_alpha2("US").unwrap();
assert_eq!(usa.name, "United States of America");
assert_eq!(usa.alpha3, "USA");

// Case-insensitive lookups
let japan = lookup_by_alpha3("jpn").unwrap();
assert_eq!(japan.alpha2, "JP");

// Numeric codes (auto zero-padded)
let germany = lookup_by_numeric("276").unwrap();
assert_eq!(germany.name, "Germany");

HTTP Status Codes

HTTP status code registry with grouping helpers.

use rsfulmen::foundry::http_statuses::{lookup_status, get_reason, is_success, StatusGroup};

let ok = lookup_status(200).unwrap();
assert_eq!(ok.reason, "OK");
assert_eq!(ok.group, StatusGroup::Success);

assert!(is_success(201));
assert!(!is_success(404));

let reason = get_reason(404).unwrap();
assert_eq!(reason, "Not Found");

Exit Codes

Standardized exit codes with categories and signal handling.

use rsfulmen::foundry::exit_codes::{
    lookup_exit_code, is_signal_exit, get_signal_from_exit,
    EXIT_SUCCESS, EXIT_CONFIG_INVALID, ExitCategory,
};

// Use standard constants
std::process::exit(EXIT_SUCCESS);

// Look up exit code metadata
let code = lookup_exit_code(20).unwrap();
assert_eq!(code.name, "EXIT_CONFIG_INVALID");
assert_eq!(code.category, ExitCategory::Configuration);

// Signal detection (128+)
assert!(is_signal_exit(130));  // SIGINT
let signal = get_signal_from_exit(130).unwrap();
assert_eq!(signal, 2);  // SIGINT = 2

Error Handling (error_handling)

Canonical error envelope that extends Pathfinder's schema with optional telemetry fields (severity, correlation_id, exit_code, etc.). Payloads are JSON serializable and can be validated offline when schema-validation is enabled.

use rsfulmen::error_handling::{ErrorResponse, PathfinderErrorResponse, Severity, WrapOptions};

let base = PathfinderErrorResponse::new("CONFIG_INVALID", "Config load failed");
let err = ErrorResponse::wrap(
    base,
    WrapOptions {
        severity: Some(Severity::High),
        exit_code: Some(20),
        ..WrapOptions::default()
    },
)
.unwrap();

println!("{}", err.to_json_string_pretty().unwrap());

Telemetry Metrics (telemetry_metrics)

Taxonomy-backed counters, gauges, and histograms exported as schema-valid JSON events.

use rsfulmen::telemetry_metrics::Metrics;

let metrics = Metrics::new();
metrics.counter("schema_validations").unwrap().inc(None).unwrap();

let events = metrics.flush().unwrap();
assert!(!events.is_empty());

Installation

Add to your Cargo.toml:

[dependencies]
rsfulmen = "0.1"

Feature Flags

rsfulmen supports minimal installs for lightweight consumers (e.g. sysprims).

[dependencies]
# All features (default)
rsfulmen = "0.1"

# Foundry core only (signals, exit-codes, countries, http-statuses)
rsfulmen = { version = "0.1", default-features = false, features = ["foundry-core"] }

# Add MIME types (adds serde_json)
rsfulmen = { version = "0.1", default-features = false, features = ["foundry-mime-types"] }

# Add patterns (adds regex/glob)
rsfulmen = { version = "0.1", default-features = false, features = ["foundry-patterns"] }

# Similarity (standalone module; heavy)
rsfulmen = { version = "0.1", default-features = false, features = ["similarity"] }

# Schema validation (heavy)
rsfulmen = { version = "0.1", default-features = false, features = ["schema-validation"] }

Feature Matrix

Development

Prerequisites

• Rust 1.83+
• goneat for SSOT sync (installed via make bootstrap)

Quick Start

# Install development tools
make bootstrap

# Sync Crucible assets
make sync

# Run tests
make test

# Run all quality checks
make check-all

Makefile Targets

Crucible Sync

rsfulmen syncs schemas, documentation, and configuration from Crucible:

# Update to latest Crucible
make sync

# Check sync provenance
cat .goneat/ssot/provenance.json

Synced assets are stored in:

• config/crucible-rs/ — Configuration files and foundry catalogs
• schemas/crucible-rs/ — JSON schemas
• docs/crucible-rs/ — Documentation and standards

Ecosystem

rsfulmen is part of the Fulmen helper library family:

All libraries sync from Crucible and follow the Fulmen Helper Library Standard.

Contributing

Contributions are welcome! Please ensure:

• Code follows Rust idioms and conventions
• Tests are included for new functionality
• Documentation is updated
• Changes are consistent with Crucible standards
• make check-all passes before submitting

License

Licensed under the MIT License. See LICENSE file for details.

Changelog

See CHANGELOG.md for version history.