feat: add an opt-in NATS JetStream publish path for the notify and audit targets (#4634)

feat(targets): add an opt-in NATS JetStream publish path for the notify and audit targets

The NATS notify and audit targets publish through NATS Core, which returns
before the server has durably accepted the message. A broker restart or a
connection drop between the publish and the flush loses the event, even though
the send queue has already cleared it, and no acknowledgement gates that clear.

An opt-in JetStream publish path clears a queued event only after the server
returns a durable PublishAck, so delivery is at-least-once across a broker
restart or a reconnect. It applies to both the notify and audit NATS targets, is
off by default, and is byte-identical to the NATS Core path when disabled.

The path includes durable store-and-forward, a stable dedup id sent as the
Nats-Msg-Id header so a replayed event is collapsed by the stream duplicate
window, pre-flight stream validation, and a bounded failed-events store for
terminally-failed and retry-exhausted events. Three configuration keys per
target select it: JETSTREAM_ENABLE, JETSTREAM_STREAM_NAME, and
JETSTREAM_ACK_TIMEOUT_SECS, under the RUSTFS_NOTIFY_NATS_ and RUSTFS_AUDIT_NATS_
prefixes.

The on-disk batch filename separator changes from colon to underscore so
batch names are valid on Windows filesystems, with transparent read-back
of files written under the previous separator. The migration affects the
shared queue store for every target type and lands with this feature
because the store gains its first Windows-exercised paths here.

Co-authored-by: houseme <housemecn@gmail.com>

crates/obs/src/metrics/collectors/audit.rs

@@ -33,6 +33,8 @@ pub struct AuditTargetStats {
     pub target_id: String,
     /// Number of messages that failed to send
     pub failed_messages: u64,
+    /// Number of messages held in the failed-events store
+    pub failed_store_length: u64,
     /// Number of unsent messages in queue
     pub queue_length: u64,
     /// Total number of messages sent
@@ -48,7 +50,7 @@ pub fn collect_audit_metrics(stats: &[AuditTargetStats]) -> Vec<PrometheusMetric
         return Vec::new();
     }
 
-    let mut metrics = Vec::with_capacity(stats.len() * 3);
+    let mut metrics = Vec::with_capacity(stats.len() * 4);
     for stat in stats {
         let target_id_label: Cow<'static, str> = Cow::Owned(stat.target_id.clone());
 
@@ -56,6 +58,10 @@ pub fn collect_audit_metrics(stats: &[AuditTargetStats]) -> Vec<PrometheusMetric
             PrometheusMetric::from_descriptor(&AUDIT_FAILED_MESSAGES_MD, stat.failed_messages as f64)
                 .with_label("target_id", target_id_label.clone()),
         );
+        metrics.push(
+            PrometheusMetric::from_descriptor(&AUDIT_FAILED_STORE_LENGTH_MD, stat.failed_store_length as f64)
+                .with_label("target_id", target_id_label.clone()),
+        );
         metrics.push(
             PrometheusMetric::from_descriptor(&AUDIT_TARGET_QUEUE_LENGTH_MD, stat.queue_length as f64)
                 .with_label("target_id", target_id_label.clone()),
@@ -80,12 +86,14 @@ mod tests {
             AuditTargetStats {
                 target_id: "target-1".to_string(),
                 failed_messages: 5,
+                failed_store_length: 3,
                 queue_length: 10,
                 total_messages: 1000,
             },
             AuditTargetStats {
                 target_id: "target-2".to_string(),
                 failed_messages: 2,
+                failed_store_length: 1,
                 queue_length: 5,
                 total_messages: 500,
             },
@@ -93,12 +101,19 @@ mod tests {
 
         let metrics = collect_audit_metrics(&stats);
 
-        assert_eq!(metrics.len(), 6); // 2 targets * 3 metrics each
+        assert_eq!(metrics.len(), 8); // 2 targets * 4 metrics each
 
         let failed = metrics
             .iter()
             .find(|m| m.value == 5.0 && m.labels.iter().any(|(k, v)| *k == "target_id" && v == "target-1"));
         assert!(failed.is_some());
+
+        let failed_store = metrics.iter().find(|m| {
+            m.value == 3.0
+                && m.name == AUDIT_FAILED_STORE_LENGTH_MD.get_full_metric_name()
+                && m.labels.iter().any(|(k, v)| *k == "target_id" && v == "target-1")
+        });
+        assert!(failed_store.is_some());
     }
 
     #[test]
@@ -111,6 +126,7 @@ mod tests {
     #[test]
     fn audit_target_totals_are_exported_as_gauges() {
         assert_eq!(AUDIT_FAILED_MESSAGES_MD.metric_type, MetricType::Gauge);
+        assert_eq!(AUDIT_FAILED_STORE_LENGTH_MD.metric_type, MetricType::Gauge);
         assert_eq!(AUDIT_TARGET_QUEUE_LENGTH_MD.metric_type, MetricType::Gauge);
         assert_eq!(AUDIT_TOTAL_MESSAGES_MD.metric_type, MetricType::Gauge);
     }

crates/obs/src/metrics/collectors/notification_target.rs

@@ -16,14 +16,15 @@
 
 use crate::metrics::report::PrometheusMetric;
 use crate::metrics::schema::notification_target::{
-    NOTIFICATION_TARGET_FAILED_MESSAGES_MD, NOTIFICATION_TARGET_QUEUE_LENGTH_MD, NOTIFICATION_TARGET_TOTAL_MESSAGES_MD,
-    TARGET_ID, TARGET_TYPE,
+    NOTIFICATION_TARGET_FAILED_MESSAGES_MD, NOTIFICATION_TARGET_FAILED_STORE_LENGTH_MD, NOTIFICATION_TARGET_QUEUE_LENGTH_MD,
+    NOTIFICATION_TARGET_TOTAL_MESSAGES_MD, TARGET_ID, TARGET_TYPE,
 };
 use std::borrow::Cow;
 
 #[derive(Debug, Clone, Default)]
 pub struct NotificationTargetStats {
     pub failed_messages: u64,
+    pub failed_store_length: u64,
     pub queue_length: u64,
     pub target_id: String,
     pub target_type: String,
@@ -35,7 +36,7 @@ pub fn collect_notification_target_metrics(stats: &[NotificationTargetStats]) ->
         return Vec::new();
     }
 
-    let mut metrics = Vec::with_capacity(stats.len() * 3);
+    let mut metrics = Vec::with_capacity(stats.len() * 4);
     for stat in stats {
         let target_id: Cow<'static, str> = Cow::Owned(stat.target_id.clone());
         let target_type: Cow<'static, str> = Cow::Owned(stat.target_type.clone());
@@ -45,6 +46,11 @@ pub fn collect_notification_target_metrics(stats: &[NotificationTargetStats]) ->
                 .with_label(TARGET_ID, target_id.clone())
                 .with_label(TARGET_TYPE, target_type.clone()),
         );
+        metrics.push(
+            PrometheusMetric::from_descriptor(&NOTIFICATION_TARGET_FAILED_STORE_LENGTH_MD, stat.failed_store_length as f64)
+                .with_label(TARGET_ID, target_id.clone())
+                .with_label(TARGET_TYPE, target_type.clone()),
+        );
         metrics.push(
             PrometheusMetric::from_descriptor(&NOTIFICATION_TARGET_QUEUE_LENGTH_MD, stat.queue_length as f64)
                 .with_label(TARGET_ID, target_id.clone())
@@ -69,6 +75,7 @@ mod tests {
     fn test_collect_notification_target_metrics() {
         let stats = vec![NotificationTargetStats {
             failed_messages: 2,
+            failed_store_length: 3,
             queue_length: 4,
             target_id: "primary:webhook".to_string(),
             target_type: "webhook".to_string(),
@@ -77,7 +84,15 @@ mod tests {
 
         let metrics = collect_notification_target_metrics(&stats);
 
-        assert_eq!(metrics.len(), 3);
+        assert_eq!(metrics.len(), 4);
+        assert!(metrics.iter().any(|metric| {
+            metric.value == 3.0
+                && metric.name == NOTIFICATION_TARGET_FAILED_STORE_LENGTH_MD.get_full_metric_name()
+                && metric
+                    .labels
+                    .iter()
+                    .any(|(key, value)| *key == TARGET_ID && value == "primary:webhook")
+        }));
         assert!(metrics.iter().any(|metric| {
             metric.value == 42.0
                 && metric
@@ -94,6 +109,7 @@ mod tests {
     #[test]
     fn notification_target_totals_are_exported_as_gauges() {
         assert_eq!(NOTIFICATION_TARGET_FAILED_MESSAGES_MD.metric_type, MetricType::Gauge);
+        assert_eq!(NOTIFICATION_TARGET_FAILED_STORE_LENGTH_MD.metric_type, MetricType::Gauge);
         assert_eq!(NOTIFICATION_TARGET_QUEUE_LENGTH_MD.metric_type, MetricType::Gauge);
         assert_eq!(NOTIFICATION_TARGET_TOTAL_MESSAGES_MD.metric_type, MetricType::Gauge);
     }

crates/obs/src/metrics/scheduler.rs

@@ -1222,6 +1222,7 @@ pub fn init_metrics_runtime(token: CancellationToken) {
                             .into_iter()
                             .map(|snapshot| AuditTargetStats {
                                 failed_messages: snapshot.failed_messages,
+                                failed_store_length: snapshot.failed_store_length,
                                 queue_length: snapshot.queue_length,
                                 target_id: snapshot.target_id,
                                 total_messages: snapshot.total_messages,
@@ -1274,6 +1275,7 @@ pub fn init_metrics_runtime(token: CancellationToken) {
                             .into_iter()
                             .map(|snapshot| NotificationTargetStats {
                                 failed_messages: snapshot.failed_messages,
+                                failed_store_length: snapshot.failed_store_length,
                                 queue_length: snapshot.queue_length,
                                 target_id: snapshot.target_id,
                                 target_type: snapshot.target_type,

crates/obs/src/metrics/schema/audit.rs

@@ -33,6 +33,15 @@ pub static AUDIT_FAILED_MESSAGES_MD: LazyLock<MetricDescriptor> = LazyLock::new(
     )
 });
 
+pub static AUDIT_FAILED_STORE_LENGTH_MD: LazyLock<MetricDescriptor> = LazyLock::new(|| {
+    new_gauge_md(
+        MetricName::AuditFailedStoreLength,
+        "Number of audit messages held in the failed-events store for target",
+        &[TARGET_ID],
+        subsystems::AUDIT,
+    )
+});
+
 pub static AUDIT_TARGET_QUEUE_LENGTH_MD: LazyLock<MetricDescriptor> = LazyLock::new(|| {
     new_gauge_md(
         MetricName::AuditTargetQueueLength,

crates/obs/src/metrics/schema/entry/metric_name.rs

@@ -175,6 +175,7 @@ pub enum MetricName {
 
     // Audit metrics
     AuditFailedMessages,
+    AuditFailedStoreLength,
     AuditTargetQueueLength,
     AuditTotalMessages,
 
@@ -221,6 +222,7 @@ pub enum MetricName {
     NotificationEventsSentTotal,
     NotificationEventsSkippedTotal,
     NotificationTargetFailedMessages,
+    NotificationTargetFailedStoreLength,
     NotificationTargetQueueLength,
     NotificationTargetTotalMessages,
 
@@ -581,6 +583,7 @@ impl MetricName {
             Self::ApiTrafficRecvBytes => "traffic_received_bytes".to_string(),
 
             Self::AuditFailedMessages => "failed_messages".to_string(),
+            Self::AuditFailedStoreLength => "failed_store_length".to_string(),
             Self::AuditTargetQueueLength => "target_queue_length".to_string(),
             Self::AuditTotalMessages => "total_messages".to_string(),
 
@@ -627,6 +630,7 @@ impl MetricName {
             Self::NotificationEventsSentTotal => "events_sent_total".to_string(),
             Self::NotificationEventsSkippedTotal => "events_skipped_total".to_string(),
             Self::NotificationTargetFailedMessages => "failed_messages".to_string(),
+            Self::NotificationTargetFailedStoreLength => "failed_store_length".to_string(),
             Self::NotificationTargetQueueLength => "target_queue_length".to_string(),
             Self::NotificationTargetTotalMessages => "total_messages".to_string(),
 

crates/obs/src/metrics/schema/notification_target.rs

@@ -31,6 +31,15 @@ pub static NOTIFICATION_TARGET_FAILED_MESSAGES_MD: LazyLock<MetricDescriptor> =
     )
 });
 
+pub static NOTIFICATION_TARGET_FAILED_STORE_LENGTH_MD: LazyLock<MetricDescriptor> = LazyLock::new(|| {
+    new_gauge_md(
+        MetricName::NotificationTargetFailedStoreLength,
+        "Number of notification messages held in the failed-events store for target",
+        &NOTIFICATION_TARGET_LABELS,
+        subsystems::NOTIFICATION,
+    )
+});
+
 pub static NOTIFICATION_TARGET_QUEUE_LENGTH_MD: LazyLock<MetricDescriptor> = LazyLock::new(|| {
     new_gauge_md(
         MetricName::NotificationTargetQueueLength,