Skip to main content

laser_wire/
hello.rs

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
11/// Capability feature bits advertised in [`OpVersions::features`]. Each constant
12/// names one managed sub-feature a server serves beyond the base surface, so a
13/// binary client feature-detects it (before attempting the op) the way the HTTP
14/// surface reads the boolean flags on `Capabilities`. Additive and pinned
15/// cross-repo: a new bit is set by a newer server and ignored by an older
16/// client (which simply does not light up that capability).
17pub mod feature {
18    /// The key-value store serves compare-and-swap (`AGDX_KV_CAS`).
19    pub const KV_CAS: u64 = 1 << 0;
20    /// The query surface honors `Consistency::ReadYourWrites`.
21    pub const READ_YOUR_WRITES: u64 = 1 << 1;
22    /// Retired with linearizable query reads. No server sets it and the bit is
23    /// never reused.
24    pub const STRONG_CONSISTENCY: u64 = 1 << 2;
25    /// The key-value store serves fenced compare-and-swap (`AGDX_KV_CAS_FENCED`).
26    pub const KV_CAS_FENCED: u64 = 1 << 3;
27    /// Retired with the run registry. No server sets it and the bit is never
28    /// reused.
29    pub const AGENT_WORKFLOW: u64 = 1 << 4;
30    /// The query surface serves lexical relevance search (`Query.text`).
31    pub const KEYWORD_SEARCH: u64 = 1 << 5;
32    /// The deployment publishes the change feed (`ChangeRecord`s on the
33    /// changes topic) for bindings that opt into `notify`.
34    pub const WATCH: u64 = 1 << 6;
35    /// The streaming server serves the authorization control band (`AGDX_AUTHZ_*`).
36    pub const AUTHZ: u64 = 1 << 7;
37    /// Retired with lakehouse destinations. No server sets it and the bit is
38    /// never reused.
39    pub const DESTINATIONS: u64 = 1 << 8;
40    /// The key-value store serves the revocable fenced-lease contract at
41    /// `KV_LEASE_OP_VERSION`: holder-scoped acquire, renewal
42    /// (`AGDX_KV_LEASE_RENEW`), holder-and-fence-validated release, fenced
43    /// compare-and-swap requiring a live lease, and the barriered read
44    /// (`KvGet::min_position`). Subsumes [`KV_CAS_FENCED`]: a client must not
45    /// send the reshaped lease ops (or a barriered read) to a server without
46    /// this bit, which would silently decode them under the old contract.
47    pub const KV_FENCED_LEASES: u64 = 1 << 9;
48    /// The streaming server serves consumer filters: filtered reads, fenced
49    /// acknowledgments, previews, sample tests, and validation
50    /// (`AGDX_FILTERED_POLL` and the rest of the delivery band's server-native
51    /// decade). Server-native, so it holds with the managed backend disabled.
52    /// The saved-filter catalog additionally needs the backend's `filter` op
53    /// version.
54    pub const CONSUMER_FILTERS: u64 = 1 << 10;
55    /// The streaming server serves group-aware reads: `FilterRef::Group`
56    /// resolves a consumer group's own policy, an unbound group is delivered
57    /// unfiltered without payload decoding, pages and acknowledgments carry the
58    /// execution mode and policy generation, and the request may bound the
59    /// examined records and wait for a catalog position. A client must not send
60    /// the automatic selector to a server without this bit.
61    pub const GROUP_POLICY_READS: u64 = 1 << 11;
62    /// The managed backend serves session reads for one named stream.
63    pub const SESSIONS: u64 = 1 << 12;
64    /// The managed backend runs in stream tenancy: every managed name is
65    /// scoped to one stream, and the change feed and dead letters of each
66    /// stream ride their own ops topics.
67    pub const STREAM_TENANCY: u64 = 1 << 13;
68    /// The managed backend serves whole-record projections, control replies
69    /// that wait for the applied outcome, and binding status on the projection
70    /// browse.
71    pub const MATERIALIZATIONS: u64 = 1 << 14;
72}
73
74/// The wire op versions a server accepts, one per surface, plus the capability
75/// feature bits it advertises. A pinned wire shape, mirrored by the HTTP
76/// capabilities `versions` block.
77#[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    /// The agent envelope (AGDX) version LaserData Cloud consumes for its
86    /// conversation projections. `0` means "not advertised" and is skipped on
87    /// encode, so pre-AGDX hello frames stay byte-identical and decode unchanged.
88    #[serde(default, skip_serializing_if = "is_zero")]
89    pub agent: u32,
90    /// The knowledge-graph op version served. `0` means not served, skipped on
91    /// encode so a pre-graph hello frame stays byte-identical. Mirrors the
92    /// `managed_graph` HTTP capability flag. (Agentic memory rides this plus the
93    /// query surface, so it has no op version of its own.)
94    #[serde(default, skip_serializing_if = "is_zero")]
95    pub graph: u32,
96    /// The consumer-filter catalog op version served by the managed backend. Zero
97    /// means the catalog (saved filters and group bindings) is not served.
98    #[serde(default, skip_serializing_if = "is_zero")]
99    pub filter: u32,
100    /// Capability feature bits (see [`feature`]): managed sub-features served
101    /// beyond the base surface (compare-and-swap, read-your-writes, and the
102    /// rest). `0` (the default) is skipped on encode, so a pre-feature
103    /// hello reply stays byte-identical and an old client just sees no extra
104    /// capabilities.
105    #[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    /// Versions per surface. The struct is `#[non_exhaustive]` (new surfaces
119    /// land without a breaking change), so this is the constructor.
120    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    /// Returns a copy advertising this agent-envelope (AGDX) version.
134    #[must_use]
135    pub fn with_agent(mut self, agent: u32) -> Self {
136        self.agent = agent;
137        self
138    }
139
140    /// Returns a copy advertising the knowledge-graph op version served.
141    #[must_use]
142    pub fn with_graph(mut self, graph: u32) -> Self {
143        self.graph = graph;
144        self
145    }
146
147    /// Returns a copy advertising the consumer-filter catalog version served.
148    #[must_use]
149    pub fn with_filter(mut self, filter: u32) -> Self {
150        self.filter = filter;
151        self
152    }
153
154    /// Returns a copy advertising the capability feature bits in `features`
155    /// (an OR of [`feature`] constants).
156    #[must_use]
157    pub fn with_features(mut self, features: u64) -> Self {
158        self.features = features;
159        self
160    }
161
162    /// Whether a [`feature`] bit (or set of bits) is advertised.
163    pub const fn has_feature(&self, bit: u64) -> bool {
164        self.features & bit == bit
165    }
166}
167
168/// Body of the `AGDX_HELLO` probe reply: the wire op versions the server (and
169/// its managed backend) accepts, mirroring the HTTP capabilities `versions`
170/// block. A pinned wire shape. Pre-versioned
171/// servers answer the probe with an empty body, which a client treats as "no
172/// versions advertised", never an error.
173#[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    /// Constructor for the non-exhaustive wire struct.
182    pub fn new(versions: OpVersions) -> Self {
183        Self { versions }
184    }
185}
186
187pub const BACKEND_DESCRIPTOR_VERSION: u32 = 1;
188
189/// One observed backend resource and its structured, secret-free capabilities.
190#[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    /// The provisioned or configured raw SQL query identity failed its privilege check, so raw SQL is refused while materialization continues.
434    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    /// The aggregate functions the backend computes.
445    #[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    /// The largest record body a whole-record row stores.
522    #[serde(default)]
523    pub max_payload_bytes: u64,
524}
525
526/// The managed backend's capability announcement to the streaming server, sent over their
527/// private socket on connect (`AGDX_BACKEND_HELLO_CODE`). The streaming server caches the
528/// `versions` and the advertised `backends`, and relays them verbatim when it answers a
529/// client `AGDX_HELLO` / capabilities probe, so the streaming server never hardcodes feature
530/// bits or backend identities the backend may or may not serve.
531/// This makes the backend the single source of its own capability truth and
532/// keeps the binary `features` bitset and the HTTP capability flags in agreement
533/// with what is actually served. A separate type from [`HelloReply`] because the
534/// direction and sender differ (backend to streaming server, not server to client).
535const 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    /// Materialization backends the server currently exposes (the ones it has
554    /// open). A client routes only to an advertised id. Empty (the default) is
555    /// skipped on encode, so a pre-backends announce stays byte-identical and an
556    /// older reader simply sees no advertised backends.
557    #[serde(default, skip_serializing_if = "Vec::is_empty")]
558    pub backends: Vec<BackendDescriptor>,
559    /// The stream/topic names this deployment uses. Absent (the default) is
560    /// skipped on encode, so a pre-topology announce stays byte-identical and
561    /// an older reader sees no advertised topology (falls back to its
562    /// own [`WireTopology::default`]).
563    #[serde(default, skip_serializing_if = "Option::is_none")]
564    pub topology: Option<WireTopology>,
565    /// The consumer-filter evaluation the streaming server serves, set with
566    /// the `CONSUMER_FILTERS` bit. Absent from an older server, whose client
567    /// then assumes its own evaluator.
568    #[serde(default, skip_serializing_if = "Option::is_none")]
569    pub filters: Option<FilterAnnounce>,
570}
571
572/// The consumer-filter evaluation a server serves. A client refuses to run a
573/// filter under another evaluator version or with a codec the server does not
574/// list, so a version gap fails before the first page instead of filtering
575/// differently.
576#[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    /// Longest filtered wait the server holds. Zero means it serves no
583    /// filtered wait, so a reader paces idle rounds itself.
584    #[serde(default, skip_serializing_if = "is_zero_u32")]
585    pub max_wait_ms: u32,
586}
587
588impl FilterAnnounce {
589    /// What this build of the evaluator serves.
590    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    /// Whether a filter with `evaluator_version` and `codec` evaluates here
605    /// exactly as it would in the client that built it.
606    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    /// Constructor for the non-exhaustive wire struct.
613    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    /// Returns a copy announcing the served consumer-filter evaluation.
624    #[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    /// Returns a copy advertising `backends`.
637    #[must_use]
638    pub fn with_backends(mut self, backends: Vec<BackendDescriptor>) -> Self {
639        self.backends = backends;
640        self
641    }
642
643    /// Returns a copy advertising the deployment's `topology`.
644    #[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        // The pinned `HelloReply` shape (CBOR named fields). The connect-time
697        // probe decodes exactly this shape.
698        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        // Pre-versioned servers answer the probe with an empty body. The probe
743        // treats a failed decode as "no versions advertised", never an error.
744        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        // No advertised backends (the default) is omitted on the wire, so a
776        // pre-backends announce stays byte-identical.
777        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        // has_feature on a combined mask requires every bit present.
831        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        // No advertised feature (0) is omitted on the wire, so a pre-feature
839        // hello reply stays byte-identical.
840        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}