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