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

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