1use std::collections::BTreeMap;
2
3use serde::{Deserialize, Serialize};
4use thiserror::Error;
5
6use crate::{
7 MAX_PLUGIN_DIAGNOSTICS, MAX_PLUGIN_EVENT_ID_BYTES, MAX_PLUGIN_EVENT_NAME_BYTES,
8 MAX_PLUGIN_MEASUREMENTS, MAX_PLUGIN_PLATFORM_BYTES, MAX_PLUGIN_PROTOCOL_BYTES,
9 MAX_PLUGIN_THREAD_BYTES, PluginDiagnostic, PluginMeasurement, PluginProtocolViolation,
10 protocol::{validate_attributes, validate_optional_text, validate_text},
11};
12
13pub const MAX_BENCHMARK_BATCH_EVENTS: usize = 512;
14pub const MAX_BENCHMARK_THRESHOLD_VIOLATIONS: usize = 128;
15
16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(rename_all = "camelCase")]
19pub struct BenchmarkEvent {
20 pub run_id: String,
21 pub session_id: String,
22 pub platform: String,
23 pub source_protocol: Option<String>,
24 pub event_name: String,
25 pub timestamp_ns: u64,
26 pub elapsed_ns: u64,
27 pub thread: Option<String>,
28 #[serde(default)]
29 pub attributes: BTreeMap<String, String>,
30}
31
32impl BenchmarkEvent {
33 pub fn validate(&self) -> Result<(), BenchmarkSinkError> {
34 validate_text("benchmark.run_id", &self.run_id, MAX_PLUGIN_EVENT_ID_BYTES)?;
35 validate_text(
36 "benchmark.session_id",
37 &self.session_id,
38 MAX_PLUGIN_EVENT_ID_BYTES,
39 )?;
40 validate_text(
41 "benchmark.platform",
42 &self.platform,
43 MAX_PLUGIN_PLATFORM_BYTES,
44 )?;
45 validate_optional_text(
46 "benchmark.source_protocol",
47 self.source_protocol.as_deref(),
48 MAX_PLUGIN_PROTOCOL_BYTES,
49 )?;
50 validate_text(
51 "benchmark.event_name",
52 &self.event_name,
53 MAX_PLUGIN_EVENT_NAME_BYTES,
54 )?;
55 validate_optional_text(
56 "benchmark.thread",
57 self.thread.as_deref(),
58 MAX_PLUGIN_THREAD_BYTES,
59 )?;
60 validate_attributes(&self.attributes)?;
61 Ok(())
62 }
63}
64
65#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase")]
68pub struct BenchmarkEventBatch {
69 pub events: Vec<BenchmarkEvent>,
70}
71
72impl BenchmarkEventBatch {
73 pub fn validate(&self) -> Result<(), BenchmarkSinkError> {
74 if self.events.len() > MAX_BENCHMARK_BATCH_EVENTS {
75 return Err(BenchmarkSinkError::ProtocolViolation(format!(
76 "benchmark batch exceeds the {MAX_BENCHMARK_BATCH_EVENTS}-event protocol limit"
77 )));
78 }
79 for event in &self.events {
80 event.validate()?;
81 }
82 Ok(())
83 }
84}
85
86#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
88#[serde(rename_all = "camelCase")]
89pub struct BenchmarkSinkStatus {
90 pub accepted_events: u64,
91}
92
93impl BenchmarkSinkStatus {
94 pub fn validate_for_batch(&self, batch_event_count: usize) -> Result<(), BenchmarkSinkError> {
95 let batch_event_count = u64::try_from(batch_event_count).map_err(|_| {
96 BenchmarkSinkError::ProtocolViolation(
97 "benchmark batch size cannot be represented by the protocol".to_owned(),
98 )
99 })?;
100 if self.accepted_events > batch_event_count {
101 return Err(BenchmarkSinkError::ProtocolViolation(format!(
102 "benchmark sink accepted {} events from a {batch_event_count}-event batch",
103 self.accepted_events
104 )));
105 }
106 Ok(())
107 }
108}
109
110#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
111#[serde(rename_all = "camelCase")]
112pub struct BenchmarkThresholdViolation {
113 pub measurement: String,
114 pub actual: f64,
115 pub threshold: f64,
116 pub comparison: String,
117}
118
119#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122pub struct BenchmarkSinkReport {
123 pub accepted_events: u64,
124 pub dropped_events: u64,
125 #[serde(default)]
126 pub measurements: Vec<PluginMeasurement>,
127 #[serde(default)]
128 pub threshold_violations: Vec<BenchmarkThresholdViolation>,
129 #[serde(default)]
130 pub diagnostics: Vec<PluginDiagnostic>,
131}
132
133impl BenchmarkSinkReport {
134 pub fn validate(&self) -> Result<(), BenchmarkSinkError> {
135 if self.measurements.len() > MAX_PLUGIN_MEASUREMENTS {
136 return Err(BenchmarkSinkError::ProtocolViolation(format!(
137 "benchmark report exceeds the {MAX_PLUGIN_MEASUREMENTS}-measurement protocol limit"
138 )));
139 }
140 if self.diagnostics.len() > MAX_PLUGIN_DIAGNOSTICS {
141 return Err(BenchmarkSinkError::ProtocolViolation(format!(
142 "benchmark report exceeds the {MAX_PLUGIN_DIAGNOSTICS}-diagnostic protocol limit"
143 )));
144 }
145 if self.threshold_violations.len() > MAX_BENCHMARK_THRESHOLD_VIOLATIONS {
146 return Err(BenchmarkSinkError::ProtocolViolation(format!(
147 "benchmark report exceeds the {MAX_BENCHMARK_THRESHOLD_VIOLATIONS}-threshold-violation protocol limit"
148 )));
149 }
150 for measurement in &self.measurements {
151 measurement.validate()?;
152 }
153 for diagnostic in &self.diagnostics {
154 diagnostic.validate()?;
155 }
156 for violation in &self.threshold_violations {
157 validate_text(
158 "threshold_violation.measurement",
159 &violation.measurement,
160 MAX_PLUGIN_EVENT_NAME_BYTES,
161 )?;
162 validate_text(
163 "threshold_violation.comparison",
164 &violation.comparison,
165 MAX_PLUGIN_EVENT_NAME_BYTES,
166 )?;
167 if !violation.actual.is_finite() || !violation.threshold.is_finite() {
168 return Err(BenchmarkSinkError::ProtocolViolation(format!(
169 "threshold violation `{}` contains a non-finite value",
170 violation.measurement
171 )));
172 }
173 }
174 Ok(())
175 }
176}
177
178#[derive(Debug, Error, Clone, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(tag = "code", content = "message")]
184pub enum BenchmarkSinkFailure {
185 #[serde(rename = "sinkFailed")]
186 #[error("sink failed: {0}")]
187 Failed(String),
188}
189
190impl From<BenchmarkSinkFailure> for BenchmarkSinkError {
191 fn from(value: BenchmarkSinkFailure) -> Self {
192 match value {
193 BenchmarkSinkFailure::Failed(message) => Self::SinkFailed(message),
194 }
195 }
196}
197
198pub trait PluginBenchmarkSink: Send + Sync {
219 fn name(&self) -> &str;
220
221 fn on_event_batch(
222 &self,
223 batch: &BenchmarkEventBatch,
224 ) -> Result<BenchmarkSinkStatus, BenchmarkSinkFailure>;
225
226 fn flush(&self) -> Result<BenchmarkSinkReport, BenchmarkSinkFailure> {
227 Ok(BenchmarkSinkReport::default())
228 }
229}
230
231#[derive(Debug, Error, Clone, PartialEq, Eq, Serialize, Deserialize)]
233#[serde(rename_all = "camelCase", tag = "code", content = "message")]
234pub enum BenchmarkSinkError {
235 #[error("payload codec error: {0}")]
236 PayloadCodec(String),
237 #[error("plugin ABI violation: {0}")]
238 AbiViolation(String),
239 #[error("sink failed: {0}")]
240 SinkFailed(String),
241 #[error("sink protocol violation: {0}")]
242 ProtocolViolation(String),
243}
244
245impl From<PluginProtocolViolation> for BenchmarkSinkError {
246 fn from(value: PluginProtocolViolation) -> Self {
247 Self::ProtocolViolation(value.to_string())
248 }
249}
250
251pub trait BenchmarkSink: Send + Sync {
253 fn name(&self) -> &str;
254
255 fn on_event_batch(
256 &self,
257 batch: &BenchmarkEventBatch,
258 ) -> Result<BenchmarkSinkStatus, BenchmarkSinkError>;
259
260 fn flush(&self) -> Result<BenchmarkSinkReport, BenchmarkSinkError> {
261 Ok(BenchmarkSinkReport::default())
262 }
263}
264
265#[cfg(test)]
266mod tests {
267 use super::*;
268
269 #[test]
270 fn batch_limit_is_part_of_the_protocol() {
271 let event = BenchmarkEvent {
272 run_id: "run".to_owned(),
273 session_id: "session".to_owned(),
274 platform: "test".to_owned(),
275 source_protocol: None,
276 event_name: "tick".to_owned(),
277 timestamp_ns: 0,
278 elapsed_ns: 0,
279 thread: None,
280 attributes: BTreeMap::new(),
281 };
282 let batch = BenchmarkEventBatch {
283 events: vec![event; MAX_BENCHMARK_BATCH_EVENTS + 1],
284 };
285 assert!(matches!(
286 batch.validate(),
287 Err(BenchmarkSinkError::ProtocolViolation(_))
288 ));
289 }
290
291 #[test]
292 fn sink_status_cannot_accept_more_events_than_the_input_batch() {
293 let status = BenchmarkSinkStatus { accepted_events: 2 };
294 assert!(matches!(
295 status.validate_for_batch(1),
296 Err(BenchmarkSinkError::ProtocolViolation(_))
297 ));
298 }
299
300 #[test]
301 fn benchmark_events_validate_all_transport_text_fields() {
302 let event = BenchmarkEvent {
303 run_id: String::new(),
304 session_id: "session".to_owned(),
305 platform: "test".to_owned(),
306 source_protocol: None,
307 event_name: "tick".to_owned(),
308 timestamp_ns: 0,
309 elapsed_ns: 0,
310 thread: None,
311 attributes: BTreeMap::new(),
312 };
313
314 assert!(matches!(
315 event.validate(),
316 Err(BenchmarkSinkError::ProtocolViolation(message))
317 if message.contains("benchmark.run_id")
318 ));
319 }
320
321 #[test]
322 fn benchmark_reports_bound_threshold_violations() {
323 let violation = BenchmarkThresholdViolation {
324 measurement: "latency".to_owned(),
325 actual: 2.0,
326 threshold: 1.0,
327 comparison: "greater-than".to_owned(),
328 };
329 let report = BenchmarkSinkReport {
330 threshold_violations: vec![violation; MAX_BENCHMARK_THRESHOLD_VIOLATIONS + 1],
331 ..BenchmarkSinkReport::default()
332 };
333
334 assert!(matches!(
335 report.validate(),
336 Err(BenchmarkSinkError::ProtocolViolation(message))
337 if message.contains("threshold-violation")
338 ));
339 }
340}