Skip to main content

zero_client/client/
query_context.rs

1//! Materializes queries over an IVM branch, registers named ones with the
2//! query manager, and flushes views when a transaction commits
3//! (`ZeroContext` in `packages/zero-client/src/client/context.ts`, with
4//! `materializeImpl`, `runImpl`, and `preloadImpl` from
5//! `packages/zql/src/query/query-delegate-base.ts`).
6
7use super::engine::BatchViewUpdates;
8use super::ivm_branch::IvmBranch;
9use super::log::Log;
10use super::measure_push::MeasurePush;
11use super::query_manager::{ClientMetric, Got, GotCallback, MetricsDelegate, closed_error};
12use super::replica_store::KvDiff;
13use super::{ConnectionError, Deferred, Error, QueryError};
14use crate::ast::Ast;
15use crate::builder::{BuilderDelegate, OptimisticAggregate, build_pipeline, group_view_input};
16use crate::hash::query::{hash_of_ast, hash_of_name_and_args};
17use crate::ivm::{
18    ArrayView, DeferredInput, Input, PipelineError, ResultType, Row, Source, SourceInput,
19    ViewValue, capture,
20};
21use crate::map::OrderedMap;
22use crate::protocol::ErroredQuery;
23use crate::query::{AnyQuery, CustomQueryId};
24use crate::schema::Column;
25use crate::ttl::Ttl;
26use std::cell::{Cell, RefCell};
27use std::collections::{HashMap, HashSet};
28use std::rc::{Rc, Weak};
29
30/// Builds pipelines over the sources of an IVM branch.
31struct BranchDelegate {
32    branch: Rc<IvmBranch>,
33    /// The synced client reads aggregates from the rows the server streams;
34    /// a mutator's query the server hasn't answered computes them.
35    aggregates_from_source: bool,
36    /// Times the pushes of each source connection, for the inspector.
37    metrics: Option<Rc<dyn MetricsDelegate>>,
38}
39
40impl BuilderDelegate for BranchDelegate {
41    fn get_source(&self, table_name: &str) -> Option<Rc<dyn Source>> {
42        self.branch.source(table_name).map(|s| s as Rc<dyn Source>)
43    }
44
45    fn aggregates_from_source(&self) -> bool {
46        self.aggregates_from_source
47    }
48
49    fn get_aggregate_source(
50        &self,
51        name: &str,
52        columns: OrderedMap<Column>,
53        primary_key: Vec<String>,
54        optimistic: Option<OptimisticAggregate>,
55    ) -> Option<Rc<dyn Source>> {
56        Some(
57            self.branch
58                .aggregate_source(name, columns, primary_key, optimistic),
59        )
60    }
61
62    fn aggregate_key_columns(&self, table: &str, columns: &[String]) -> Vec<String> {
63        self.branch.server_column_names(table, columns)
64    }
65
66    fn decorate_source_input(&self, input: Rc<dyn SourceInput>, query_id: &str) -> Rc<dyn Input> {
67        match &self.metrics {
68            Some(m) => MeasurePush::new(input, query_id, m.clone()),
69            None => input,
70        }
71    }
72}
73
74/// Registers a named query with the server; returns its unregister.
75pub(crate) type AddCustomQuery =
76    Box<dyn Fn(&CustomQueryId, &Ast, &Ttl, GotCallback) -> Box<dyn Fn()>>;
77pub(crate) type UpdateCustomQuery = Rc<dyn Fn(&CustomQueryId, &Ttl)>;
78pub(crate) type Microtask = Rc<dyn Fn(Box<dyn FnOnce()>)>;
79/// Builds a deferred pipeline; returns the release to call once every
80/// pending pipeline is built.
81type AttachPipeline = Box<dyn FnOnce() -> Result<Box<dyn FnOnce()>, PipelineError>>;
82
83/// How many view notifications are under way on a client.
84pub(crate) type NotificationGate = Rc<Cell<u32>>;
85
86type Callback = Rc<dyn Fn()>;
87type RemovePendingAttach = Box<dyn Fn()>;
88
89/// A query's pipeline and, when it is built later, its placeholder input.
90type BuiltPipeline = (Rc<dyn Input>, Option<Rc<DeferredInput>>);
91
92pub(crate) struct QueryContext {
93    me: Weak<QueryContext>,
94    pub(crate) branch: Rc<IvmBranch>,
95    delegate: Rc<BranchDelegate>,
96    add_custom_query: AddCustomQuery,
97    update_custom_query: UpdateCustomQuery,
98    microtask: Microtask,
99    commit_listeners: RefCell<Vec<(u64, Callback)>>,
100    next_listener_id: Cell<u64>,
101    /// Until the replica is loaded into the sources, pipelines are built
102    /// later, together (`mark_pipelines_ready`).
103    pipelines_ready: Cell<bool>,
104    pending_pipelines: RefCell<Vec<(u64, AttachPipeline)>>,
105    log: Option<Log>,
106    /// Why the client closed, once it has.
107    closed_reason: Box<dyn Fn() -> Option<ConnectionError>>,
108    /// The hashes of the unnamed queries already warned about.
109    warned_local_only: RefCell<HashSet<String>>,
110    pub(crate) notifications: NotificationGate,
111    /// The app's `batch_view_updates`, which every update of the views
112    /// goes through.
113    batch_view_updates: Option<BatchViewUpdates>,
114    /// Why pushing into the branch failed, once it has (`#advanceError` in
115    /// `ivm-branch.ts`): the branch is unusable from then on.
116    branch_failure: RefCell<Option<PipelineError>>,
117    /// Where materializations are timed: none for a mutator's queries.
118    metrics: Option<Rc<dyn MetricsDelegate>>,
119}
120
121/// The settled state of a view's query: still waiting, confirmed by the
122/// server, or failed.
123#[derive(Clone)]
124enum Completion {
125    Pending,
126    Complete,
127    Failed(ErroredQuery),
128}
129
130/// What a view's query has heard, shared by the closures of `materialize`.
131struct Track {
132    attached: bool,
133    got: Got,
134    query_complete: Completion,
135    resolved: Option<Completion>,
136    on_resolved: Option<Rc<dyn Fn(Completion)>>,
137    view: Weak<ArrayView>,
138    destroyed: bool,
139    /// For the end-to-end materialization metric.
140    timing: Option<Rc<ViewTiming>>,
141}
142
143/// When and what a view started materializing, for its metrics.
144struct ViewTiming {
145    metrics: Rc<dyn MetricsDelegate>,
146    t0: f64,
147    query_id: String,
148    ast: Ast,
149}
150
151type TrackRef = Rc<RefCell<Track>>;
152
153fn settle(track: &TrackRef, r: Completion) {
154    let on_resolved = {
155        let mut t = track.borrow_mut();
156        if t.resolved.is_some() {
157            return;
158        }
159        t.resolved = Some(r.clone());
160        t.on_resolved.clone()
161    };
162    if let Some(f) = on_resolved {
163        f(r);
164    }
165}
166
167fn maybe_resolve_complete(track: &TrackRef) {
168    let (resolve, timing) = {
169        let mut t = track.borrow_mut();
170        let ok = t.attached && t.got == Got::Yes && matches!(t.query_complete, Completion::Pending);
171        if ok {
172            t.query_complete = Completion::Complete;
173        }
174        (ok, t.timing.clone())
175    };
176    if resolve {
177        if let Some(t) = timing {
178            t.metrics.add_metric(
179                ClientMetric::MaterializationEndToEnd,
180                t.metrics.monotonic_now() - t.t0,
181                &t.query_id,
182                Some(&t.ast),
183            );
184        }
185        settle(track, Completion::Complete);
186    }
187}
188
189fn maybe_mark_cached(track: &TrackRef) {
190    let view = {
191        let t = track.borrow();
192        if t.attached && t.got == Got::Cached && matches!(t.query_complete, Completion::Pending) {
193            t.view.upgrade()
194        } else {
195            None
196        }
197    };
198    if let Some(v) = view {
199        v.mark_cached();
200    }
201}
202
203fn query_id(query: &AnyQuery) -> String {
204    match query.custom_query_id() {
205        Some(id) => hash_of_name_and_args(&id.name, &id.args),
206        None => hash_of_ast(query.ast()),
207    }
208}
209
210/// Which rows `Zero::run` returns.
211#[derive(Clone, Copy, Debug, PartialEq, Eq)]
212pub enum RunType {
213    /// What the local replica holds now.
214    Unknown,
215    /// Once the store holds a server-confirmed result, from this connection or
216    /// an earlier one.
217    Cached,
218    /// Once the server has confirmed the result on this connection.
219    Complete,
220}
221
222impl RunType {
223    /// The type as JS names it.
224    pub fn as_str(self) -> &'static str {
225        match self {
226            RunType::Unknown => "unknown",
227            RunType::Cached => "cached",
228            RunType::Complete => "complete",
229        }
230    }
231
232    /// The type JS names `s`, if any.
233    pub fn parse(s: &str) -> Option<RunType> {
234        Some(match s {
235            "unknown" => RunType::Unknown,
236            "cached" => RunType::Cached,
237            "complete" => RunType::Complete,
238            _ => return None,
239        })
240    }
241}
242
243/// What `preload` returns.
244#[derive(Clone)]
245pub struct Preload {
246    /// Stops syncing the query (after its TTL).
247    pub cleanup: Rc<dyn Fn()>,
248    /// Settles once the store holds a server-confirmed result, from this
249    /// connection or an earlier one.
250    pub cached: Deferred<()>,
251    /// Settles once the server has confirmed the result on this connection.
252    pub complete: Deferred<()>,
253}
254
255impl QueryContext {
256    #[allow(clippy::too_many_arguments)]
257    pub(crate) fn new(
258        branch: Rc<IvmBranch>,
259        add_custom_query: AddCustomQuery,
260        update_custom_query: UpdateCustomQuery,
261        microtask: Microtask,
262        log: Option<Log>,
263        closed_reason: Box<dyn Fn() -> Option<ConnectionError>>,
264        aggregates_from_source: bool,
265        batch_view_updates: Option<BatchViewUpdates>,
266        metrics: Option<Rc<dyn MetricsDelegate>>,
267    ) -> Rc<Self> {
268        Rc::new_cyclic(|me| QueryContext {
269            me: me.clone(),
270            delegate: Rc::new(BranchDelegate {
271                branch: branch.clone(),
272                aggregates_from_source,
273                metrics: metrics.clone(),
274            }),
275            branch,
276            add_custom_query,
277            update_custom_query,
278            microtask,
279            commit_listeners: RefCell::default(),
280            next_listener_id: Cell::new(0),
281            pipelines_ready: Cell::new(false),
282            pending_pipelines: RefCell::default(),
283            log,
284            closed_reason,
285            warned_local_only: RefCell::default(),
286            notifications: Rc::default(),
287            branch_failure: RefCell::new(None),
288            batch_view_updates,
289            metrics,
290        })
291    }
292
293    /// A context for the queries a mutator runs: nothing is registered with
294    /// the server, and the branch is already populated.
295    pub(crate) fn local(branch: Rc<IvmBranch>, aggregates_from_source: bool) -> Rc<Self> {
296        let context = QueryContext::new(
297            branch,
298            Box::new(|_, _, _, _| Box::new(|| {})),
299            Rc::new(|_, _| {}),
300            Rc::new(|f| f()),
301            None,
302            Box::new(|| None),
303            aggregates_from_source,
304            None,
305            None,
306        );
307        context.mark_pipelines_ready();
308        context
309    }
310
311    /// Whether listeners are being told about a change. JS mutators are
312    /// async, so a mutation made from a listener commits once the
313    /// notification is over.
314    pub(crate) fn is_notifying(&self) -> bool {
315        self.notifications.get() > 0
316    }
317
318    pub(crate) fn branch_failure(&self) -> Option<PipelineError> {
319        self.branch_failure.borrow().clone()
320    }
321
322    /// The error of a query waiting for the server on a closed client.
323    fn closed_error(&self, query: &AnyQuery) -> Option<QueryError> {
324        let reason = (self.closed_reason)()?;
325        let id = query_id(query);
326        let name = query.custom_query_id().map(|c| c.name.as_str());
327        Some(QueryError::new(Some(closed_error(&id, name, &reason))))
328    }
329
330    /// Warns, once per query, that an unnamed query is waited for or
331    /// preloaded: it only sees local data, so the server never confirms it.
332    fn warn_local_only(&self, query: &AnyQuery, consequence: &str) {
333        if query.custom_query_id().is_some() {
334            return;
335        }
336        let Some(log) = &self.log else { return };
337        let hash = hash_of_ast(query.ast());
338        if !self.warned_local_only.borrow_mut().insert(hash.clone()) {
339            return;
340        }
341        log.warn(|| {
342            format!(
343                "The unnamed query of \"{}\" (hash {hash}) only sees local data and is never \
344                 complete: {consequence}. To sync it from the server, use a named query.",
345                query.table()
346            )
347        });
348    }
349
350    pub(crate) fn on_transaction_commit(&self, listener: impl Fn() + 'static) -> Box<dyn Fn()> {
351        let id = self.next_listener_id.get();
352        self.next_listener_id.set(id + 1);
353        self.commit_listeners
354            .borrow_mut()
355            .push((id, Rc::new(listener)));
356        let me = self.me.clone();
357        Box::new(move || {
358            if let Some(me) = me.upgrade() {
359                me.commit_listeners.borrow_mut().retain(|(i, _)| *i != id);
360            }
361        })
362    }
363
364    fn on_pipelines_ready(&self, attach: AttachPipeline) -> Box<dyn Fn()> {
365        assert!(
366            !self.pipelines_ready.get(),
367            "onPipelinesReady called while pipelines are ready"
368        );
369        let id = self.next_listener_id.get();
370        self.next_listener_id.set(id + 1);
371        self.pending_pipelines.borrow_mut().push((id, attach));
372        let me = self.me.clone();
373        Box::new(move || {
374            if let Some(me) = me.upgrade() {
375                me.pending_pipelines.borrow_mut().retain(|(i, _)| *i != id);
376            }
377        })
378    }
379
380    /// Builds and hydrates every deferred pipeline, in materialization
381    /// order, as one batch of view updates.
382    pub(crate) fn mark_pipelines_ready(&self) {
383        if self.pipelines_ready.get() {
384            return;
385        }
386        if self.pending_pipelines.borrow().is_empty() {
387            self.pipelines_ready.set(true);
388            return;
389        }
390        self.batch(|| self.attach_pending_pipelines());
391    }
392
393    fn attach_pending_pipelines(&self) {
394        let mut releases = Vec::new();
395        loop {
396            let next = {
397                let mut p = self.pending_pipelines.borrow_mut();
398                if p.is_empty() {
399                    break;
400                }
401                p.remove(0)
402            };
403            // A failing view has already been marked as errored; the others
404            // are still built.
405            if let Ok(release) = (next.1)() {
406                releases.push(release);
407            }
408        }
409        self.pipelines_ready.set(true);
410        for r in releases {
411            r();
412        }
413        self.end_transaction();
414    }
415
416    /// Pushes `diff` into the branch and flushes the views. A push an
417    /// operator fails still flushes what the views got, and then fails.
418    pub(crate) fn process_changes(
419        &self,
420        diff: &KvDiff,
421        rows: &HashMap<String, Row>,
422    ) -> Result<(), PipelineError> {
423        if let Some(f) = self.branch_failure() {
424            return Err(f);
425        }
426        let result = self.batch(|| {
427            let result = capture(|| self.branch.apply(diff, rows));
428            self.end_transaction();
429            result
430        });
431        if let Err(f) = result {
432            *self.branch_failure.borrow_mut() = Some(f.clone());
433            return Err(f);
434        }
435        Ok(())
436    }
437
438    /// Runs `apply_view_updates` through the app's `batch_view_updates`
439    /// (`batchViewUpdates` in `context.ts`).
440    fn batch<T>(&self, apply_view_updates: impl FnOnce() -> T) -> T {
441        let Some(batch) = self.batch_view_updates.clone() else {
442            return apply_view_updates();
443        };
444        let mut apply = Some(apply_view_updates);
445        let mut result = None;
446        batch(&mut || {
447            if let Some(apply) = apply.take() {
448                result = Some(apply());
449            }
450        });
451        result.expect("batchViewUpdates must call applyViewUpdates synchronously.")
452    }
453
454    fn end_transaction(&self) {
455        self.notifications.set(self.notifications.get() + 1);
456        let listeners: Vec<Rc<dyn Fn()>> = self
457            .commit_listeners
458            .borrow()
459            .iter()
460            .map(|(_, l)| l.clone())
461            .collect();
462        for l in listeners {
463            l();
464        }
465        self.notifications.set(self.notifications.get() - 1);
466    }
467
468    pub(crate) fn materialize(
469        &self,
470        query: &AnyQuery,
471        ttl: &Ttl,
472    ) -> Result<MaterializedView, Error> {
473        if let Some(message) = query.invalid() {
474            return Err(PipelineError::new(message).into());
475        }
476        if let Some(f) = self.branch_failure() {
477            return Err(f.into());
478        }
479        let custom_query_id = query.custom_query_id().cloned();
480        let ast = query.ast().clone();
481        let query_id = query_id(query);
482        let microtask = self.microtask.clone();
483        let defer_pipeline = !self.pipelines_ready.get();
484        let track: TrackRef = Rc::new(RefCell::new(Track {
485            attached: !defer_pipeline,
486            got: Got::No,
487            query_complete: Completion::Pending,
488            resolved: None,
489            on_resolved: None,
490            view: Weak::new(),
491            destroyed: false,
492            timing: self.metrics.as_ref().map(|m| {
493                Rc::new(ViewTiming {
494                    metrics: m.clone(),
495                    t0: m.monotonic_now(),
496                    query_id: query_id.clone(),
497                    ast: ast.clone(),
498                })
499            }),
500        }));
501        let got_callback: GotCallback = {
502            let track = track.clone();
503            Rc::new(move |value: Got, error: Option<ErroredQuery>| {
504                // Removals are deferred while mutations are pending, so a
505                // destroyed view can still hear from the query manager.
506                if track.borrow().destroyed {
507                    return;
508                }
509                if let Some(error) = error {
510                    settle(&track, Completion::Failed(error.clone()));
511                    track.borrow_mut().query_complete = Completion::Failed(error);
512                    return;
513                }
514                track.borrow_mut().got = value;
515                match value {
516                    Got::Cached => maybe_mark_cached(&track),
517                    Got::No => {
518                        let v = track.borrow().view.upgrade();
519                        if let Some(v) = v {
520                            v.unmark_cached();
521                        }
522                    }
523                    Got::Yes => maybe_resolve_complete(&track),
524                }
525            })
526        };
527        let remove_added_query: Rc<dyn Fn()> = match &custom_query_id {
528            Some(id) => Rc::from((self.add_custom_query)(id, &ast, ttl, got_callback)),
529            None => Rc::new(|| {}),
530        };
531        let built = (|| -> Result<BuiltPipeline, PipelineError> {
532            let (pipeline, deferred): (Rc<dyn Input>, _) = if defer_pipeline {
533                let delegate = self.delegate.clone();
534                let ast = ast.clone();
535                let query_id = query_id.clone();
536                let build = move || build_pipeline(&ast, delegate.as_ref(), &query_id);
537                // A probe gets the schema, and makes a query that cannot be
538                // built fail now rather than later.
539                let probe = build()?;
540                let schema = probe.get_schema();
541                probe.destroy();
542                let deferred = DeferredInput::new(schema, Box::new(build));
543                (deferred.clone(), Some(deferred))
544            } else {
545                (
546                    build_pipeline(&ast, self.delegate.as_ref(), &query_id)?,
547                    None,
548                )
549            };
550            // A view of a grouped query shows only its columns and value.
551            let input = if ast.group_by.is_some() {
552                group_view_input(pipeline, &ast, self.delegate.as_ref())?
553            } else {
554                pipeline
555            };
556            Ok((input, deferred))
557        })();
558        let (input, deferred) = match built {
559            Ok(b) => b,
560            Err(e) => {
561                remove_added_query();
562                return Err(e.into());
563            }
564        };
565        let complete = track.borrow().query_complete.clone();
566        let format = query.format().clone();
567        let hydrated = self.batch(|| {
568            capture(|| match &complete {
569                Completion::Complete => ArrayView::new(input.clone(), format.clone(), None, true),
570                Completion::Failed(e) => {
571                    ArrayView::new(input.clone(), format.clone(), Some(e.clone()), false)
572                }
573                Completion::Pending => ArrayView::new(input.clone(), format.clone(), None, false),
574            })
575        });
576        let created = match hydrated {
577            Ok(v) => v,
578            Err(e) => {
579                // Unlike JS, which leaves the query registered, nothing is
580                // left behind: there is no view to destroy.
581                track.borrow_mut().destroyed = true;
582                input.destroy();
583                remove_added_query();
584                return Err(e.into());
585            }
586        };
587        let timing = track.borrow().timing.clone();
588        if deferred.is_none()
589            && let Some(t) = &timing
590        {
591            t.metrics.add_metric(
592                ClientMetric::MaterializationClient,
593                t.metrics.monotonic_now() - t.t0,
594                &query_id,
595                None,
596            );
597        }
598        if matches!(complete, Completion::Pending) {
599            let weak = Rc::downgrade(&created);
600            let microtask = microtask.clone();
601            let on_resolved: Rc<dyn Fn(Completion)> = Rc::new(move |r| match r {
602                Completion::Complete => {
603                    let weak = weak.clone();
604                    microtask(Box::new(move || {
605                        if let Some(v) = weak.upgrade() {
606                            v.set_result_type(ResultType::Complete, None);
607                        }
608                    }));
609                }
610                Completion::Failed(e) => {
611                    let weak = weak.clone();
612                    let inner = microtask.clone();
613                    microtask(Box::new(move || {
614                        inner(Box::new(move || {
615                            if let Some(v) = weak.upgrade() {
616                                v.set_result_type(ResultType::Error, Some(e));
617                            }
618                        }));
619                    }));
620                }
621                Completion::Pending => {}
622            });
623            let resolved = {
624                let mut t = track.borrow_mut();
625                t.on_resolved = Some(on_resolved.clone());
626                t.resolved.clone()
627            };
628            if let Some(r) = resolved {
629                on_resolved(r);
630            }
631        }
632        let remove_commit_observer = {
633            let weak = Rc::downgrade(&created);
634            self.on_transaction_commit(move || {
635                if let Some(v) = weak.upgrade() {
636                    v.flush();
637                }
638            })
639        };
640        let remove_pending_attach: Rc<RefCell<Option<RemovePendingAttach>>> = Rc::default();
641        {
642            let track = track.clone();
643            let remove_pending_attach = remove_pending_attach.clone();
644            let input = input.clone();
645            let remove_added_query = remove_added_query.clone();
646            created.set_on_destroy(move || {
647                track.borrow_mut().destroyed = true;
648                if let Some(r) = remove_pending_attach.borrow_mut().take() {
649                    r();
650                }
651                input.destroy();
652                remove_commit_observer();
653                remove_added_query();
654            });
655        }
656        if let Some(deferred) = deferred {
657            let weak = Rc::downgrade(&created);
658            let track = track.clone();
659            let remove = remove_pending_attach.clone();
660            let name = custom_query_id
661                .as_ref()
662                .map(|c| c.name.clone())
663                .unwrap_or_default();
664            let query_id = query_id.clone();
665            let attach: AttachPipeline = Box::new(move || {
666                remove.borrow_mut().take();
667                if deferred.destroyed() {
668                    return Ok(Box::new(|| {}));
669                }
670                let t1 = timing.as_ref().map(|t| t.metrics.monotonic_now());
671                if let Some(v) = weak.upgrade() {
672                    v.hold_data();
673                }
674                if let Err(error) = deferred.attach() {
675                    let e = ErroredQuery::App {
676                        id: query_id,
677                        name,
678                        message: Some(error.to_string()),
679                        details: None,
680                    };
681                    track.borrow_mut().query_complete = Completion::Failed(e.clone());
682                    settle(&track, Completion::Failed(e));
683                    return Err(error);
684                }
685                let hydrate_ms = timing
686                    .as_ref()
687                    .zip(t1)
688                    .map(|(t, t1)| (t.clone(), t.metrics.monotonic_now() - t1));
689                Ok(Box::new(move || {
690                    if track.borrow().destroyed {
691                        return;
692                    }
693                    track.borrow_mut().attached = true;
694                    if let Some(v) = weak.upgrade() {
695                        v.release_data();
696                    }
697                    if let Some((t, ms)) = hydrate_ms {
698                        t.metrics.add_metric(
699                            ClientMetric::MaterializationClient,
700                            ms,
701                            &t.query_id,
702                            None,
703                        );
704                    }
705                    maybe_resolve_complete(&track);
706                    maybe_mark_cached(&track);
707                }))
708            });
709            *remove_pending_attach.borrow_mut() = Some(self.on_pipelines_ready(attach));
710        }
711        track.borrow_mut().view = Rc::downgrade(&created);
712        maybe_mark_cached(&track);
713        let update_ttl: Box<dyn Fn(&Ttl)> = match custom_query_id {
714            Some(id) => {
715                let update = self.update_custom_query.clone();
716                Box::new(move |ttl| update(&id, ttl))
717            }
718            None => Box::new(|_| {}),
719        };
720        Ok(MaterializedView::new(
721            created,
722            update_ttl,
723            self.notifications.clone(),
724        ))
725    }
726
727    /// `runImpl`: the rows now, or once the server has confirmed them.
728    pub(crate) fn run(
729        &self,
730        query: &AnyQuery,
731        run_type: RunType,
732        ttl: Option<&Ttl>,
733    ) -> Deferred<ViewValue> {
734        let result = Deferred::new();
735        // On a closed client, waiting for the server fails at once rather
736        // than never settling, without materializing anything.
737        if run_type != RunType::Unknown
738            && let Some(error) = self.closed_error(query)
739        {
740            result.reject(error);
741            return result;
742        }
743        let default = Ttl::String(Ttl::DEFAULT.into());
744        let v = match self.materialize(query, ttl.unwrap_or(&default)) {
745            Ok(v) => v,
746            Err(e) => {
747                // JS's `run` is async: a query that can't be materialized
748                // rejects it.
749                result.reject(e);
750                return result;
751            }
752        };
753        if run_type == RunType::Unknown {
754            let data = v.data();
755            v.destroy();
756            result.resolve(data);
757            return result;
758        }
759        self.warn_local_only(
760            query,
761            &format!("a run waiting for .{} never returns", run_type.as_str()),
762        );
763        {
764            let v = v.clone();
765            result.on_settle(move |_| v.destroy());
766        }
767        let r = result.clone();
768        // Destroying the view on settle removes the listener.
769        let _ = v.add_listener(move |data, result_type, error| {
770            if result_type == ResultType::Complete
771                || (run_type == RunType::Cached && result_type == ResultType::Cached)
772            {
773                r.resolve(data.clone());
774            } else if result_type == ResultType::Error {
775                r.reject(QueryError {
776                    error: error.cloned(),
777                    data: Some(data.clone()),
778                });
779            }
780        });
781        result
782    }
783
784    /// The rows of `query` now, for a query run inside a mutator.
785    pub(crate) fn snapshot(&self, query: &AnyQuery) -> Result<ViewValue, Error> {
786        let v = self.materialize(query, &Ttl::String(Ttl::DEFAULT.into()))?;
787        let data = v.data();
788        v.destroy();
789        Ok(data)
790    }
791
792    /// `preloadImpl`: keeps a query's rows synced without a view.
793    pub(crate) fn preload(&self, query: &AnyQuery, ttl: &Ttl) -> Preload {
794        let cached = Deferred::new();
795        let complete = Deferred::new();
796        let noop: Rc<dyn Fn()> = Rc::new(|| {});
797        // On a closed client, both fail at once and nothing is registered.
798        if let Some(error) = self.closed_error(query) {
799            cached.reject(error.clone());
800            complete.reject(error);
801            return Preload {
802                cleanup: noop,
803                cached,
804                complete,
805            };
806        }
807        if let Some(message) = query.invalid() {
808            if let Some(log) = &self.log {
809                log.error(|| message.to_owned());
810            }
811            cached.reject(PipelineError::new(message));
812            complete.reject(PipelineError::new(message));
813            return Preload {
814                cleanup: noop,
815                cached,
816                complete,
817            };
818        }
819        let Some(id) = query.custom_query_id() else {
820            self.warn_local_only(
821                query,
822                "preloading it does nothing, and its cached and complete never settle",
823            );
824            return Preload {
825                cleanup: noop,
826                cached,
827                complete,
828            };
829        };
830        let (c, p) = (cached.clone(), complete.clone());
831        let cleanup = (self.add_custom_query)(
832            id,
833            query.ast(),
834            ttl,
835            Rc::new(move |got, error| {
836                if let Some(error) = error {
837                    c.reject(QueryError::new(Some(error.clone())));
838                    p.reject(QueryError::new(Some(error)));
839                    return;
840                }
841                if got == Got::Yes {
842                    c.resolve(());
843                    p.resolve(());
844                } else if got == Got::Cached {
845                    c.resolve(());
846                }
847            }),
848        );
849        Preload {
850            cleanup: Rc::from(cleanup),
851            cached,
852            complete,
853        }
854    }
855}
856
857/// Called with a view's data, result type, and error.
858pub type ViewListener = Rc<dyn Fn(&ViewValue, ResultType, Option<&ErroredQuery>)>;
859
860/// What a view reads from its client: replaced when the client is
861/// (`rebind`).
862struct ViewBinding {
863    view: Rc<ArrayView>,
864    update_ttl: Box<dyn Fn(&Ttl)>,
865    notifications: NotificationGate,
866}
867
868struct ViewInner {
869    binding: RefCell<ViewBinding>,
870    remove_forward: RefCell<Option<Box<dyn Fn()>>>,
871    destroyed: Cell<bool>,
872    listeners: RefCell<Vec<(u64, ViewListener)>>,
873    next_listener_id: Cell<u64>,
874    /// How many notification passes are under way. As in JS, a listener
875    /// that destroys the view doesn't keep the pass from reaching the
876    /// others.
877    forwarding: Cell<u32>,
878}
879
880/// A view of a query that stays current as data changes (`TypedView`).
881#[derive(Clone)]
882pub struct MaterializedView(Rc<ViewInner>);
883
884/// A view that doesn't keep it alive.
885pub(crate) struct WeakView(Weak<ViewInner>);
886
887impl WeakView {
888    pub(crate) fn upgrade(&self) -> Option<MaterializedView> {
889        self.0.upgrade().map(MaterializedView)
890    }
891}
892
893impl MaterializedView {
894    fn new(
895        view: Rc<ArrayView>,
896        update_ttl: Box<dyn Fn(&Ttl)>,
897        notifications: NotificationGate,
898    ) -> Self {
899        let inner = Rc::new(ViewInner {
900            binding: RefCell::new(ViewBinding {
901                view,
902                update_ttl,
903                notifications,
904            }),
905            remove_forward: RefCell::new(None),
906            destroyed: Cell::new(false),
907            listeners: RefCell::default(),
908            next_listener_id: Cell::new(0),
909            forwarding: Cell::new(0),
910        });
911        ViewInner::forward(&inner);
912        MaterializedView(inner)
913    }
914
915    fn view(&self) -> Rc<ArrayView> {
916        self.0.binding.borrow().view.clone()
917    }
918
919    pub(crate) fn downgrade(&self) -> WeakView {
920        WeakView(Rc::downgrade(&self.0))
921    }
922
923    /// Reads `fresh`, the same query on a client that replaced this one's,
924    /// from now on; the listeners hear its data at once. The view this one
925    /// read before is destroyed with `fresh`.
926    pub(crate) fn rebind(&self, fresh: MaterializedView) {
927        if self.is_destroyed() {
928            return;
929        }
930        for inner in [&self.0, &fresh.0] {
931            if let Some(r) = inner.remove_forward.borrow_mut().take() {
932                r();
933            }
934        }
935        std::mem::swap(
936            &mut *self.0.binding.borrow_mut(),
937            &mut *fresh.0.binding.borrow_mut(),
938        );
939        ViewInner::forward(&self.0);
940    }
941
942    /// The view's rows now.
943    pub fn data(&self) -> ViewValue {
944        self.view().data()
945    }
946
947    /// Whether the server has confirmed the rows on this connection
948    /// (`Complete`) or an earlier one (`Cached`), or not yet (`Unknown`), or
949    /// the query failed (`Error`).
950    pub fn result_type(&self) -> ResultType {
951        self.view().listener_result_type().0
952    }
953
954    /// Why the query failed, when it did.
955    pub fn error(&self) -> Option<ErroredQuery> {
956        self.view().listener_result_type().1
957    }
958
959    /// Whether `destroy` was called.
960    pub fn is_destroyed(&self) -> bool {
961        self.0.destroyed.get()
962    }
963
964    /// The primary key columns of the rows.
965    pub fn primary_key(&self) -> Vec<String> {
966        self.view().schema().primary_key.clone()
967    }
968
969    /// Calls `listener` now and whenever the data or result type change.
970    /// Returns the function that removes it.
971    pub fn add_listener(
972        &self,
973        listener: impl Fn(&ViewValue, ResultType, Option<&ErroredQuery>) + 'static,
974    ) -> Box<dyn Fn()> {
975        let id = self.0.next_listener_id.get();
976        self.0.next_listener_id.set(id + 1);
977        let listener: ViewListener = Rc::new(listener);
978        self.0.listeners.borrow_mut().push((id, listener.clone()));
979        let view = self.view();
980        let (ty, error) = view.listener_result_type();
981        listener(&view.data(), ty, error.as_ref());
982        let weak = Rc::downgrade(&self.0);
983        Box::new(move || {
984            if let Some(inner) = weak.upgrade() {
985                inner.listeners.borrow_mut().retain(|(i, _)| *i != id);
986            }
987        })
988    }
989
990    /// Stops updating the view and releases its query, which the server
991    /// keeps syncing for the query's TTL.
992    pub fn destroy(&self) {
993        self.0.destroy();
994    }
995
996    /// Raises the query's TTL; a lower one is ignored.
997    pub fn update_ttl(&self, ttl: &Ttl) {
998        (self.0.binding.borrow().update_ttl)(ttl);
999    }
1000}
1001
1002impl ViewInner {
1003    /// Passes what the bound view says on to the listeners.
1004    fn forward(inner: &Rc<ViewInner>) {
1005        let weak = Rc::downgrade(inner);
1006        let view = inner.binding.borrow().view.clone();
1007        let remove = view.add_listener(move |data, result_type| {
1008            let Some(inner) = weak.upgrade() else { return };
1009            let (error, notifications) = {
1010                let b = inner.binding.borrow();
1011                (b.view.listener_result_type().1, b.notifications.clone())
1012            };
1013            notifications.set(notifications.get() + 1);
1014            inner.forwarding.set(inner.forwarding.get() + 1);
1015            // Each listener in turn, reading the list again after every
1016            // call, as JS iterates a `Set` that changes meanwhile.
1017            let mut last: Option<u64> = None;
1018            loop {
1019                let next = inner
1020                    .listeners
1021                    .borrow()
1022                    .iter()
1023                    .find(|(id, _)| last.is_none_or(|l| *id > l))
1024                    .cloned();
1025                let Some((id, listener)) = next else { break };
1026                last = Some(id);
1027                listener(data, result_type, error.as_ref());
1028            }
1029            notifications.set(notifications.get() - 1);
1030            inner.forwarding.set(inner.forwarding.get() - 1);
1031            // Destroyed during the pass: its listeners went on hearing it.
1032            if inner.destroyed.get() && inner.forwarding.get() == 0 {
1033                inner.listeners.borrow_mut().clear();
1034            }
1035        });
1036        *inner.remove_forward.borrow_mut() = Some(remove);
1037    }
1038
1039    fn destroy(&self) {
1040        if self.destroyed.replace(true) {
1041            return;
1042        }
1043        if let Some(r) = self.remove_forward.borrow_mut().take() {
1044            r();
1045        }
1046        if self.forwarding.get() == 0 {
1047            self.listeners.borrow_mut().clear();
1048        }
1049        let view = self.binding.borrow().view.clone();
1050        view.destroy();
1051    }
1052}
1053
1054impl Drop for ViewInner {
1055    fn drop(&mut self) {
1056        self.destroy();
1057    }
1058}