Skip to main content

rustduck_core/
report.rs

1use std::panic::{AssertUnwindSafe, catch_unwind};
2use std::rc::Rc;
3use std::sync::{Arc, Mutex, OnceLock};
4
5use rustduck_sys::bridge::{self as sys_bridge, ffi};
6
7use crate::buffer::{decode_utf16, encode_utf16};
8use crate::error::native_exception;
9use crate::{Error, Result};
10
11/// TSDuck report severity.
12#[repr(i32)]
13#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
14#[non_exhaustive]
15pub enum Severity {
16    /// Fatal error.
17    Fatal = -5,
18    /// Severe error.
19    Severe = -4,
20    /// Error.
21    Error = -3,
22    /// Warning.
23    Warning = -2,
24    /// Informational message.
25    Info = -1,
26    /// Verbose message.
27    Verbose = 0,
28    /// Debug message.
29    Debug = 1,
30}
31
32impl Severity {
33    const fn abi_value(self) -> i32 {
34        self as i32
35    }
36
37    fn from_i32(value: i32) -> Option<Self> {
38        match value {
39            -5 => Some(Self::Fatal),
40            -4 => Some(Self::Severe),
41            -3 => Some(Self::Error),
42            -2 => Some(Self::Warning),
43            -1 => Some(Self::Info),
44            0 => Some(Self::Verbose),
45            1 => Some(Self::Debug),
46            _ => None,
47        }
48    }
49}
50
51/// Configuration for an asynchronous TSDuck report.
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub struct AsyncReportConfig {
54    /// Maximum accepted severity.
55    pub severity: Severity,
56    /// Serialize producer calls into the report queue.
57    pub synchronous_log: bool,
58    /// Prefix messages with time information when supported by TSDuck.
59    pub timed_log: bool,
60    /// Maximum queued message count.
61    pub log_message_count: usize,
62}
63
64impl Default for AsyncReportConfig {
65    fn default() -> Self {
66        Self {
67            severity: Severity::Info,
68            synchronous_log: false,
69            timed_log: false,
70            log_message_count: 512,
71        }
72    }
73}
74
75/// An error contained while forwarding a native report callback.
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77#[non_exhaustive]
78pub enum ReportForwarderError {
79    /// The native callback passed a null message pointer with a non-zero length,
80    /// an odd byte length, or invalid UTF-16.
81    InvalidMessage,
82    /// TSDuck passed a severity value not represented by [`Severity`].
83    InvalidSeverity {
84        /// The unrecognized native severity value.
85        severity: i32,
86    },
87    /// The user callback panicked. The message was discarded.
88    Panic,
89}
90
91/// Thread-safe native-report callback forwarding.
92///
93/// A forwarder can be cloned and inspected from any thread. Its handler can run
94/// on a TSDuck worker thread or, when synchronous logging is enabled, on the
95/// producer thread; it must perform bounded non-blocking work. A panic is
96/// contained, discards that message, and becomes visible through
97/// [`Self::take_error`].
98///
99/// The callback receives a validated [`Severity`] and a decoded message. TSDuck's
100/// callback ABI has no userdata, so a process can have only one active
101/// forwarding destination. Multiple reports may share it by cloning the same
102/// forwarder; [`Report::asynchronous_with_forwarder`] rejects a different
103/// forwarder until every report using the active one is terminated or dropped.
104#[derive(Clone)]
105pub struct ReportForwarder {
106    state: Arc<ReportForwarderState>,
107}
108
109type ReportForwarderCallback = dyn Fn(Severity, &str) + Send + Sync + 'static;
110
111struct ReportForwarderState {
112    callback: Arc<ReportForwarderCallback>,
113    error: Mutex<Option<ReportForwarderError>>,
114}
115
116struct RegisteredReportForwarder {
117    state: Arc<ReportForwarderState>,
118    report_count: usize,
119}
120
121impl ReportForwarder {
122    /// Creates a forwarder for decoded native log messages.
123    pub fn new<F>(callback: F) -> Self
124    where
125        F: Fn(Severity, &str) + Send + Sync + 'static,
126    {
127        Self {
128            state: Arc::new(ReportForwarderState {
129                callback: Arc::new(callback),
130                error: Mutex::new(None),
131            }),
132        }
133    }
134
135    /// Returns and clears the first callback error observed since the previous
136    /// call.
137    #[must_use]
138    pub fn take_error(&self) -> Option<ReportForwarderError> {
139        self.state
140            .error
141            .lock()
142            .unwrap_or_else(|poisoned| poisoned.into_inner())
143            .take()
144    }
145}
146
147struct ActiveReportForwarder {
148    state: Arc<ReportForwarderState>,
149}
150
151impl Drop for ActiveReportForwarder {
152    fn drop(&mut self) {
153        let mut active = active_report_forwarder()
154            .lock()
155            .unwrap_or_else(|poisoned| poisoned.into_inner());
156        let Some(registered) = active.as_mut() else {
157            return;
158        };
159        if !Arc::ptr_eq(&registered.state, &self.state) {
160            return;
161        }
162        if registered.report_count == 1 {
163            *active = None;
164        } else {
165            registered.report_count -= 1;
166        }
167    }
168}
169
170fn active_report_forwarder() -> &'static Mutex<Option<RegisteredReportForwarder>> {
171    static ACTIVE: OnceLock<Mutex<Option<RegisteredReportForwarder>>> = OnceLock::new();
172    ACTIVE.get_or_init(|| Mutex::new(None))
173}
174
175fn acquire_report_forwarder(forwarder: &ReportForwarder) -> Result<ActiveReportForwarder> {
176    let mut active = active_report_forwarder()
177        .lock()
178        .unwrap_or_else(|poisoned| poisoned.into_inner());
179    match active.as_mut() {
180        None => {
181            *active = Some(RegisteredReportForwarder {
182                state: Arc::clone(&forwarder.state),
183                report_count: 1,
184            });
185        }
186        Some(registered) if Arc::ptr_eq(&registered.state, &forwarder.state) => {
187            registered.report_count += 1;
188        }
189        Some(_) => {
190            return Err(Error::InvalidState {
191                object: "ReportForwarder",
192                operation: "create a forwarding report",
193                state: "a different forwarder is active",
194            });
195        }
196    }
197    Ok(ActiveReportForwarder {
198        state: Arc::clone(&forwarder.state),
199    })
200}
201
202fn record_forwarder_error(state: &ReportForwarderState, error: ReportForwarderError) {
203    let mut recorded = state
204        .error
205        .lock()
206        .unwrap_or_else(|poisoned| poisoned.into_inner());
207    if recorded.is_none() {
208        *recorded = Some(error);
209    }
210}
211
212fn dispatch_report_forwarder(severity: i32, message: &[u8], message_valid: bool) {
213    let state = {
214        let active = active_report_forwarder()
215            .lock()
216            .unwrap_or_else(|poisoned| poisoned.into_inner());
217        active
218            .as_ref()
219            .map(|registered| Arc::clone(&registered.state))
220    };
221    let Some(state) = state else {
222        return;
223    };
224
225    if !message_valid {
226        record_forwarder_error(&state, ReportForwarderError::InvalidMessage);
227        return;
228    }
229    let Some(severity) = Severity::from_i32(severity) else {
230        record_forwarder_error(&state, ReportForwarderError::InvalidSeverity { severity });
231        return;
232    };
233    let Ok(message) = decode_utf16("ReportForwarder", message) else {
234        record_forwarder_error(&state, ReportForwarderError::InvalidMessage);
235        return;
236    };
237
238    if catch_unwind(AssertUnwindSafe(|| (state.callback)(severity, &message))).is_err() {
239        record_forwarder_error(&state, ReportForwarderError::Panic);
240    }
241}
242
243/// A TSDuck report owner.
244///
245/// `Report` is `!Send + !Sync`. Native objects borrowing a report retain an
246/// `Rc<Report>` and release their native owner before releasing that `Rc`.
247pub struct Report {
248    // `native` must be dropped before `_forwarder`: `RustDuckReport` waits for
249    // its async worker, preventing a native callback from observing a released
250    // forwarding state.
251    native: cxx::UniquePtr<RustDuckReport>,
252    _forwarder: Option<ActiveReportForwarder>,
253    asynchronous: bool,
254    terminated: bool,
255}
256
257type RustDuckReport = ffi::RustDuckReport;
258
259impl Report {
260    fn from_native(
261        native: std::result::Result<cxx::UniquePtr<RustDuckReport>, cxx::Exception>,
262        asynchronous: bool,
263        forwarder: Option<ActiveReportForwarder>,
264    ) -> Result<Rc<Self>> {
265        let native = native.map_err(|error| native_exception("Report::new", error))?;
266        if native.is_null() {
267            return Err(Error::NativeFailure {
268                operation: "Report::new",
269            });
270        }
271        Ok(Rc::new(Self {
272            native,
273            _forwarder: forwarder,
274            asynchronous,
275            terminated: false,
276        }))
277    }
278
279    /// Returns TSDuck's process-wide null report.
280    pub fn null() -> Result<Rc<Self>> {
281        Self::from_native(ffi::rustduck_report_null(), false, None)
282    }
283
284    /// Returns TSDuck's process-wide standard-error report.
285    pub fn stderr() -> Result<Rc<Self>> {
286        Self::from_native(ffi::rustduck_report_stderr(), false, None)
287    }
288
289    /// Creates an owned asynchronous report.
290    pub fn asynchronous(config: AsyncReportConfig) -> Result<Rc<Self>> {
291        Self::from_native(
292            ffi::rustduck_report_asynchronous(
293                config.severity.abi_value(),
294                config.synchronous_log,
295                config.timed_log,
296                config.log_message_count,
297            ),
298            true,
299            None,
300        )
301    }
302
303    /// Creates an asynchronous report that forwards native diagnostics.
304    ///
305    /// The callback receives an owned, decoded view only for the duration of
306    /// its invocation. It may run on a TSDuck worker or producer thread and
307    /// must not block. `timed_log` is rejected because TSDuck's callback-report
308    /// ABI does not expose that option.
309    ///
310    /// TSDuck's callback-report ABI has no per-report userdata. Multiple
311    /// forwarding reports can run only when they clone this same forwarder; a
312    /// different destination is rejected until every active report using the
313    /// current one is terminated or dropped. Each report retains its forwarding
314    /// state until native asynchronous shutdown has completed.
315    ///
316    /// # Errors
317    ///
318    /// Returns an error when `timed_log` is enabled, a different forwarding
319    /// destination is active, or TSDuck cannot construct the native report.
320    pub fn asynchronous_with_forwarder(
321        config: AsyncReportConfig,
322        forwarder: ReportForwarder,
323    ) -> Result<Rc<Self>> {
324        if config.timed_log {
325            return Err(Error::InvalidArgument {
326                field: "AsyncReportConfig::timed_log",
327                message: "TSDuck callback reports do not support timed logging".to_owned(),
328            });
329        }
330        if !sys_bridge::install_report_callback_dispatcher(dispatch_report_forwarder) {
331            return Err(Error::InvalidState {
332                object: "ReportForwarder",
333                operation: "install callback dispatcher",
334                state: "incompatible dispatcher installed",
335            });
336        }
337
338        let active = acquire_report_forwarder(&forwarder)?;
339        Self::from_native(
340            ffi::rustduck_report_asynchronous_with_forwarder(
341                config.severity.abi_value(),
342                config.synchronous_log,
343                config.log_message_count,
344            ),
345            true,
346            Some(active),
347        )
348    }
349
350    /// Changes this report's maximum severity.
351    pub fn set_max_severity(&mut self, severity: Severity) -> Result<()> {
352        self.ensure_active("set maximum severity")?;
353        ffi::rustduck_report_set_max_severity(self.native.pin_mut(), severity.abi_value())
354            .map_err(|error| native_exception("Report::set_max_severity", error))
355    }
356
357    /// Writes one message to this report.
358    pub fn log(&self, severity: Severity, message: &str) -> Result<()> {
359        self.ensure_active("log")?;
360        let message = encode_utf16(message);
361        ffi::rustduck_report_log(self.native(), severity.abi_value(), &message)
362            .map_err(|error| native_exception("Report::log", error))
363    }
364
365    /// Flushes and terminates an asynchronous report.
366    ///
367    /// This waits for queued forwarding callbacks to finish. Calling it more
368    /// than once is a no-op; static reports cannot be terminated.
369    pub fn terminate(&mut self) -> Result<()> {
370        if !self.asynchronous {
371            return Err(Error::InvalidState {
372                object: "Report",
373                operation: "terminate",
374                state: "static",
375            });
376        }
377        if self.terminated {
378            return Ok(());
379        }
380        ffi::rustduck_report_terminate(self.native.pin_mut())
381            .map_err(|error| native_exception("Report::terminate", error))?;
382        self.terminated = true;
383        // Native termination waits for the async worker, so no callback can
384        // observe the forwarding slot after it is released.
385        self._forwarder.take();
386        Ok(())
387    }
388
389    fn ensure_active(&self, operation: &'static str) -> Result<()> {
390        if self.terminated {
391            return Err(Error::InvalidState {
392                object: "Report",
393                operation,
394                state: "terminated",
395            });
396        }
397        Ok(())
398    }
399
400    pub(crate) fn native(&self) -> &RustDuckReport {
401        self.native
402            .as_ref()
403            .expect("Report construction rejects null owners")
404    }
405}
406
407#[cfg(test)]
408mod tests {
409    use super::*;
410
411    fn forwarder_test_lock() -> std::sync::MutexGuard<'static, ()> {
412        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
413        LOCK.get_or_init(|| Mutex::new(()))
414            .lock()
415            .expect("forwarder test lock")
416    }
417
418    #[test]
419    fn severity_uses_stable_abi_values() {
420        assert_eq!(Severity::Error.abi_value(), -3);
421        assert_eq!(Severity::from_i32(42), None);
422    }
423
424    #[test]
425    fn rejects_timed_callback_reports_before_reserving_the_forwarder() {
426        let forwarder = ReportForwarder::new(|_, _| {});
427        assert!(matches!(
428            Report::asynchronous_with_forwarder(
429                AsyncReportConfig {
430                    timed_log: true,
431                    ..AsyncReportConfig::default()
432                },
433                forwarder
434            ),
435            Err(Error::InvalidArgument {
436                field: "AsyncReportConfig::timed_log",
437                ..
438            })
439        ));
440    }
441
442    #[test]
443    fn contains_forwarder_panics() {
444        let _lock = forwarder_test_lock();
445        let forwarder = ReportForwarder::new(|_, _| panic!("callback"));
446        let active = acquire_report_forwarder(&forwarder).expect("first forwarder");
447        dispatch_report_forwarder(Severity::Info.abi_value(), &[0xFF, 0xFE, b'x', 0], true);
448        assert_eq!(forwarder.take_error(), Some(ReportForwarderError::Panic));
449        drop(active);
450    }
451
452    #[test]
453    fn retains_the_first_callback_error() {
454        let _lock = forwarder_test_lock();
455        let forwarder = ReportForwarder::new(|_, _| {});
456        let active = acquire_report_forwarder(&forwarder).expect("first forwarder");
457        dispatch_report_forwarder(99, &[], true);
458        dispatch_report_forwarder(Severity::Info.abi_value(), &[0x01], true);
459        assert_eq!(
460            forwarder.take_error(),
461            Some(ReportForwarderError::InvalidSeverity { severity: 99 })
462        );
463        drop(active);
464    }
465
466    #[test]
467    fn permits_reports_sharing_one_forwarder() {
468        let _lock = forwarder_test_lock();
469        let forwarder = ReportForwarder::new(|_, _| {});
470        let first = acquire_report_forwarder(&forwarder).expect("first forwarder");
471        let second = acquire_report_forwarder(&forwarder).expect("shared forwarder");
472        drop(first);
473        let third = acquire_report_forwarder(&forwarder).expect("remaining shared forwarder");
474        drop(second);
475        drop(third);
476    }
477
478    #[test]
479    fn rejects_a_different_forwarder_while_one_is_active() {
480        let _lock = forwarder_test_lock();
481        let first = ReportForwarder::new(|_, _| {});
482        let second = ReportForwarder::new(|_, _| {});
483        let active = acquire_report_forwarder(&first).expect("first forwarder");
484        assert!(acquire_report_forwarder(&second).is_err());
485        drop(active);
486    }
487}