1use super::events_count_read_budget::CountReadBudget;
2use super::paths::{
3 DEFAULT_APPEND_QUEUE_BATCHES, DEFAULT_APPEND_QUEUE_BYTES, EVENTS_PROTOCOL_VERSION,
4 FORWARDER_BACKOFF, REQUEST_TIMEOUT,
5};
6use super::protocol::{EventsRequest, EventsResponse};
7use super::socket_path::validate_events_socket_path;
8use crate::daemon::{read_frame, write_frame};
9use khive_db::StorageBackend;
10use khive_storage::{Event, EventStore, StorageError, StorageResult};
11use serde::Serialize;
12use std::path::{Path, PathBuf};
13use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
14use std::sync::Arc;
15use std::time::Duration;
16use tokio::net::UnixStream;
17
18#[cfg(unix)]
25pub(super) async fn connect_verified(socket_path: &Path) -> std::io::Result<UnixStream> {
26 let stream = UnixStream::connect(socket_path).await?;
27 let own_euid = unsafe { libc::geteuid() } as u32;
29 let peer = crate::daemon::peer_uid(&stream)?;
30 if !crate::daemon::uid_is_permitted(peer, own_euid) {
31 return Err(std::io::Error::new(
32 std::io::ErrorKind::PermissionDenied,
33 format!(
34 "events socket {} answered by uid {peer}, not this process's uid {own_euid}; \
35 refusing to exchange event frames with an unowned daemon",
36 socket_path.display()
37 ),
38 ));
39 }
40 Ok(stream)
41}
42
43#[cfg(unix)]
47#[derive(Debug, Clone, Copy, Serialize)]
48pub struct EventsForwardingMetrics {
49 pub forwarded_batches: u64,
50 pub forwarded_events: u64,
51 pub dropped_batches: u64,
52 pub dropped_events: u64,
53 pub queued_bytes: usize,
55}
56
57#[cfg(unix)]
58#[derive(Debug, Default)]
59pub(super) struct ForwardingCounters {
60 pub(super) forwarded_batches: AtomicU64,
61 pub(super) forwarded_events: AtomicU64,
62 pub(super) dropped_batches: AtomicU64,
63 pub(super) dropped_events: AtomicU64,
64 pub(super) queued_bytes: AtomicUsize,
65}
66
67#[cfg(unix)]
70#[derive(Debug)]
71pub(super) struct AppendByteReservation {
72 pub(super) counters: Arc<ForwardingCounters>,
73 pub(super) bytes: usize,
74}
75
76#[cfg(unix)]
77impl Drop for AppendByteReservation {
78 fn drop(&mut self) {
79 self.counters
80 .queued_bytes
81 .fetch_sub(self.bytes, Ordering::AcqRel);
82 }
83}
84
85#[cfg(unix)]
86#[derive(Debug)]
87pub(super) struct QueuedAppend {
88 pub(super) request: EventsRequest,
89 pub(super) count: u64,
90 pub(super) _reservation: AppendByteReservation,
91}
92
93#[cfg(all(test, unix))]
94impl QueuedAppend {
95 pub(super) fn unmetered(
96 namespace: &str,
97 events: Vec<Event>,
98 counters: Arc<ForwardingCounters>,
99 ) -> Self {
100 let count = events.len() as u64;
101 Self {
102 request: EventsRequest::AppendEvents {
103 protocol_version: EVENTS_PROTOCOL_VERSION,
104 namespace: namespace.to_string(),
105 events,
106 },
107 count,
108 _reservation: AppendByteReservation { counters, bytes: 0 },
109 }
110 }
111}
112
113#[cfg(unix)]
116#[derive(Default)]
117pub(super) struct BoundedFrameCounter {
118 pub(super) bytes: usize,
119 pub(super) exceeded: bool,
120}
121
122#[cfg(unix)]
123impl std::io::Write for BoundedFrameCounter {
124 fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
125 let next = self.bytes.saturating_add(buf.len());
126 if next > crate::daemon::MAX_FRAME_BYTES {
127 self.exceeded = true;
128 return Err(std::io::Error::new(
129 std::io::ErrorKind::InvalidData,
130 "events append request exceeds IPC frame cap",
131 ));
132 }
133 self.bytes = next;
134 Ok(buf.len())
135 }
136
137 fn flush(&mut self) -> std::io::Result<()> {
138 Ok(())
139 }
140}
141
142#[cfg(unix)]
143pub(super) fn reserve_append_bytes(
144 counters: &Arc<ForwardingCounters>,
145 bytes: usize,
146 budget: usize,
147) -> Option<AppendByteReservation> {
148 let mut used = counters.queued_bytes.load(Ordering::Acquire);
149 loop {
150 let next = used.checked_add(bytes)?;
151 if next > budget {
152 return None;
153 }
154 match counters.queued_bytes.compare_exchange_weak(
155 used,
156 next,
157 Ordering::AcqRel,
158 Ordering::Acquire,
159 ) {
160 Ok(_) => {
161 return Some(AppendByteReservation {
162 counters: Arc::clone(counters),
163 bytes,
164 });
165 }
166 Err(observed) => used = observed,
167 }
168 }
169}
170
171#[cfg(unix)]
179pub struct EventsSplitClient {
180 pub(super) socket_path: PathBuf,
181 pub(super) append_tx: tokio::sync::mpsc::Sender<QueuedAppend>,
182 pub(super) append_queue_byte_budget: usize,
183 pub(super) counters: Arc<ForwardingCounters>,
184 pub(super) outage_logged: Arc<AtomicBool>,
187 pub(super) preflight_store: Arc<dyn EventStore>,
189}
190
191#[cfg(unix)]
192impl std::fmt::Debug for EventsSplitClient {
193 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
194 f.debug_struct("EventsSplitClient")
195 .field("socket_path", &self.socket_path)
196 .finish_non_exhaustive()
197 }
198}
199
200#[cfg(unix)]
201impl EventsSplitClient {
202 pub fn new(socket_path: PathBuf) -> crate::error::RuntimeResult<Arc<Self>> {
204 Self::new_with_queue_depth(socket_path, DEFAULT_APPEND_QUEUE_BATCHES)
205 }
206
207 pub fn new_with_queue_depth(
210 socket_path: PathBuf,
211 queue_depth: usize,
212 ) -> crate::error::RuntimeResult<Arc<Self>> {
213 Self::new_with_queue_depth_and_delivery_timeout(socket_path, queue_depth, REQUEST_TIMEOUT)
214 }
215
216 pub(super) fn new_with_queue_depth_and_delivery_timeout(
220 socket_path: PathBuf,
221 queue_depth: usize,
222 delivery_timeout: Duration,
223 ) -> crate::error::RuntimeResult<Arc<Self>> {
224 Self::new_with_limits_and_delivery_timeout(
225 socket_path,
226 queue_depth,
227 DEFAULT_APPEND_QUEUE_BYTES,
228 delivery_timeout,
229 )
230 }
231
232 pub(super) fn new_with_limits_and_delivery_timeout(
233 socket_path: PathBuf,
234 queue_depth: usize,
235 byte_budget: usize,
236 delivery_timeout: Duration,
237 ) -> crate::error::RuntimeResult<Arc<Self>> {
238 validate_events_socket_path(&socket_path)?;
239 let preflight_backend = StorageBackend::memory()?;
240 let preflight_store = preflight_backend.events()?;
241 let (append_tx, append_rx) = tokio::sync::mpsc::channel::<QueuedAppend>(queue_depth.max(1));
245 let counters = Arc::new(ForwardingCounters::default());
246 let outage_logged = Arc::new(AtomicBool::new(false));
247
248 let client = Arc::new(Self {
249 socket_path: socket_path.clone(),
250 append_tx,
251 append_queue_byte_budget: byte_budget,
252 counters: Arc::clone(&counters),
253 outage_logged: Arc::clone(&outage_logged),
254 preflight_store,
255 });
256
257 crate::daemon::spawn_named_tracked_task(
258 "events_forwarder",
259 run_forwarder(
260 socket_path,
261 append_rx,
262 counters,
263 outage_logged,
264 delivery_timeout,
265 crate::daemon::daemon_shutdown_token(),
266 ),
267 );
268 Ok(client)
269 }
270
271 pub fn metrics(&self) -> EventsForwardingMetrics {
273 EventsForwardingMetrics {
274 forwarded_batches: self.counters.forwarded_batches.load(Ordering::Relaxed),
275 forwarded_events: self.counters.forwarded_events.load(Ordering::Relaxed),
276 dropped_batches: self.counters.dropped_batches.load(Ordering::Relaxed),
277 dropped_events: self.counters.dropped_events.load(Ordering::Relaxed),
278 queued_bytes: self.counters.queued_bytes.load(Ordering::Acquire),
279 }
280 }
281
282 pub(super) fn enqueue(&self, namespace: &str, events: Vec<Event>) {
285 let count = events.len() as u64;
286 let request = EventsRequest::AppendEvents {
287 protocol_version: EVENTS_PROTOCOL_VERSION,
288 namespace: namespace.to_string(),
289 events,
290 };
291 let mut frame_size = BoundedFrameCounter::default();
292 if let Err(error) = serde_json::to_writer(&mut frame_size, &request) {
293 self.count_append_drop(
294 count,
295 if frame_size.exceeded {
296 "frame cap"
297 } else {
298 "serialization"
299 },
300 );
301 tracing::warn!(error = %error, "events append batch could not fit a wire frame");
302 return;
303 }
304 let Some(reservation) = reserve_append_bytes(
305 &self.counters,
306 frame_size.bytes,
307 self.append_queue_byte_budget,
308 ) else {
309 self.count_append_drop(count, "queue byte budget");
310 return;
311 };
312 let batch = QueuedAppend {
313 request,
314 count,
315 _reservation: reservation,
316 };
317 match self.append_tx.try_send(batch) {
318 Ok(()) => {}
319 Err(_) => {
320 self.count_append_drop(count, "queue batch limit");
322 }
323 }
324 }
325
326 pub(super) fn count_append_drop(&self, count: u64, reason: &'static str) {
327 self.counters
328 .dropped_batches
329 .fetch_add(1, Ordering::Relaxed);
330 self.counters
331 .dropped_events
332 .fetch_add(count, Ordering::Relaxed);
333 if !self.outage_logged.swap(true, Ordering::Relaxed) {
334 tracing::warn!(
335 dropped_events = count,
336 reason,
337 "events append queue rejected loss-tolerant batch"
338 );
339 }
340 }
341
342 pub(super) async fn round_trip(
347 &self,
348 request: &EventsRequest,
349 ) -> StorageResult<EventsResponse> {
350 let op = "events daemon round-trip";
351 let payload = serialize_events_request(request)?;
352 let attempt = events_round_trip_attempt(&self.socket_path, &payload);
353 let bytes = match tokio::time::timeout(REQUEST_TIMEOUT, attempt).await {
354 Ok(Ok(bytes)) => bytes,
355 Ok(Err(("read", error))) => {
356 return Err(StorageError::Serialization {
357 capability: khive_storage::StorageCapability::Events,
358 message: format!(
359 "events daemon closed or broke the response after connection at {}: {error}",
360 self.socket_path.display()
361 ),
362 });
363 }
364 Ok(Err((stage, error))) => {
365 return Err(StorageError::Pool {
366 operation: op.into(),
367 message: format!(
368 "events daemon {stage} failed at {}: {error}",
369 self.socket_path.display()
370 ),
371 });
372 }
373 Err(_elapsed) => {
374 return Err(StorageError::Timeout {
375 operation: op.into(),
376 });
377 }
378 };
379
380 deserialize_events_response(&bytes)
381 }
382
383 pub(super) async fn round_trip_count(
384 &self,
385 request: &EventsRequest,
386 budget: &CountReadBudget,
387 ) -> StorageResult<EventsResponse> {
388 budget
389 .scope(self.round_trip_read(request, budget, "events daemon count round-trip"))
390 .await
391 }
392
393 pub(super) async fn round_trip_query(
394 &self,
395 request: &EventsRequest,
396 budget: &CountReadBudget,
397 ) -> StorageResult<EventsResponse> {
398 budget
399 .scope_operation(
400 "query_events",
401 self.round_trip_read(request, budget, "events daemon query_events round-trip"),
402 )
403 .await
404 }
405
406 async fn round_trip_read(
407 &self,
408 request: &EventsRequest,
409 budget: &CountReadBudget,
410 operation: &'static str,
411 ) -> StorageResult<EventsResponse> {
412 let payload = serialize_events_request(request)?;
413 let attempt = events_round_trip_attempt(&self.socket_path, &payload);
414 let result = khive_storage::await_request_read_phase(operation, attempt)
415 .await
416 .map_err(|error| budget.attribute(error))?;
417 let bytes = match result {
418 Ok(bytes) => bytes,
419 Err(("read", error)) => {
420 return Err(StorageError::Serialization {
421 capability: khive_storage::StorageCapability::Events,
422 message: format!(
423 "events daemon closed or broke the response after connection at {}: {error}",
424 self.socket_path.display()
425 ),
426 })
427 }
428 Err((stage, error)) => {
429 return Err(StorageError::Pool {
430 operation: operation.into(),
431 message: format!(
432 "events daemon {stage} failed at {}: {error}",
433 self.socket_path.display()
434 ),
435 })
436 }
437 };
438 deserialize_events_response(&bytes)
439 }
440}
441
442#[cfg(unix)]
443pub(super) fn serialize_events_request(request: &EventsRequest) -> StorageResult<Vec<u8>> {
444 serde_json::to_vec(request).map_err(|error| StorageError::Serialization {
445 capability: khive_storage::StorageCapability::Events,
446 message: format!("events request serialization failed: {error}"),
447 })
448}
449
450#[cfg(unix)]
451pub(super) fn deserialize_events_response(bytes: &[u8]) -> StorageResult<EventsResponse> {
452 serde_json::from_slice(bytes).map_err(|error| StorageError::Serialization {
453 capability: khive_storage::StorageCapability::Events,
454 message: format!("events response deserialization failed: {error}"),
455 })
456}
457
458#[cfg(unix)]
459pub(super) async fn events_round_trip_attempt(
460 socket_path: &Path,
461 payload: &[u8],
462) -> Result<Vec<u8>, (&'static str, std::io::Error)> {
463 let mut stream = connect_verified(socket_path)
464 .await
465 .map_err(|error| ("connect", error))?;
466 write_frame(&mut stream, payload)
467 .await
468 .map_err(|error| ("write", error))?;
469 read_frame(&mut stream)
470 .await
471 .map_err(|error| ("read", error))
472}
473
474#[cfg(unix)]
481pub(super) fn drain_dropped_queue(
482 rx: &mut tokio::sync::mpsc::Receiver<QueuedAppend>,
483 counters: &ForwardingCounters,
484) {
485 let mut dropped_batches = 0u64;
486 let mut dropped_events = 0u64;
487 while let Ok(batch) = rx.try_recv() {
488 dropped_batches += 1;
489 dropped_events += batch.count;
490 }
492 if dropped_batches > 0 {
493 counters
494 .dropped_batches
495 .fetch_add(dropped_batches, Ordering::Relaxed);
496 counters
497 .dropped_events
498 .fetch_add(dropped_events, Ordering::Relaxed);
499 tracing::warn!(
500 dropped_batches,
501 dropped_events,
502 "events forwarder shutting down; dropping queued loss-tolerant batches"
503 );
504 }
505}
506
507#[cfg(unix)]
512pub(super) async fn run_forwarder(
513 socket_path: PathBuf,
514 mut rx: tokio::sync::mpsc::Receiver<QueuedAppend>,
515 counters: Arc<ForwardingCounters>,
516 outage_logged: Arc<AtomicBool>,
517 delivery_timeout: Duration,
518 shutdown: tokio_util::sync::CancellationToken,
519) {
520 let mut conn: Option<UnixStream> = None;
528 loop {
529 let batch = tokio::select! {
530 _ = shutdown.cancelled() => {
531 drain_dropped_queue(&mut rx, &counters);
532 break;
533 },
534 received = rx.recv() => match received {
535 Some(batch) => batch,
536 None => break,
537 },
538 };
539 let count = batch.count;
540 let payload = match serde_json::to_vec(&batch.request) {
541 Ok(payload) => payload,
542 Err(error) => {
543 counters.dropped_batches.fetch_add(1, Ordering::Relaxed);
544 counters.dropped_events.fetch_add(count, Ordering::Relaxed);
545 tracing::error!(error = %error, "events forwarder serialization failed; batch dropped");
546 continue;
547 }
548 };
549
550 let delivered = tokio::select! {
558 _ = shutdown.cancelled() => {
559 counters.dropped_batches.fetch_add(1, Ordering::Relaxed);
560 counters.dropped_events.fetch_add(count, Ordering::Relaxed);
561 tracing::warn!(
562 dropped_events = count,
563 "events forwarder shutting down mid-delivery; in-flight batch dropped"
564 );
565 drain_dropped_queue(&mut rx, &counters);
566 break;
567 },
568 outcome = tokio::time::timeout(
569 delivery_timeout,
570 deliver_batch(&socket_path, &mut conn, &payload),
571 ) => match outcome {
572 Ok(delivered) => delivered,
573 Err(_elapsed) => {
574 conn = None;
575 false
576 }
577 },
578 };
579 if delivered {
580 counters.forwarded_batches.fetch_add(1, Ordering::Relaxed);
581 counters
582 .forwarded_events
583 .fetch_add(count, Ordering::Relaxed);
584 if outage_logged.swap(false, Ordering::Relaxed) {
585 tracing::info!("events daemon reachable again; forwarding resumed");
586 }
587 } else {
588 counters.dropped_batches.fetch_add(1, Ordering::Relaxed);
589 counters.dropped_events.fetch_add(count, Ordering::Relaxed);
590 if !outage_logged.swap(true, Ordering::Relaxed) {
591 tracing::warn!(
592 socket = %socket_path.display(),
593 "events daemon unreachable; dropping loss-tolerant events until it returns"
594 );
595 }
596 tokio::select! {
597 _ = shutdown.cancelled() => {
598 drain_dropped_queue(&mut rx, &counters);
599 break;
600 },
601 _ = tokio::time::sleep(FORWARDER_BACKOFF) => {}
602 }
603 }
604 }
605}
606
607#[cfg(unix)]
612pub(super) async fn deliver_batch(
613 socket_path: &Path,
614 conn: &mut Option<UnixStream>,
615 payload: &[u8],
616) -> bool {
617 for _attempt in 0..2u8 {
618 if conn.is_none() {
619 match connect_verified(socket_path).await {
620 Ok(stream) => *conn = Some(stream),
621 Err(_) => return false,
622 }
623 }
624 let stream = conn.as_mut().expect("connection populated above");
625 let ok = async {
626 write_frame(stream, payload).await?;
627 let bytes = read_frame(stream).await?;
628 std::io::Result::Ok(bytes)
629 }
630 .await;
631 match ok {
632 Ok(bytes) => {
633 return !matches!(
634 serde_json::from_slice::<EventsResponse>(&bytes),
635 Ok(EventsResponse::Error { .. }) | Err(_)
636 );
637 }
638 Err(_) => {
639 *conn = None;
642 }
643 }
644 }
645 false
646}