toolkit/
lib.rs

1#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
2//! # `ToolKit` - Declarative Gear System
3//!
4//! A unified crate for building modular applications with declarative gear definitions.
5//!
6//! ## Features
7//!
8//! - **Declarative**: Use `#[gear(...)]` attribute to declare gears
9//! - **Auto-discovery**: Gears 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 toolkit::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 Gear Example
55//!
56//! ```rust,ignore
57//! use toolkit::{gear, Gear, DbGear, RestfulGear, StatefulGear};
58//!
59//! #[derive(Default)]
60//! #[gear(name = "user", deps = ["database"], capabilities = [db, rest, stateful])]
61//! pub struct UserGear;
62//!
63//! // Implement the declared capabilities...
64//! ```
65
66// When running tests, make ::toolkit resolve to this crate so macros work
67#[cfg(test)]
68extern crate self as toolkit;
69
70pub use anyhow::Result;
71pub use async_trait::async_trait;
72
73// Re-export tokio so `#[gear(...)]`-generated code can reference
74// `::toolkit::tokio::...` without requiring gears to add a direct tokio dep.
75pub use tokio;
76
77// Re-export inventory for user convenience
78pub use inventory;
79
80// Gear system exports
81pub use crate::contracts::*;
82pub use crate::contracts::{GrpcServiceCapability, RegisterGrpcServiceFn};
83
84// Configuration gear
85pub mod config;
86pub use config::{ConfigError, ConfigProvider, gear_config_or_default, gear_config_required};
87
88// Context gear
89pub mod context;
90pub use context::{GearContextBuilder, GearCtx};
91
92// Gear system implementations for macro code
93pub mod client_hub;
94pub mod registry;
95
96// Re-export main types
97pub use client_hub::ClientHub;
98pub use registry::GearRegistry;
99
100// Re-export the macros from the proc-macro crate
101pub use toolkit_macros::{ExpandVars, gear, lifecycle};
102
103// Re-export var_expand gear so derive-generated impls resolve via ::toolkit::var_expand
104pub use toolkit_utils::var_expand;
105
106// Core gear contracts and traits
107pub mod contracts;
108// Type-safe API operation builder
109pub mod api;
110pub use api::{
111    IntoCanonical, OpenApiInfo, OpenApiRegistry, OpenApiRegistryImpl, OperationBuilder,
112    error_mapping_middleware,
113};
114pub use toolkit_odata::{Page, PageInfo};
115
116// HTTP utilities
117pub mod http;
118pub use http::sse::SseBroadcaster;
119
120// Telemetry utilities
121pub mod telemetry;
122
123pub mod backends;
124pub mod lifecycle;
125pub mod plugins;
126pub mod runtime;
127
128// Domain layer marker traits for DDD enforcement
129pub mod domain;
130pub use domain::{DomainErrorMarker, DomainModel};
131
132// Directory API for service discovery
133pub mod directory;
134pub use directory::{
135    DirectoryClient, LocalDirectoryClient, RegisterInstanceInfo, ServiceEndpoint,
136    ServiceInstanceInfo,
137};
138
139// GTS schema support
140pub mod gts;
141
142// Security context scoping wrapper (re-exported from toolkit-sdk)
143pub use toolkit_sdk::{Secured, WithSecurityContext};
144
145pub use backends::{
146    BackendKind, GearRuntimeBackend, InstanceHandle, LocalProcessBackend, OopBackend,
147    OopGearConfig, OopSpawnConfig,
148};
149pub use lifecycle::{Lifecycle, Runnable, Status, StopReason, WithLifecycle};
150pub use plugins::GtsPluginSelector;
151pub use runtime::{
152    DEFAULT_SHUTDOWN_DEADLINE, DbOptions, Endpoint, GearInstance, GearManager, OopGearSpawnConfig,
153    OopSpawnOptions, RunOptions, ShutdownOptions, run,
154};
155
156#[cfg(feature = "bootstrap")]
157pub mod bootstrap;
toolkit/lib.rs

toolkit/
lib.rs
