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::{Engine, MutatorFn, MutatorResult, UpdateNeededReason, ZeroOptions};
7use super::query_context::{MaterializedView, Preload, RunType, WeakView};
8use super::storage::DroppedDatabases;
9use super::transaction::Transaction;
10use super::{ApplicationError, Deferred, Error, Scheduler, SocketFactory};
11use crate::ivm::ViewValue;
12use crate::json::Value;
13use crate::query::AnyQuery;
14use crate::schema::Schema;
15use crate::ttl::Ttl;
16use std::cell::{Cell, RefCell};
17use std::collections::HashMap;
18use std::rc::Rc;
19use std::sync::Arc;
20
21type MutatorBody<C> = dyn Fn(&Transaction, Option<&Value>, &C) -> Result<Option<Value>, Error>;
22
23/// A mutator the client can run and replay by name (`defineMutator` in
24/// `packages/zql/src/mutate/mutator.ts`). The name must match the TS
25/// registry entry the API server runs.
26///
27/// The body runs synchronously: once optimistically, and again on every
28/// rebase over new server data while the mutation is pending, so it must
29/// only depend on the transaction, the arguments, and the context. It
30/// returns what the caller's `client` outcome carries.
31pub struct Mutator<C> {
32    /// The name the server runs it by: its path in the TS mutator registry.
33    pub name: String,
34    body: Rc<MutatorBody<C>>,
35}
36
37impl<C> Clone for Mutator<C> {
38    fn clone(&self) -> Self {
39        Mutator {
40            name: self.name.clone(),
41            body: self.body.clone(),
42        }
43    }
44}
45
46impl<C> Mutator<C> {
47    /// A mutator over JSON arguments: `args` is `None` when the caller
48    /// passed none (JS `undefined`).
49    pub fn new(
50        name: impl Into<String>,
51        body: impl Fn(&Transaction, Option<&Value>, &C) -> Result<Option<Value>, Error> + 'static,
52    ) -> Self {
53        Mutator {
54            name: name.into(),
55            body: Rc::new(body),
56        }
57    }
58}
59
60/// A Zero client: syncs the rows of named queries from zero-cache into a
61/// local replica, keeps materialized views of them current, and runs
62/// mutators optimistically before the server confirms them.
63///
64/// `C` is what mutators are given besides their arguments, such as the
65/// logged-in user's auth data. Everything runs on the thread that made the
66/// client, driven by the [`Scheduler`] and the socket events.
67pub struct Zero<C = ()> {
68    core: Rc<Core>,
69    context: Rc<C>,
70}
71
72/// What the client keeps to replace its engine by a new one on the same
73/// store when the server lost its state (`replaceClient` in zero-swift's
74/// `ZeroClient`): the views and preloads move to the new engine.
75struct Core {
76    engine: RefCell<Rc<Engine>>,
77    schema: Arc<Schema>,
78    options: ZeroOptions,
79    functions: Rc<HashMap<String, MutatorFn>>,
80    scheduler: Rc<dyn Scheduler>,
81    socket_factory: Option<Rc<dyn SocketFactory>>,
82    connection: Connection,
83    views: RefCell<Vec<(WeakView, AnyQuery, Ttl)>>,
84    preloads: RefCell<Vec<Rc<PreloadRecord>>>,
85}
86
87/// A preload, which a replacement starts again on the new engine until
88/// its cleanup.
89struct PreloadRecord {
90    query: AnyQuery,
91    ttl: Ttl,
92    cleanup: RefCell<Rc<dyn Fn()>>,
93    active: Cell<bool>,
94}
95
96impl<C: 'static> Zero<C> {
97    /// - `schema`: the app's schema.
98    /// - `mutators`: every mutator the client may run. Pending mutations
99    ///   are replayed by name, so each must be registered.
100    /// - `scheduler`: the clock and timers, on the app's event loop; tests
101    ///   pass a [`ManualScheduler`](crate::testing::ManualScheduler).
102    /// - `socket_factory`: opens the sync socket. Without one the client
103    ///   runs locally.
104    ///
105    /// When the server no longer has the client's state, such as after it
106    /// closed the connection for a message over its size limit, and the
107    /// app set no `on_client_state_not_found`, the client replaces itself
108    /// by a new one on the same store, as JS reloads the page: a new client
109    /// ID and client group, the views and preloads kept, and pending
110    /// mutations of the old client group dropped.
111    pub fn new(
112        schema: Arc<Schema>,
113        context: C,
114        mutators: Vec<Mutator<C>>,
115        options: ZeroOptions,
116        scheduler: Rc<dyn Scheduler>,
117        socket_factory: Option<Rc<dyn SocketFactory>>,
118    ) -> Result<Self, Error> {
119        let context = Rc::new(context);
120        let mut functions: HashMap<String, MutatorFn> = HashMap::new();
121        for m in mutators {
122            if functions.contains_key(&m.name) {
123                return Err(ApplicationError::new(format!(
124                    "Mutator \"{}\" is registered twice",
125                    m.name
126                ))
127                .into());
128            }
129            let (body, context) = (m.body.clone(), context.clone());
130            functions.insert(m.name, Rc::new(move |tx, args| body(tx, args, &context)));
131        }
132        let functions = Rc::new(functions);
133        let engine = Engine::new(
134            schema.clone(),
135            options.clone(),
136            functions.clone(),
137            scheduler.clone(),
138            socket_factory.clone(),
139            true,
140        )?;
141        let connection = Connection::new(engine.clone());
142        let core = Rc::new(Core {
143            engine: RefCell::new(engine.clone()),
144            schema,
145            options,
146            functions,
147            scheduler,
148            socket_factory,
149            connection,
150            views: RefCell::default(),
151            preloads: RefCell::default(),
152        });
153        Core::attach(&core, &engine);
154        Ok(Zero { core, context })
155    }
156
157    fn engine(&self) -> Rc<Engine> {
158        self.core.engine()
159    }
160
161    /// The client's ID, which changes when it replaces itself.
162    pub fn client_id(&self) -> String {
163        self.engine().client_id.clone()
164    }
165
166    /// The client group's ID, which changes when the client replaces
167    /// itself.
168    pub fn client_group_id(&self) -> String {
169        self.engine().client_group_id.clone()
170    }
171
172    /// The user the client syncs for.
173    pub fn user_id(&self) -> Option<&str> {
174        self.core.options.user_id.as_deref()
175    }
176
177    /// The app's schema.
178    pub fn schema(&self) -> &Arc<Schema> {
179        &self.core.schema
180    }
181
182    /// What the mutators are given besides their arguments.
183    pub fn context(&self) -> &C {
184        &self.context
185    }
186
187    /// Whether the client is closed.
188    pub fn closed(&self) -> bool {
189        self.engine().closed()
190    }
191
192    /// The client's connection to zero-cache.
193    pub fn connection(&self) -> &Connection {
194        &self.core.connection
195    }
196
197    /// A view of the query's rows that stays current. Named queries are
198    /// synced from the server; an unnamed one only sees local data.
199    pub fn materialize(&self, query: &AnyQuery, ttl: &Ttl) -> Result<MaterializedView, Error> {
200        let e = self.engine();
201        let view = e.event_loop.call(|| e.context.materialize(query, ttl))?;
202        let mut views = self.core.views.borrow_mut();
203        views.retain(|(v, _, _)| v.upgrade().is_some_and(|v| !v.is_destroyed()));
204        views.push((view.downgrade(), query.clone(), ttl.clone()));
205        Ok(view)
206    }
207
208    /// The query's rows: what the replica holds now (`Unknown`), or once
209    /// the server has confirmed them on this connection (`Complete`) or
210    /// any (`Cached`). Await the result, or read it once settled.
211    ///
212    /// An unnamed query only sees local data: the server never confirms
213    /// it, so waiting for `Complete` or `Cached` never settles.
214    pub fn run(
215        &self,
216        query: &AnyQuery,
217        run_type: RunType,
218        ttl: Option<&Ttl>,
219    ) -> Deferred<ViewValue> {
220        let e = self.engine();
221        e.event_loop.call(|| e.context.run(query, run_type, ttl))
222    }
223
224    /// Keeps the query's rows synced without a view, until `cleanup`.
225    /// Preloading an unnamed query does nothing.
226    pub fn preload(&self, query: &AnyQuery, ttl: &Ttl) -> Preload {
227        let e = self.engine();
228        let preload = e.event_loop.call(|| e.context.preload(query, ttl));
229        let record = Rc::new(PreloadRecord {
230            query: query.clone(),
231            ttl: ttl.clone(),
232            cleanup: RefCell::new(preload.cleanup),
233            active: Cell::new(true),
234        });
235        let mut preloads = self.core.preloads.borrow_mut();
236        preloads.retain(|p| p.active.get());
237        preloads.push(record.clone());
238        Preload {
239            cleanup: Rc::new(move || {
240                record.active.set(false);
241                let cleanup = record.cleanup.borrow().clone();
242                cleanup();
243            }),
244            cached: preload.cached,
245            complete: preload.complete,
246        }
247    }
248
249    /// Runs a mutator on the client now and sends it to the server. A
250    /// mutator not registered with this client doesn't run: both outcomes
251    /// are a `ZeroError` saying so. JS throws that error instead.
252    pub fn mutate(&self, name: &str, args: Option<Value>) -> MutatorResult {
253        let e = self.engine();
254        e.event_loop.call(|| e.mutate(name, args))
255    }
256
257    /// The app was shown, or hidden. Hidden for
258    /// `ZeroOptions::hidden_disconnect_delay_ms`, the client disconnects
259    /// until it is shown again.
260    pub fn set_visible(&self, visible: bool) {
261        let e = self.engine();
262        e.event_loop.call(|| e.set_visible(visible));
263    }
264
265    /// The network may be back: reconnect without waiting for the backoff.
266    pub fn reconnect_now(&self) {
267        let e = self.engine();
268        e.event_loop.call(|| e.reconnect_now());
269    }
270
271    /// Calls `done` once the server has confirmed every pending mutation,
272    /// or when it can't.
273    pub fn when_pending_settled(&self, done: impl FnOnce() + 'static) {
274        let e = self.engine();
275        e.event_loop.call(|| e.when_pending_settled(done));
276    }
277
278    /// Runs `body` as a task of the client's event loop: the work it
279    /// queues runs before this returns, as after a timer or a socket event.
280    #[doc(hidden)]
281    pub fn dispatch<T>(&self, body: impl FnOnce() -> T) -> T {
282        self.engine().event_loop.dispatch(body)
283    }
284
285    /// Closes the connection. Pending mutations and queries fail, and
286    /// views stop updating.
287    pub fn close(&self) {
288        let e = self.engine();
289        e.event_loop.call(|| e.close());
290    }
291
292    /// Waits for the local store's queued writes, such as before the app
293    /// exits. A failure to write them is reported to
294    /// `ZeroOptions::on_storage_failure`.
295    pub fn flush_storage(&self) {
296        self.engine().database.flush();
297    }
298
299    /// Closes the client and deletes its local data (`zero.delete()`): the
300    /// replica and pending mutations of this user and storage key, under
301    /// every schema version. Pending mutations the server hasn't confirmed
302    /// are lost. Use it to log a user out.
303    pub fn delete(&self) -> DroppedDatabases {
304        self.close();
305        let name = replicache_name(&self.engine().database.name);
306        ReplicaDatabase::drop_matching(&self.core.options.storage, &|n| n == name)
307    }
308}
309
310impl Core {
311    fn engine(&self) -> Rc<Engine> {
312        self.engine.borrow().clone()
313    }
314
315    /// Hooks `engine` up to the client: the connection hears it needs an
316    /// update, and the client replaces it when it lost its state.
317    fn attach(core: &Rc<Core>, engine: &Rc<Engine>) {
318        let connection = Rc::downgrade(&core.connection.0);
319        *engine.on_update_needed.borrow_mut() = Some(Rc::new(move |reason| {
320            if let Some(c) = connection.upgrade() {
321                *c.update_needed.borrow_mut() = Some(reason.clone());
322            }
323        }));
324        if core.options.on_client_state_not_found.is_none() {
325            let core = Rc::downgrade(core);
326            *engine.on_client_state_not_found.borrow_mut() = Some(Rc::new(move || {
327                if let Some(core) = core.upgrade() {
328                    Core::replace(&core);
329                }
330            }));
331        }
332    }
333
334    /// Replaces the engine, which can't sync any longer, by a new one on
335    /// the same store, and moves the views and preloads to it.
336    fn replace(core: &Rc<Core>) {
337        let old = core.engine();
338        if old.closed() {
339            return;
340        }
341        // The new engine goes on with the token the app last gave, not the
342        // one it started with.
343        let mut options = core.options.clone();
344        let auth = old.auth.borrow().clone();
345        options.auth = (!auth.is_empty()).then_some(auth);
346        let new = match Engine::new(
347            core.schema.clone(),
348            options,
349            core.functions.clone(),
350            core.scheduler.clone(),
351            core.socket_factory.clone(),
352            old.visible.get(),
353        ) {
354            Ok(new) => new,
355            Err(e) => {
356                old.log
357                    .error(|| format!("Failed to replace the client: {e}"));
358                return;
359            }
360        };
361        *core.engine.borrow_mut() = new.clone();
362        Core::attach(core, &new);
363        core.connection.bind(new.clone());
364        let views: Vec<_> = {
365            let mut views = core.views.borrow_mut();
366            views.retain(|(v, _, _)| v.upgrade().is_some_and(|v| !v.is_destroyed()));
367            views
368                .iter()
369                .filter_map(|(v, q, t)| Some((v.upgrade()?, q.clone(), t.clone())))
370                .collect()
371        };
372        for (view, query, ttl) in views {
373            if let Ok(fresh) = new
374                .event_loop
375                .call(|| new.context.materialize(&query, &ttl))
376            {
377                view.rebind(fresh);
378            }
379        }
380        let preloads: Vec<_> = {
381            let mut preloads = core.preloads.borrow_mut();
382            preloads.retain(|p| p.active.get());
383            preloads.clone()
384        };
385        for record in preloads {
386            let preload = new
387                .event_loop
388                .call(|| new.context.preload(&record.query, &record.ttl));
389            *record.cleanup.borrow_mut() = preload.cleanup;
390        }
391        old.event_loop.call(|| old.close());
392    }
393}
394
395impl<C> Drop for Zero<C> {
396    /// Dropping the client closes it: otherwise its socket would stay
397    /// open, and its timers run, with no client left to hear them.
398    fn drop(&mut self) {
399        let e = self.core.engine();
400        e.event_loop.call(|| e.close());
401    }
402}
403
404type StateListener = Rc<dyn Fn(&ConnectionState)>;
405
406struct ConnectionInner {
407    engine: RefCell<Rc<Engine>>,
408    /// Counts the engines bound, so a replaced one isn't heard.
409    generation: Cell<u64>,
410    state: RefCell<ConnectionState>,
411    update_needed: RefCell<Option<UpdateNeededReason>>,
412    listeners: RefCell<Vec<(u64, StateListener)>>,
413    next_id: Cell<u64>,
414}
415
416/// The connection to zero-cache (`Connection` in
417/// `packages/zero-client/src/client/connection.ts`).
418#[derive(Clone)]
419pub struct Connection(Rc<ConnectionInner>);
420
421impl Connection {
422    fn new(engine: Rc<Engine>) -> Self {
423        let inner = Rc::new(ConnectionInner {
424            state: RefCell::new(ConnectionState::of(&engine.connection_manager.state())),
425            engine: RefCell::new(engine.clone()),
426            generation: Cell::new(0),
427            update_needed: RefCell::new(None),
428            listeners: RefCell::default(),
429            next_id: Cell::new(0),
430        });
431        let connection = Connection(inner);
432        connection.listen(&engine);
433        connection
434    }
435
436    /// Follows `engine`'s state from now on, and reports it.
437    fn bind(&self, engine: Rc<Engine>) {
438        *self.0.engine.borrow_mut() = engine.clone();
439        self.0.generation.set(self.0.generation.get() + 1);
440        self.listen(&engine);
441        self.0
442            .changed(ConnectionState::of(&engine.connection_manager.state()));
443    }
444
445    fn listen(&self, engine: &Engine) {
446        let weak = Rc::downgrade(&self.0);
447        let generation = self.0.generation.get();
448        // The manager lives as long as the engine, which the connection
449        // keeps until it binds another.
450        let _ = engine.connection_manager.subscribe(move |s| {
451            let Some(inner) = weak.upgrade() else { return };
452            if inner.generation.get() == generation {
453                inner.changed(ConnectionState::of(s));
454            }
455        });
456    }
457
458    /// The state now.
459    pub fn state(&self) -> ConnectionState {
460        self.0.state.borrow().clone()
461    }
462
463    /// Why the app must be updated to sync, once the server said so
464    /// (`onUpdateNeeded`). Reconnecting doesn't help.
465    pub fn update_needed(&self) -> Option<UpdateNeededReason> {
466        self.0.update_needed.borrow().clone()
467    }
468
469    /// Calls `listener` on every change of `state`. Returns the function
470    /// that removes it.
471    pub fn subscribe(&self, listener: impl Fn(&ConnectionState) + 'static) -> Box<dyn Fn()> {
472        let id = self.0.next_id.get();
473        self.0.next_id.set(id + 1);
474        self.0.listeners.borrow_mut().push((id, Rc::new(listener)));
475        let weak = Rc::downgrade(&self.0);
476        Box::new(move || {
477            if let Some(inner) = weak.upgrade() {
478                inner.listeners.borrow_mut().retain(|(i, _)| *i != id);
479            }
480        })
481    }
482
483    /// Resumes connecting from `needs-auth` or `error`. With `auth`, sets
484    /// the token first; when already connected, the server gets the new
485    /// token.
486    pub fn connect(&self, auth: Option<String>) {
487        let e = self.0.engine.borrow().clone();
488        e.event_loop.call(|| e.connect(auth.map(Some)));
489    }
490}
491
492impl ConnectionInner {
493    fn changed(&self, state: ConnectionState) {
494        *self.state.borrow_mut() = state.clone();
495        let listeners: Vec<_> = self
496            .listeners
497            .borrow()
498            .iter()
499            .map(|(_, l)| l.clone())
500            .collect();
501        for l in listeners {
502            l(&state);
503        }
504    }
505}