toolkit/api/
mod.rs

1//! Type-safe API operation builder with compile-time guarantees
2//!
3//! This gear provides a type-state builder pattern that enforces at compile time
4//! that API operations cannot be registered unless both a handler and at least one
5//! response are specified.
6
7pub mod api_dto;
8pub mod canonical_error_layer;
9pub mod error_layer;
10pub mod odata;
11pub mod openapi_registry;
12pub mod operation_builder;
13pub mod response;
14pub mod rest;
15pub mod select;
16
17#[cfg(test)]
18#[cfg_attr(coverage_nightly, coverage(off))]
19mod odata_policy_tests;
20
21pub use canonical_error_layer::canonical_error_middleware;
22pub use error_layer::{IntoCanonical, error_mapping_middleware, map_error_to_canonical};
23pub use openapi_registry::{OpenApiInfo, OpenApiRegistry, OpenApiRegistryImpl, ensure_schema};
24pub use operation_builder::{
25    INTERNAL_TOKEN_SECURITY_SCHEME, Missing, OperationBuilder, OperationSpec, ParamLocation,
26    ParamSpec, Present, ResponseHeaderSpec, ResponseHeaderType, ResponseSpec, RouteAuth,
27    ThrottlingSpec, state,
28};
29pub use select::{apply_select, page_to_projected_json, project_json};
30pub use toolkit_trace_context::{
31    current_request_id, extract_request_id, extract_trace_id, with_request_id,
32};
33
34/// Prelude that re-exports the canonical error types and common API utilities.
35pub mod canonical_prelude {
36    // Canonical error types
37    pub use toolkit_canonical_errors::{CanonicalError, Problem, resource_error};
38
39    /// Result type alias for handlers using the canonical error catalog.
40    ///
41    /// Returns [`CanonicalError`] (not [`Problem`]) so handler `?` chains
42    /// resolve through `From<DomainError> for CanonicalError` — the
43    /// long-lived per-gear mapping. The canonical error middleware
44    /// (`toolkit::api::canonical_error_middleware`) converts the
45    /// `CanonicalError` to a wire `Problem` and fills `instance` /
46    /// `trace_id` on the way out, so handlers never need to construct a
47    /// `Problem` themselves.
48    pub type ApiResult<T = ()> = std::result::Result<T, CanonicalError>;
49
50    // Same response sugar / OData / axum re-exports as the legacy prelude
51    pub use super::odata::OData;
52    pub use super::response::{JsonBody, JsonPage, created_json, no_content, ok_json};
53    pub use super::rest::extract;
54    pub use super::select::apply_select;
55    pub use axum::{Json, http::StatusCode, response::IntoResponse};
56}
toolkit/api/mod.rs

toolkit/api/
mod.rs
