timber_rust/service/
service.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 Dante Doménech Martinez dante19031999@gmail.com
3
4use crate::service::ServiceError;
5use crate::service::fallback::Fallback;
6use crate::{LoggerStatus, Message};
7use std::any::Any;
8
9/// The [`Service`] trait defines the core execution logic for a logging backend.
10///
11/// A [`Service`] acts as the internal "Worker" or "Driver" sitting behind a [`LoggerImpl`][`crate::LoggerImpl`].
12/// While the logger handles the frontend API and message queuing, the [`Service`] is responsible
13/// for the actual side effects, such as disk I/O, network transmission, or database insertion.
14///
15/// ### Hierarchy & Resilience
16/// This trait extends [`Fallback`]. Every implementation must provide a mechanism to handle
17/// messages that fail to be processed after the service's internal retry logic has been exhausted.
18///
19/// ### Threading Model
20/// Implementations are typically executed within a dedicated background thread. Therefore,
21/// any state held by a [`Service`] must be thread-safe (`Send + Sync`) to ensure
22/// consistent behavior across the asynchronous boundary.
23///
24///
25pub trait Service: Fallback {
26    /// Returns the current operational `[LoggerStatus`] of the service.
27    fn status(&self) -> LoggerStatus;
28
29    /// Processes a single [Message].
30    ///
31    /// # Arguments
32    /// * `msg` - A reference to the [Message] to be processed.
33    ///
34    /// # Returns
35    /// * [`Ok(())`][`Ok`] if the message was handled successfully.
36    /// * [`Err(ServiceError)`][`ServiceError`] if an error occurred.
37    ///
38    /// # Concurrency & Thread Safety
39    /// This method takes `&self`, meaning it can be called concurrently from
40    /// multiple threads if the [`LoggerImpl`][`crate::LoggerImpl`] allows it.
41    ///
42    /// > [!NOTE]
43    /// > If the implementation requires modification of internal state (e.g.,
44    /// > incrementing a counter or writing to a shared file), it must use
45    /// > **Interior Mutability** (e.g., [`AtomicU64`][`std::sync::atomic::AtomicU64`], [`Mutex`][`std::sync::Mutex`], or [`mpsc`][`std::sync::mpsc::channel()`]).
46    fn work(&self, msg: &Message) -> Result<(), ServiceError>;
47
48    /// Returns a reference to the underlying type as [Any] for downcasting.
49    fn as_any(&self) -> &dyn Any;
50}
timber_rust/service/service.rs

timber_rust/service/
service.rs
