1use crate::destination::BackendResourceId;
2use crate::error::InvalidError;
3use crate::filter::{FILTER_EVALUATOR_VERSION, FilterCodec};
4use crate::query::{AggFunc, Consistency, SqlDialect};
5use crate::schema::LogicalTypeKind;
6use crate::topology::WireTopology;
7use crate::validate::Validate;
8use serde::{Deserialize, Serialize};
9use std::collections::BTreeSet;
10
11pub mod feature {
18 pub const KV_CAS: u64 = 1 << 0;
20 pub const READ_YOUR_WRITES: u64 = 1 << 1;
22 pub const STRONG_CONSISTENCY: u64 = 1 << 2;
25 pub const KV_CAS_FENCED: u64 = 1 << 3;
27 pub const AGENT_WORKFLOW: u64 = 1 << 4;
30 pub const KEYWORD_SEARCH: u64 = 1 << 5;
32 pub const WATCH: u64 = 1 << 6;
35 pub const AUTHZ: u64 = 1 << 7;
37 pub const DESTINATIONS: u64 = 1 << 8;
40 pub const KV_FENCED_LEASES: u64 = 1 << 9;
48 pub const CONSUMER_FILTERS: u64 = 1 << 10;
55 pub const GROUP_POLICY_READS: u64 = 1 << 11;
62 pub const SESSIONS: u64 = 1 << 12;
64 pub const STREAM_TENANCY: u64 = 1 << 13;
68 pub const MATERIALIZATIONS: u64 = 1 << 14;
72}
73
74#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
79#[non_exhaustive]
80pub struct OpVersions {
81 pub query: u32,
82 pub control: u32,
83 pub kv: u32,
84 pub fork: u32,
85 #[serde(default, skip_serializing_if = "is_zero")]
89 pub agent: u32,
90 #[serde(default, skip_serializing_if = "is_zero")]
95 pub graph: u32,
96 #[serde(default, skip_serializing_if = "is_zero")]
99 pub filter: u32,
100 #[serde(default, skip_serializing_if = "is_zero_u64")]
106 pub features: u64,
107}
108
109fn is_zero(value: &u32) -> bool {
110 *value == 0
111}
112
113fn is_zero_u64(value: &u64) -> bool {
114 *value == 0
115}
116
117impl OpVersions {
118 pub fn new(query: u32, control: u32, kv: u32, fork: u32) -> Self {
121 Self {
122 query,
123 control,
124 kv,
125 fork,
126 agent: 0,
127 graph: 0,
128 filter: 0,
129 features: 0,
130 }
131 }
132
133 #[must_use]
135 pub fn with_agent(mut self, agent: u32) -> Self {
136 self.agent = agent;
137 self
138 }
139
140 #[must_use]
142 pub fn with_graph(mut self, graph: u32) -> Self {
143 self.graph = graph;
144 self
145 }
146
147 #[must_use]
149 pub fn with_filter(mut self, filter: u32) -> Self {
150 self.filter = filter;
151 self
152 }
153
154 #[must_use]
157 pub fn with_features(mut self, features: u64) -> Self {
158 self.features = features;
159 self
160 }
161
162 pub const fn has_feature(&self, bit: u64) -> bool {
164 self.features & bit == bit
165 }
166}
167
168#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
174#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
175#[non_exhaustive]
176pub struct HelloReply {
177 pub versions: OpVersions,
178}
179
180impl HelloReply {
181 pub fn new(versions: OpVersions) -> Self {
183 Self { versions }
184 }
185}
186
187pub const BACKEND_DESCRIPTOR_VERSION: u32 = 1;
188
189#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
191#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
192#[non_exhaustive]
193pub struct BackendDescriptor {
194 pub descriptor_version: u32,
195 pub resource_id: BackendResourceId,
196 pub mode: BackendMode,
197 pub label: String,
198 pub implementation: BackendImplementation,
199 pub observed_backend_generation: u64,
200 pub runtime_configuration_revision: u64,
201 pub desired_state: BackendDesiredState,
202 pub observed_state: BackendObservedState,
203 pub readiness: BackendReadiness,
204 #[serde(default, skip_serializing_if = "Option::is_none")]
205 pub query: Option<QueryCapabilities>,
206 pub schema: SchemaCapabilities,
207 pub limits: BackendLimits,
208}
209
210impl BackendDescriptor {
211 pub fn new(
212 resource_id: BackendResourceId,
213 mode: BackendMode,
214 label: impl Into<String>,
215 implementation: BackendImplementation,
216 observed_backend_generation: u64,
217 runtime_configuration_revision: u64,
218 ) -> Self {
219 Self {
220 descriptor_version: BACKEND_DESCRIPTOR_VERSION,
221 resource_id,
222 mode,
223 label: label.into(),
224 implementation,
225 observed_backend_generation,
226 runtime_configuration_revision,
227 desired_state: BackendDesiredState::Disabled,
228 observed_state: BackendObservedState::Disabled,
229 readiness: BackendReadiness::not_ready(BackendReadinessCode::Disabled),
230 query: None,
231 schema: SchemaCapabilities::default(),
232 limits: BackendLimits::default(),
233 }
234 }
235
236 #[must_use]
237 pub fn with_state(
238 mut self,
239 desired_state: BackendDesiredState,
240 observed_state: BackendObservedState,
241 readiness: BackendReadiness,
242 ) -> Self {
243 self.desired_state = desired_state;
244 self.observed_state = observed_state;
245 self.readiness = readiness;
246 self
247 }
248
249 #[must_use]
250 pub fn with_query(mut self, capabilities: QueryCapabilities) -> Self {
251 self.query = Some(capabilities);
252 self
253 }
254
255 #[must_use]
256 pub fn with_schema(mut self, capabilities: SchemaCapabilities) -> Self {
257 self.schema = capabilities;
258 self
259 }
260
261 #[must_use]
262 pub fn with_limits(mut self, limits: BackendLimits) -> Self {
263 self.limits = limits;
264 self
265 }
266}
267
268impl Validate for BackendDescriptor {
269 fn validate(&self) -> Result<(), InvalidError> {
270 if self.descriptor_version != BACKEND_DESCRIPTOR_VERSION {
271 return Err(InvalidError::new(format!(
272 "backend descriptor version must be {BACKEND_DESCRIPTOR_VERSION}"
273 )));
274 }
275 if self.resource_id.as_u128() == 0
276 || self.observed_backend_generation == 0
277 || self.runtime_configuration_revision == 0
278 {
279 return Err(InvalidError::new(
280 "backend identity and observed revisions must be nonzero",
281 ));
282 }
283 validate_descriptor_text("backend label", &self.label)?;
284 validate_descriptor_text("backend implementation kind", &self.implementation.kind)?;
285 validate_descriptor_text(
286 "backend implementation version",
287 &self.implementation.version,
288 )?;
289 self.readiness.validate()?;
290 if self.readiness.ready && self.observed_state != BackendObservedState::Ready {
291 return Err(InvalidError::new(
292 "ready backend must report the ready observed state",
293 ));
294 }
295 if let Some(query) = &self.query {
296 query.validate()?;
297 }
298 if self.readiness.ready {
299 if self.schema.logical_schema && self.limits.max_schema_fields == 0 {
300 return Err(InvalidError::new(
301 "ready logical-schema backend must advertise a schema-field limit",
302 ));
303 }
304 if self.query.is_some()
305 && (self.limits.max_query_rows == 0
306 || self.limits.max_query_bytes == 0
307 || self.limits.max_scan_bytes == 0
308 || self.limits.max_query_micros == 0
309 || self.limits.max_concurrent_queries == 0)
310 {
311 return Err(InvalidError::new(
312 "ready query backend must advertise nonzero query limits",
313 ));
314 }
315 }
316 Ok(())
317 }
318}
319
320#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
321#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
322#[serde(rename_all = "snake_case")]
323#[non_exhaustive]
324pub enum BackendMode {
325 Operational,
326}
327
328#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
329#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
330pub struct BackendImplementation {
331 pub kind: String,
332 pub version: String,
333}
334
335#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
336#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
337#[serde(rename_all = "snake_case")]
338#[non_exhaustive]
339pub enum BackendDesiredState {
340 Disabled,
341 Enabled,
342}
343
344#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
345#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
346#[serde(rename_all = "snake_case")]
347#[non_exhaustive]
348pub enum BackendObservedState {
349 Disabled,
350 Starting,
351 Ready,
352 Degraded,
353 Unavailable,
354}
355
356#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
357#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
358pub struct BackendReadiness {
359 pub ready: bool,
360 pub reasons: Vec<BackendReadinessReason>,
361 pub observed_at_micros: u64,
362}
363
364impl BackendReadiness {
365 pub fn not_ready(code: BackendReadinessCode) -> Self {
366 Self {
367 ready: false,
368 reasons: vec![BackendReadinessReason { code, detail: None }],
369 observed_at_micros: 0,
370 }
371 }
372
373 pub fn ready(observed_at_micros: u64) -> Self {
374 Self {
375 ready: true,
376 reasons: Vec::new(),
377 observed_at_micros,
378 }
379 }
380}
381
382impl Validate for BackendReadiness {
383 fn validate(&self) -> Result<(), InvalidError> {
384 if self.ready {
385 if !self.reasons.is_empty() || self.observed_at_micros == 0 {
386 return Err(InvalidError::new(
387 "ready backend requires an observation time and no failure reasons",
388 ));
389 }
390 return Ok(());
391 }
392 if self.reasons.is_empty() {
393 return Err(InvalidError::new(
394 "not-ready backend requires at least one stable reason",
395 ));
396 }
397 if self.reasons.len() > 32 {
398 return Err(InvalidError::new(
399 "backend readiness reason count exceeds cap 32",
400 ));
401 }
402 for reason in &self.reasons {
403 if let Some(detail) = &reason.detail {
404 validate_descriptor_text("backend readiness detail", detail)?;
405 }
406 }
407 Ok(())
408 }
409}
410
411#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
412#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
413pub struct BackendReadinessReason {
414 pub code: BackendReadinessCode,
415 #[serde(default, skip_serializing_if = "Option::is_none")]
416 pub detail: Option<String>,
417}
418
419#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
420#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
421#[serde(rename_all = "snake_case")]
422#[non_exhaustive]
423pub enum BackendReadinessCode {
424 Disabled,
425 ConfigurationPending,
426 ConfigurationRejected,
427 CredentialUnavailable,
428 ObjectStoreUnavailable,
429 CatalogUnavailable,
430 QueryRuntimeUnavailable,
431 GenerationMismatch,
432 ProbeFailed,
433 QueryIdentityRejected,
435}
436
437#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
438#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
439pub struct QueryCapabilities {
440 pub dialects: Vec<SqlDialect>,
441 pub consistency: Vec<Consistency>,
442 pub logical_types: Vec<LogicalTypeKind>,
443 pub raw_sql: bool,
444 #[serde(default, skip_serializing_if = "Vec::is_empty")]
446 pub aggregates: Vec<AggFunc>,
447 #[serde(default)]
448 pub vector_search: bool,
449 #[serde(default)]
450 pub text_search: bool,
451}
452
453impl Validate for QueryCapabilities {
454 fn validate(&self) -> Result<(), InvalidError> {
455 if self.dialects.is_empty() || self.consistency.is_empty() || self.logical_types.is_empty()
456 {
457 return Err(InvalidError::new(
458 "query capabilities require dialect, consistency, and logical-type coverage",
459 ));
460 }
461 ensure_unique(
462 "query dialect",
463 self.dialects.iter().map(|value| *value as u8),
464 )?;
465 ensure_unique(
466 "query consistency",
467 self.consistency.iter().map(|value| *value as u8),
468 )?;
469 ensure_unique(
470 "query logical type",
471 self.logical_types.iter().map(|value| *value as u8),
472 )?;
473 ensure_unique(
474 "query aggregate",
475 self.aggregates.iter().map(|value| *value as u8),
476 )?;
477 if self.raw_sql && self.dialects.is_empty() {
478 return Err(InvalidError::new(
479 "raw SQL capability requires an explicit dialect",
480 ));
481 }
482 Ok(())
483 }
484}
485
486fn ensure_unique(label: &str, values: impl IntoIterator<Item = u8>) -> Result<(), InvalidError> {
487 let mut seen = BTreeSet::new();
488 if values.into_iter().all(|value| seen.insert(value)) {
489 Ok(())
490 } else {
491 Err(InvalidError::new(format!("backend repeats a {label}")))
492 }
493}
494
495fn validate_descriptor_text(label: &str, value: &str) -> Result<(), InvalidError> {
496 if value.is_empty() || value.len() > 4096 || value.chars().any(char::is_control) {
497 return Err(InvalidError::new(format!(
498 "{label} must contain 1..=4096 bytes without control characters"
499 )));
500 }
501 Ok(())
502}
503
504#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
505#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
506pub struct SchemaCapabilities {
507 pub logical_schema: bool,
508 pub arrow_ipc_stream: bool,
509 pub schema_evolution: bool,
510}
511
512#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
513#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
514pub struct BackendLimits {
515 pub max_query_rows: u64,
516 pub max_query_bytes: u64,
517 pub max_scan_bytes: u64,
518 pub max_query_micros: u64,
519 pub max_concurrent_queries: u32,
520 pub max_schema_fields: u32,
521 #[serde(default)]
523 pub max_payload_bytes: u64,
524}
525
526const fn backend_ready_by_default() -> bool {
536 true
537}
538
539const fn backend_is_ready(ready: &bool) -> bool {
540 *ready
541}
542
543#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
544#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
545#[non_exhaustive]
546pub struct BackendAnnounce {
547 pub versions: OpVersions,
548 #[serde(
549 default = "backend_ready_by_default",
550 skip_serializing_if = "backend_is_ready"
551 )]
552 pub ready: bool,
553 #[serde(default, skip_serializing_if = "Vec::is_empty")]
558 pub backends: Vec<BackendDescriptor>,
559 #[serde(default, skip_serializing_if = "Option::is_none")]
564 pub topology: Option<WireTopology>,
565 #[serde(default, skip_serializing_if = "Option::is_none")]
569 pub filters: Option<FilterAnnounce>,
570}
571
572#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
577#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
578pub struct FilterAnnounce {
579 pub evaluator_version: u32,
580 #[serde(default, skip_serializing_if = "Vec::is_empty")]
581 pub codecs: Vec<FilterCodec>,
582 #[serde(default, skip_serializing_if = "is_zero_u32")]
585 pub max_wait_ms: u32,
586}
587
588impl FilterAnnounce {
589 pub fn served() -> Self {
591 Self {
592 evaluator_version: FILTER_EVALUATOR_VERSION,
593 codecs: vec![
594 FilterCodec::Json,
595 FilterCodec::HeadersOnly,
596 FilterCodec::Avro,
597 FilterCodec::Protobuf,
598 FilterCodec::Cbor,
599 ],
600 max_wait_ms: 0,
601 }
602 }
603
604 pub fn evaluates(&self, evaluator_version: u32, codec: FilterCodec) -> bool {
607 self.evaluator_version == evaluator_version && self.codecs.contains(&codec)
608 }
609}
610
611impl BackendAnnounce {
612 pub fn new(versions: OpVersions) -> Self {
614 Self {
615 versions,
616 ready: true,
617 backends: Vec::new(),
618 topology: None,
619 filters: None,
620 }
621 }
622
623 #[must_use]
625 pub fn with_filters(mut self, filters: FilterAnnounce) -> Self {
626 self.filters = Some(filters);
627 self
628 }
629
630 #[must_use]
631 pub const fn unavailable(mut self) -> Self {
632 self.ready = false;
633 self
634 }
635
636 #[must_use]
638 pub fn with_backends(mut self, backends: Vec<BackendDescriptor>) -> Self {
639 self.backends = backends;
640 self
641 }
642
643 #[must_use]
645 pub fn with_topology(mut self, topology: WireTopology) -> Self {
646 self.topology = Some(topology);
647 self
648 }
649}
650
651impl Validate for BackendAnnounce {
652 fn validate(&self) -> Result<(), InvalidError> {
653 let mut resources = BTreeSet::new();
654 for backend in &self.backends {
655 backend.validate()?;
656 if !resources.insert(backend.resource_id) {
657 return Err(InvalidError::new(
658 "backend announcement repeats a resource id",
659 ));
660 }
661 }
662 if self.ready
663 && !self.backends.is_empty()
664 && !self.backends.iter().any(|backend| backend.readiness.ready)
665 {
666 return Err(InvalidError::new(
667 "ready backend announcement must contain a ready backend",
668 ));
669 }
670 Ok(())
671 }
672}
673
674#[cfg(all(test, feature = "cbor"))]
675mod tests {
676 use super::*;
677 use crate::codes::{CONTROL_OP_VERSION, FORK_OP_VERSION, KV_OP_VERSION, QUERY_OP_VERSION};
678 use crate::framing::{decode_named, encode_named};
679
680 fn backend(resource_id: u128, mode: BackendMode, label: &str, kind: &str) -> BackendDescriptor {
681 BackendDescriptor::new(
682 BackendResourceId::from_u128(resource_id),
683 mode,
684 label,
685 BackendImplementation {
686 kind: kind.to_owned(),
687 version: "1.0.0".to_owned(),
688 },
689 1,
690 1,
691 )
692 }
693
694 #[test]
695 fn given_a_hello_reply_when_round_tripped_then_should_preserve_versions() {
696 let reply = HelloReply::new(OpVersions::new(
699 QUERY_OP_VERSION,
700 CONTROL_OP_VERSION,
701 KV_OP_VERSION,
702 FORK_OP_VERSION,
703 ));
704 let bytes = encode_named(&reply).expect("hello reply serializes");
705 let back: HelloReply = decode_named(&bytes).expect("hello reply deserializes");
706 assert_eq!(back, reply);
707 }
708
709 #[test]
710 fn given_a_backend_announce_when_round_tripped_then_should_preserve_features() {
711 let announce = BackendAnnounce::new(
712 OpVersions::new(
713 QUERY_OP_VERSION,
714 CONTROL_OP_VERSION,
715 KV_OP_VERSION,
716 FORK_OP_VERSION,
717 )
718 .with_features(feature::KV_CAS | feature::READ_YOUR_WRITES),
719 );
720 let bytes = encode_named(&announce).expect("serializes");
721 let back: BackendAnnounce = decode_named(&bytes).expect("deserializes");
722 assert_eq!(back, announce);
723 assert!(back.versions.has_feature(feature::KV_CAS));
724 }
725
726 #[test]
727 fn given_an_unavailable_backend_announce_when_round_tripped_then_should_stay_unavailable() {
728 let announce = BackendAnnounce::new(OpVersions::new(
729 QUERY_OP_VERSION,
730 CONTROL_OP_VERSION,
731 KV_OP_VERSION,
732 FORK_OP_VERSION,
733 ))
734 .unavailable();
735 let bytes = encode_named(&announce).expect("serializes");
736 let back: BackendAnnounce = decode_named(&bytes).expect("deserializes");
737 assert!(!back.ready);
738 }
739
740 #[test]
741 fn given_an_empty_hello_body_when_decoded_then_should_yield_no_versions() {
742 assert!(decode_named::<HelloReply>(&[]).is_err());
745 }
746
747 #[test]
748 fn given_advertised_backends_when_round_tripped_then_should_preserve_them_and_skip_empty() {
749 let announce = BackendAnnounce::new(OpVersions::new(
750 QUERY_OP_VERSION,
751 CONTROL_OP_VERSION,
752 KV_OP_VERSION,
753 FORK_OP_VERSION,
754 ))
755 .with_backends(vec![
756 backend(1, BackendMode::Operational, "Embedded", "embedded"),
757 backend(
758 2,
759 BackendMode::Operational,
760 "Analytics warehouse",
761 "columnar",
762 ),
763 ]);
764 let bytes = encode_named(&announce).expect("encodes");
765 let back: BackendAnnounce = decode_named(&bytes).expect("decodes");
766 assert_eq!(back, announce);
767 assert_eq!(back.backends.len(), 2);
768 assert_eq!(
769 back.backends[1].resource_id,
770 BackendResourceId::from_u128(2)
771 );
772 assert_eq!(back.backends[1].implementation.kind, "columnar");
773 assert_eq!(back.backends[1].label, "Analytics warehouse");
774
775 let plain = BackendAnnounce::new(OpVersions::new(1, 1, 1, 1));
778 let json = serde_json::to_string(&plain).expect("json");
779 assert!(!json.contains("backends"), "empty backends omitted: {json}");
780 }
781
782 #[test]
783 fn given_announce_without_topology_when_decoded_then_should_default_none() {
784 let announce = BackendAnnounce::new(OpVersions::new(
785 QUERY_OP_VERSION,
786 CONTROL_OP_VERSION,
787 KV_OP_VERSION,
788 FORK_OP_VERSION,
789 ));
790 let bytes = encode_named(&announce).expect("encodes");
791 let back: BackendAnnounce = decode_named(&bytes).expect("decodes");
792 assert_eq!(back.topology, None);
793 let json = serde_json::to_string(&announce).expect("json");
794 assert!(
795 !json.contains("topology"),
796 "absent topology omitted: {json}"
797 );
798 }
799
800 #[test]
801 fn given_announce_with_topology_when_round_tripped_then_should_preserve_it() {
802 let custom = WireTopology {
803 ops_stream: "custom-ops".to_owned(),
804 ..WireTopology::default()
805 };
806 let announce = BackendAnnounce::new(OpVersions::new(
807 QUERY_OP_VERSION,
808 CONTROL_OP_VERSION,
809 KV_OP_VERSION,
810 FORK_OP_VERSION,
811 ))
812 .with_topology(custom.clone());
813 let bytes = encode_named(&announce).expect("encodes");
814 let back: BackendAnnounce = decode_named(&bytes).expect("decodes");
815 assert_eq!(back.topology, Some(custom));
816 }
817
818 #[test]
819 fn given_advertised_features_when_round_tripped_then_should_preserve_bits_and_skip_zero() {
820 let versions = OpVersions::new(
821 QUERY_OP_VERSION,
822 CONTROL_OP_VERSION,
823 KV_OP_VERSION,
824 FORK_OP_VERSION,
825 )
826 .with_features(feature::KV_CAS | feature::READ_YOUR_WRITES);
827 assert!(versions.has_feature(feature::KV_CAS));
828 assert!(versions.has_feature(feature::READ_YOUR_WRITES));
829 assert!(!versions.has_feature(feature::STRONG_CONSISTENCY));
830 assert!(versions.has_feature(feature::KV_CAS | feature::READ_YOUR_WRITES));
832 assert!(!versions.has_feature(feature::KV_CAS | feature::STRONG_CONSISTENCY));
833 let reply = HelloReply::new(versions);
834 let bytes = encode_named(&reply).expect("encodes");
835 let back: HelloReply = decode_named(&bytes).expect("decodes");
836 assert_eq!(back, reply);
837 assert!(back.versions.has_feature(feature::READ_YOUR_WRITES));
838 let plain = HelloReply::new(OpVersions::new(1, 1, 1, 1));
841 let json = serde_json::to_string(&plain).expect("json");
842 assert!(!json.contains("features"), "zero features omitted: {json}");
843 }
844
845 #[test]
846 fn given_announced_filter_evaluation_when_round_tripped_then_should_gate_codecs_and_versions() {
847 let announce = BackendAnnounce::new(OpVersions::new(1, 1, 1, 1))
848 .with_filters(FilterAnnounce::served());
849 let bytes = encode_named(&announce).expect("serializes");
850 let back: BackendAnnounce = decode_named(&bytes).expect("deserializes");
851 let filters = back.filters.expect("the evaluation is announced");
852 assert!(filters.evaluates(FILTER_EVALUATOR_VERSION, FilterCodec::Json));
853 assert!(!filters.evaluates(FILTER_EVALUATOR_VERSION + 1, FilterCodec::Json));
854 assert!(!filters.evaluates(FILTER_EVALUATOR_VERSION, FilterCodec::Unknown));
855 let plain =
856 encode_named(&BackendAnnounce::new(OpVersions::new(1, 1, 1, 1))).expect("serializes");
857 let older: BackendAnnounce = decode_named(&plain).expect("deserializes");
858 assert_eq!(older.filters, None);
859 }
860
861 #[test]
862 fn given_the_feature_bits_when_read_then_should_match_the_pinned_values() {
863 assert_eq!(
864 [
865 feature::KV_CAS,
866 feature::READ_YOUR_WRITES,
867 feature::STRONG_CONSISTENCY,
868 feature::KV_CAS_FENCED,
869 feature::AGENT_WORKFLOW,
870 feature::KEYWORD_SEARCH,
871 feature::WATCH,
872 feature::AUTHZ,
873 feature::DESTINATIONS,
874 feature::KV_FENCED_LEASES,
875 feature::CONSUMER_FILTERS,
876 feature::GROUP_POLICY_READS,
877 feature::SESSIONS,
878 feature::STREAM_TENANCY,
879 feature::MATERIALIZATIONS,
880 ],
881 [
882 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384
883 ]
884 );
885 }
886
887 #[test]
888 fn given_op_versions_with_zero_surfaces_when_encoded_then_should_omit_them_and_keep_set_ones() {
889 let advertised = OpVersions::new(1, 1, 1, 1)
890 .with_agent(2)
891 .with_graph(3)
892 .with_filter(4);
893 let json = serde_json::to_value(advertised).expect("encode advertised surfaces");
894 let decoded: OpVersions = serde_json::from_value(json).expect("decode advertised surfaces");
895 assert_eq!(decoded, advertised);
896 let plain =
897 serde_json::to_value(OpVersions::new(1, 1, 1, 1)).expect("encode base surfaces");
898 assert_eq!(
899 (plain.get("agent"), plain.get("graph"), plain.get("filter")),
900 (None, None, None)
901 );
902 }
903
904 #[test]
905 fn given_a_ready_announce_with_a_filter_wait_when_encoded_then_should_keep_only_the_wait() {
906 let waiting =
907 BackendAnnounce::new(OpVersions::new(1, 1, 1, 1)).with_filters(FilterAnnounce {
908 max_wait_ms: 250,
909 ..FilterAnnounce::served()
910 });
911 let json = serde_json::to_value(&waiting).expect("encode a ready announce");
912 assert!(
913 json.get("ready").is_none(),
914 "a ready announce omits ready: {json}"
915 );
916 let decoded: BackendAnnounce =
917 serde_json::from_value(json).expect("decode a ready announce");
918 assert_eq!(decoded, waiting);
919 let served =
920 serde_json::to_value(FilterAnnounce::served()).expect("encode the served evaluation");
921 assert!(
922 served.get("max_wait_ms").is_none(),
923 "a zero wait is omitted: {served}"
924 );
925 }
926
927 #[test]
928 fn given_a_backend_descriptor_when_validated_then_should_refuse_each_broken_invariant() {
929 let ready = ready_backend(1);
930 ready.validate().expect("a ready backend with every limit");
931 backend(1, BackendMode::Operational, "Embedded", "embedded")
932 .validate()
933 .expect("a backend that is not ready");
934 BackendDescriptor {
935 label: "l".repeat(4096),
936 ..ready.clone()
937 }
938 .validate()
939 .expect("a label at the cap");
940 let refused = [
941 (
942 "another descriptor version",
943 BackendDescriptor {
944 descriptor_version: BACKEND_DESCRIPTOR_VERSION + 1,
945 ..ready.clone()
946 },
947 ),
948 (
949 "a zero resource id",
950 BackendDescriptor {
951 resource_id: BackendResourceId::from_u128(0),
952 ..ready.clone()
953 },
954 ),
955 (
956 "a zero backend generation",
957 BackendDescriptor {
958 observed_backend_generation: 0,
959 ..ready.clone()
960 },
961 ),
962 (
963 "a zero configuration revision",
964 BackendDescriptor {
965 runtime_configuration_revision: 0,
966 ..ready.clone()
967 },
968 ),
969 (
970 "an empty label",
971 BackendDescriptor {
972 label: String::new(),
973 ..ready.clone()
974 },
975 ),
976 (
977 "a label past the cap",
978 BackendDescriptor {
979 label: "l".repeat(4097),
980 ..ready.clone()
981 },
982 ),
983 (
984 "a ready backend still starting",
985 BackendDescriptor {
986 observed_state: BackendObservedState::Starting,
987 ..ready.clone()
988 },
989 ),
990 (
991 "a logical schema without a field limit",
992 BackendDescriptor {
993 limits: BackendLimits {
994 max_schema_fields: 0,
995 ..ready.limits.clone()
996 },
997 ..ready.clone()
998 },
999 ),
1000 ];
1001 for (case, descriptor) in refused {
1002 assert!(descriptor.validate().is_err(), "{case} must be refused");
1003 }
1004 let limits = &ready.limits;
1005 let zero_query_limits = [
1006 BackendLimits {
1007 max_query_rows: 0,
1008 ..limits.clone()
1009 },
1010 BackendLimits {
1011 max_query_bytes: 0,
1012 ..limits.clone()
1013 },
1014 BackendLimits {
1015 max_scan_bytes: 0,
1016 ..limits.clone()
1017 },
1018 BackendLimits {
1019 max_query_micros: 0,
1020 ..limits.clone()
1021 },
1022 BackendLimits {
1023 max_concurrent_queries: 0,
1024 ..limits.clone()
1025 },
1026 ];
1027 for limits in zero_query_limits {
1028 let descriptor = BackendDescriptor {
1029 limits,
1030 ..ready.clone()
1031 };
1032 assert!(
1033 descriptor.validate().is_err(),
1034 "a ready query backend needs every query limit"
1035 );
1036 }
1037 }
1038
1039 #[test]
1040 fn given_backend_readiness_when_validated_then_should_need_a_time_or_a_bounded_reason_list() {
1041 let not_ready = |reasons: usize| BackendReadiness {
1042 ready: false,
1043 reasons: vec![
1044 BackendReadinessReason {
1045 code: BackendReadinessCode::ProbeFailed,
1046 detail: None,
1047 };
1048 reasons
1049 ],
1050 observed_at_micros: 0,
1051 };
1052 BackendReadiness::ready(5)
1053 .validate()
1054 .expect("ready with an observation time");
1055 not_ready(32).validate().expect("reasons at the cap");
1056 assert!(not_ready(33).validate().is_err(), "reasons past the cap");
1057 assert!(
1058 BackendReadiness::ready(0).validate().is_err(),
1059 "ready without an observation time"
1060 );
1061 }
1062
1063 #[test]
1064 fn given_query_capabilities_when_validated_then_should_need_coverage_without_repeats() {
1065 capabilities()
1066 .validate()
1067 .expect("full coverage with raw SQL");
1068 let refused = [
1069 (
1070 "no dialect",
1071 QueryCapabilities {
1072 dialects: Vec::new(),
1073 raw_sql: false,
1074 ..capabilities()
1075 },
1076 ),
1077 (
1078 "no consistency level",
1079 QueryCapabilities {
1080 consistency: Vec::new(),
1081 ..capabilities()
1082 },
1083 ),
1084 (
1085 "no logical type",
1086 QueryCapabilities {
1087 logical_types: Vec::new(),
1088 ..capabilities()
1089 },
1090 ),
1091 (
1092 "a repeated dialect",
1093 QueryCapabilities {
1094 dialects: vec![SqlDialect::Postgres, SqlDialect::Postgres],
1095 ..capabilities()
1096 },
1097 ),
1098 ];
1099 for (case, rejected) in refused {
1100 assert!(rejected.validate().is_err(), "{case} must be refused");
1101 }
1102 }
1103
1104 #[test]
1105 fn given_a_backend_announce_when_validated_then_should_need_unique_ids_and_a_ready_backend() {
1106 let versions = OpVersions::new(1, 1, 1, 1);
1107 let not_ready = backend(2, BackendMode::Operational, "Analytics", "columnar");
1108 BackendAnnounce::new(versions)
1109 .validate()
1110 .expect("a ready announce without backends");
1111 BackendAnnounce::new(versions)
1112 .with_backends(vec![ready_backend(1), not_ready.clone()])
1113 .validate()
1114 .expect("a ready announce with a ready backend");
1115 assert!(
1116 BackendAnnounce::new(versions)
1117 .with_backends(vec![not_ready])
1118 .validate()
1119 .is_err(),
1120 "a ready announce without a ready backend"
1121 );
1122 assert!(
1123 BackendAnnounce::new(versions)
1124 .with_backends(vec![ready_backend(1), ready_backend(1)])
1125 .validate()
1126 .is_err(),
1127 "a repeated resource id"
1128 );
1129 }
1130
1131 fn ready_backend(resource_id: u128) -> BackendDescriptor {
1132 backend(
1133 resource_id,
1134 BackendMode::Operational,
1135 "Embedded",
1136 "embedded",
1137 )
1138 .with_state(
1139 BackendDesiredState::Enabled,
1140 BackendObservedState::Ready,
1141 BackendReadiness::ready(5),
1142 )
1143 .with_query(capabilities())
1144 .with_schema(SchemaCapabilities {
1145 logical_schema: true,
1146 arrow_ipc_stream: false,
1147 schema_evolution: false,
1148 })
1149 .with_limits(BackendLimits {
1150 max_query_rows: 1000,
1151 max_query_bytes: 1_048_576,
1152 max_scan_bytes: 1_073_741_824,
1153 max_query_micros: 1_000_000,
1154 max_concurrent_queries: 8,
1155 max_schema_fields: 64,
1156 max_payload_bytes: 0,
1157 })
1158 }
1159
1160 fn capabilities() -> QueryCapabilities {
1161 QueryCapabilities {
1162 dialects: vec![SqlDialect::Postgres],
1163 consistency: vec![Consistency::Eventual],
1164 logical_types: vec![LogicalTypeKind::String],
1165 raw_sql: true,
1166 aggregates: vec![AggFunc::Count],
1167 vector_search: false,
1168 text_search: false,
1169 }
1170 }
1171}
1172const fn is_zero_u32(value: &u32) -> bool {
1173 *value == 0
1174}