angzarr_client/
lib.rs

1//! Ergonomic Rust client for Angzarr gRPC services.
2//!
3//! This crate provides typed clients with fluent builder APIs for interacting
4//! with Angzarr aggregate coordinator and query services.
5//!
6//! # Quick Start
7//!
8//! ```rust,ignore
9//! use angzarr_client::{DomainClient, CommandBuilderExt, QueryBuilderExt};
10//! use uuid::Uuid;
11//!
12//! async fn example() -> angzarr_client::Result<()> {
13//!     // Connect to a domain's coordinator
14//!     let client = DomainClient::connect("http://localhost:1310").await?;
15//!
16//!     // Execute a command
17//!     let cart_id = Uuid::new_v4();
18//!     let response = client.command_handler
19//!         .command("cart", cart_id)
20//!         .with_command("type.googleapis.com/examples.CreateCart", &create_cart)
21//!         .execute()
22//!         .await?;
23//!
24//!     // Query events
25//!     let events = client.query
26//!         .query("cart", cart_id)
27//!         .range(0)
28//!         .get_pages()
29//!         .await?;
30//!     Ok(())
31//! }
32//! ```
33//!
34//! # Mocking for Tests
35//!
36//! Implement the `GatewayClient` and `QueryClient` traits to create mock clients:
37//!
38//! ```rust,ignore
39//! use angzarr_client::traits::{GatewayClient, QueryClient};
40//! use angzarr_client::proto::CommandBook;
41//! use async_trait::async_trait;
42//!
43//! struct MockAggregate;
44//!
45//! #[async_trait]
46//! impl GatewayClient for MockAggregate {
47//!     async fn execute(&self, _cmd: CommandBook)
48//!         -> angzarr_client::Result<angzarr_client::proto::CommandResponse>
49//!     {
50//!         // Return mock response
51//!         Ok(angzarr_client::proto::CommandResponse::default())
52//!     }
53//! }
54//! ```
55
56/// Version of the angzarr-client crate, injected at build time from VERSION file.
57pub const VERSION: &str = env!("ANGZARR_CLIENT_VERSION");
58
59pub mod builder;
60pub mod client;
61pub mod convert;
62pub mod error;
63pub mod handler;
64pub mod proto;
65pub mod proto_ext;
66pub mod router;
67pub mod server;
68pub mod traits;
69pub mod validation;
70
71// Re-export main types at crate root
72pub use client::{CommandHandlerClient, DomainClient, QueryClient, SpeculativeClient};
73pub use error::{ClientError, Result};
74
75// Re-export builder extension traits for fluent API
76pub use builder::{CommandBuilderExt, QueryBuilderExt};
77
78// Re-export helpers
79pub use builder::{decode_event, events_from_response, root_from_cover};
80pub use convert::{
81    full_type_name, full_type_url, now, parse_timestamp, proto_to_uuid, try_unpack, type_matches,
82    type_name_from_url, type_url, type_url_matches_exact, unpack, uuid_to_proto, TYPE_URL_PREFIX,
83};
84
85// Re-export extension traits
86pub use proto_ext::{
87    CommandBookExt, CommandPageExt, CoverExt, EditionExt, EventBookExt, EventPageExt, ProtoUuidExt,
88    UuidExt,
89};
90
91// Re-export router types
92pub use router::{
93    // Helper functions
94    event_book_from,
95    event_page,
96    new_event_book,
97    new_event_book_multi,
98    pack_event,
99    // Factory support for per-request handlers and HOF
100    BoxedHandlerFactory,
101    HandlerFactory,
102    HandlerHOF,
103    // Upcaster types
104    BoxedUpcasterHandler,
105    UpcasterHandler,
106    UpcasterHandlerHOF,
107    UpcasterMode,
108    UpcasterRouter,
109    // CloudEvents types
110    CloudEventsHandler,
111    CloudEventsProjector,
112    CloudEventsRouter,
113    // Handler traits
114    CommandHandlerDomainHandler,
115    // Mode markers
116    CommandHandlerMode,
117    // Router types
118    CommandHandlerRouter,
119    // Error types
120    CommandRejectedError,
121    CommandResult,
122    // State management
123    EventApplier,
124    EventApplierHOF,
125    StateFactory,
126    StateRouter,
127    // Process Manager types
128    ProcessManagerDomainHandler,
129    ProcessManagerMode,
130    ProcessManagerResponse,
131    ProcessManagerRouter,
132    // Projector types
133    ProjectorDomainHandler,
134    ProjectorMode,
135    ProjectorRouter,
136    RejectionHandlerResponse,
137    // Saga types
138    SagaContext,
139    SagaDomainHandler,
140    SagaHandlerResponse,
141    SagaMode,
142    SagaRouter,
143    UnpackAny,
144};
145
146// Note: dispatch_command! and dispatch_event! macros are available at crate root
147// via #[macro_export] in router/dispatch.rs
148
149// Re-export handler types
150pub use handler::{
151    CloudEventsGrpcHandler, CommandHandlerGrpc, ProcessManagerGrpcHandler, ProjectorHandler,
152    SagaHandler, StatePacker, UpcasterGrpcHandler, UpcasterHandleClosureFn, UpcasterHandleFn,
153};
154
155// Re-export server utilities
156pub use server::{
157    run_cloudevents_projector, run_command_handler_server, run_process_manager_server,
158    run_projector_server, run_saga_server, run_upcaster_server, ServerConfig,
159};
160
161// Re-export validation helpers
162pub use validation::{
163    require_exists, require_non_negative, require_not_empty, require_not_empty_str,
164    require_not_exists, require_positive, require_status, require_status_not,
165};
166
167// Re-export proc macros for OO-style component definitions
168pub use angzarr_macros::{
169    aggregate, applies, handles, prepares, process_manager, projector, projects, rejected, saga,
170};
angzarr_client/lib.rs

angzarr_client/
lib.rs
