public/kaptan
1
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(diagnostics): split error and shutdown messages

Browse Source
This commit is contained in:
Onur Özkan committed 2026-08-09 22:20:59 +03:00
1 parent 9646451645
commit afafd126d7
25 files changed
+608 -225
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

libs/kaptan-log-mavlink/src/lib.rs
+130 -24
View File
@@ -9,7 +9,7 @@
#[cfg(test)]
extern crate std;
use kaptan_log::{LogRecord, RecordChannel, ShutdownReason, ShutdownReport};
use kaptan_log::{LogRecord, LogText, RecordChannel, ShutdownReason, ShutdownReport};
use kaptan_mavlink::message::kaptan::{
KAPTAN_ERROR_DATA, KAPTAN_LOG_DATA, KAPTAN_SHUTDOWN_DATA, KaptanErrorFlags, KaptanLogFlags,
KaptanShutdownReason,
@@ -17,6 +17,10 @@ use kaptan_mavlink::message::kaptan::{
/// Exact capacity of the fixed text field in [`KAPTAN_LOG_DATA`].
pub const LOG_MESSAGE_BYTES: usize = 160;
/// Exact capacity of the fixed error identity path field.
pub const ERROR_PATH_BYTES: usize = 96;
/// Exact capacity of the fixed error additional-information field.
pub const ERROR_ADDITIONAL_INFORMATION_BYTES: usize = 64;
/// One generated diagnostic payload. A platform-owned link remains the sole
/// MAVLink framing, admission, DMA, and retry owner.
@@ -34,23 +38,61 @@ pub enum DiagnosticPayload {
/// MAVLink. `RecordChannel` is the only routing decision: ordinary records
/// become `KAPTAN_LOG`, while error-or-higher records become `KAPTAN_ERROR`.
pub fn encode_diagnostic(record: &LogRecord) -> DiagnosticPayload {
let message = record.message();
debug_assert!(usize::from(message.len()) <= LOG_MESSAGE_BYTES);
match record.channel() {
RecordChannel::Log => DiagnosticPayload::Log(KAPTAN_LOG_DATA {
level: record.severity() as u8,
flags: KaptanLogFlags::from_bits_retain(record.flags().bits()),
message_length: message.len(),
message: *message.bytes(),
}),
RecordChannel::Error => DiagnosticPayload::Error(KAPTAN_ERROR_DATA {
flags: KaptanErrorFlags::from_bits_retain(record.flags().error_bits()),
message_length: message.len(),
message: *message.bytes(),
}),
RecordChannel::Log => {
let message = record
.message()
.expect("log channel must contain ordinary message text");
debug_assert!(usize::from(message.len()) <= LOG_MESSAGE_BYTES);
DiagnosticPayload::Log(KAPTAN_LOG_DATA {
level: record.severity() as u8,
flags: KaptanLogFlags::from_bits_retain(record.flags().bits()),
message_length: message.len(),
message: *message.bytes(),
})
}
RecordChannel::Error => {
let path = record
.error_path()
.expect("error channel must contain an identity path");
let additional_information = record
.additional_information()
.expect("error channel must contain additional-information storage");
let (path, path_length, path_clipped) = project_text::<ERROR_PATH_BYTES>(path);
let (additional_information, additional_information_length, information_clipped) =
project_text::<ERROR_ADDITIONAL_INFORMATION_BYTES>(additional_information);
let mut flags = record.flags().error_bits();
if path_clipped || information_clipped {
flags |= KaptanErrorFlags::KAPTAN_ERROR_FLAG_TRUNCATED.bits();
}
DiagnosticPayload::Error(KAPTAN_ERROR_DATA {
flags: KaptanErrorFlags::from_bits_retain(flags),
path_length,
additional_information_length,
path,
additional_information,
})
}
}
}
fn project_text<const N: usize>(text: &LogText) -> ([u8; N], u8, bool) {
let source = text.as_str();
let retained = source
.char_indices()
.take_while(|(index, character)| index + character.len_utf8() <= N)
.map(|(index, character)| index + character.len_utf8())
.last()
.unwrap_or(0);
let mut bytes = [0; N];
bytes[..retained].copy_from_slice(&source.as_bytes()[..retained]);
(
bytes,
retained as u8,
text.is_truncated() || retained != source.len(),
)
}
/// Encodes one typed shutdown event. The caller owns when a shutdown is safe
/// to report; this pure adapter cannot run a shutdown state machine.
pub const fn encode_shutdown(report: ShutdownReport) -> KAPTAN_SHUTDOWN_DATA {
@@ -66,10 +108,13 @@ pub const fn encode_shutdown(report: ShutdownReport) -> KAPTAN_SHUTDOWN_DATA {
mod tests {
use std::sync::Once;
use super::{DiagnosticPayload, LOG_MESSAGE_BYTES, encode_diagnostic, encode_shutdown};
use super::{
DiagnosticPayload, ERROR_ADDITIONAL_INFORMATION_BYTES, ERROR_PATH_BYTES, LOG_MESSAGE_BYTES,
encode_diagnostic, encode_shutdown,
};
use kaptan_log::{
EventHub, FacadeIngress, GlobalLogger, LogFilter, LogFlags, LogRecord, LogText, Severity,
ShutdownReason, ShutdownReport,
ErrorAdditionalInformation, ErrorPath, EventHub, FacadeIngress, GlobalLogger, LogFilter,
LogFlags, LogRecord, LogText, Severity, ShutdownReason, ShutdownReport,
};
use kaptan_mavlink::{
encoder::MavlinkEncoder,
@@ -123,8 +168,12 @@ mod tests {
panic!("log::error! must not produce KAPTAN_LOG");
};
assert!(
payload.message[..usize::from(payload.message_length)]
.ends_with(b"critical error survives")
payload.path[..usize::from(payload.path_length)]
.ends_with(b"kaptan_log_mavlink::tests")
);
assert_eq!(
&payload.additional_information[..usize::from(payload.additional_information_length)],
b"critical error survives"
);
}
@@ -153,19 +202,28 @@ mod tests {
}
assert_eq!(data.message.len(), LOG_MESSAGE_BYTES);
let error = LogRecord::new(
Severity::Error,
let error = LogRecord::error(
LogFlags::TRACE.with(LogFlags::COALESCED),
LogText::from_message("driver::Error::Transfer"),
ErrorPath::from_message("driver::Error::Transfer"),
ErrorAdditionalInformation::new(),
);
let DiagnosticPayload::Error(error_data) = encode_diagnostic(&error) else {
panic!("error record must use KAPTAN_ERROR");
};
assert_eq!(error_data.flags.bits(), LogFlags::COALESCED.bits());
assert_eq!(error_data.message_length, 23);
assert_eq!(KAPTAN_ERROR_DATA::ENCODED_LEN, 162);
assert_eq!(error_data.path_length, 23);
assert_eq!(error_data.additional_information_length, 0);
assert_eq!(&error_data.path[..23], b"driver::Error::Transfer");
assert!(
error_data
.additional_information
.iter()
.all(|byte| *byte == 0)
);
assert_eq!(KAPTAN_ERROR_DATA::ENCODED_LEN, 163);
let error_frame = encoder.custom(&error_data);
assert_eq!(error_frame.message_id(), 51_021);
assert!(error_frame.raw_bytes().len() <= 175);
assert!(matches!(
MavMessage::parse(
mavlink::MavlinkVersion::V2,
@@ -176,6 +234,54 @@ mod tests {
));
}
#[test]
fn error_wire_projection_clips_each_component_independently() {
let error = LogRecord::error(
LogFlags::NONE,
ErrorPath::from_message(&"p".repeat(LOG_MESSAGE_BYTES)),
ErrorAdditionalInformation::from_message(&"i".repeat(LOG_MESSAGE_BYTES)),
);
let DiagnosticPayload::Error(payload) = encode_diagnostic(&error) else {
panic!("error record must use KAPTAN_ERROR");
};
assert_eq!(usize::from(payload.path_length), ERROR_PATH_BYTES);
assert_eq!(
usize::from(payload.additional_information_length),
ERROR_ADDITIONAL_INFORMATION_BYTES
);
assert_eq!(payload.flags.bits(), LogFlags::TRUNCATED.bits());
assert_eq!(&payload.path, &[b'p'; ERROR_PATH_BYTES]);
assert_eq!(
&payload.additional_information,
&[b'i'; ERROR_ADDITIONAL_INFORMATION_BYTES]
);
}
#[test]
fn error_path_remains_decodable_when_only_additional_information_clips() {
let error = LogRecord::error(
LogFlags::NONE,
ErrorPath::from_message("kaptan::driver::Transfer"),
ErrorAdditionalInformation::from_message(&"é".repeat(80)),
);
let DiagnosticPayload::Error(payload) = encode_diagnostic(&error) else {
panic!("error record must use KAPTAN_ERROR");
};
assert_eq!(
core::str::from_utf8(&payload.path[..usize::from(payload.path_length)]),
Ok("kaptan::driver::Transfer")
);
assert_eq!(usize::from(payload.additional_information_length), 64);
assert!(
core::str::from_utf8(
&payload.additional_information
[..usize::from(payload.additional_information_length)]
)
.is_ok()
);
assert!(payload.flags.bits() & LogFlags::TRUNCATED.bits() != 0);
}
#[test]
fn typed_shutdown_maps_to_its_sole_generated_message() {
let data = encode_shutdown(ShutdownReport::new(ShutdownReason::Safety));