Skip to main content

zero_client/client/
inspector.rs

1//! The inspector (`packages/zero-client/src/client/inspector`): the
2//! client's queries and metrics, what the server knows of them, and the
3//! server's analysis of a query, for debugging and tooling.
4//!
5//! Its RPCs go over the sync socket as `inspect` messages
6//! (`packages/zero-protocol/src/inspect-up.ts` and `inspect-down.ts`).
7
8use super::engine::Engine;
9use super::planner_debug;
10use super::{ClientErrorKind, ConnectionError, Deferred, Error};
11use crate::ast::{Ast, ast_to_zql};
12use crate::decode::JsonCodable;
13use crate::json::{Object, Value};
14use crate::keys::ENTITIES_PREFIX;
15use crate::map::OrderedMap;
16use crate::query::ZeroQuery;
17use crate::schema::{NameMapper, Schema};
18use crate::tdigest::TDigest;
19use crate::ttl::Ttl;
20use std::cell::{Cell, RefCell};
21use std::rc::Rc;
22use std::sync::Arc;
23
24/// The client's and the server's query metrics (`Metrics` in
25/// `lazy-inspector.ts`), each a digest of times in ms.
26#[derive(Clone, Debug, Default, PartialEq)]
27pub struct Metrics {
28    /// `query-materialization-client`: building and hydrating a view.
29    pub query_materialization_client: TDigest,
30    /// `query-materialization-end-to-end`: from materializing a query
31    /// until the server has sent its rows.
32    pub query_materialization_end_to_end: TDigest,
33    /// `query-update-client`: a change through a query's pipeline. Only one
34    /// change in 32 is timed, and counts 32 times.
35    pub query_update_client: TDigest,
36    /// `query-materialization-server`: the server hydrating a query.
37    pub query_materialization_server: TDigest,
38    /// `query-update-server`: a change through the server's pipeline.
39    pub query_update_server: TDigest,
40}
41
42impl Metrics {
43    /// The digests by JS name, as their JSON forms.
44    pub fn to_json(&self) -> Value {
45        let mut o = Object::new();
46        o.insert(
47            "query-materialization-client",
48            self.query_materialization_client.to_json(),
49        );
50        o.insert(
51            "query-materialization-end-to-end",
52            self.query_materialization_end_to_end.to_json(),
53        );
54        o.insert("query-update-client", self.query_update_client.to_json());
55        o.insert(
56            "query-materialization-server",
57            self.query_materialization_server.to_json(),
58        );
59        o.insert("query-update-server", self.query_update_server.to_json());
60        Value::Object(o)
61    }
62}
63
64/// One query's client metrics (`QueryClientMetrics`): the last
65/// materialization's times, and its updates.
66#[derive(Clone, Debug, Default)]
67pub(crate) struct QueryClientMetrics {
68    pub(crate) query_materialization_client: Option<f64>,
69    pub(crate) query_materialization_end_to_end: Option<f64>,
70    pub(crate) query_update_client: TDigest,
71}
72
73/// What [`Inspector::analyze_query`] asks the server for besides the
74/// basics (`AnalyzeQueryOptions`). Options left `None` are not sent.
75#[derive(Clone, Debug, Default, PartialEq)]
76pub struct AnalyzeQueryOptions {
77    /// The rows the query read from each source.
78    pub vended_rows: Option<bool>,
79    /// The rows the query synced, by table.
80    pub synced_rows: Option<bool>,
81    /// The planner's debug events, for
82    /// [`Inspector::format_planner_events`].
83    pub join_plans: Option<bool>,
84}
85
86impl AnalyzeQueryOptions {
87    /// The options as sent; `None` when none is set.
88    fn to_json(&self) -> Option<Value> {
89        let mut o = Object::new();
90        for (key, v) in [
91            ("vendedRows", self.vended_rows),
92            ("syncedRows", self.synced_rows),
93            ("joinPlans", self.join_plans),
94        ] {
95            if let Some(v) = v {
96                o.insert(key, Value::Bool(v));
97            }
98        }
99        (!o.is_empty()).then_some(Value::Object(o))
100    }
101}
102
103/// One of the planner's debug events (`PlanDebugEventJSON` in
104/// `packages/zero-protocol/src/analyze-query-result.ts`), as JSON: its
105/// `type` says which.
106#[derive(Clone, Debug, PartialEq)]
107pub struct PlanDebugEvent(pub Value);
108
109/// Rows by query (or table).
110pub type RowsByQuery = OrderedMap<Vec<Object>>;
111/// Row counts by source, then by query.
112pub type RowCountsBySource = OrderedMap<OrderedMap<f64>>;
113/// Rows by source, then by query.
114pub type RowsBySource = OrderedMap<RowsByQuery>;
115
116/// The server's analysis of a query (`AnalyzeQueryResult` in
117/// `packages/zero-protocol/src/analyze-query-result.ts`).
118#[derive(Clone, Debug, Default, PartialEq)]
119pub struct AnalyzeQueryResult {
120    /// What the server warns about the query.
121    pub warnings: Vec<String>,
122    /// The rows synced, by table, when asked for.
123    pub synced_rows: Option<RowsByQuery>,
124    /// How many rows were synced.
125    pub synced_row_count: f64,
126    /// When the analysis started, in ms.
127    pub start: f64,
128    /// When it ended, in ms.
129    pub end: f64,
130    /// How long it took, in ms.
131    pub elapsed: Option<f64>,
132    /// The query after the permissions applied, as ZQL.
133    pub after_permissions: Option<String>,
134    /// The rows each source vended, counted.
135    pub vended_row_counts: Option<RowCountsBySource>,
136    /// The rows each source vended, when asked for.
137    pub vended_rows: Option<RowsBySource>,
138    /// SQLite's query plans, by query.
139    pub sqlite_plans: Option<OrderedMap<Vec<String>>>,
140    /// The rows read, by source and query.
141    pub read_rows: Option<RowsBySource>,
142    /// The rows read, counted by source and query.
143    pub read_row_counts_by_query: Option<RowCountsBySource>,
144    /// How many rows were read.
145    pub read_row_count: Option<f64>,
146    /// The database scans, counted by source and query.
147    pub db_scans_by_query: Option<RowCountsBySource>,
148    /// The planner's debug events, when asked for.
149    pub join_plans: Option<Vec<PlanDebugEvent>>,
150}
151
152fn record<T>(v: Option<&Value>, f: impl Fn(&Value) -> T) -> Option<OrderedMap<T>> {
153    let o = v?.as_object()?;
154    Some(o.iter().map(|(k, v)| (k.clone(), f(v))).collect())
155}
156
157fn rows(v: &Value) -> Vec<Object> {
158    v.as_array()
159        .map(|a| a.iter().filter_map(|r| r.as_object().cloned()).collect())
160        .unwrap_or_default()
161}
162
163fn number(v: &Value) -> f64 {
164    v.as_f64().unwrap_or(f64::NAN)
165}
166
167fn record_json<T>(r: &OrderedMap<T>, f: impl Fn(&T) -> Value) -> Value {
168    Value::Object(r.iter().map(|(k, v)| (k.clone(), f(v))).collect())
169}
170
171fn rows_json(rows: &[Object]) -> Value {
172    Value::Array(rows.iter().cloned().map(Value::Object).collect())
173}
174
175impl AnalyzeQueryResult {
176    /// The result of the JSON the server sent, already checked against
177    /// `analyzeQueryResultSchema`.
178    pub fn from_json(v: &Value) -> Self {
179        let get = |k: &str| v.get(k);
180        let counts = |k: &str| record(get(k), |v| record(Some(v), number).unwrap_or_default());
181        let by_source = |k: &str| record(get(k), |v| record(Some(v), rows).unwrap_or_default());
182        AnalyzeQueryResult {
183            warnings: get("warnings")
184                .and_then(Value::as_array)
185                .map(|a| {
186                    a.iter()
187                        .filter_map(|w| w.as_str().map(str::to_owned))
188                        .collect()
189                })
190                .unwrap_or_default(),
191            synced_rows: record(get("syncedRows"), rows),
192            synced_row_count: get("syncedRowCount").map_or(f64::NAN, number),
193            start: get("start").map_or(f64::NAN, number),
194            end: get("end").map_or(f64::NAN, number),
195            elapsed: get("elapsed").and_then(Value::as_f64),
196            after_permissions: get("afterPermissions")
197                .and_then(Value::as_str)
198                .map(str::to_owned),
199            vended_row_counts: counts("vendedRowCounts"),
200            vended_rows: by_source("vendedRows"),
201            sqlite_plans: record(get("sqlitePlans"), |v| {
202                v.as_array()
203                    .map(|a| {
204                        a.iter()
205                            .filter_map(|s| s.as_str().map(str::to_owned))
206                            .collect()
207                    })
208                    .unwrap_or_default()
209            }),
210            read_rows: by_source("readRows"),
211            read_row_counts_by_query: counts("readRowCountsByQuery"),
212            read_row_count: get("readRowCount").and_then(Value::as_f64),
213            db_scans_by_query: counts("dbScansByQuery"),
214            join_plans: get("joinPlans")
215                .and_then(Value::as_array)
216                .map(|a| a.iter().cloned().map(PlanDebugEvent).collect()),
217        }
218    }
219
220    /// The result as JSON, as the server sent it.
221    pub fn to_json(&self) -> Value {
222        let counts =
223            |c: &RowCountsBySource| record_json(c, |q| record_json(q, |n| Value::Number(*n)));
224        let by_source = |r: &RowsBySource| record_json(r, |q| record_json(q, |r| rows_json(r)));
225        let mut o = Object::new();
226        o.insert(
227            "warnings",
228            Value::Array(self.warnings.iter().cloned().map(Value::String).collect()),
229        );
230        if let Some(r) = &self.synced_rows {
231            o.insert("syncedRows", record_json(r, |r| rows_json(r)));
232        }
233        o.insert("syncedRowCount", Value::Number(self.synced_row_count));
234        o.insert("start", Value::Number(self.start));
235        o.insert("end", Value::Number(self.end));
236        if let Some(e) = self.elapsed {
237            o.insert("elapsed", Value::Number(e));
238        }
239        if let Some(a) = &self.after_permissions {
240            o.insert("afterPermissions", Value::String(a.clone()));
241        }
242        if let Some(c) = &self.vended_row_counts {
243            o.insert("vendedRowCounts", counts(c));
244        }
245        if let Some(r) = &self.vended_rows {
246            o.insert("vendedRows", by_source(r));
247        }
248        if let Some(p) = &self.sqlite_plans {
249            o.insert(
250                "sqlitePlans",
251                record_json(p, |p| {
252                    Value::Array(p.iter().cloned().map(Value::String).collect())
253                }),
254            );
255        }
256        if let Some(r) = &self.read_rows {
257            o.insert("readRows", by_source(r));
258        }
259        if let Some(c) = &self.read_row_counts_by_query {
260            o.insert("readRowCountsByQuery", counts(c));
261        }
262        if let Some(n) = self.read_row_count {
263            o.insert("readRowCount", Value::Number(n));
264        }
265        if let Some(c) = &self.db_scans_by_query {
266            o.insert("dbScansByQuery", counts(c));
267        }
268        if let Some(p) = &self.join_plans {
269            o.insert(
270                "joinPlans",
271                Value::Array(p.iter().map(|e| e.0.clone()).collect()),
272            );
273        }
274        Value::Object(o)
275    }
276}
277
278/// A query as the server and the client know it (`Query` in
279/// `inspector/query.ts`): one row of the server's `queries` answer, with
280/// the client's metrics merged in.
281#[derive(Clone, Debug, PartialEq)]
282pub struct InspectorQuery {
283    /// The named query's name; `None` for an unnamed one.
284    pub name: Option<String>,
285    /// The named query's arguments; `None` for an unnamed one.
286    pub args: Option<Vec<Value>>,
287    /// Whether the server has synced the query's rows.
288    pub got: bool,
289    /// The query's TTL, normalized.
290    pub ttl: Ttl,
291    /// When the query became inactive, in ms since 1970; `None` while
292    /// active.
293    pub inactivated_at: Option<f64>,
294    /// How many rows the query synced.
295    pub row_count: f64,
296    /// Whether the server deleted the query.
297    pub deleted: bool,
298    /// The query's ID, its hash.
299    pub id: String,
300    /// The client that wants it.
301    pub client_id: String,
302    /// The client's and the server's metrics of it.
303    pub metrics: Metrics,
304    /// The query as this client built it, as ZQL; `None` when this client
305    /// doesn't know it.
306    pub client_zql: Option<String>,
307    /// The query the server runs, as ZQL.
308    pub server_zql: Option<String>,
309    /// How long the client took to hydrate it, in ms.
310    pub hydrate_client: Option<f64>,
311    /// How long the server took to hydrate it, in ms.
312    pub hydrate_server: Option<f64>,
313    /// How long it took from materializing to the server's rows, in ms.
314    pub hydrate_total: Option<f64>,
315    /// The median client update, in ms.
316    pub update_client_p50: Option<f64>,
317    /// The 95th percentile client update, in ms.
318    pub update_client_p95: Option<f64>,
319    /// The median server update, in ms.
320    pub update_server_p50: Option<f64>,
321    /// The 95th percentile server update, in ms.
322    pub update_server_p95: Option<f64>,
323}
324
325/// `TimeClip` of `new Date(ms)`: the integer part, NaN past ±8.64e15.
326fn time_clip(ms: f64) -> f64 {
327    if !ms.is_finite() || ms.abs() > 8.64e15 {
328        return f64::NAN;
329    }
330    ms.trunc() + 0.0
331}
332
333fn percentile(d: &TDigest, q: f64) -> Option<f64> {
334    let n = d.quantile(q);
335    (!n.is_nan()).then_some(n)
336}
337
338fn zql(ast: &Ast) -> String {
339    format!("{}{}", ast.table, ast_to_zql(ast, false))
340}
341
342impl InspectorQuery {
343    /// The query of a row of the server's `queries` answer.
344    fn new(row: &Value, engine: &Engine) -> Self {
345        let get = |k: &str| row.get(k);
346        let str_of = |k: &str| {
347            get(k)
348                .and_then(Value::as_str)
349                .unwrap_or_default()
350                .to_owned()
351        };
352        let id = str_of("queryID");
353        let server_ast = get("ast").and_then(|a| Ast::from_json(a).ok());
354        let client_metrics = engine.query_manager.query_metrics(&id);
355        let server = get("metrics").filter(|m| !m.is_null());
356        let hydrate_server = server
357            .and_then(|m| m.get("query-hydration-server-ms"))
358            .and_then(Value::as_f64);
359        let cm = client_metrics.clone().unwrap_or_default();
360        let mut metrics = Metrics {
361            query_update_client: cm.query_update_client.clone(),
362            ..Metrics::default()
363        };
364        if let Some(v) = cm.query_materialization_client {
365            metrics.query_materialization_client.add(v, 1.0);
366        }
367        if let Some(v) = cm.query_materialization_end_to_end {
368            metrics.query_materialization_end_to_end.add(v, 1.0);
369        }
370        if let Some(server) = server {
371            if let Some(ms) = hydrate_server {
372                metrics.query_materialization_server.add(ms, 1.0);
373            }
374            if let Some(d) = server
375                .get("query-update-server")
376                .and_then(|d| TDigest::from_json_value(d).ok())
377            {
378                metrics.query_update_server = d;
379            }
380        }
381        InspectorQuery {
382            name: get("name").and_then(Value::as_str).map(str::to_owned),
383            args: get("args").and_then(Value::as_array).cloned(),
384            got: get("got").and_then(Value::as_bool).unwrap_or_default(),
385            ttl: Ttl::Milliseconds(get("ttl").and_then(Value::as_f64).unwrap_or_default())
386                .normalized(),
387            inactivated_at: get("inactivatedAt").and_then(Value::as_f64).map(time_clip),
388            row_count: get("rowCount").and_then(Value::as_f64).unwrap_or_default(),
389            deleted: get("deleted").and_then(Value::as_bool).unwrap_or_default(),
390            client_id: str_of("clientID"),
391            client_zql: engine.query_manager.query_ast(&id).as_ref().map(zql),
392            server_zql: server_ast.as_ref().map(zql),
393            hydrate_client: client_metrics
394                .as_ref()
395                .and_then(|m| m.query_materialization_client),
396            hydrate_server,
397            hydrate_total: client_metrics
398                .as_ref()
399                .and_then(|m| m.query_materialization_end_to_end),
400            update_client_p50: percentile(&metrics.query_update_client, 0.5),
401            update_client_p95: percentile(&metrics.query_update_client, 0.95),
402            update_server_p50: percentile(&metrics.query_update_server, 0.5),
403            update_server_p95: percentile(&metrics.query_update_server, 0.95),
404            metrics,
405            id,
406        }
407    }
408}
409
410/// What the inspector's handles share: the client, and the admin password
411/// zero-cache last accepted (`adminPassword`), which is presented again
412/// when a new connection isn't authenticated yet.
413pub(crate) struct InspectorHost {
414    pub(crate) engine: Box<dyn Fn() -> Option<Rc<Engine>>>,
415    pub(crate) schema: Arc<Schema>,
416    pub(crate) admin_password: RefCell<Option<String>>,
417}
418
419/// The error of an RPC the server refused for want of authentication.
420/// JS prompts for the password there.
421fn authentication_required() -> Error {
422    Error::Message(
423        "Authentication failed: zero-cache requires the inspector to authenticate. \
424         Call `authenticate(password)` with its admin password first."
425            .into(),
426    )
427}
428
429fn closed() -> Error {
430    ConnectionError::client(
431        ClientErrorKind::ClientClosed,
432        "Zero instance closed by user",
433    )
434    .into()
435}
436
437enum Answer {
438    Done(Result<Value, Error>),
439    Unauthenticated,
440}
441
442/// What an answer means for an RPC expecting `expect` (`rpcNoAuthTry`).
443fn classify(answer: &Result<Object, Error>, expect: &str) -> Answer {
444    let body = match answer {
445        Ok(b) => b,
446        Err(e) => return Answer::Done(Err(e.clone())),
447    };
448    let op = body.get("op").and_then(Value::as_str).unwrap_or_default();
449    let value = body.get("value").cloned().unwrap_or_default();
450    if op == "error" {
451        let message = value.as_str().unwrap_or_default().to_owned();
452        return Answer::Done(Err(Error::Message(message)));
453    }
454    if op == expect {
455        return Answer::Done(Ok(value));
456    }
457    if op == "authenticated" && value == Value::Bool(false) {
458        return Answer::Unauthenticated;
459    }
460    Answer::Done(Err(Error::Message(format!(
461        "Expected an inspector \"{expect}\" answer, got \"{op}\""
462    ))))
463}
464
465fn op(name: &str) -> Object {
466    let mut o = Object::new();
467    o.insert("op", Value::from(name));
468    o
469}
470
471impl InspectorHost {
472    fn engine(&self) -> Option<Rc<Engine>> {
473        let e = (self.engine)()?;
474        e.query_manager.keep_evicted();
475        Some(e)
476    }
477
478    /// Sends `body` with a new ID; settles with the server's answer.
479    fn send(&self, body: Object) -> Deferred<Object> {
480        let out = Deferred::new();
481        match self.engine() {
482            None => out.reject(closed()),
483            Some(e) => {
484                let o = out.clone();
485                e.event_loop
486                    .call(|| e.inspect(body, Box::new(move |r| o.settle(r))));
487            }
488        }
489        out
490    }
491
492    /// `authenticateSocket`.
493    fn authenticate_once(&self, password: &str) -> Deferred<bool> {
494        let mut body = op("authenticate");
495        body.insert("value", Value::from(password));
496        let out = Deferred::new();
497        let o = out.clone();
498        self.send(body)
499            .on_settle(move |r| match classify(r, "authenticated") {
500                Answer::Done(r) => o.settle(r.map(|v| v == Value::Bool(true))),
501                Answer::Unauthenticated => o.resolve(false),
502            });
503        out
504    }
505
506    /// `rpc`: sends `body`, and when the connection isn't authenticated,
507    /// presents the password accepted last and tries again.
508    fn rpc(self: &Rc<Self>, body: Object, expect: &'static str) -> Deferred<Value> {
509        let out = Deferred::new();
510        let (host, o) = (self.clone(), out.clone());
511        self.send(body.clone())
512            .on_settle(move |r| match classify(r, expect) {
513                Answer::Done(r) => o.settle(r),
514                Answer::Unauthenticated => host.authenticate_and_retry(body, expect, o),
515            });
516        out
517    }
518
519    fn authenticate_and_retry(
520        self: &Rc<Self>,
521        body: Object,
522        expect: &'static str,
523        out: Deferred<Value>,
524    ) {
525        let Some(password) = self.admin_password.borrow().clone() else {
526            return out.reject(authentication_required());
527        };
528        let host = self.clone();
529        self.authenticate_once(&password)
530            .on_settle(move |r| match r {
531                Err(e) => out.reject(e.clone()),
532                Ok(false) => {
533                    *host.admin_password.borrow_mut() = None;
534                    out.reject(authentication_required());
535                }
536                Ok(true) => host
537                    .send(body)
538                    .on_settle(move |r| match classify(r, expect) {
539                        Answer::Done(r) => out.settle(r),
540                        Answer::Unauthenticated => out.reject(authentication_required()),
541                    }),
542            });
543    }
544
545    /// The server's `queries` answer, as queries, slowest server hydration
546    /// first.
547    fn queries(self: &Rc<Self>, client_id: Option<&str>) -> Deferred<Vec<InspectorQuery>> {
548        let mut body = op("queries");
549        if let Some(id) = client_id {
550            body.insert("clientID", Value::from(id));
551        }
552        let out = Deferred::new();
553        let (host, o) = (self.clone(), out.clone());
554        self.rpc(body, "queries").on_settle(move |r| {
555            let rows = match r {
556                Ok(v) => v.as_array().cloned().unwrap_or_default(),
557                Err(e) => return o.reject(e.clone()),
558            };
559            let Some(engine) = host.engine() else {
560                return o.reject(closed());
561            };
562            let mut queries: Vec<InspectorQuery> = rows
563                .iter()
564                .map(|r| InspectorQuery::new(r, &engine))
565                .collect();
566            queries.sort_by(|a, b| {
567                let (a, b) = (
568                    a.hydrate_server.unwrap_or(0.0),
569                    b.hydrate_server.unwrap_or(0.0),
570                );
571                b.partial_cmp(&a).unwrap_or(std::cmp::Ordering::Equal)
572            });
573            o.resolve(queries);
574        });
575        out
576    }
577
578    /// The clients in the local store whose group `group` (any for
579    /// `None`) is.
580    fn clients(self: &Rc<Self>, group: Option<&str>) -> Deferred<Vec<InspectorClient>> {
581        let out = Deferred::new();
582        match self.engine() {
583            None => out.reject(closed()),
584            Some(e) => out.resolve(
585                e.database
586                    .clients()
587                    .into_iter()
588                    .filter(|c| group.is_none_or(|g| c.client_group_id == g))
589                    .map(|c| InspectorClient {
590                        host: self.clone(),
591                        id: c.id,
592                        client_group_id: c.client_group_id,
593                    })
594                    .collect(),
595            ),
596        }
597        out
598    }
599
600    /// The clients of `clients` the server has queries of, in the order
601    /// it answers (`clientsWithQueries`).
602    fn clients_with_queries(
603        self: &Rc<Self>,
604        clients: Deferred<Vec<InspectorClient>>,
605    ) -> Deferred<Vec<InspectorClient>> {
606        let out = Deferred::new();
607        let o = out.clone();
608        clients.on_settle(move |r| {
609            let clients = match r {
610                Ok(c) => c.clone(),
611                Err(e) => return o.reject(e.clone()),
612            };
613            if clients.is_empty() {
614                return o.resolve(Vec::new());
615            }
616            let found: Rc<RefCell<Vec<InspectorClient>>> = Rc::default();
617            let left = Rc::new(Cell::new(clients.len()));
618            for client in clients {
619                let (o, found, left) = (o.clone(), found.clone(), left.clone());
620                let queries = client.queries();
621                queries.on_settle(move |r| match r {
622                    Err(e) => o.reject(e.clone()),
623                    Ok(q) => {
624                        if !q.is_empty() {
625                            found.borrow_mut().push(client);
626                        }
627                        left.set(left.get() - 1);
628                        if left.get() == 0 {
629                            o.resolve(found.borrow().clone());
630                        }
631                    }
632                });
633            }
634        });
635        out
636    }
637
638    /// The entries of the store of `client_id`'s group with keys starting
639    /// with `prefix`, in key order.
640    fn entries(&self, client_id: &str, prefix: &str) -> Result<Vec<(String, Value)>, Error> {
641        let e = self.engine().ok_or_else(closed)?;
642        let client = e
643            .database
644            .clients()
645            .into_iter()
646            .find(|c| c.id == client_id)
647            .ok_or_else(|| Error::Message(format!("Client not found: {client_id}")))?;
648        let collect = |m: &super::replica_store::KvMap| {
649            m.scan(prefix)
650                .map(|(k, v)| (k.clone(), v.clone()))
651                .collect::<Vec<_>>()
652        };
653        // The client's own group is what the store holds now, as JS
654        // persists it before reading.
655        if client.client_group_id == e.client_group_id {
656            return Ok(collect(&e.store.borrow().main));
657        }
658        let group = e
659            .database
660            .group_entries(&client.client_group_id)
661            .ok_or_else(|| {
662                Error::Message(format!(
663                    "Client group not found: {}",
664                    client.client_group_id
665                ))
666            })?;
667        Ok(collect(&group))
668    }
669}
670
671fn settled<T: Clone + 'static>(r: Result<T, Error>) -> Deferred<T> {
672    let d = Deferred::new();
673    d.settle(r);
674    d
675}
676
677/// The inspector of a client (`Inspector` in `inspector/inspector.ts`),
678/// from [`Zero::inspector`](super::Zero::inspector).
679///
680/// zero-cache may require its admin password first: an RPC it refuses
681/// fails with an error saying so (JS prompts for the password instead).
682/// Once [`authenticate`](Self::authenticate) succeeds, the password is
683/// presented again when a new connection isn't authenticated yet.
684///
685/// An RPC waits for the connection. It fails when the connection drops
686/// before the answer, and when the client closes.
687pub struct Inspector<C = ()> {
688    pub(crate) host: Rc<InspectorHost>,
689    pub(crate) context: Rc<C>,
690    pub(crate) client_id: String,
691    pub(crate) client_group_id: String,
692}
693
694impl<C> Clone for Inspector<C> {
695    fn clone(&self) -> Self {
696        Inspector {
697            host: self.host.clone(),
698            context: self.context.clone(),
699            client_id: self.client_id.clone(),
700            client_group_id: self.client_group_id.clone(),
701        }
702    }
703}
704
705impl<C> Inspector<C> {
706    /// This client.
707    pub fn client(&self) -> InspectorClient {
708        InspectorClient {
709            host: self.host.clone(),
710            id: self.client_id.clone(),
711            client_group_id: self.client_group_id.clone(),
712        }
713    }
714
715    /// This client's group.
716    pub fn client_group(&self) -> InspectorClientGroup {
717        self.client().client_group()
718    }
719
720    /// The client's query metrics merged with the server's
721    /// (`inspectorMetrics`).
722    pub fn metrics(&self) -> Deferred<Metrics> {
723        let out = Deferred::new();
724        let (host, o) = (self.host.clone(), out.clone());
725        self.host.rpc(op("metrics"), "metrics").on_settle(move |r| {
726            let server = match r {
727                Ok(v) => v.clone(),
728                Err(e) => return o.reject(e.clone()),
729            };
730            let Some(engine) = host.engine() else {
731                return o.reject(closed());
732            };
733            let digest = |k: &str| {
734                server
735                    .get(k)
736                    .and_then(|d| TDigest::from_json_value(d).ok())
737                    .unwrap_or_default()
738            };
739            let mut metrics = engine.query_manager.metrics();
740            metrics.query_materialization_server = digest("query-materialization-server");
741            metrics.query_update_server = digest("query-update-server");
742            o.resolve(metrics);
743        });
744        out
745    }
746
747    /// Every client in the local store.
748    pub fn clients(&self) -> Deferred<Vec<InspectorClient>> {
749        self.host.clients(None)
750    }
751
752    /// The clients in the local store the server has queries of: asks the
753    /// server for each client's queries.
754    pub fn clients_with_queries(&self) -> Deferred<Vec<InspectorClient>> {
755        self.host.clients_with_queries(self.host.clients(None))
756    }
757
758    /// zero-cache's version.
759    pub fn server_version(&self) -> Deferred<String> {
760        let out = Deferred::new();
761        let o = out.clone();
762        self.host.rpc(op("version"), "version").on_settle(move |r| {
763            o.settle(r.clone().map(|v| v.as_str().unwrap_or_default().to_owned()))
764        });
765        out
766    }
767
768    fn analyze(
769        &self,
770        mut body: Object,
771        options: &AnalyzeQueryOptions,
772    ) -> Deferred<AnalyzeQueryResult> {
773        if let Some(o) = options.to_json() {
774            body.insert("options", o);
775        }
776        let out = Deferred::new();
777        let o = out.clone();
778        self.host.rpc(body, "analyze-query").on_settle(move |r| {
779            o.settle(
780                r.as_ref()
781                    .map(AnalyzeQueryResult::from_json)
782                    .map_err(Clone::clone),
783            )
784        });
785        out
786    }
787
788    /// Asks the server to analyze `query`: by name and arguments for a
789    /// named query, and by its AST, with the server's names, otherwise.
790    pub fn analyze_query(
791        &self,
792        query: &impl ZeroQuery<C>,
793        options: AnalyzeQueryOptions,
794    ) -> Deferred<AnalyzeQueryResult> {
795        let query = query.any_query(&self.context);
796        let mut body = op("analyze-query");
797        match query.custom_query_id() {
798            Some(id) => {
799                body.insert("name", Value::from(id.name.as_str()));
800                body.insert("args", Value::Array(id.args.clone()));
801            }
802            None => match NameMapper::client_to_server(&self.host.schema).map(query.ast()) {
803                Ok(ast) => {
804                    body.insert("ast", ast.to_json());
805                }
806                Err(e) => return settled(Err(Error::Message(e.to_string()))),
807            },
808        }
809        self.analyze(body, &options)
810    }
811
812    /// Asks the server to analyze `ast`, which is sent as is: it must
813    /// have the server's names.
814    pub fn analyze_server_ast(
815        &self,
816        ast: &Ast,
817        options: AnalyzeQueryOptions,
818    ) -> Deferred<AnalyzeQueryResult> {
819        let mut body = op("analyze-query");
820        body.insert("ast", ast.to_json());
821        self.analyze(body, &options)
822    }
823
824    /// Asks the server to analyze the named query `name` with `args`,
825    /// which its query handler resolves.
826    pub fn analyze_named_query(
827        &self,
828        name: &str,
829        args: Vec<Value>,
830        options: AnalyzeQueryOptions,
831    ) -> Deferred<AnalyzeQueryResult> {
832        let mut body = op("analyze-query");
833        body.insert("name", Value::from(name));
834        body.insert("args", Value::Array(args));
835        self.analyze(body, &options)
836    }
837
838    /// Authenticates with zero-cache's admin password: true when it
839    /// accepts it (or runs in a development mode that doesn't check).
840    /// zero-cache authenticates each connection; an accepted password is
841    /// presented again on a new one.
842    pub fn authenticate(&self, password: &str) -> Deferred<bool> {
843        let out = Deferred::new();
844        let (host, o, password) = (self.host.clone(), out.clone(), password.to_owned());
845        self.host.authenticate_once(&password).on_settle(move |r| {
846            if matches!(r, Ok(true)) {
847                *host.admin_password.borrow_mut() = Some(password);
848            }
849            o.settle(r.clone());
850        });
851        out
852    }
853
854    /// The planner's debug events (`AnalyzeQueryResult::join_plans`) as
855    /// text: each attempt's costs, then the plan chosen.
856    pub fn format_planner_events(&self, events: &[PlanDebugEvent]) -> String {
857        planner_debug::format_planner_events(events)
858    }
859}
860
861/// A client in the local store (`Client` in `inspector/client.ts`).
862#[derive(Clone)]
863pub struct InspectorClient {
864    host: Rc<InspectorHost>,
865    id: String,
866    client_group_id: String,
867}
868
869impl std::fmt::Debug for InspectorClient {
870    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
871        f.debug_struct("InspectorClient")
872            .field("id", &self.id)
873            .field("client_group_id", &self.client_group_id)
874            .finish()
875    }
876}
877
878impl InspectorClient {
879    /// The client's ID.
880    pub fn id(&self) -> &str {
881        &self.id
882    }
883
884    /// The client's group.
885    pub fn client_group(&self) -> InspectorClientGroup {
886        InspectorClientGroup {
887            host: self.host.clone(),
888            id: self.client_group_id.clone(),
889        }
890    }
891
892    /// The server's queries of this client.
893    pub fn queries(&self) -> Deferred<Vec<InspectorQuery>> {
894        self.host.queries(Some(&self.id))
895    }
896
897    /// Every entry of the client's local store, in key order: its rows,
898    /// desired and got queries, and the rest.
899    pub fn map(&self) -> Deferred<OrderedMap<Value>> {
900        settled(
901            self.host
902                .entries(&self.id, "")
903                .map(|e| e.into_iter().collect()),
904        )
905    }
906
907    /// The rows of table `table` in the client's local store, in key
908    /// order.
909    pub fn rows(&self, table: &str) -> Deferred<Vec<Object>> {
910        let prefix = format!("{ENTITIES_PREFIX}{table}/");
911        settled(self.host.entries(&self.id, &prefix).map(|e| {
912            e.into_iter()
913                .filter_map(|(_, v)| match v {
914                    Value::Object(o) => Some(o),
915                    _ => None,
916                })
917                .collect()
918        }))
919    }
920}
921
922/// A client group in the local store (`ClientGroup` in
923/// `inspector/client-group.ts`).
924#[derive(Clone)]
925pub struct InspectorClientGroup {
926    host: Rc<InspectorHost>,
927    id: String,
928}
929
930impl std::fmt::Debug for InspectorClientGroup {
931    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
932        f.debug_struct("InspectorClientGroup")
933            .field("id", &self.id)
934            .finish()
935    }
936}
937
938impl InspectorClientGroup {
939    /// The group's ID.
940    pub fn id(&self) -> &str {
941        &self.id
942    }
943
944    /// The group's clients in the local store.
945    pub fn clients(&self) -> Deferred<Vec<InspectorClient>> {
946        self.host.clients(Some(&self.id))
947    }
948
949    /// The group's clients the server has queries of.
950    pub fn clients_with_queries(&self) -> Deferred<Vec<InspectorClient>> {
951        self.host
952            .clients_with_queries(self.host.clients(Some(&self.id)))
953    }
954
955    /// The server's queries of the group's clients.
956    pub fn queries(&self) -> Deferred<Vec<InspectorQuery>> {
957        self.host.queries(None)
958    }
959}