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
66// When running tests, make ::modkit resolve to this crate so macros work
67#[cfg(test)]
68extern crate self as modkit;
69
70pub use anyhow::Result;
71pub use async_trait::async_trait;
72
73// Re-export inventory for user convenience
74pub use inventory;
75
76// Module system exports
77pub use crate::contracts::*;
78pub use crate::contracts::{GrpcServiceCapability, RegisterGrpcServiceFn};
79
80// Configuration module
81pub mod config;
82pub use config::{ConfigError, ConfigProvider, module_config_or_default, module_config_required};
83
84// Context module
85pub mod context;
86pub use context::{ModuleContextBuilder, ModuleCtx};
87
88// Module system implementations for macro code
89pub mod client_hub;
90pub mod registry;
91
92// Re-export main types
93pub use client_hub::ClientHub;
94pub use registry::ModuleRegistry;
95
96// Re-export the macros from the proc-macro crate
97pub use modkit_macros::{lifecycle, module};
98
99// Core module contracts and traits
100pub mod contracts;
101// Type-safe API operation builder
102pub mod api;
103pub use api::{
104    IntoProblem, OpenApiInfo, OpenApiRegistry, OpenApiRegistryImpl, OperationBuilder,
105    error_mapping_middleware,
106};
107pub use modkit_odata::{Page, PageInfo};
108
109// HTTP utilities
110pub mod http;
111pub use api::problem::{
112    Problem, ValidationError, bad_request, conflict, internal_error, not_found,
113};
114pub use http::sse::SseBroadcaster;
115
116// Telemetry utilities
117pub mod telemetry;
118
119pub mod backends;
120pub mod lifecycle;
121pub mod plugins;
122pub mod runtime;
123
124// Error catalog runtime support
125pub mod errors;
126
127// Ergonomic result types
128pub mod result;
129pub use result::ApiResult;
130
131// Domain layer support (DDD patterns)
132#[doc(hidden)]
133pub mod domain;
134pub use domain::DomainModel;
135
136// Directory API for service discovery
137pub mod directory;
138pub use directory::{
139    DirectoryClient, LocalDirectoryClient, RegisterInstanceInfo, ServiceEndpoint,
140    ServiceInstanceInfo,
141};
142
143// GTS schema support
144pub mod gts;
145
146// Security context scoping wrapper (re-exported from modkit-sdk)
147pub use modkit_sdk::{Secured, WithSecurityContext};
148
149pub use backends::{
150    BackendKind, InstanceHandle, LocalProcessBackend, ModuleRuntimeBackend, OopBackend,
151    OopModuleConfig, OopSpawnConfig,
152};
153pub use lifecycle::{Lifecycle, Runnable, Status, StopReason, WithLifecycle};
154pub use plugins::GtsPluginSelector;
155pub use runtime::{
156    DbOptions, Endpoint, ModuleInstance, ModuleManager, OopModuleSpawnConfig, OopSpawnOptions,
157    RunOptions, ShutdownOptions, run,
158};
159
160#[cfg(feature = "bootstrap")]
161pub mod bootstrap;
modkit/lib.rs

modkit/
lib.rs
