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