ModKit

Declarative module system and common runtime utilities used across CyberFabric.

Overview

The cf-modkit crate provides:

• Module registration and lifecycle (inventory-based discovery)
• ClientHub for typed in-process clients
• REST/OpenAPI helpers (OperationBuilder, OpenApiRegistry, RFC-9457 Problem)
• Runtime helpers (module registry/manager, lifecycle helpers)

Features

• db (default): Enables DB integration (depends on cf-modkit-db), including:
  • DatabaseCapability (migrations contract)
  • DbOptions::Manager (runtime DB manager support)
  • DB handle resolution in ModuleCtx / ModuleContextBuilder

Build without DB

To build cf-modkit without pulling in cf-modkit-db and its transitive dependencies:

cargo build -p cf-modkit --no-default-features

License

Licensed under Apache-2.0.

lib.rs:

ModKit - Declarative Module System

A unified crate for building modular applications with declarative module definitions.

Features

• Declarative: Use #[module(...)] attribute to declare modules
• Auto-discovery: Modules are automatically discovered via inventory
• Type-safe: Compile-time validation of capabilities
• Phase-based lifecycle: executed by HostRuntime (see runtime/host_runtime.rs docs)

Golden Path: Stateless Handlers

For optimal performance and readability, prefer stateless handlers that receive Extension<T> and other extractors rather than closures that capture environment.

Recommended Pattern

use axum::{Extension, Json};
use modkit::api::{OperationBuilder, Problem};
use std::sync::Arc;

async fn list_users(
    Extension(svc): Extension<Arc<UserService>>,
) -> Result<Json<Vec<UserDto>>, Problem> {
    let users = svc.list_users().await.map_err(Problem::from)?;
    Ok(Json(users))
}

pub fn router(service: Arc<UserService>) -> axum::Router {
    let op = OperationBuilder::get("/users-info/v1/users")
        .summary("List users")
        .handler(list_users)
        .json_response(200, "List of users")
        .standard_errors(&registry);

    axum::Router::new()
        .route("/users-info/v1/users", axum::routing::get(list_users))
        .layer(Extension(service))
        .layer(op.to_layer())
}

Benefits

• Performance: No closure captures or cloning on each request
• Readability: Clear function signatures show exactly what data is needed
• Testability: Easy to unit test handlers with mock state
• Type Safety: Compile-time verification of dependencies
• Flexibility: Individual service injection without coupling

Basic Module Example

use modkit::{module, Module, DbModule, RestfulModule, StatefulModule};

#[derive(Default)]
#[module(name = "user", deps = ["database"], capabilities = [db, rest, stateful])]
pub struct UserModule;

// Implement the declared capabilities...