Skip to main content

zero_client/client/
zero.rs

1//! The public client (`Zero` in `packages/zero-client/src/client/zero.ts`)
2//! and its connection (`connection.ts`).
3
4use super::connection_manager::ConnectionState;
5use super::database::{ReplicaDatabase, replicache_name};
6use super::engine::{
7    Engine, MutationServerOutcome, MutatorFn, MutatorResult, UpdateNeededReason, ZeroOptions,
8};
9use super::inspector::{Inspector, InspectorHost};
10use super::live_view::LiveView;
11use super::mutation_tracker::OutcomeListeners;
12use super::query_context::{MaterializedView, Preload, RunType, WeakView};
13use super::storage::DroppedDatabases;
14use super::transaction::Transaction;
15use super::{ApplicationError, Deferred, Error, Scheduler, SocketFactory};
16use crate::ivm::ViewValue;
17use crate::json::Value;
18use crate::query::{AnyQuery, ZeroQuery};
19use crate::schema::Schema;
20use crate::ttl::Ttl;
21use crate::typed::TypedQuery;
22use std::cell::{Cell, RefCell};
23use std::collections::HashMap;
24use std::rc::Rc;
25use std::sync::Arc;
26
27type MutatorBody<C> = dyn Fn(&Transaction, Option<&Value>, &C) -> Result<Option<Value>, Error>;
28
29/// A mutator the client can run and replay by name (`defineMutator` in
30/// `packages/zql/src/mutate/mutator.ts`). The name must match the TS
31/// registry entry the API server runs.
32///
33/// The body runs synchronously: once optimistically, and again on every
34/// rebase over new server data while the mutation is pending, so it must
35/// only depend on the transaction, the arguments, and the context. It
36/// returns what the caller's `client` outcome carries.
37pub struct Mutator<C> {
38    /// The name the server runs it by: its path in the TS mutator registry.
39    pub name: String,
40    body: Rc<MutatorBody<C>>,
41}
42
43impl<C> Clone for Mutator<C> {
44    fn clone(&self) -> Self {
45        Mutator {
46            name: self.name.clone(),
47            body: self.body.clone(),
48        }
49    }
50}
51
52impl<C> Mutator<C> {
53    /// A mutator over JSON arguments: `args` is `None` when the caller
54    /// passed none (JS `undefined`).
55    pub fn new(
56        name: impl Into<String>,
57        body: impl Fn(&Transaction, Option<&Value>, &C) -> Result<Option<Value>, Error> + 'static,
58    ) -> Self {
59        Mutator {
60            name: name.into(),
61            body: Rc::new(body),
62        }
63    }
64}
65
66/// A mutator applied to its arguments, ready for [`Zero::mutate_request`]
67/// (`MutateRequest` in JS and Swift). A `define_mutator` definition makes
68/// one with `with`.
69#[derive(Clone, Debug, PartialEq)]
70pub struct MutateRequest {
71    /// The mutator's name.
72    pub name: String,
73    /// Its arguments as sent: `None` when it takes none (JS `undefined`).
74    pub args: Option<Value>,
75}
76
77impl MutateRequest {
78    /// A request with arguments already in their JSON form, for example to
79    /// replay a mutation by name. Prefer a definition's `with`.
80    pub fn new(name: impl Into<String>, args: Option<Value>) -> Self {
81        MutateRequest {
82            name: name.into(),
83            args,
84        }
85    }
86}
87
88/// A Zero client: syncs the rows of named queries from zero-cache into a
89/// local replica, keeps materialized views of them current, and runs
90/// mutators optimistically before the server confirms them.
91///
92/// `C` is what mutators are given besides their arguments, such as the
93/// logged-in user's auth data. Everything runs on the thread that made the
94/// client, driven by the [`Scheduler`] and the socket events.
95pub struct Zero<C = ()> {
96    core: Rc<Core>,
97    context: Rc<C>,
98}
99
100/// What the client keeps to replace its engine by a new one on the same
101/// store when the server lost its state (`replaceClient` in zero-swift's
102/// `ZeroClient`): the views and preloads move to the new engine.
103struct Core {
104    engine: RefCell<Rc<Engine>>,
105    schema: Arc<Schema>,
106    options: ZeroOptions,
107    functions: Rc<HashMap<String, MutatorFn>>,
108    scheduler: Rc<dyn Scheduler>,
109    socket_factory: Option<Rc<dyn SocketFactory>>,
110    connection: Connection,
111    views: RefCell<Vec<(WeakView, AnyQuery, Ttl)>>,
112    preloads: RefCell<Vec<Rc<PreloadRecord>>>,
113    /// What the client's inspectors share, once there is one.
114    inspector: RefCell<Option<Rc<InspectorHost>>>,
115    /// The mutation outcome listeners, which every engine reports to.
116    outcome_listeners: Rc<OutcomeListeners>,
117}
118
119/// A preload, which a replacement starts again on the new engine until
120/// its cleanup.
121struct PreloadRecord {
122    query: AnyQuery,
123    ttl: Ttl,
124    cleanup: RefCell<Rc<dyn Fn()>>,
125    active: Cell<bool>,
126}
127
128impl<C: 'static> Zero<C> {
129    /// - `schema`: the app's schema.
130    /// - `mutators`: every mutator the client may run. Pending mutations
131    ///   are replayed by name, so each must be registered.
132    /// - `scheduler`: the clock and timers, on the app's event loop; tests
133    ///   pass a [`ManualScheduler`](crate::testing::ManualScheduler).
134    /// - `socket_factory`: opens the sync socket. Without one the client
135    ///   runs locally.
136    ///
137    /// When the server no longer has the client's state, such as after it
138    /// closed the connection for a message over its size limit, and the
139    /// app set no `on_client_state_not_found`, the client replaces itself
140    /// by a new one on the same store, as JS reloads the page: a new client
141    /// ID and client group, the views and preloads kept, and pending
142    /// mutations of the old client group dropped.
143    pub fn new(
144        schema: Arc<Schema>,
145        context: C,
146        mutators: Vec<Mutator<C>>,
147        options: ZeroOptions,
148        scheduler: Rc<dyn Scheduler>,
149        socket_factory: Option<Rc<dyn SocketFactory>>,
150    ) -> Result<Self, Error> {
151        let context = Rc::new(context);
152        let mut functions: HashMap<String, MutatorFn> = HashMap::new();
153        for m in mutators {
154            if functions.contains_key(&m.name) {
155                return Err(ApplicationError::new(format!(
156                    "Mutator \"{}\" is registered twice",
157                    m.name
158                ))
159                .into());
160            }
161            let (body, context) = (m.body.clone(), context.clone());
162            functions.insert(m.name, Rc::new(move |tx, args| body(tx, args, &context)));
163        }
164        let functions = Rc::new(functions);
165        let engine = Engine::new(
166            schema.clone(),
167            options.clone(),
168            functions.clone(),
169            scheduler.clone(),
170            socket_factory.clone(),
171            true,
172        )?;
173        let connection = Connection::new(engine.clone());
174        let core = Rc::new(Core {
175            engine: RefCell::new(engine.clone()),
176            schema,
177            options,
178            functions,
179            scheduler,
180            socket_factory,
181            connection,
182            views: RefCell::default(),
183            preloads: RefCell::default(),
184            inspector: RefCell::default(),
185            outcome_listeners: Rc::default(),
186        });
187        Core::attach(&core, &engine);
188        Ok(Zero { core, context })
189    }
190
191    fn engine(&self) -> Rc<Engine> {
192        self.core.engine()
193    }
194
195    /// The client's ID, which changes when it replaces itself.
196    pub fn client_id(&self) -> String {
197        self.engine().client_id.clone()
198    }
199
200    /// The client group's ID, which changes when the client replaces
201    /// itself.
202    pub fn client_group_id(&self) -> String {
203        self.engine().client_group_id.clone()
204    }
205
206    /// The user the client syncs for.
207    pub fn user_id(&self) -> Option<&str> {
208        self.core.options.user_id.as_deref()
209    }
210
211    /// The app's schema.
212    pub fn schema(&self) -> &Arc<Schema> {
213        &self.core.schema
214    }
215
216    /// What the mutators are given besides their arguments.
217    pub fn context(&self) -> &C {
218        &self.context
219    }
220
221    /// Whether the client is closed.
222    pub fn closed(&self) -> bool {
223        self.engine().closed()
224    }
225
226    /// The client's connection to zero-cache.
227    pub fn connection(&self) -> &Connection {
228        &self.core.connection
229    }
230
231    /// A view of the query's rows that stays current. Named queries are
232    /// synced from the server; an unnamed one only sees local data.
233    pub fn materialize(
234        &self,
235        query: &(impl ZeroQuery<C> + ?Sized),
236        ttl: &Ttl,
237    ) -> Result<MaterializedView, Error> {
238        let query = query.any_query(self.context());
239        let e = self.engine();
240        let view = e.event_loop.call(|| e.context.materialize(&query, ttl))?;
241        let mut views = self.core.views.borrow_mut();
242        views.retain(|(v, _, _)| v.upgrade().is_some_and(|v| !v.is_destroyed()));
243        views.push((view.downgrade(), query.into_owned(), ttl.clone()));
244        Ok(view)
245    }
246
247    /// The query's result read as its Rust type and kept current: its rows,
248    /// the row of a `one()` query, or the value of an aggregate, from a
249    /// typed [`Query`](crate::typed::Query) or a named query's
250    /// `QueryRequest`. Fails when the query can't be materialized, or when
251    /// its rows don't read as the type (an [`Error::Message`] saying why).
252    pub fn live<Q>(&self, query: &Q, ttl: &Ttl) -> Result<LiveView<Q::Value>, Error>
253    where
254        Q: TypedQuery<C> + ?Sized,
255        Q::Value: 'static,
256    {
257        LiveView::new(self.materialize(query, ttl)?)
258    }
259
260    /// The query's rows: what the replica holds now (`Unknown`), or once
261    /// the server has confirmed them on this connection (`Complete`) or
262    /// any (`Cached`). Await the result, or read it once settled.
263    ///
264    /// An unnamed query only sees local data: the server never confirms
265    /// it, so waiting for `Complete` or `Cached` never settles.
266    pub fn run(
267        &self,
268        query: &(impl ZeroQuery<C> + ?Sized),
269        run_type: RunType,
270        ttl: Option<&Ttl>,
271    ) -> Deferred<ViewValue> {
272        let query = query.any_query(self.context());
273        let e = self.engine();
274        e.event_loop.call(|| e.context.run(&query, run_type, ttl))
275    }
276
277    /// Keeps the query's rows synced without a view, until `cleanup`.
278    /// Preloading an unnamed query does nothing. JS's default `ttl` for a
279    /// preload is [`Ttl::DEFAULT_PRELOAD`], not `Ttl::default()`.
280    pub fn preload(&self, query: &(impl ZeroQuery<C> + ?Sized), ttl: &Ttl) -> Preload {
281        let query = query.any_query(self.context());
282        let e = self.engine();
283        let preload = e.event_loop.call(|| e.context.preload(&query, ttl));
284        let record = Rc::new(PreloadRecord {
285            query: query.into_owned(),
286            ttl: ttl.clone(),
287            cleanup: RefCell::new(preload.cleanup),
288            active: Cell::new(true),
289        });
290        let mut preloads = self.core.preloads.borrow_mut();
291        preloads.retain(|p| p.active.get());
292        preloads.push(record.clone());
293        Preload {
294            cleanup: Rc::new(move || {
295                record.active.set(false);
296                let cleanup = record.cleanup.borrow().clone();
297                cleanup();
298            }),
299            cached: preload.cached,
300            complete: preload.complete,
301        }
302    }
303
304    /// The inspector (`zero.inspector`): the client's queries and metrics
305    /// and what zero-cache knows of them, for debugging and tooling.
306    pub fn inspector(&self) -> Inspector<C> {
307        let host = self
308            .core
309            .inspector
310            .borrow_mut()
311            .get_or_insert_with(|| {
312                let core = Rc::downgrade(&self.core);
313                Rc::new(InspectorHost {
314                    engine: Box::new(move || core.upgrade().map(|c| c.engine())),
315                    schema: self.core.schema.clone(),
316                    admin_password: RefCell::new(None),
317                })
318            })
319            .clone();
320        // Evicted queries are kept for it from now on.
321        self.engine().query_manager.keep_evicted();
322        Inspector {
323            host,
324            context: self.context.clone(),
325            client_id: self.client_id(),
326            client_group_id: self.client_group_id(),
327        }
328    }
329
330    /// Runs a mutator on the client now and sends it to the server. A
331    /// mutator not registered with this client doesn't run: both outcomes
332    /// are a `ZeroError` saying so. JS throws that error instead.
333    pub fn mutate(&self, name: &str, args: Option<Value>) -> MutatorResult {
334        let e = self.engine();
335        e.event_loop.call(|| e.mutate(name, args))
336    }
337
338    /// [`mutate`](Zero::mutate) of a request, such as a `define_mutator`
339    /// definition applied to its arguments: JS's and Swift's
340    /// `zero.mutate(request)`.
341    pub fn mutate_request(&self, request: MutateRequest) -> MutatorResult {
342        self.mutate(&request.name, request.args)
343    }
344
345    /// Calls `listener` with the server's outcome of each mutation this
346    /// client makes, once per mutation, as the server reports it. Returns
347    /// the function that removes it.
348    ///
349    /// Unlike a mutation's `server` result, it hears the outcome of a
350    /// mutation sent again after the connection came back: `server` settles
351    /// with [`MutationOutcome::ZeroError`](super::MutationOutcome::ZeroError)
352    /// when the client gives up connecting
353    /// ([`disconnect_timeout_ms`](ZeroOptions::disconnect_timeout_ms)), and
354    /// the mutation is replayed when it reconnects. A mutation still pending
355    /// when the app quits is replayed when it next launches, but its outcome
356    /// isn't reported, nor is a pending mutation's when the client replaces
357    /// itself. The listeners stay with the client when it does.
358    ///
359    /// Use it for a single place that shows rejections, instead of each
360    /// `server` result, so a rejection isn't shown twice. To read the
361    /// outcomes elsewhere, such as from an async task, send them to a
362    /// channel from the listener. Swift's `addMutationOutcomeListener`: the
363    /// JS client has no counterpart.
364    pub fn add_mutation_outcome_listener(
365        &self,
366        listener: impl Fn(&MutationServerOutcome) + 'static,
367    ) -> Box<dyn Fn()> {
368        let id = self.core.outcome_listeners.add(Rc::new(listener));
369        let weak = Rc::downgrade(&self.core.outcome_listeners);
370        Box::new(move || {
371            if let Some(listeners) = weak.upgrade() {
372                listeners.remove(id);
373            }
374        })
375    }
376
377    /// The app was shown, or hidden. Hidden for
378    /// `ZeroOptions::hidden_disconnect_delay_ms`, the client disconnects
379    /// until it is shown again.
380    pub fn set_visible(&self, visible: bool) {
381        let e = self.engine();
382        e.event_loop.call(|| e.set_visible(visible));
383    }
384
385    /// The network may be back: reconnect without waiting for the backoff.
386    pub fn reconnect_now(&self) {
387        let e = self.engine();
388        e.event_loop.call(|| e.reconnect_now());
389    }
390
391    /// Calls `done` once the server has confirmed every pending mutation,
392    /// or when it can't.
393    pub fn when_pending_settled(&self, done: impl FnOnce() + 'static) {
394        let e = self.engine();
395        e.event_loop.call(|| e.when_pending_settled(done));
396    }
397
398    /// Runs `body` as a task of the client's event loop: the work it
399    /// queues runs before this returns, as after a timer or a socket event.
400    #[doc(hidden)]
401    pub fn dispatch<T>(&self, body: impl FnOnce() -> T) -> T {
402        self.engine().event_loop.dispatch(body)
403    }
404
405    /// Closes the connection. Pending mutations and queries fail, and
406    /// views stop updating.
407    pub fn close(&self) {
408        let e = self.engine();
409        e.event_loop.call(|| e.close());
410    }
411
412    /// Waits for the local store's queued writes, such as before the app
413    /// exits. A failure to write them is reported to
414    /// `ZeroOptions::on_storage_failure`.
415    pub fn flush_storage(&self) {
416        self.engine().database.flush();
417    }
418
419    /// Closes the client and deletes its local data (`zero.delete()`): the
420    /// replica and pending mutations of this user and storage key, under
421    /// every schema version. Pending mutations the server hasn't confirmed
422    /// are lost. Use it to log a user out.
423    pub fn delete(&self) -> DroppedDatabases {
424        self.close();
425        let name = replicache_name(&self.engine().database.name);
426        ReplicaDatabase::drop_matching(&self.core.options.storage, &|n| n == name)
427    }
428}
429
430impl Core {
431    fn engine(&self) -> Rc<Engine> {
432        self.engine.borrow().clone()
433    }
434
435    /// Hooks `engine` up to the client: the connection hears it needs an
436    /// update, the mutation outcome listeners hear its mutations' outcomes,
437    /// and the client replaces it when it lost its state.
438    fn attach(core: &Rc<Core>, engine: &Rc<Engine>) {
439        engine.set_mutation_outcome_listeners(core.outcome_listeners.clone());
440        let connection = Rc::downgrade(&core.connection.0);
441        *engine.on_update_needed.borrow_mut() = Some(Rc::new(move |reason| {
442            if let Some(c) = connection.upgrade() {
443                *c.update_needed.borrow_mut() = Some(reason.clone());
444            }
445        }));
446        if core.options.on_client_state_not_found.is_none() {
447            let core = Rc::downgrade(core);
448            *engine.on_client_state_not_found.borrow_mut() = Some(Rc::new(move || {
449                if let Some(core) = core.upgrade() {
450                    Core::replace(&core);
451                }
452            }));
453        }
454    }
455
456    /// Replaces the engine, which can't sync any longer, by a new one on
457    /// the same store, and moves the views and preloads to it.
458    fn replace(core: &Rc<Core>) {
459        let old = core.engine();
460        if old.closed() {
461            return;
462        }
463        // The new engine goes on with the token the app last gave, not the
464        // one it started with.
465        let mut options = core.options.clone();
466        let auth = old.auth.borrow().clone();
467        options.auth = (!auth.is_empty()).then_some(auth);
468        let new = match Engine::new(
469            core.schema.clone(),
470            options,
471            core.functions.clone(),
472            core.scheduler.clone(),
473            core.socket_factory.clone(),
474            old.visible.get(),
475        ) {
476            Ok(new) => new,
477            Err(e) => {
478                old.log
479                    .error(|| format!("Failed to replace the client: {e}"));
480                return;
481            }
482        };
483        *core.engine.borrow_mut() = new.clone();
484        Core::attach(core, &new);
485        core.connection.bind(new.clone());
486        let views: Vec<_> = {
487            let mut views = core.views.borrow_mut();
488            views.retain(|(v, _, _)| v.upgrade().is_some_and(|v| !v.is_destroyed()));
489            views
490                .iter()
491                .filter_map(|(v, q, t)| Some((v.upgrade()?, q.clone(), t.clone())))
492                .collect()
493        };
494        for (view, query, ttl) in views {
495            if let Ok(fresh) = new
496                .event_loop
497                .call(|| new.context.materialize(&query, &ttl))
498            {
499                view.rebind(fresh);
500            }
501        }
502        let preloads: Vec<_> = {
503            let mut preloads = core.preloads.borrow_mut();
504            preloads.retain(|p| p.active.get());
505            preloads.clone()
506        };
507        for record in preloads {
508            let preload = new
509                .event_loop
510                .call(|| new.context.preload(&record.query, &record.ttl));
511            *record.cleanup.borrow_mut() = preload.cleanup;
512        }
513        old.event_loop.call(|| old.close());
514    }
515}
516
517impl<C> Drop for Zero<C> {
518    /// Dropping the client closes it: otherwise its socket would stay
519    /// open, and its timers run, with no client left to hear them.
520    fn drop(&mut self) {
521        let e = self.core.engine();
522        e.event_loop.call(|| e.close());
523    }
524}
525
526type StateListener = Rc<dyn Fn(&ConnectionState)>;
527
528struct ConnectionInner {
529    engine: RefCell<Rc<Engine>>,
530    /// Counts the engines bound, so a replaced one isn't heard.
531    generation: Cell<u64>,
532    state: RefCell<ConnectionState>,
533    update_needed: RefCell<Option<UpdateNeededReason>>,
534    listeners: RefCell<Vec<(u64, StateListener)>>,
535    next_id: Cell<u64>,
536}
537
538/// The connection to zero-cache (`Connection` in
539/// `packages/zero-client/src/client/connection.ts`).
540#[derive(Clone)]
541pub struct Connection(Rc<ConnectionInner>);
542
543impl Connection {
544    fn new(engine: Rc<Engine>) -> Self {
545        let inner = Rc::new(ConnectionInner {
546            state: RefCell::new(ConnectionState::of(&engine.connection_manager.state())),
547            engine: RefCell::new(engine.clone()),
548            generation: Cell::new(0),
549            update_needed: RefCell::new(None),
550            listeners: RefCell::default(),
551            next_id: Cell::new(0),
552        });
553        let connection = Connection(inner);
554        connection.listen(&engine);
555        connection
556    }
557
558    /// Follows `engine`'s state from now on, and reports it.
559    fn bind(&self, engine: Rc<Engine>) {
560        *self.0.engine.borrow_mut() = engine.clone();
561        self.0.generation.set(self.0.generation.get() + 1);
562        self.listen(&engine);
563        self.0
564            .changed(ConnectionState::of(&engine.connection_manager.state()));
565    }
566
567    fn listen(&self, engine: &Engine) {
568        let weak = Rc::downgrade(&self.0);
569        let generation = self.0.generation.get();
570        // The manager lives as long as the engine, which the connection
571        // keeps until it binds another.
572        let _ = engine.connection_manager.subscribe(move |s| {
573            let Some(inner) = weak.upgrade() else { return };
574            if inner.generation.get() == generation {
575                inner.changed(ConnectionState::of(s));
576            }
577        });
578    }
579
580    /// The state now.
581    pub fn state(&self) -> ConnectionState {
582        self.0.state.borrow().clone()
583    }
584
585    /// Why the app must be updated to sync, once the server said so
586    /// (`onUpdateNeeded`). Reconnecting doesn't help.
587    pub fn update_needed(&self) -> Option<UpdateNeededReason> {
588        self.0.update_needed.borrow().clone()
589    }
590
591    /// Calls `listener` on every change of `state`. Returns the function
592    /// that removes it.
593    pub fn subscribe(&self, listener: impl Fn(&ConnectionState) + 'static) -> Box<dyn Fn()> {
594        let id = self.0.next_id.get();
595        self.0.next_id.set(id + 1);
596        self.0.listeners.borrow_mut().push((id, Rc::new(listener)));
597        let weak = Rc::downgrade(&self.0);
598        Box::new(move || {
599            if let Some(inner) = weak.upgrade() {
600                inner.listeners.borrow_mut().retain(|(i, _)| *i != id);
601            }
602        })
603    }
604
605    /// Resumes connecting from `needs-auth` or `error` (`connect` in
606    /// `connection.ts`). From any other state it only applies `auth`, and
607    /// after a disconnect for a missing `cache_url` it never reconnects.
608    ///
609    /// `auth` first sets or clears the token, as `connect({auth})` does;
610    /// when already connected, the server gets a new non-empty token in
611    /// `updateAuth`. A token on a client without a `user_id` is an
612    /// [`Error::Connection`] of kind `Internal` (JS's rejection), and
613    /// nothing changes.
614    ///
615    /// It returns once the connection is asked to resume, not once it
616    /// has: JS's promise waits for the next state, which
617    /// [`subscribe`](Self::subscribe) follows here.
618    pub fn connect(&self, auth: ConnectAuth) -> Result<(), Error> {
619        let auth = match auth {
620            ConnectAuth::Keep => None,
621            ConnectAuth::Set(token) => Some(Some(token)),
622            ConnectAuth::Clear => Some(None),
623        };
624        let e = self.0.engine.borrow().clone();
625        e.event_loop.call(|| e.connect(auth))
626    }
627}
628
629/// What [`Connection::connect`] does with the auth token first: the
630/// `auth` of `connect({auth})` absent, a string, or `null`.
631#[derive(Clone, Debug, PartialEq, Eq, Hash)]
632pub enum ConnectAuth {
633    /// Keeps the token (no `auth`).
634    Keep,
635    /// Replaces the token.
636    Set(String),
637    /// Removes the token (`auth: null`).
638    Clear,
639}
640
641impl ConnectionInner {
642    fn changed(&self, state: ConnectionState) {
643        *self.state.borrow_mut() = state.clone();
644        let listeners: Vec<_> = self
645            .listeners
646            .borrow()
647            .iter()
648            .map(|(_, l)| l.clone())
649            .collect();
650        for l in listeners {
651            l(&state);
652        }
653    }
654}