use core::fmt;
use astrs_time::HlcTimestamp;
use oxicode::{Decode, Encode};
use serde::{Deserialize, Serialize};
use crate::common::log::LogLevel;
use crate::ids::{BuildId, DataflowId, NodeId};
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RequestScope {
#[default]
#[oxicode(variant = 0)]
Read,
#[oxicode(variant = 1)]
Mutate,
}
impl RequestScope {
pub const ALL: &'static [Self] = &[Self::Read, Self::Mutate];
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Read => "read",
Self::Mutate => "mutate",
}
}
#[must_use]
pub const fn is_mutating(self) -> bool {
matches!(self, Self::Mutate)
}
}
impl fmt::Display for RequestScope {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum DataflowSource {
#[oxicode(variant = 0)]
Manifest {
yaml: String,
working_dir: Option<String>,
},
#[oxicode(variant = 1)]
Build {
build: BuildId,
},
}
impl DataflowSource {
#[must_use]
pub fn from_manifest(yaml: impl Into<String>) -> Self {
Self::Manifest {
yaml: yaml.into(),
working_dir: None,
}
}
#[must_use]
pub fn manifest_text(&self) -> Option<&str> {
match self {
Self::Manifest { yaml, .. } => Some(yaml),
Self::Build { .. } => None,
}
}
#[must_use]
pub const fn build(&self) -> Option<BuildId> {
match self {
Self::Manifest { .. } => None,
Self::Build { build } => Some(*build),
}
}
}
impl fmt::Display for DataflowSource {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Manifest { yaml, working_dir } => match working_dir {
Some(dir) => write!(f, "manifest ({} bytes) in {dir}", yaml.len()),
None => write!(f, "manifest ({} bytes)", yaml.len()),
},
Self::Build { build } => write!(f, "build {build}"),
}
}
}
pub const DEFAULT_LOG_LIMIT: u32 = 1_000;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct LogQuery {
pub min_level: Option<LogLevel>,
pub since: Option<HlcTimestamp>,
pub until: Option<HlcTimestamp>,
pub contains: Option<String>,
pub target: Option<String>,
pub limit: Option<u32>,
}
impl LogQuery {
#[must_use]
pub const fn new() -> Self {
Self {
min_level: None,
since: None,
until: None,
contains: None,
target: None,
limit: Some(DEFAULT_LOG_LIMIT),
}
}
#[must_use]
pub const fn with_min_level(mut self, level: LogLevel) -> Self {
self.min_level = Some(level);
self
}
#[must_use]
pub const fn with_window(mut self, since: HlcTimestamp, until: HlcTimestamp) -> Self {
self.since = Some(since);
self.until = Some(until);
self
}
#[must_use]
pub fn with_contains(mut self, needle: impl Into<String>) -> Self {
self.contains = Some(needle.into());
self
}
#[must_use]
pub fn with_target(mut self, target: impl Into<String>) -> Self {
self.target = Some(target.into());
self
}
#[must_use]
pub const fn with_limit(mut self, limit: Option<u32>) -> Self {
self.limit = limit;
self
}
#[must_use]
pub const fn is_unfiltered(&self) -> bool {
self.min_level.is_none()
&& self.since.is_none()
&& self.until.is_none()
&& self.contains.is_none()
&& self.target.is_none()
}
#[must_use]
pub fn matches(&self, record: &crate::common::LogRecord) -> bool {
if let Some(level) = self.min_level
&& !record.level.is_enabled_at(level)
{
return false;
}
if let Some(since) = self.since
&& record.timestamp < since
{
return false;
}
if let Some(until) = self.until
&& record.timestamp >= until
{
return false;
}
if let Some(needle) = &self.contains
&& !record.message.contains(needle.as_str())
{
return false;
}
if let Some(target) = &self.target
&& record.target != *target
{
return false;
}
true
}
}
impl Default for LogQuery {
fn default() -> Self {
Self::new()
}
}
impl fmt::Display for LogQuery {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
if self.is_unfiltered() {
return f.write_str("all records");
}
let mut parts: Vec<String> = Vec::new();
if let Some(level) = self.min_level {
parts.push(format!("level ≥ {level}"));
}
if let Some(since) = self.since {
parts.push(format!("since {since}"));
}
if let Some(until) = self.until {
parts.push(format!("until {until}"));
}
if let Some(needle) = &self.contains {
parts.push(format!("containing {needle:?}"));
}
if let Some(target) = &self.target {
parts.push(format!("target {target}"));
}
f.write_str(&parts.join(", "))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct TopicQuery {
pub max_rate_hz: Option<u32>,
pub head_bytes: Option<u32>,
pub include_metadata: bool,
pub latest_only: bool,
pub limit: Option<u64>,
}
impl TopicQuery {
#[must_use]
pub const fn new() -> Self {
Self {
max_rate_hz: None,
head_bytes: None,
include_metadata: true,
latest_only: false,
limit: None,
}
}
#[must_use]
pub const fn with_max_rate_hz(mut self, rate: Option<u32>) -> Self {
self.max_rate_hz = rate;
self
}
#[must_use]
pub const fn with_head_bytes(mut self, bytes: Option<u32>) -> Self {
self.head_bytes = bytes;
self
}
#[must_use]
pub const fn with_metadata(mut self, include: bool) -> Self {
self.include_metadata = include;
self
}
#[must_use]
pub const fn with_latest_only(mut self, latest_only: bool) -> Self {
self.latest_only = latest_only;
self
}
#[must_use]
pub const fn with_limit(mut self, limit: Option<u64>) -> Self {
self.limit = limit;
self
}
#[must_use]
pub const fn min_interval_ms(&self) -> Option<u64> {
match self.max_rate_hz {
None => None,
Some(0) => Some(u64::MAX),
Some(rate) => Some(1_000 / rate as u64),
}
}
#[must_use]
pub const fn wants_payload(&self) -> bool {
!matches!(self.head_bytes, Some(0))
}
}
impl Default for TopicQuery {
fn default() -> Self {
Self::new()
}
}
impl fmt::Display for TopicQuery {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut parts: Vec<String> = Vec::new();
if let Some(rate) = self.max_rate_hz {
parts.push(format!("≤{rate} Hz"));
}
if let Some(bytes) = self.head_bytes {
parts.push(format!("first {bytes} B"));
}
if self.latest_only {
parts.push("latest only".to_owned());
}
if let Some(limit) = self.limit {
parts.push(format!("{limit} messages"));
}
if !self.include_metadata {
parts.push("no metadata".to_owned());
}
if parts.is_empty() {
return f.write_str("everything");
}
f.write_str(&parts.join(", "))
}
}
#[derive(
Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, Encode, Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ParamScope {
#[oxicode(variant = 0)]
Global,
#[oxicode(variant = 1)]
Dataflow {
dataflow: DataflowId,
},
#[oxicode(variant = 2)]
Node {
dataflow: DataflowId,
node: NodeId,
},
}
impl ParamScope {
#[must_use]
pub const fn node(dataflow: DataflowId, node: NodeId) -> Self {
Self::Node { dataflow, node }
}
#[must_use]
pub const fn dataflow_scope(dataflow: DataflowId) -> Self {
Self::Dataflow { dataflow }
}
#[must_use]
pub const fn dataflow(&self) -> Option<DataflowId> {
match self {
Self::Global => None,
Self::Dataflow { dataflow } | Self::Node { dataflow, .. } => Some(*dataflow),
}
}
#[must_use]
pub const fn node_id(&self) -> Option<&NodeId> {
match self {
Self::Node { node, .. } => Some(node),
_ => None,
}
}
#[must_use]
pub fn parent(&self) -> Option<Self> {
match self {
Self::Global => None,
Self::Dataflow { .. } => Some(Self::Global),
Self::Node { dataflow, .. } => Some(Self::Dataflow {
dataflow: *dataflow,
}),
}
}
#[must_use]
pub fn lookup_chain(&self) -> Vec<Self> {
let mut chain = vec![self.clone()];
let mut current = self.clone();
while let Some(parent) = current.parent() {
chain.push(parent.clone());
current = parent;
}
chain
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::Global => "global",
Self::Dataflow { .. } => "dataflow",
Self::Node { .. } => "node",
}
}
}
impl fmt::Display for ParamScope {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Global => f.write_str("global"),
Self::Dataflow { dataflow } => write!(f, "dataflow {dataflow}"),
Self::Node { dataflow, node } => write!(f, "node {node} of dataflow {dataflow}"),
}
}
}
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ErrorCode {
#[default]
#[oxicode(variant = 0)]
Internal,
#[oxicode(variant = 1)]
NotFound,
#[oxicode(variant = 2)]
AlreadyExists,
#[oxicode(variant = 3)]
InvalidArgument,
#[oxicode(variant = 4)]
FailedPrecondition,
#[oxicode(variant = 5)]
PermissionDenied,
#[oxicode(variant = 6)]
Unavailable,
#[oxicode(variant = 7)]
Timeout,
#[oxicode(variant = 8)]
ResourceExhausted,
#[oxicode(variant = 9)]
Unsupported,
#[oxicode(variant = 10)]
Cancelled,
#[oxicode(variant = 11)]
ValidationFailed,
#[oxicode(variant = 12)]
BuildFailed,
}
impl ErrorCode {
pub const ALL: &'static [Self] = &[
Self::Internal,
Self::NotFound,
Self::AlreadyExists,
Self::InvalidArgument,
Self::FailedPrecondition,
Self::PermissionDenied,
Self::Unavailable,
Self::Timeout,
Self::ResourceExhausted,
Self::Unsupported,
Self::Cancelled,
Self::ValidationFailed,
Self::BuildFailed,
];
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Internal => "internal",
Self::NotFound => "not_found",
Self::AlreadyExists => "already_exists",
Self::InvalidArgument => "invalid_argument",
Self::FailedPrecondition => "failed_precondition",
Self::PermissionDenied => "permission_denied",
Self::Unavailable => "unavailable",
Self::Timeout => "timeout",
Self::ResourceExhausted => "resource_exhausted",
Self::Unsupported => "unsupported",
Self::Cancelled => "cancelled",
Self::ValidationFailed => "validation_failed",
Self::BuildFailed => "build_failed",
}
}
#[must_use]
pub const fn is_retryable(self) -> bool {
matches!(
self,
Self::Unavailable | Self::Timeout | Self::ResourceExhausted | Self::Internal
)
}
#[must_use]
pub const fn is_caller_error(self) -> bool {
matches!(
self,
Self::NotFound
| Self::AlreadyExists
| Self::InvalidArgument
| Self::FailedPrecondition
| Self::PermissionDenied
| Self::Unsupported
| Self::ValidationFailed
)
}
#[must_use]
pub const fn exit_code(self) -> u8 {
match self {
Self::Internal => 1,
Self::Cancelled => 2,
Self::InvalidArgument => 3,
Self::NotFound => 4,
Self::AlreadyExists => 5,
Self::FailedPrecondition => 6,
Self::PermissionDenied => 7,
Self::Unavailable => 8,
Self::Timeout => 9,
Self::ResourceExhausted => 10,
Self::Unsupported => 11,
Self::ValidationFailed => 12,
Self::BuildFailed => 13,
}
}
}
impl fmt::Display for ErrorCode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::codec::{WireEncode, round_trip};
use crate::common::LogRecord;
#[test]
fn request_scope_indices_are_frozen() {
for (index, scope) in RequestScope::ALL.iter().enumerate() {
assert_eq!(usize::from(scope.encode_to_vec().unwrap()[0]), index);
}
assert!(RequestScope::Mutate.is_mutating());
assert!(!RequestScope::Read.is_mutating());
assert_eq!(RequestScope::default(), RequestScope::Read);
assert_eq!(RequestScope::Mutate.to_string(), "mutate");
}
#[test]
fn dataflow_sources_are_exclusive_by_construction() {
let inline = DataflowSource::from_manifest("nodes: []");
assert_eq!(inline.manifest_text(), Some("nodes: []"));
assert_eq!(inline.build(), None);
assert_eq!(round_trip(&inline).unwrap(), inline);
let built = DataflowSource::Build {
build: BuildId::from_u128(3),
};
assert_eq!(built.manifest_text(), None);
assert_eq!(built.build(), Some(BuildId::from_u128(3)));
assert_eq!(usize::from(built.encode_to_vec().unwrap()[0]), 1);
assert!(built.to_string().contains("build"));
assert!(inline.to_string().contains("manifest"));
}
#[test]
fn a_default_log_query_is_capped_but_unfiltered() {
let query = LogQuery::default();
assert!(query.is_unfiltered());
assert_eq!(query.limit, Some(DEFAULT_LOG_LIMIT));
assert_eq!(query.to_string(), "all records");
}
#[test]
fn log_queries_filter_exactly_what_they_name() {
let record = LogRecord::new(HlcTimestamp::new(100, 0), LogLevel::Info, "queue full")
.with_target("astrs_daemon::spawn");
assert!(LogQuery::new().matches(&record));
assert!(
LogQuery::new()
.with_min_level(LogLevel::Info)
.matches(&record)
);
assert!(
!LogQuery::new()
.with_min_level(LogLevel::Error)
.matches(&record)
);
assert!(LogQuery::new().with_contains("queue").matches(&record));
assert!(!LogQuery::new().with_contains("camera").matches(&record));
assert!(
LogQuery::new()
.with_target("astrs_daemon::spawn")
.matches(&record)
);
assert!(!LogQuery::new().with_target("other").matches(&record));
assert!(
LogQuery::new()
.with_window(HlcTimestamp::new(0, 0), HlcTimestamp::new(200, 0))
.matches(&record)
);
assert!(
!LogQuery::new()
.with_window(HlcTimestamp::new(200, 0), HlcTimestamp::new(300, 0))
.matches(&record)
);
assert!(
!LogQuery::new()
.with_window(HlcTimestamp::new(0, 0), HlcTimestamp::new(100, 0))
.matches(&record),
"the upper bound is exclusive"
);
}
#[test]
fn log_queries_round_trip_and_describe_themselves() {
let query = LogQuery::new()
.with_min_level(LogLevel::Warn)
.with_contains("queue")
.with_target("astrs_daemon")
.with_limit(Some(10))
.with_window(HlcTimestamp::new(1, 0), HlcTimestamp::new(2, 0));
assert_eq!(round_trip(&query).unwrap(), query);
assert!(!query.is_unfiltered());
let text = query.to_string();
for needle in ["level", "since", "until", "containing", "target"] {
assert!(text.contains(needle), "{text} is missing {needle}");
}
}
#[test]
fn topic_queries_compute_their_pacing() {
assert_eq!(TopicQuery::new().min_interval_ms(), None);
assert_eq!(
TopicQuery::new()
.with_max_rate_hz(Some(4))
.min_interval_ms(),
Some(250)
);
assert_eq!(
TopicQuery::new()
.with_max_rate_hz(Some(0))
.min_interval_ms(),
Some(u64::MAX),
"a zero rate must not divide by zero"
);
assert!(TopicQuery::new().wants_payload());
assert!(!TopicQuery::new().with_head_bytes(Some(0)).wants_payload());
assert!(TopicQuery::new().with_head_bytes(Some(64)).wants_payload());
}
#[test]
fn topic_queries_round_trip_and_describe_themselves() {
let query = TopicQuery::new()
.with_max_rate_hz(Some(2))
.with_head_bytes(Some(32))
.with_latest_only(true)
.with_limit(Some(100))
.with_metadata(false);
assert_eq!(round_trip(&query).unwrap(), query);
let text = query.to_string();
for needle in ["Hz", "first", "latest only", "messages", "no metadata"] {
assert!(text.contains(needle), "{text} is missing {needle}");
}
assert_eq!(TopicQuery::new().to_string(), "everything");
}
#[test]
fn param_scopes_nest_and_fall_back() {
let dataflow = DataflowId::from_u128(1);
let node = ParamScope::node(dataflow, NodeId::new("camera").unwrap());
assert_eq!(node.dataflow(), Some(dataflow));
assert_eq!(node.node_id().map(NodeId::as_str), Some("camera"));
assert_eq!(node.parent(), Some(ParamScope::dataflow_scope(dataflow)));
let chain = node.lookup_chain();
assert_eq!(chain.len(), 3);
assert_eq!(chain[0], node);
assert_eq!(chain[1], ParamScope::dataflow_scope(dataflow));
assert_eq!(chain[2], ParamScope::Global);
assert_eq!(ParamScope::Global.lookup_chain(), vec![ParamScope::Global]);
assert_eq!(ParamScope::Global.dataflow(), None);
assert_eq!(ParamScope::Global.node_id(), None);
}
#[test]
fn param_scope_indices_are_frozen() {
let scopes = [
ParamScope::Global,
ParamScope::dataflow_scope(DataflowId::from_u128(1)),
ParamScope::node(DataflowId::from_u128(1), NodeId::new("camera").unwrap()),
];
for (index, scope) in scopes.into_iter().enumerate() {
assert_eq!(usize::from(scope.encode_to_vec().unwrap()[0]), index);
assert_eq!(round_trip(&scope).unwrap(), scope);
assert!(!scope.kind_name().is_empty());
assert!(!scope.to_string().is_empty());
}
}
#[test]
fn error_code_indices_are_frozen_and_exit_codes_are_distinct() {
let mut exits = std::collections::BTreeSet::new();
for (index, code) in ErrorCode::ALL.iter().enumerate() {
assert_eq!(usize::from(code.encode_to_vec().unwrap()[0]), index);
assert!(exits.insert(code.exit_code()), "{code} reuses an exit code");
assert_ne!(code.exit_code(), 0, "an error never exits successfully");
}
assert_eq!(ErrorCode::ALL.len(), 13);
assert_eq!(ErrorCode::default(), ErrorCode::Internal);
}
#[test]
fn error_codes_classify_themselves_consistently() {
for &code in ErrorCode::ALL {
assert!(
!(code.is_caller_error() && code.is_retryable()),
"{code} is both the caller's fault and retryable"
);
assert!(!code.as_str().is_empty());
}
assert!(ErrorCode::Unavailable.is_retryable());
assert!(ErrorCode::NotFound.is_caller_error());
}
}