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}