Crate dynpatch

Crate dynpatch 

Source
Expand description

§dynpatch

Safe live code reloading for Rust applications.

dynpatch enables runtime hot-patching of Rust code with strong safety guarantees, transactional semantics, and automatic rollback on failure.

§Features

  • Runtime hot patching: Update code without restarting
  • Safety first: Strong ABI/type compatibility checks
  • Transactional: All-or-nothing activation with automatic rollback
  • State continuity: Optional state migration between versions
  • Minimal overhead: Lock-free implementation swapping
  • Developer friendly: Macros, CLI, file watching, and introspection

§Quick Start

§Basic Usage

ⓘ
use dynpatch::prelude::*;

// Initialize the runtime
init();

// Load a patch
reload("path/to/patch.so")?;

// Check active patch
if let Some(info) = active_patch_info() {
    println!("Active: {} v{}", info.name, info.version);
}

// Rollback if needed
rollback()?;

§Advanced Configuration

ⓘ
use dynpatch::prelude::*;
use dynpatch_interface::Version;

// Configure the runtime with specific requirements
RuntimeBuilder::new()
    .interface_version(Version::new(1, 0, 0))
    .type_hash(0x1234567890abcdef)
    .init();

§Mark code as patchable

ⓘ
use dynpatch::prelude::*;

#[patch_trait]
pub trait Handler {
    fn handle(&self, request: Request) -> Response;
}

#[patchable]
fn process_data(data: &str) -> String {
    data.to_uppercase()
}

§Hot-reload configuration

ⓘ
use dynpatch::config::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Deserialize, Serialize)]
struct AppConfig {
    max_connections: usize,
    timeout_ms: u64,
}

impl HotConfig for AppConfig {}

fn main() {
    let watcher = watch::<AppConfig, _>("config.toml").unwrap();
     
    loop {
        let config = watcher.get();
        println!("Max connections: {}", config.max_connections);
        std::thread::sleep(std::time::Duration::from_secs(1));
    }
}

§Architecture

dynpatch consists of several components:

  • dynpatch-core: Runtime engine for loading and managing patches
  • dynpatch-macro: Procedural macros for marking patchable code
  • dynpatch-interface: Shared types for host-patch communication
  • dynpatch-watcher: File watching and config reloading
  • dynpatch-cli: Command-line tool for building and managing patches

§Safety Guarantees

  • ABI validation: Type layout and signature checking before activation
  • Version compatibility: Semantic versioning with compatibility rules
  • Transactional swaps: Atomic activation with automatic rollback on failure
  • Thread safety: Lock-free RCU-like publication using arc-swap
  • Panic safety: Catch initialization panics and rollback

§Optional Features

  • watcher (default) - File watching and config reloading
  • abi_stable - Enhanced ABI checks using abi_stable crate
  • metrics - Performance and operation metrics
  • signing - Cryptographic patch signature verification
  • sandbox - Process isolation for untrusted patches
  • json, yaml, toml - Config format support

Modules§

config
prelude
Prelude module for convenient imports

Structs§

PatchInfo
Information about a loaded patch
PatchMetadata
Metadata about a patch
PatchRecord
Historical record of a patch load/unload
RuntimeBuilder
Builder for configuring the dynpatch runtime
TypeLayout
Information about type layout for ABI validation
Version
Version information for patches

Enums§

PatchError
Errors that can occur during patch operations

Traits§

PatchInterface
Trait for patchable interfaces
StateMigration
State migration trait for carrying state across patch versions

Functions§

active_patch_info
Get information about the currently active patch
compute_type_hash
Compute a deterministic hash of a type’s name for compatibility checking
history
Get the history of all loaded patches
init
Initialize the dynpatch runtime with default settings
reload
Reload a patch from the specified path
rollback
Rollback to the previous patch
watch
Watch a file and call a callback on changes

Attribute Macros§

patch_entry
Mark patch entry point with initialization
patch_impl
Mark a struct as a patch implementation
patch_trait
Mark a trait as a patchable interface
patchable
Mark a function as patchable

Derive Macros§

HotConfig
Derive macro for hot-reloadable configuration