feat: add subscription management and graceful shutdown support (v0.3.6)

- Add SubscriptionHandle for managing stream lifecycle
- Implement graceful shutdown with stop() methods
- Update documentation with new features
- Bump version to 0.3.6

src/streaming/yellowstone_grpc.rs

@@ -7,7 +7,7 @@ use yellowstone_grpc_proto::geyser::CommitmentLevel;
 
 use crate::common::AnyResult;
 use crate::streaming::common::{
-    EventBatchProcessor, MetricsManager, PerformanceMetrics, StreamClientConfig,
+    EventBatchProcessor, MetricsManager, PerformanceMetrics, StreamClientConfig, SubscriptionHandle,
 };
 use crate::streaming::event_parser::common::filter::EventTypeFilter;
 use crate::streaming::event_parser::{Protocol, UnifiedEvent};
@@ -26,7 +26,6 @@ pub struct AccountFilter {
     pub owner: Vec<String>,
 }
 
-#[derive(Clone)]
 pub struct YellowstoneGrpc {
     pub endpoint: String,
     pub x_token: Option<String>,
@@ -35,6 +34,7 @@ pub struct YellowstoneGrpc {
     pub subscription_manager: SubscriptionManager,
     pub metrics_manager: MetricsManager,
     pub event_processor: EventProcessor,
+    pub subscription_handle: Arc<Mutex<Option<SubscriptionHandle>>>,
 }
 
 impl YellowstoneGrpc {
@@ -67,6 +67,7 @@ impl YellowstoneGrpc {
             subscription_manager,
             metrics_manager,
             event_processor,
+            subscription_handle: Arc::new(Mutex::new(None)),
         })
     }
 
@@ -112,6 +113,14 @@ impl YellowstoneGrpc {
         self.config.enable_metrics = enabled;
     }
 
+    /// 停止当前订阅
+    pub async fn stop(&self) {
+        let mut handle_guard = self.subscription_handle.lock().await;
+        if let Some(handle) = handle_guard.take() {
+            handle.stop();
+        }
+    }
+
     /// Simplified immediate event subscription (recommended for simple scenarios)
     ///
     /// # Parameters
@@ -138,9 +147,13 @@ impl YellowstoneGrpc {
     where
         F: Fn(Box<dyn UnifiedEvent>) + Send + Sync + 'static,
     {
+        // 如果已有活跃订阅，先停止它
+        self.stop().await;
+
+        let mut metrics_handle = None;
         // 启动自动性能监控（如果启用）
         if self.config.enable_metrics {
-            self.metrics_manager.start_auto_monitoring().await;
+            metrics_handle = self.metrics_manager.start_auto_monitoring().await;
         }
 
         let transactions = self.subscription_manager.get_subscribe_request_filter(
@@ -166,7 +179,7 @@ impl YellowstoneGrpc {
 
         // 启动流处理任务
         let backpressure_strategy = self.config.backpressure.strategy;
-        tokio::spawn(async move {
+        let stream_handle = tokio::spawn(async move {
             while let Some(message) = stream.next().await {
                 match message {
                     Ok(msg) => {
@@ -192,7 +205,7 @@ impl YellowstoneGrpc {
 
         // 即时处理交易，无批处理
         let event_processor = self.event_processor.clone();
-        tokio::spawn(async move {
+        let event_handle = tokio::spawn(async move {
             while let Some(event_pretty) = rx.next().await {
                 if let Err(e) = event_processor
                     .process_event_transaction_with_metrics(
@@ -209,7 +222,12 @@ impl YellowstoneGrpc {
             }
         });
 
-        tokio::signal::ctrl_c().await?;
+        // 保存订阅句柄
+        let subscription_handle =
+            SubscriptionHandle::new(stream_handle, event_handle, metrics_handle);
+        let mut handle_guard = self.subscription_handle.lock().await;
+        *handle_guard = Some(subscription_handle);
+
         Ok(())
     }
 
@@ -245,9 +263,13 @@ impl YellowstoneGrpc {
     where
         F: Fn(Box<dyn UnifiedEvent>) + Send + Sync + 'static,
     {
+        // 如果已有活跃订阅，先停止它
+        self.stop().await;
+
+        let mut metrics_handle = None;
         // 启动自动性能监控（如果启用）
         if self.config.enable_metrics {
-            self.metrics_manager.start_auto_monitoring().await;
+            metrics_handle = self.metrics_manager.start_auto_monitoring().await;
         }
 
         let transactions = self.subscription_manager.get_subscribe_request_filter(
@@ -286,7 +308,7 @@ impl YellowstoneGrpc {
 
         // Start task to process the stream
         let backpressure_strategy = self.config.backpressure.strategy;
-        tokio::spawn(async move {
+        let stream_handle = tokio::spawn(async move {
             while let Some(message) = stream.next().await {
                 match message {
                     Ok(msg) => {
@@ -312,7 +334,7 @@ impl YellowstoneGrpc {
 
         // Process transactions with batch processing
         let event_processor = self.event_processor.clone();
-        tokio::spawn(async move {
+        let event_handle = tokio::spawn(async move {
             while let Some(event_pretty) = rx.next().await {
                 if let Err(e) = event_processor
                     .process_event_transaction_with_batch(
@@ -332,11 +354,32 @@ impl YellowstoneGrpc {
             batch_processor.flush();
         });
 
-        tokio::signal::ctrl_c().await?;
+        // 保存订阅句柄
+        let subscription_handle =
+            SubscriptionHandle::new(stream_handle, event_handle, metrics_handle);
+        let mut handle_guard = self.subscription_handle.lock().await;
+        *handle_guard = Some(subscription_handle);
+
         Ok(())
     }
 }
 
+// 实现 Clone trait 以支持模块间共享
+impl Clone for YellowstoneGrpc {
+    fn clone(&self) -> Self {
+        Self {
+            endpoint: self.endpoint.clone(),
+            x_token: self.x_token.clone(),
+            config: self.config.clone(),
+            metrics: self.metrics.clone(),
+            subscription_manager: self.subscription_manager.clone(),
+            metrics_manager: self.metrics_manager.clone(),
+            event_processor: self.event_processor.clone(),
+            subscription_handle: self.subscription_handle.clone(), // 共享同一个 Arc<Mutex<>>
+        }
+    }
+}
+
 // 实现 Clone trait 以支持模块间共享
 impl Clone for EventProcessor {
     fn clone(&self) -> Self {