⚡ Velomorph

High-performance, zero-copy struct transformation with asynchronous background deallocation for low-latency Rust systems.

📖 Overview

Velomorph is a specialized toolkit for Rust developers who need to transform data structures at extreme speeds. It is specifically designed for high-throughput network applications, real-time data processing, and microservices where every microsecond of P99 latency matters.

It solves three critical bottlenecks in data pipelines:

Memory Jitter: Large objects are offloaded to a background "Janitor" thread for deallocation, preventing drop() calls from blocking your critical path.
Allocation Overhead: First-class support for Cow<'a, str> allows you to borrow strings from input buffers rather than cloning them.
Boilerplate: A sophisticated procedural macro handles the mapping between Option<T> and T with built-in strict validation.

✨ Key Features

🚀 Zero-Copy Transformation: Leverage Rust's ownership model to move or borrow data with zero heap allocations during morphing.
🧹 The Janitor Pattern: Offload heavy payloads (like Vec<u8>) to a dedicated cleanup thread and protect P99 latency from deallocation spikes.
🛡️ Type-Aware Macro: The #[derive(Morph)] macro automatically detects target types to decide between Strict (error if None), Passthrough (Option to Option), or Borrowed (Cow) modes.
🔀 Advanced Mapping Controls: Supports enum morphing, field transforms (with), defaults, skips, and type-level validation hooks.
🔌 Tokio Integration (Opt-in): Enable the janitor feature when background deallocation is needed.

🏗 Project Structure

Velomorph is structured as a workspace for maximum efficiency:

velomorph-lib: The core runtime, traits, and the Janitor implementation.
velomorph-derive: The procedural macro that generates the high-performance transformation code.

🚀 Quick Start

Add the following to your Cargo.toml:

Cargo.toml

[dependencies]
velomorph = "0.2.0"

Enable Janitor offloading explicitly when needed:

[dependencies]
velomorph = { version = "0.2.0", features = ["janitor"] }

Then create src/main.rs:

src/main.rs

use std::borrow::Cow;
use uuid::Uuid;
use velomorph::{TryMorph, Morph};
#[cfg(feature = "janitor")]
use velomorph::Janitor;

// 1. Define your raw source data (e.g., from a network buffer).
pub struct SourcePacket<'a> {
    pub uuid_v4: Option<Uuid>,  // Legacy / external field name
    pub user_str: &'a str,      // Another external/opaque name
    pub payload: Option<Vec<u8>>,
}

// 2. Define your optimized domain model.
//    Here we also *rename* the incoming fields using `#[morph(from = "...")]`.
#[derive(Morph, Debug)]
#[morph(from = "SourcePacket")]
pub struct InternalEvent<'a> {
    #[morph(from = "uuid_v4")]
    pub id: Uuid,               // Strict: Returns Error if None in source

    #[morph(from = "user_str")]
    pub username: Cow<'a, str>, // Zero-copy: Borrows from the source
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the background cleanup worker when enabled
    #[cfg(feature = "janitor")]
    let janitor = Janitor::new();
    
    let raw = SourcePacket {
        uuid_v4: Some(Uuid::new_v4()),
        user_str: "sensor_alpha_01",
        payload: Some(vec![0u8; 1024 * 1024 * 50]), // 50MB payload
    };

    // Morph!
    // - `janitor` is available in this signature when the feature is enabled.
    // - 'username' is borrowed (zero allocations).
    // - 'id' is validated and unwrapped.
    #[cfg(feature = "janitor")]
    let event: InternalEvent = raw.try_morph(&janitor)?;
    #[cfg(not(feature = "janitor"))]
    let event: InternalEvent = raw.try_morph()?;

    println!("Morphed event: {:?}", event);
    Ok(())
}

Showcase Modes (Explicit Janitor Usage)

The full_showcase example demonstrates both execution paths clearly:

Without janitor feature:

cargo run -p full_showcase

With janitor feature enabled:

cargo run -p full_showcase --features janitor

In janitor mode, the example explicitly offloads the heavy payload via Janitor::offload(...) before morphing.

🛠 How it Works

Background Deallocation (The Janitor Pattern)

In high-load systems, calling drop() on a large Vec or a complex tree can take several milliseconds as the OS reclaims memory. Velomorph provides a Janitor helper that can move these objects to an isolated OS thread via an unbounded channel.

This ensures that the thread handling your critical network requests or business logic never stalls due to memory management jitter when you choose to offload deallocation from your code path.

The Morph Macro Logic

The #[derive(Morph)] macro performs a deep analysis of your struct fields at compile time to generate the most efficient mapping possible:

Target Type	Source Type	Strategy	Result
`T`	`Option<T>`	Strict	Returns `MorphError::MissingField` if `None`.
`Option<T>`	`Option<T>`	Passthrough	Moves the `Option` as-is.
`Cow<'a, str>`	`&'a str`	Zero-Copy	Borrows the string (no heap allocation).

You can also choose a custom source type instead of the default RawInput:

#[derive(Morph)]
#[morph(from = "RawPacket<'a>")]
pub struct InternalEvent<'a> {
    pub id: u64,
    pub tag: std::borrow::Cow<'a, str>,
}

Advanced attributes:

#[derive(Morph)]
#[morph(from = "Source", validate = "validate_target")]
struct Target {
    #[morph(from = "legacy_id", with = "parse_id")]
    id: u64,
    #[morph(default)]
    retries: u32,
    #[morph(skip)]
    cache_key: String,
}

with transform functions currently use the form fn(SourceType) -> Result<TargetType, E>. Enum targets use same-name variant mapping by default, with per-variant overrides via #[morph(from = "...")].

Memory Safety & Lifetimes

Velomorph is built on top of Rust's strict ownership rules. By using Cow<'a, str>, the compiler guarantees that the source buffer (e.g., your network packet) lives at least as long as your transformed InternalEvent. If the source buffer is dropped, the compiler will catch the error at build time.

🗺 v0.2 Status

Velomorph 0.2 includes:

🧩 Modular Janitor: Optional background cleanup via feature flags.
🏷 Flexible Sources: Type-level and field-level from mapping.
🛠 Custom Transforms: Field-level with transforms.
🧱 Defaults & Skips: Field-level default / default = "..." and skip controls.
🏗 Validation Logic: Type-level post-transformation validation hooks.
🔄 Enum Support: Same-name variant mapping with explicit variant overrides.

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📜 License

Licensed under either of:

Built for speed. Engineered for reliability. ⚡ Velomorph.

velomorph 0.2.0