modkit/
lib.rs

1#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
2//! # `ModKit` - Declarative Module System
3//!
4//! A unified crate for building modular applications with declarative module definitions.
5//!
6//! ## Features
7//!
8//! - **Declarative**: Use `#[module(...)]` attribute to declare modules
9//! - **Auto-discovery**: Modules are automatically discovered via inventory
10//! - **Type-safe**: Compile-time validation of capabilities
11//! - **Phase-based lifecycle**: executed by `HostRuntime` (see `runtime/host_runtime.rs` docs)
12//!
13//! ## Golden Path: Stateless Handlers
14//!
15//! For optimal performance and readability, prefer stateless handlers that receive
16//! `Extension<T>` and other extractors rather than closures that capture environment.
17//!
18//! ### Recommended Pattern
19//!
20//! ```rust,ignore
21//! use axum::{Extension, Json};
22//! use modkit::api::{OperationBuilder, Problem};
23//! use std::sync::Arc;
24//!
25//! async fn list_users(
26//!     Extension(svc): Extension<Arc<UserService>>,
27//! ) -> Result<Json<Vec<UserDto>>, Problem> {
28//!     let users = svc.list_users().await.map_err(Problem::from)?;
29//!     Ok(Json(users))
30//! }
31//!
32//! pub fn router(service: Arc<UserService>) -> axum::Router {
33//!     let op = OperationBuilder::get("/users-info/v1/users")
34//!         .summary("List users")
35//!         .handler(list_users)
36//!         .json_response(200, "List of users")
37//!         .standard_errors(&registry);
38//!
39//!     axum::Router::new()
40//!         .route("/users-info/v1/users", axum::routing::get(list_users))
41//!         .layer(Extension(service))
42//!         .layer(op.to_layer())
43//! }
44//! ```
45//!
46//! ### Benefits
47//!
48//! - **Performance**: No closure captures or cloning on each request
49//! - **Readability**: Clear function signatures show exactly what data is needed
50//! - **Testability**: Easy to unit test handlers with mock state
51//! - **Type Safety**: Compile-time verification of dependencies
52//! - **Flexibility**: Individual service injection without coupling
53//!
54//! ## Basic Module Example
55//!
56//! ```rust,ignore
57//! use modkit::{module, Module, DbModule, RestfulModule, StatefulModule};
58//!
59//! #[derive(Default)]
60//! #[module(name = "user", deps = ["database"], capabilities = [db, rest, stateful])]
61//! pub struct UserModule;
62//!
63//! // Implement the declared capabilities...
64//! ```
65
66pub use anyhow::Result;
67pub use async_trait::async_trait;
68
69// Re-export inventory for user convenience
70pub use inventory;
71
72// Module system exports
73pub use crate::contracts::*;
74pub use crate::contracts::{GrpcServiceCapability, RegisterGrpcServiceFn};
75
76// Configuration module
77pub mod config;
78pub use config::{ConfigError, ConfigProvider, module_config_or_default, module_config_required};
79
80// Context module
81pub mod context;
82pub use context::{ModuleContextBuilder, ModuleCtx};
83
84// Module system implementations for macro code
85pub mod client_hub;
86pub mod registry;
87
88// Re-export main types
89pub use client_hub::ClientHub;
90pub use registry::ModuleRegistry;
91
92// Re-export the macros from the proc-macro crate
93pub use modkit_macros::{lifecycle, module};
94
95// Core module contracts and traits
96pub mod contracts;
97// Type-safe API operation builder
98pub mod api;
99pub use api::{
100    IntoProblem, OpenApiInfo, OpenApiRegistry, OpenApiRegistryImpl, OperationBuilder,
101    error_mapping_middleware,
102};
103pub use modkit_odata::{Page, PageInfo};
104
105// HTTP utilities
106pub mod http;
107pub use api::problem::{
108    Problem, ValidationError, bad_request, conflict, internal_error, not_found,
109};
110pub use http::client::TracedClient;
111pub use http::sse::SseBroadcaster;
112
113// Telemetry utilities
114pub mod telemetry;
115
116pub mod backends;
117pub mod lifecycle;
118pub mod plugins;
119pub mod runtime;
120
121// Error catalog runtime support
122pub mod errors;
123
124// Ergonomic result types
125pub mod result;
126pub use result::ApiResult;
127
128// Directory API for service discovery
129pub mod directory;
130pub use directory::{
131    DirectoryClient, LocalDirectoryClient, RegisterInstanceInfo, ServiceEndpoint,
132    ServiceInstanceInfo,
133};
134
135// GTS schema support
136pub mod gts;
137
138// Security context scoping wrapper (re-exported from modkit-sdk)
139pub use modkit_sdk::{Secured, WithSecurityContext};
140
141pub use backends::{
142    BackendKind, InstanceHandle, LocalProcessBackend, ModuleRuntimeBackend, OopBackend,
143    OopModuleConfig, OopSpawnConfig,
144};
145pub use lifecycle::{Lifecycle, Runnable, Status, StopReason, WithLifecycle};
146pub use plugins::GtsPluginSelector;
147pub use runtime::{
148    DbOptions, Endpoint, ModuleInstance, ModuleManager, OopModuleSpawnConfig, OopSpawnOptions,
149    RunOptions, ShutdownOptions, run,
150};
151
152#[cfg(feature = "bootstrap")]
153pub mod bootstrap;
modkit/lib.rs

modkit/
lib.rs
