Skip to main content

oxigeo_pubsub/
lib.rs

1//! OxiGeo Pub/Sub - Google Cloud Pub/Sub integration for OxiGeo.
2//!
3//! This crate provides comprehensive support for Google Cloud Pub/Sub messaging,
4//! including publishing, subscribing, schema validation, and monitoring capabilities.
5//!
6//! # Features
7//!
8//! - **Publisher**: Async message publishing with batching and ordering keys
9//! - **Subscriber**: Pull and push subscriptions with flow control
10//! - **Schema Support**: Avro and Protobuf schema validation (feature-gated)
11//! - **Monitoring**: Cloud Monitoring integration for metrics and observability
12//! - **Dead Letter Queues**: Automatic handling of failed messages
13//! - **Flow Control**: Intelligent message throttling and backpressure
14//!
15//! # Example: Publishing Messages
16//!
17//! ```no_run
18//! # #[cfg(feature = "publisher")]
19//! # mod example {
20//! use oxigeo_pubsub::{Publisher, PublisherConfig, Message};
21//!
22//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
23//!     let config = PublisherConfig::new("my-project", "my-topic")
24//!         .with_batching(true)
25//!         .with_batch_size(100);
26//!
27//!     let publisher = Publisher::new(config).await?;
28//!
29//!     let message = Message::new(b"Hello, Pub/Sub!".to_vec())
30//!         .with_attribute("source", "oxigeo")
31//!         .with_ordering_key("order-1");
32//!
33//!     let message_id = publisher.publish(message).await?;
34//!     println!("Published message: {}", message_id);
35//!     Ok(())
36//! }
37//! # }
38//! ```
39//!
40//! # Example: Subscribing to Messages
41//!
42//! ```no_run
43//! # #[cfg(feature = "subscriber")]
44//! # mod example {
45//! use oxigeo_pubsub::{Subscriber, SubscriberConfig, HandlerResult};
46//!
47//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
48//!     let config = SubscriberConfig::new("my-project", "my-subscription")
49//!         .with_ack_deadline(30);
50//!
51//!     let subscriber = Subscriber::new(config).await?;
52//!
53//!     let _handle = subscriber.start(|message| {
54//!         println!("Received: {:?}", message.data);
55//!         HandlerResult::Ack
56//!     }).await?;
57//!
58//!     // Wait for shutdown signal...
59//!     subscriber.stop();
60//!     Ok(())
61//! }
62//! # }
63//! ```
64//!
65//! # Feature Flags
66//!
67//! - `std` (default): Enable standard library support
68//! - `async` (default): Enable async runtime support
69//! - `publisher` (default): Enable publisher functionality
70//! - `subscriber` (default): Enable subscriber functionality
71//! - `schema`: Enable schema support
72//! - `avro`: Enable Apache Avro schema support
73//! - `protobuf`: Enable Protocol Buffers schema support
74//! - `monitoring`: Enable Cloud Monitoring integration
75//! - `batching`: Enable message batching
76//! - `ordering`: Enable message ordering
77//! - `flow-control`: Enable flow control
78//! - `dead-letter`: Enable dead letter queue support
79//!
80//! # Pure Rust Implementation
81//!
82//! This crate uses Pure Rust implementations for all functionality:
83//! - `google-cloud-pubsub` for Pub/Sub operations
84//! - `google-cloud-auth` for authentication
85//! - `google-cloud-monitoring` for monitoring (optional)
86//! - `apache-avro` for Avro schema support (optional)
87//! - `prost` for Protocol Buffers support (optional)
88//!
89//! # COOLJAPAN Policy Compliance
90//!
91//! - ✅ Pure Rust (no C/Fortran dependencies)
92//! - ✅ No `unwrap()` usage (proper error handling)
93//! - ✅ Files under 2000 lines (modular design)
94//! - ✅ Workspace dependencies
95
96#![deny(missing_docs)]
97#![deny(clippy::unwrap_used)]
98#![deny(clippy::panic)]
99#![warn(clippy::expect_used)]
100#![cfg_attr(not(feature = "std"), no_std)]
101
102#[cfg(feature = "alloc")]
103extern crate alloc;
104
105pub mod error;
106
107#[cfg(feature = "publisher")]
108pub mod publisher;
109
110#[cfg(feature = "subscriber")]
111pub mod subscriber;
112
113#[cfg(feature = "schema")]
114pub mod schema;
115
116#[cfg(feature = "monitoring")]
117pub mod monitoring;
118
119#[cfg(feature = "pubsub-client")]
120pub mod topic;
121
122#[cfg(feature = "pubsub-client")]
123pub mod subscription;
124
125// Re-exports for convenience
126pub use error::{PubSubError, Result};
127
128#[cfg(feature = "publisher")]
129pub use publisher::{
130    DEFAULT_BATCH_SIZE, DEFAULT_BATCH_TIMEOUT_MS, DEFAULT_MAX_OUTSTANDING_PUBLISHES,
131    MAX_MESSAGE_SIZE, Message, Publisher, PublisherConfig, PublisherStats, RetryConfig,
132};
133
134#[cfg(feature = "subscriber")]
135pub use subscriber::{
136    DEFAULT_ACK_DEADLINE_SECONDS, DEFAULT_HANDLER_CONCURRENCY, DEFAULT_MAX_OUTSTANDING_BYTES,
137    DEFAULT_MAX_OUTSTANDING_MESSAGES, DeadLetterConfig, FlowControlSettings, HandlerResult,
138    ReceivedMessage, Subscriber, SubscriberConfig, SubscriberStats, SubscriptionType,
139};
140
141#[cfg(feature = "schema")]
142pub use schema::{Schema, SchemaEncoding, SchemaRegistry, SchemaValidator};
143
144#[cfg(all(feature = "schema", feature = "avro"))]
145pub use schema::AvroSchema;
146
147#[cfg(all(feature = "schema", feature = "protobuf"))]
148pub use schema::ProtobufSchema;
149
150#[cfg(feature = "monitoring")]
151pub use monitoring::{
152    LatencyTracker, MetricPoint, MetricType, MetricValue, MetricsCollector, MetricsExporter,
153    OperationTimer, PublisherMetrics, SubscriberMetrics,
154};
155
156#[cfg(feature = "pubsub-client")]
157pub use topic::{TopicBuilder, TopicConfig, TopicManager, TopicMetadata, TopicStats};
158
159#[cfg(all(feature = "pubsub-client", feature = "schema"))]
160pub use topic::SchemaSettings;
161
162#[cfg(feature = "pubsub-client")]
163pub use subscription::{
164    DeadLetterPolicy, ExpirationPolicy, RetryPolicy, SubscriptionBuilder, SubscriptionCreateConfig,
165    SubscriptionManager, SubscriptionMetadata, SubscriptionStats,
166};
167
168/// Crate version.
169pub const VERSION: &str = env!("CARGO_PKG_VERSION");
170
171/// Crate name.
172pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
173
174/// Gets the crate version.
175pub fn version() -> &'static str {
176    VERSION
177}
178
179/// Gets the crate name.
180pub fn crate_name() -> &'static str {
181    CRATE_NAME
182}
183
184#[cfg(test)]
185mod tests {
186    use super::*;
187
188    #[test]
189    fn test_version() {
190        assert!(!version().is_empty());
191    }
192
193    #[test]
194    fn test_crate_name() {
195        assert_eq!(crate_name(), "oxigeo-pubsub");
196    }
197}