Skip to main content

Crate modkit

Crate modkit 

Source
Expand description

§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.

ⓘ
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...

Re-exports§

pub use crate::contracts::GrpcServiceCapability;
pub use crate::contracts::RegisterGrpcServiceFn;
pub use config::ConfigError;
pub use config::ConfigProvider;
pub use config::module_config_or_default;
pub use config::module_config_required;
pub use context::ModuleContextBuilder;
pub use context::ModuleCtx;
pub use client_hub::ClientHub;
pub use registry::ModuleRegistry;
pub use api::IntoProblem;
pub use api::OpenApiInfo;
pub use api::OpenApiRegistry;
pub use api::OpenApiRegistryImpl;
pub use api::OperationBuilder;
pub use api::error_mapping_middleware;
pub use api::problem::bad_request;
pub use api::problem::conflict;
pub use api::problem::internal_error;
pub use api::problem::not_found;
pub use http::sse::SseBroadcaster;
pub use result::ApiResult;
pub use domain::DomainErrorMarker;
pub use domain::DomainModel;
pub use directory::LocalDirectoryClient;
pub use backends::BackendKind;
pub use backends::InstanceHandle;
pub use backends::LocalProcessBackend;
pub use backends::ModuleRuntimeBackend;
pub use backends::OopBackend;
pub use backends::OopModuleConfig;
pub use backends::OopSpawnConfig;
pub use lifecycle::Lifecycle;
pub use lifecycle::Runnable;
pub use lifecycle::Status;
pub use lifecycle::StopReason;
pub use lifecycle::WithLifecycle;
pub use plugins::GtsPluginSelector;
pub use runtime::DbOptions;
pub use runtime::Endpoint;
pub use runtime::ModuleInstance;
pub use runtime::ModuleManager;
pub use runtime::OopModuleSpawnConfig;
pub use runtime::OopSpawnOptions;
pub use runtime::RunOptions;
pub use runtime::ShutdownOptions;
pub use runtime::run;
pub use inventory;
pub use crate::contracts::*;

Modules§

api
Type-safe API operation builder with compile-time guarantees
backends
Backend abstraction for out-of-process module management
client_hub
Minimalistic, type-safe ClientHub.
config
Configuration module for typed module configuration access.
context
contracts
directory
Directory API - contract for service discovery and instance resolution
domain
Domain Layer Marker Traits
errors
Re-export error catalog types from modkit-errors
gts
http
HTTP utilities for modkit
lifecycle
plugins
registry
result
Ergonomic result types for API handlers
runtime
telemetry
Telemetry utilities for OpenTelemetry integration
var_expand
Single-pass expansion of ${VAR} placeholders from environment variables.

Structs§

Page
PageInfo
Problem
RFC 9457 Problem Details for HTTP APIs.
RegisterInstanceInfo
Information for registering a new module instance
Secured
A wrapper that binds a SecurityContext to a client reference.
ServiceEndpoint
Represents an endpoint where a service can be reached
ServiceInstanceInfo
Information about a service instance
ValidationError
Collection of validation errors for 422 responses.

Traits§

DirectoryClient
Directory API trait for service discovery and instance management
WithSecurityContext
Extension trait that adds the security_ctx method to any type.

Type Aliases§

Result
Result<T, Error>

Attribute Macros§

async_trait
lifecycle
module
Main #[module] attribute macro

Derive Macros§

ExpandVars
Derive macro that implements [modkit::var_expand::ExpandVars].