varta_client/
lib.rs

1#![deny(missing_docs, unsafe_op_in_unsafe_fn, rust_2018_idioms)]
2#![forbid(clippy::dbg_macro, clippy::print_stdout)]
3
4//! Varta agent API — `Varta::connect` opens a transport to the observer;
5//! `Varta::beat` emits a fire-and-forget 32-byte VLP frame with zero
6//! post-init heap traffic.
7//!
8//! # Transports
9//!
10//! The default transport is [`UdsTransport`] (Unix Domain Socket). Alternative
11//! transports are available behind feature flags (e.g. `udp` for UDP).
12//! The [`BeatTransport`] trait allows custom transport implementations.
13//!
14//! The crate re-exports [`Frame`], [`Status`], and [`DecodeError`] from
15//! `varta-vlp` so downstream consumers depend on a single facade.
16
17// Class-A safety guard: refuse to compile a build that combines the
18// degraded-entropy panic-hook fallback with the strict safety profile.
19// The fallback path derives IVs through a SipHash mixer rather than an OS
20// entropy source — acceptable for embedded targets that have explicitly
21// opted in, never acceptable when `safety-profile-strict` is asserted.
22// Mirrors the `prometheus-exporter` + `compile-time-config` exclusion in
23// `crates/varta-watch/src/lib.rs`.
24#[cfg(all(feature = "accept-degraded-entropy", feature = "safety-profile-strict"))]
25compile_error!(
26    "`accept-degraded-entropy` cannot be combined with `safety-profile-strict` \
27     — Class-A safety-critical builds intentionally exclude the non-cryptographic \
28     IV-derivation fallback (`fallback_iv_random`). Choose one: drop the \
29     degraded-entropy variant, or drop the strict safety profile."
30);
31
32pub mod client;
33pub mod transport;
34
35#[cfg(feature = "secure-udp")]
36pub mod secure_transport;
37
38#[cfg(feature = "panic-handler")]
39pub mod panic;
40
41pub use client::{classify_send_error, BeatError, BeatOutcome, DropReason, Varta};
42pub use transport::{BeatTransport, UdsTransport};
43
44#[cfg(feature = "udp")]
45pub use transport::UdpTransport;
46
47#[cfg(feature = "secure-udp")]
48pub use secure_transport::SecureUdpTransport;
49
50pub use varta_vlp::{DecodeError, Frame, Status, NONCE_TERMINAL};
51
52/// Install the panic hook — see [`panic::install`] for the full contract.
53#[cfg(feature = "panic-handler")]
54pub use panic::install as install_panic_handler;
55
56/// Install the UDP panic hook — see [`panic::install_panic_handler_udp`] for
57/// the full contract.
58#[cfg(all(feature = "panic-handler", feature = "udp"))]
59pub use panic::install_panic_handler_udp;
60
61/// Error returned by [`install_panic_handler_secure_udp`].
62#[cfg(all(feature = "panic-handler", feature = "secure-udp"))]
63pub use panic::PanicInstallError;
64
65/// Install the secure UDP panic hook (fail-closed) — see
66/// [`panic::install_panic_handler_secure_udp`] for the full contract.
67#[cfg(all(feature = "panic-handler", feature = "secure-udp"))]
68pub use panic::install_panic_handler_secure_udp;
69
70/// Install the secure UDP panic hook with non-cryptographic IV fallback — see
71/// [`panic::install_panic_handler_secure_udp_accept_degraded_entropy`] for
72/// the full contract including nonce-reuse risk.
73///
74/// Gated behind the explicit `accept-degraded-entropy` feature. Builds
75/// that pin `safety-profile-strict` cannot enable this feature (see the
76/// `compile_error!` at the top of this crate).
77#[cfg(feature = "accept-degraded-entropy")]
78pub use panic::install_panic_handler_secure_udp_accept_degraded_entropy;
varta_client/lib.rs

varta_client/
lib.rs
