modkit/api/
mod.rs

1//! Type-safe API operation builder with compile-time guarantees
2//!
3//! This module 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_trace;
9pub mod error_layer;
10pub mod odata;
11pub mod openapi_registry;
12pub mod operation_builder;
13pub mod problem;
14pub mod response;
15pub mod select;
16pub mod trace_layer;
17
18#[cfg(test)]
19#[cfg_attr(coverage_nightly, coverage(off))]
20mod odata_policy_tests;
21
22pub use error_layer::{
23    IntoProblem, error_mapping_middleware, extract_trace_id, map_error_to_problem,
24};
25pub use openapi_registry::{OpenApiInfo, OpenApiRegistry, OpenApiRegistryImpl, ensure_schema};
26pub use operation_builder::{
27    Missing, OperationBuilder, OperationSpec, ParamLocation, ParamSpec, Present, RateLimitSpec,
28    ResponseSpec, state,
29};
30pub use problem::{
31    APPLICATION_PROBLEM_JSON, Problem, ValidationError, bad_request, conflict, internal_error,
32    not_found,
33};
34pub use select::{apply_select, page_to_projected_json, project_json};
35pub use trace_layer::{WithRequestContext, WithTraceContext};
36
37/// Prelude module that re-exports common API types and utilities for module authors
38pub mod prelude {
39    // Result type (Problem-only)
40    pub use crate::result::ApiResult;
41
42    // Problem type for error construction
43    pub use super::problem::Problem;
44
45    // Response sugar
46    pub use super::response::{JsonBody, JsonPage, created_json, no_content, ok_json};
47
48    // OData and field projection
49    pub use super::select::apply_select;
50
51    // Useful axum bits (common in handlers)
52    pub use axum::{Json, http::StatusCode, response::IntoResponse};
53}
54
55/// Parallel prelude for modules migrated to the canonical error catalog.
56///
57/// Mirrors [`prelude`] but re-exports `Problem` and `ApiResult` from
58/// `modkit-canonical-errors` so handlers can write the usual
59/// `ApiResult<JsonBody<T>>` signature without name clashes against the legacy
60/// types. Each per-module migration PR swaps `use modkit::api::prelude::*;`
61/// for `use modkit::api::canonical_prelude::*;` — no per-signature edits.
62///
63/// This module is collapsed into [`prelude`] and
64/// the legacy entries above are deleted.
65pub mod canonical_prelude {
66    // Canonical error types
67    pub use modkit_canonical_errors::{CanonicalError, Problem, resource_error};
68
69    /// Result type alias matching `prelude::ApiResult` but parameterised on
70    /// canonical `Problem`.
71    pub type ApiResult<T = ()> = std::result::Result<T, Problem>;
72
73    // Migration-time trace/instance helper. See `canonical_trace` module
74    // docs — scheduled for deletion when the canonical error middleware lands.
75    pub use super::canonical_trace::CanonicalProblemMigrationExt;
76
77    // Same response sugar / OData / axum re-exports as the legacy prelude
78    pub use super::response::{JsonBody, JsonPage, created_json, no_content, ok_json};
79    pub use super::select::apply_select;
80    pub use axum::{Json, http::StatusCode, response::IntoResponse};
81}
modkit/api/mod.rs

modkit/api/
mod.rs
