Skip to main content

subc_client_rs/
config.rs

1//! Opt-in module configuration delivery. See [`ModuleHandler`] for lifecycle hooks.
2//!
3//! Only an absent `config.gate` capability permits the existing file reader.
4//! Refusals retain the last applied view; no approved view is represented without
5//! inventing empty configuration bytes. Anchor-pending reports retry on the next
6//! `config.changed` hint. Review and apply hooks never occupy the frame reader.
7//!
8//! # A small module adopting the gate
9//!
10//! The hooks below are the entire adoption; an existing `handle` is unchanged.
11//! The declaration's user path is provided by the module's startup configuration.
12//! The review function uses only supplied bytes and the supplied old view.
13//!
14//! ```no_run
15//! use async_trait::async_trait;
16//! use serde_json::json;
17//! use std::sync::Mutex;
18//! use subc_client_rs::{ModuleHandler, RequestCtx, HandlerOutcome, config::*};
19//!
20//! struct Counter { user_file: String, value: Mutex<serde_json::Value> }
21//! fn schema() -> serde_json::Value {
22//!     json!({"$schema":"https://json-schema.org/draft/2020-12/schema",
23//!       "type":"object","unevaluatedProperties":false,"properties":{"count":{"type":"integer",
24//!       "description":"Counter value","default":0,"x-ck-apply":"live",
25//!       "x-ck-layers":["user"]}}})
26//! }
27//! fn review(request: ConfigReviewRequest) -> Result<ConfigReviewReply, String> {
28//!     let schema = Schema::new(schema()).map_err(|e| format!("{e:?}"))?;
29//!     let layers = request.layers.iter().filter_map(|l| l.bytes.as_ref().map(|b| (l,b)))
30//!         .map(|(l,b)| Ok(LayerValue::new(l.layer.known_layer().ok_or("unknown layer")?,
31//!             serde_json::from_slice(b).map_err(|_| "invalid JSON")?)))
32//!         .collect::<Result<Vec<_>, &str>>().map_err(str::to_owned)?;
33//!     let tuple = schema.review_tuple(&layers, &ValidationContext::new("counter", None))
34//!         .map_err(|_| "invalid counter configuration")?;
35//!     let old = request.base.as_ref().map(|v| v.effective.clone()).unwrap_or(json!({"count":null}));
36//!     let old_source = request.base.as_ref().and_then(|v| v.sources.get("/count")).copied().unwrap_or(Layer::Default);
37//!     if old["count"] == tuple.effective["count"] && old_source == tuple.sources["/count"] {
38//!         return Ok(ConfigReviewReply::new(vec![], vec![]));
39//!     }
40//!     let mut field = FieldChange::new("counter", "/count", RecordedValue::new(old["count"].clone()),
41//!         RecordedValue::new(tuple.effective["count"].clone()), ApplyKind::Live);
42//!     field.old_source = old_source;
43//!     field.new_source = tuple.sources["/count"];
44//!     Ok(ConfigReviewReply::new(vec![field], vec![]))
45//! }
46//! #[async_trait]
47//! impl ModuleHandler for Counter {
48//!     async fn handle(&self, _: RequestCtx, body: Vec<u8>) -> HandlerOutcome {
49//!         HandlerOutcome::Response(body)
50//!     }
51//!     fn config_declaration(&self) -> Option<ConfigDeclareRequest> {
52//!         Some(ConfigDeclareRequest::new(schema(), &self.user_file, vec![]))
53//!     }
54//!     async fn config_review(&self, request: ConfigReviewRequest) -> ConfigReviewReply {
55//!         review(request).unwrap_or_else(|reason| ConfigReviewReply::new(vec![],
56//!             vec![ConfigReviewRefusal::new("value_invalid", vec!["/count".into()], vec![reason])]))
57//!     }
58//!     async fn config_apply(&self, view: ConfigView) -> Result<(), Vec<String>> {
59//!         *self.value.lock().unwrap() = view.effective; Ok(())
60//!     }
61//!     async fn config_files(&self) {
62//!         // This path is used only with an older daemon, never on a refusal.
63//!         if let Ok(bytes) = std::fs::read(&self.user_file) {
64//!             if let Ok(value) = serde_json::from_slice(&bytes) { *self.value.lock().unwrap() = value; }
65//!         }
66//!     }
67//!     async fn on_config_state(&self, state: ConfigState) { eprintln!("{}", state.as_str()); }
68//! }
69//! # let _ = Counter { user_file: "counter.json".into(), value: Mutex::new(json!({"count":0})) };
70//! ```
71
72use std::{
73    collections::{BTreeMap, BTreeSet},
74    error::Error,
75    fmt,
76    sync::{Arc, OnceLock},
77};
78
79use serde::{de::DeserializeOwned, Serialize};
80use subc_protocol::{ErrorBody, Frame, FrameType};
81use tokio::sync::{oneshot, Notify};
82
83use crate::{ModuleHandle, ModuleHandler, RequestDispatcher, CATALOG_UPDATE_TIMEOUT};
84pub use subc_config::{ApplyKind, LayerValue, RecordedValue, Schema, ValidationContext};
85pub use subc_protocol::config::*;
86
87/// The bytes available after a refusal. Absence is not permission to read files.
88#[non_exhaustive]
89#[derive(Debug, Clone, PartialEq)]
90pub enum ConfigAvailability {
91    NoApprovedConfig,
92    LastView(ConfigView),
93}
94
95/// Wire status or refusal, with the module's retained view where applicable.
96/// `ConfigGated` with `NoApprovedConfig` carries the original refusal but no bytes.
97#[non_exhaustive]
98#[derive(Debug, Clone)]
99pub enum ConfigState {
100    Unstamped(ConfigView),
101    Pending(ConfigView),
102    Active(ConfigView),
103    Failed {
104        view: ConfigAvailability,
105        reasons: Vec<String>,
106    },
107    ConfigGated {
108        view: ConfigAvailability,
109        refusal: ErrorBody,
110    },
111    NotDeliveryTarget {
112        view: ConfigAvailability,
113        refusal: ErrorBody,
114    },
115    AnchorPending {
116        view: ConfigAvailability,
117        refusal: ErrorBody,
118    },
119}
120
121impl ConfigState {
122    /// The daemon's status or refusal spelling, without configuration values.
123    pub fn as_str(&self) -> &'static str {
124        match self {
125            Self::Unstamped(_) => "unstamped",
126            Self::Pending(_) => "pending",
127            Self::Active(_) => "active",
128            Self::Failed { .. } => "failed",
129            Self::ConfigGated { .. } => "config_gated",
130            Self::NotDeliveryTarget { .. } => "not_delivery_target",
131            Self::AnchorPending { .. } => "anchor_pending",
132        }
133    }
134}
135
136/// Non-status errors never authorize a fallback. Refusals preserve extension data.
137#[non_exhaustive]
138#[derive(Debug)]
139pub enum ConfigError {
140    Refused(ErrorBody),
141    Protocol(String),
142    Timeout,
143    ConnectionClosed,
144}
145impl fmt::Display for ConfigError {
146    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
147        match self {
148            Self::Refused(body) => write!(f, "{}: {}", body.code, body.message),
149            Self::Protocol(message) => f.write_str(message),
150            Self::Timeout => f.write_str("config request timed out"),
151            Self::ConnectionClosed => f.write_str("config connection closed"),
152        }
153    }
154}
155impl Error for ConfigError {}
156
157#[derive(Default)]
158pub(crate) struct Session {
159    pub(crate) declaration: OnceLock<ConfigDeclareRequest>,
160    changed: Notify,
161    projects: std::sync::Mutex<BTreeSet<Option<String>>>,
162    pub(crate) stop: tokio_util::sync::CancellationToken,
163}
164
165pub(crate) fn start<H: ModuleHandler>(
166    handle: ModuleHandle,
167    handler: Arc<H>,
168    dispatcher: &RequestDispatcher,
169) {
170    let Some(declaration) = handle.shared.config.declaration.get().cloned() else {
171        return;
172    };
173    let session_handle = handle.clone();
174    dispatcher.spawn(async move {
175        tokio::select! {
176            () = session_handle.shared.config.stop.cancelled() => {},
177            () = run(handle, handler, declaration) => {},
178        }
179    });
180}
181
182async fn run<H: ModuleHandler>(
183    handle: ModuleHandle,
184    handler: Arc<H>,
185    declaration: ConfigDeclareRequest,
186) {
187    if !handle.daemon_supports(CONFIG_GATE_CAPABILITY) {
188        handler.config_files().await;
189        return;
190    }
191    let mut deliveries = BTreeMap::new();
192    let delivery = deliveries.entry(None).or_insert_with(Delivery::default);
193    // A declaration refusal still consumes the one declaration on this
194    // connection. Future hints fetch again, never declare a second time.
195    match call(&handle, &declaration, CONFIG_DECLARE_OP).await {
196        Ok(_) => delivery.refresh(&handle, &*handler, None).await,
197        Err(error) => delivery.error(&*handler, error).await,
198    }
199    loop {
200        handle.shared.config.changed.notified().await;
201        let projects = std::mem::take(
202            &mut *handle
203                .shared
204                .config
205                .projects
206                .lock()
207                .unwrap_or_else(|p| p.into_inner()),
208        );
209        for project in projects {
210            deliveries
211                .entry(project.clone())
212                .or_insert_with(Delivery::default)
213                .refresh(&handle, &*handler, project)
214                .await;
215        }
216    }
217}
218
219pub(crate) fn changed(frame: &Frame, handle: &ModuleHandle) -> bool {
220    if !is_op(frame, CONFIG_CHANGED_OP) {
221        return false;
222    }
223    if handle.shared.config.declaration.get().is_some()
224        && handle.daemon_supports(CONFIG_GATE_CAPABILITY)
225    {
226        match serde_json::from_slice::<ConfigChanged>(&frame.body) {
227            Ok(hint) => {
228                handle
229                    .shared
230                    .config
231                    .projects
232                    .lock()
233                    .unwrap_or_else(|p| p.into_inner())
234                    .insert(hint.project_id);
235                handle.shared.config.changed.notify_one();
236            }
237            Err(error) => tracing::warn!(%error, "ignoring malformed config.changed"),
238        }
239    }
240    true
241}
242
243fn is_op(frame: &Frame, op: &str) -> bool {
244    serde_json::from_slice::<serde_json::Value>(&frame.body)
245        .ok()
246        .and_then(|value| {
247            value
248                .get("op")
249                .and_then(|value| value.as_str())
250                .map(|value| value == op)
251        })
252        == Some(true)
253}
254
255pub(crate) fn review<H: ModuleHandler>(
256    frame: &Frame,
257    egress: &tokio::sync::mpsc::Sender<Frame>,
258    handler: Arc<H>,
259    dispatcher: &RequestDispatcher,
260    handle: &ModuleHandle,
261) -> bool {
262    if !is_op(frame, CONFIG_REVIEW_OP) {
263        return false;
264    }
265    let frame = frame.clone();
266    let egress = egress.clone();
267    let opted_in = handle.shared.config.declaration.get().is_some()
268        && handle.daemon_supports(CONFIG_GATE_CAPABILITY);
269    let failure = dispatcher.clone();
270    dispatcher.spawn(async move {
271        let result = async {
272            let (ty, body) = if !opted_in {
273                (
274                    FrameType::Error,
275                    serde_json::to_vec(&ErrorBody::new(
276                        "unsupported_op",
277                        "module did not opt in to config.review",
278                    )),
279                )
280            } else {
281                match serde_json::from_slice::<ConfigReviewRequest>(&frame.body) {
282                    Ok(request) => (
283                        FrameType::Response,
284                        serde_json::to_vec(&handler.config_review(request).await),
285                    ),
286                    Err(_) => (
287                        FrameType::Error,
288                        serde_json::to_vec(&ErrorBody::new(
289                            "invalid_request",
290                            "invalid config.review snapshots",
291                        )),
292                    ),
293                }
294            };
295            let reply = Frame::build_with_version(
296                frame.header.ver,
297                ty,
298                crate::control_flags(),
299                0,
300                0,
301                frame.header.corr,
302                body.map_err(crate::SubcModuleError::Json)?,
303            )
304            .map_err(crate::SubcModuleError::FrameBuild)?;
305            crate::send_outbound(&egress, reply).await
306        }
307        .await;
308        if let Err(error) = result {
309            failure.fail(error);
310        }
311    });
312    true
313}
314
315#[derive(Default)]
316struct Delivery {
317    view: Option<ConfigView>,
318    report: Option<ConfigAppliedRequest>,
319}
320impl Delivery {
321    fn available(&self) -> ConfigAvailability {
322        self.view
323            .clone()
324            .map(ConfigAvailability::LastView)
325            .unwrap_or(ConfigAvailability::NoApprovedConfig)
326    }
327
328    async fn error<H: ModuleHandler>(&self, handler: &H, error: ConfigError) {
329        if let ConfigError::Refused(refusal) = error {
330            let view = self.available();
331            let state = match refusal.code.as_str() {
332                "config_gated" => ConfigState::ConfigGated { view, refusal },
333                "not_delivery_target" => ConfigState::NotDeliveryTarget { view, refusal },
334                "anchor_pending" => ConfigState::AnchorPending { view, refusal },
335                _ => {
336                    handler.on_config_error(ConfigError::Refused(refusal)).await;
337                    return;
338                }
339            };
340            handler.on_config_state(state).await;
341        } else {
342            handler.on_config_error(error).await;
343        }
344    }
345
346    async fn report<H: ModuleHandler>(&mut self, handle: &ModuleHandle, handler: &H) -> bool {
347        let Some(report) = self.report.as_ref() else {
348            return true;
349        };
350        match call(handle, report, CONFIG_APPLIED_OP).await {
351            Ok(_) => {
352                if report.result.is_ack() {
353                    if let Some(view) = self.view.as_mut() {
354                        view.status = ConfigStatus::Active;
355                        handler
356                            .on_config_state(ConfigState::Active(view.clone()))
357                            .await;
358                    }
359                }
360                self.report = None;
361                true
362            }
363            Err(error) => {
364                // Only anchor_pending explicitly permits replaying the report.
365                // During a module swap, a not-yet-promoted or replaced connection
366                // is not the delivery target. It must wait for config.changed to
367                // announce promotion, then fetch the newly assigned attempt.
368                if !matches!(&error, ConfigError::Refused(body) if body.code == "anchor_pending") {
369                    self.report = None;
370                }
371                self.error(handler, error).await;
372                false
373            }
374        }
375    }
376
377    async fn refresh<H: ModuleHandler>(
378        &mut self,
379        handle: &ModuleHandle,
380        handler: &H,
381        project: Option<String>,
382    ) {
383        if !self.report(handle, handler).await {
384            return;
385        }
386        let mut request = ConfigGetRequest::new();
387        request.project_id = project.clone();
388        let reply = match call(handle, &request, CONFIG_GET_OP)
389            .await
390            .and_then(decode::<ConfigGetReply>)
391        {
392            Ok(reply) => reply,
393            Err(error) => {
394                self.error(handler, error).await;
395                return;
396            }
397        };
398        let Some(view) = reply.pending.as_ref().or(reply.active.as_ref()) else {
399            self.error(
400                handler,
401                ConfigError::Protocol("config.get returned no view".into()),
402            )
403            .await;
404            return;
405        };
406        if view.project_id != project
407            || reply
408                .active
409                .as_ref()
410                .is_some_and(|active| active.project_id != project)
411        {
412            self.error(
413                handler,
414                ConfigError::Protocol("config.get returned another project".into()),
415            )
416            .await;
417            return;
418        }
419        // A reconnect may see both an approved recovery view and a delivery.
420        // Establish that recovery view before attempting the new configuration,
421        // so a rejected first delivery does not leave a fresh process empty.
422        if self.view.is_none() && reply.pending.is_some() {
423            if let Some(active) = &reply.active {
424                if active.status != ConfigStatus::Active
425                    || active
426                        .layers
427                        .iter()
428                        .any(|layer| layer.layer.known_layer().is_none())
429                {
430                    self.error(
431                        handler,
432                        ConfigError::Protocol("invalid recovery view".into()),
433                    )
434                    .await;
435                    return;
436                }
437                match handler.config_apply(active.clone()).await {
438                    Ok(()) => {
439                        self.view = Some(active.clone());
440                        handler
441                            .on_config_state(ConfigState::Active(active.clone()))
442                            .await;
443                    }
444                    Err(reasons) => {
445                        handler
446                            .on_config_state(ConfigState::Failed {
447                                view: self.available(),
448                                reasons,
449                            })
450                            .await;
451                        return;
452                    }
453                }
454            }
455        }
456        if !matches!(
457            view.status,
458            ConfigStatus::Active | ConfigStatus::Pending | ConfigStatus::Unstamped
459        ) || view
460            .layers
461            .iter()
462            .any(|layer| layer.layer.known_layer().is_none())
463        {
464            self.error(
465                handler,
466                ConfigError::Protocol("config.get returned an unknown status or layer".into()),
467            )
468            .await;
469            return;
470        }
471        let attempt = if reply.pending.is_some() {
472            match view.attempt {
473                Some(attempt) => Some(attempt),
474                None => {
475                    self.error(
476                        handler,
477                        ConfigError::Protocol("pending view has no delivery attempt".into()),
478                    )
479                    .await;
480                    return;
481                }
482            }
483        } else {
484            None
485        };
486        match handler.config_apply(view.clone()).await {
487            Ok(()) => {
488                self.view = Some(view.clone());
489                handler
490                    .on_config_state(match view.status {
491                        ConfigStatus::Unstamped => ConfigState::Unstamped(view.clone()),
492                        ConfigStatus::Pending => ConfigState::Pending(view.clone()),
493                        _ => ConfigState::Active(view.clone()),
494                    })
495                    .await;
496                if let Some(attempt) = attempt {
497                    let mut report = ConfigAppliedRequest::new(
498                        view.generation,
499                        attempt,
500                        ConfigApplyResult::Ack,
501                        vec![],
502                    );
503                    report.project_id = view.project_id.clone();
504                    self.report = Some(report);
505                }
506            }
507            Err(reasons) => {
508                handler
509                    .on_config_state(ConfigState::Failed {
510                        view: self.available(),
511                        reasons: reasons.clone(),
512                    })
513                    .await;
514                if let Some(attempt) = attempt {
515                    let mut report = ConfigAppliedRequest::new(
516                        view.generation,
517                        attempt,
518                        ConfigApplyResult::Nack,
519                        reasons,
520                    );
521                    report.project_id = view.project_id.clone();
522                    self.report = Some(report);
523                }
524            }
525        }
526        self.report(handle, handler).await;
527    }
528}
529
530fn decode<T: DeserializeOwned>(body: serde_json::Value) -> Result<T, ConfigError> {
531    serde_json::from_value(body).map_err(|error| ConfigError::Protocol(error.to_string()))
532}
533
534async fn call(
535    handle: &ModuleHandle,
536    request: &impl Serialize,
537    op: &str,
538) -> Result<serde_json::Value, ConfigError> {
539    let body =
540        serde_json::to_vec(request).map_err(|error| ConfigError::Protocol(error.to_string()))?;
541    let (corr, writer, rx) = {
542        let mut inner = handle.shared.lock_inner();
543        let writer = inner.writer.clone().ok_or(ConfigError::ConnectionClosed)?;
544        let corr =
545            crate::next_module_control_corr(&mut inner).ok_or(ConfigError::ConnectionClosed)?;
546        let (tx, rx) = oneshot::channel();
547        inner.pending_config_calls.insert(corr, tx);
548        (corr, writer, rx)
549    };
550    let _guard = Waiter {
551        handle: handle.clone(),
552        corr,
553    };
554    let frame = Frame::build_with_version(
555        handle.shared.negotiated_ver,
556        FrameType::Request,
557        crate::control_flags(),
558        0,
559        0,
560        corr,
561        body,
562    )
563    .map_err(|error| ConfigError::Protocol(error.to_string()))?;
564    let reply = tokio::time::timeout(CATALOG_UPDATE_TIMEOUT, async {
565        writer
566            .send(frame)
567            .await
568            .map_err(|_| ConfigError::ConnectionClosed)?;
569        rx.await.map_err(|_| ConfigError::ConnectionClosed)
570    })
571    .await
572    .map_err(|_| ConfigError::Timeout)??;
573    if reply.header.ty == FrameType::Error {
574        return Err(ConfigError::Refused(
575            serde_json::from_slice(&reply.body)
576                .map_err(|error| ConfigError::Protocol(error.to_string()))?,
577        ));
578    }
579    let body: serde_json::Value = serde_json::from_slice(&reply.body)
580        .map_err(|error| ConfigError::Protocol(error.to_string()))?;
581    if body.get("op").and_then(|op| op.as_str()) != Some(op) {
582        return Err(ConfigError::Protocol(format!("unexpected reply to {op}")));
583    }
584    Ok(body)
585}
586struct Waiter {
587    handle: ModuleHandle,
588    corr: u64,
589}
590impl Drop for Waiter {
591    fn drop(&mut self) {
592        self.handle
593            .shared
594            .lock_inner()
595            .pending_config_calls
596            .remove(&self.corr);
597    }
598}
599
600#[cfg(test)]
601mod tests;