1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
//! Strict construction and canonical encoding for current health findings.
mod encode;
use std::{any::type_name, sync::Arc};
use crate::{
catalog::{Catalog, CatalogSpec, Code, DiagnosticValidators},
diagnostic::PublicEvidence,
};
use super::{
HealthBuildError, HealthEncodeError, HealthFindingId, HealthFindingType, HealthSeverity,
ObservationTime,
};
/// Typed current service-state finding awaiting resource encoding.
#[derive(Debug)]
pub struct HealthFinding<E: PublicEvidence> {
id: HealthFindingId,
type_uri: String,
code: Code,
title: String,
detail: String,
severity: HealthSeverity,
observed_at: ObservationTime,
evidence: E,
suggestions: Vec<String>,
evidence_validator: Arc<jsonschema::Validator>,
}
impl<E: PublicEvidence> HealthFinding<E> {
/// Stable identifier for this observed finding.
pub const fn id(&self) -> &HealthFindingId {
&self.id
}
/// Permanent semantic diagnostic code.
pub const fn code(&self) -> &Code {
&self.code
}
/// Current severity of the finding.
pub const fn severity(&self) -> HealthSeverity {
self.severity
}
/// Canonical observation time.
pub const fn observed_at(&self) -> &ObservationTime {
&self.observed_at
}
/// Reviewed typed public evidence.
pub const fn evidence(&self) -> &E {
&self.evidence
}
}
impl<C: CatalogSpec> Catalog<C> {
/// Constructs a finding registered on the current-health surface.
///
/// A finding is resource data describing present state, so it carries a
/// severity and an observation time instead of a status. A healthy service
/// publishes no finding at all; the surrounding resource says so.
///
/// ```
/// use recourse::{
/// catalog::{Catalog, CatalogSpec, CodeNumber},
/// diagnostic::{DiagnosticType, PublicEvidence},
/// health::{HealthFindingId, HealthFindingType, HealthSeverity, ObservationTime},
/// };
/// use schemars::JsonSchema;
/// use serde::Serialize;
///
/// # enum ServiceCatalog {}
/// # impl CatalogSpec for ServiceCatalog {
/// # const NAME: &'static str = "example-service";
/// # const PREFIX: &'static str = "EXM";
/// # const TYPE_BASE: &'static str = "https://example.invalid/problems/";
/// # }
/// #[derive(Debug, Serialize, JsonSchema)]
/// struct QueueUnavailableEvidence {
/// consecutive_failures: u32,
/// }
///
/// impl PublicEvidence for QueueUnavailableEvidence {}
///
/// enum QueueUnavailable {}
///
/// impl DiagnosticType for QueueUnavailable {
/// type Catalog = ServiceCatalog;
/// type Evidence = QueueUnavailableEvidence;
///
/// const NUMBER: CodeNumber = CodeNumber::new(1010);
/// const TITLE: &'static str = "Job queue unavailable";
/// const DETAIL: &'static str = "The worker cannot currently reach the job queue.";
/// const SUGGESTIONS: &'static [&'static str] = &["Check queue connectivity."];
/// const DOCS: &'static str = "Verify credentials and network policy.";
/// }
///
/// impl HealthFindingType for QueueUnavailable {}
///
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let catalog = Catalog::<ServiceCatalog>::builder()
/// .health::<QueueUnavailable>()
/// .build()?;
/// let finding = catalog.try_health::<QueueUnavailable>(
/// HealthFindingId::try_new("finding_queue-unavailable")?,
/// HealthSeverity::Degraded,
/// ObservationTime::parse("2026-08-10T14:31:00Z")?,
/// QueueUnavailableEvidence {
/// consecutive_failures: 3,
/// },
/// )?;
///
/// // Compose the value into an application-owned health resource.
/// let document = finding.try_encode_value()?;
/// assert_eq!(document["severity"], "degraded");
/// assert_eq!(document["observed_at"], "2026-08-10T14:31:00Z");
/// # Ok(())
/// # }
/// # assert!(example().is_ok());
/// ```
pub fn try_health<D>(
&self,
id: HealthFindingId,
severity: HealthSeverity,
observed_at: ObservationTime,
evidence: D::Evidence,
) -> Result<HealthFinding<D::Evidence>, HealthBuildError>
where
D: HealthFindingType<Catalog = C>,
{
let definition =
self.health_definition::<D>()
.ok_or(HealthBuildError::DiagnosticNotRegistered {
diagnostic: type_name::<D>(),
})?;
let evidence_validator = self
.validators(definition.number())
.map(DiagnosticValidators::evidence)
.ok_or_else(|| HealthBuildError::ValidatorMissing {
code: definition.code().clone(),
})?;
Ok(HealthFinding {
id,
type_uri: definition.type_uri().to_owned(),
code: definition.code().clone(),
title: definition.title().to_owned(),
detail: definition.detail().to_owned(),
severity,
observed_at,
evidence,
suggestions: definition.suggestions().to_vec(),
evidence_validator,
})
}
}