Skip to main content

rustango_cms/api/
search.rs

1//! `GET /api/v2/search/?q=` — one search box, every content type.
2//!
3//! Each list endpoint has its own `?search=`, so a site-wide search used
4//! to be four parallel requests the client merged and ranked itself —
5//! with nothing in the responses to rank *by*, since none of them carries
6//! a score. That is a lot of work to hand a frontend for the most
7//! ordinary feature a site has.
8//!
9//! This runs the same per-type searches server-side and returns one
10//! ordered list of typed hits. Pages go through the real page search
11//! (`crate::search`), so a configured Postgres FTS or Elasticsearch
12//! backend applies — and so do editorial search promotions, which were
13//! previously invisible to any API client.
14//!
15//! Results are **viewer-aware**: gated pages and assets in closed
16//! collections are dropped before ranking, so search cannot be used to
17//! enumerate what the caller may not read.
18
19/// Fold `s` for a case-insensitive substring match — Unicode-aware, so
20/// `Новини` matches `новини` and `ÜBER` matches `über`. The one fold every
21/// API search fallback uses, matching the admin explorer.
22pub(crate) fn fold(s: &str) -> String {
23    s.to_lowercase()
24}
25
26/// Whether `haystack` contains `folded_needle`, a needle already passed
27/// through [`fold`].
28pub(crate) fn contains_folded(haystack: &str, folded_needle: &str) -> bool {
29    fold(haystack).contains(folded_needle)
30}
31
32// Our extractor, not axum's — see `query::Query`.
33use crate::api::query::Query;
34use axum::response::{IntoResponse, Response};
35use axum::Json;
36use rustango::core::Column as _;
37use rustango::extractors::{SessionUser, Tenant};
38use rustango::sql::FetcherPool as _;
39use serde::Deserialize;
40
41use super::query as q;
42use crate::media::Media;
43use crate::page::{Page, PageStatus};
44use crate::snippet::Snippet;
45
46/// Content types the unified search covers.
47const ALL_TYPES: [&str; 4] = ["page", "image", "document", "snippet"];
48
49#[derive(Debug, Default, Deserialize)]
50pub struct SearchQuery {
51    /// The needle. Absent or empty is a 400 — an empty search is a
52    /// client bug, and answering it with "everything" is the worst
53    /// possible guess.
54    #[serde(default, deserialize_with = "q::empty_string_as_none")]
55    pub q: Option<String>,
56    /// `?type=page,snippet` — restrict to some of the four. Unknown
57    /// names are a 400 rather than a silent empty result, since a typo
58    /// would otherwise look exactly like "no matches".
59    #[serde(default, deserialize_with = "q::empty_string_as_none")]
60    pub r#type: Option<String>,
61    #[serde(default, deserialize_with = "q::empty_as_none")]
62    pub limit: Option<usize>,
63    #[serde(default, deserialize_with = "q::empty_as_none")]
64    pub offset: Option<usize>,
65}
66
67/// `GET /api/v2/search/`
68pub async fn search(
69    tenant: Tenant,
70    SessionUser(session_user): SessionUser,
71    rustango::tenancy::member_auth::CurrentMember(member): rustango::tenancy::member_auth::CurrentMember,
72    crate::api::auth::BearerMember(bearer): crate::api::auth::BearerMember,
73    Query(qs): Query<SearchQuery>,
74) -> Response {
75    let viewer = member.as_ref().or(bearer.as_ref()).or(session_user.as_ref());
76    match search_inner(&tenant, viewer, &qs).await {
77        Ok(resp) => resp,
78        Err(e) => {
79            tracing::error!(target: "rustango_cms::api", error = %e, "search failed");
80            crate::api::error::ApiError::internal().into_response()
81        }
82    }
83}
84
85pub async fn search_inner(
86    tenant: &Tenant,
87    viewer: Option<&rustango::tenancy::auth::User>,
88    qs: &SearchQuery,
89) -> Result<Response, rustango::sql::ExecError> {
90    let pool = tenant.pool();
91    let Some(needle) = qs.q.as_deref().map(str::trim).filter(|s| !s.is_empty()) else {
92        return Ok(
93            crate::api::error::ApiError::bad_request("missing `q` query parameter")
94                .into_response(),
95        );
96    };
97
98    let wanted = match requested_types(qs.r#type.as_deref()) {
99        Ok(t) => t,
100        Err(bad) => {
101            return Ok(crate::api::error::ApiError::bad_request(format!(
102                "unknown `type` value `{bad}` — expected any of: {}",
103                ALL_TYPES.join(", ")
104            ))
105            .into_response())
106        }
107    };
108
109    let mut hits: Vec<serde_json::Value> = Vec::new();
110    if wanted.contains(&"page") {
111        hits.extend(page_hits(pool, &tenant.org.slug, viewer, needle).await?);
112    }
113    if wanted.contains(&"image") || wanted.contains(&"document") {
114        hits.extend(media_hits(pool, viewer, needle, &wanted).await?);
115    }
116    if wanted.contains(&"snippet") {
117        hits.extend(snippet_hits(pool, needle).await?);
118    }
119
120    // Rank across types by a shared, explainable score, then by title so
121    // ties are stable and a client paging through sees each row once.
122    hits.sort_by(|a, b| {
123        let sa = a["score"].as_f64().unwrap_or(0.0);
124        let sb = b["score"].as_f64().unwrap_or(0.0);
125        sb.partial_cmp(&sa)
126            .unwrap_or(std::cmp::Ordering::Equal)
127            .then_with(|| a["title"].as_str().cmp(&b["title"].as_str()))
128            .then_with(|| a["id"].as_i64().cmp(&b["id"].as_i64()))
129    });
130
131    let total_count = hits.len();
132    let limit = q::clamp_limit(qs.limit);
133    let offset = qs.offset.unwrap_or(0);
134    crate::search_promotion::log_public_query(pool, needle, offset);
135    let items: Vec<serde_json::Value> = hits.into_iter().skip(offset).take(limit).collect();
136
137    let mut meta = serde_json::to_value(q::ListMeta::paged(total_count, limit, offset))
138        .unwrap_or_else(|_| serde_json::json!({}));
139    if let Some(obj) = meta.as_object_mut() {
140        obj.insert("q".to_owned(), serde_json::json!(needle));
141        obj.insert("types".to_owned(), serde_json::json!(wanted));
142    }
143    Ok(Json(serde_json::json!({ "meta": meta, "items": items })).into_response())
144}
145
146/// Parse `?type=`, defaulting to everything.
147fn requested_types(raw: Option<&str>) -> Result<Vec<&'static str>, String> {
148    let Some(raw) = raw else {
149        return Ok(ALL_TYPES.to_vec());
150    };
151    let mut out = Vec::new();
152    for name in raw.split(',').map(str::trim).filter(|s| !s.is_empty()) {
153        match ALL_TYPES.iter().find(|t| **t == name) {
154            Some(t) => {
155                if !out.contains(t) {
156                    out.push(*t);
157                }
158            }
159            None => return Err(name.to_owned()),
160        }
161    }
162    if out.is_empty() {
163        return Ok(ALL_TYPES.to_vec());
164    }
165    Ok(out)
166}
167
168/// How well `haystack` answers `needle`, in `0.0..=1.0`.
169///
170/// Deliberately simple and the same for every type, because the point is
171/// that hits are *comparable* across types — a per-type relevance number
172/// nobody can reconcile is what the client already had. An exact title
173/// beats a prefix beats a substring; matching a secondary field (a slug,
174/// a filename, body text) scores below any title match.
175#[must_use]
176pub fn score(needle: &str, title: &str, secondary: &[&str]) -> f64 {
177    let n = fold(needle);
178    let t = fold(title);
179    if t == n {
180        return 1.0;
181    }
182    if t.starts_with(&n) {
183        return 0.8;
184    }
185    if t.contains(&n) {
186        return 0.6;
187    }
188    if secondary.iter().any(|s| contains_folded(s, &n)) {
189        return 0.3;
190    }
191    0.0
192}
193
194fn hit(
195    kind: &str,
196    id: i64,
197    title: &str,
198    url: Option<String>,
199    detail_url: String,
200    score: f64,
201) -> serde_json::Value {
202    serde_json::json!({
203        "type": kind,
204        "id": id,
205        "title": title,
206        "url": url,
207        "detail_url": detail_url,
208        "score": score,
209    })
210}
211
212async fn page_hits(
213    pool: &rustango::sql::Pool,
214    tenant_slug: &str,
215    viewer: Option<&rustango::tenancy::auth::User>,
216    needle: &str,
217) -> Result<Vec<serde_json::Value>, rustango::sql::ExecError> {
218    let mut pages: Vec<Page> = Page::objects()
219        .where_(Page::status.is_in([
220            PageStatus::Published.as_str().to_owned(),
221            PageStatus::Archived.as_str().to_owned(),
222        ]))
223        .order_by(&[("id", false)])
224        .fetch(pool)
225        .await?;
226    pages.retain(|p| p.locale_variant_of.is_none());
227
228    // #members — drop gated pages before ranking, so search cannot be
229    // used to enumerate a member-only section by guessing words.
230    let triples: Vec<(i64, String, i64)> = pages
231        .iter()
232        .map(|p| {
233            (
234                p.id.get().copied().unwrap_or_default(),
235                p.path.clone(),
236                p.page_type_id,
237            )
238        })
239        .collect();
240    let denied = crate::view_restriction::denied_page_ids(pool, viewer, &triples).await;
241
242    // The installed backend (Elasticsearch) when there is one, else
243    // Postgres full-text — the same ranking the pages list uses.
244    let ranked = crate::search::ranked_public_page_ids(pool, tenant_slug, needle, 1000).await;
245    let rank_of: std::collections::HashMap<i64, usize> = ranked
246        .as_ref()
247        .map(|ids| ids.iter().enumerate().map(|(i, id)| (*id, i)).collect())
248        .unwrap_or_default();
249
250    Ok(pages
251        .into_iter()
252        .filter(|p| !denied.contains(&p.id.get().copied().unwrap_or_default()))
253        .filter_map(|p| {
254            let id = p.id.get().copied().unwrap_or_default();
255            // A backend hit outranks a substring match, and its position
256            // in the hit list breaks ties within that band.
257            let s = match rank_of.get(&id) {
258                Some(pos) => 0.9 - (*pos as f64 / 10_000.0).min(0.25),
259                None => score(needle, &p.title, &[&p.slug, &p.url_path, &p.seo_description]),
260            };
261            (s > 0.0).then(|| {
262                hit(
263                    "page",
264                    id,
265                    &p.title,
266                    Some(if p.url_path.is_empty() {
267                        "/".to_owned()
268                    } else {
269                        p.url_path.clone()
270                    }),
271                    format!("/api/v2/pages/{id}/"),
272                    s,
273                )
274            })
275        })
276        .collect())
277}
278
279async fn media_hits(
280    pool: &rustango::sql::Pool,
281    viewer: Option<&rustango::tenancy::auth::User>,
282    needle: &str,
283    wanted: &[&str],
284) -> Result<Vec<serde_json::Value>, rustango::sql::ExecError> {
285    let rows: Vec<Media> = Media::objects().fetch(pool).await?;
286
287    // #members — the same collection gating the media listings apply.
288    let collection_ids: Vec<i64> = rows.iter().filter_map(|m| m.collection_id).collect();
289    let denied =
290        crate::collection_view_restriction::denied_collection_ids(pool, viewer, &collection_ids)
291            .await;
292
293    Ok(rows
294        .into_iter()
295        .filter(|m| {
296            m.collection_id
297                .is_none_or(|c| !denied.contains(&c))
298        })
299        .filter_map(|m| {
300            let kind = if m.kind == "image" { "image" } else { "document" };
301            if !wanted.contains(&kind) {
302                return None;
303            }
304            let id = m.id.get().copied().unwrap_or_default();
305            let s = score(needle, &m.title, &[&m.filename, &m.alt_text]);
306            (s > 0.0).then(|| {
307                hit(
308                    kind,
309                    id,
310                    &m.title,
311                    None,
312                    format!("/api/v2/{kind}s/{id}/"),
313                    s,
314                )
315            })
316        })
317        .collect())
318}
319
320async fn snippet_hits(
321    pool: &rustango::sql::Pool,
322    needle: &str,
323) -> Result<Vec<serde_json::Value>, rustango::sql::ExecError> {
324    let rows: Vec<Snippet> = Snippet::objects().fetch(pool).await?;
325    Ok(rows
326        .into_iter()
327        .filter_map(|sn| {
328            let id = sn.id.get().copied().unwrap_or_default();
329            let s = score(needle, &sn.title, &[&sn.slug, &sn.type_name, &sn.body_markdown]);
330            (s > 0.0).then(|| {
331                hit(
332                    "snippet",
333                    id,
334                    &sn.title,
335                    None,
336                    format!("/api/v2/snippets/{id}/"),
337                    s,
338                )
339            })
340        })
341        .collect())
342}
343
344#[cfg(test)]
345mod tests {
346    use super::*;
347
348    #[test]
349    fn an_exact_title_outranks_a_prefix_outranks_a_substring() {
350        assert!(score("docs", "Docs", &[]) > score("docs", "Docs and more", &[]));
351        assert!(score("docs", "Docs and more", &[]) > score("docs", "The Docs page", &[]));
352        assert!(score("docs", "The Docs page", &[]) > score("docs", "Unrelated", &["docs.pdf"]));
353    }
354
355    #[test]
356    fn a_secondary_field_still_scores() {
357        assert!(score("report", "Q4", &["annual-report.pdf"]) > 0.0);
358    }
359
360    #[test]
361    fn no_match_scores_zero() {
362        assert_eq!(score("zebra", "Docs", &["a.pdf", "body text"]), 0.0);
363    }
364
365    #[test]
366    fn matching_is_case_insensitive() {
367        assert_eq!(score("DOCS", "docs", &[]), 1.0);
368        assert!(score("dOcS", "The Docs", &[]) > 0.0);
369    }
370
371    #[test]
372    fn no_type_filter_means_every_type() {
373        assert_eq!(requested_types(None).unwrap(), ALL_TYPES.to_vec());
374        // An all-whitespace list is the same as absent, not "nothing".
375        assert_eq!(requested_types(Some(" , ")).unwrap(), ALL_TYPES.to_vec());
376    }
377
378    #[test]
379    fn a_type_filter_is_parsed_and_deduped() {
380        assert_eq!(
381            requested_types(Some("page, snippet ,page")).unwrap(),
382            vec!["page", "snippet"],
383        );
384    }
385
386    #[test]
387    fn an_unknown_type_is_an_error_not_an_empty_result() {
388        // A typo must not look identical to "no matches".
389        assert_eq!(requested_types(Some("pages")).unwrap_err(), "pages");
390        assert_eq!(requested_types(Some("page,widget")).unwrap_err(), "widget");
391    }
392}
393
394#[cfg(test)]
395mod fold_tests {
396    use super::{contains_folded, fold};
397
398    #[test]
399    fn non_latin_and_accented_text_folds() {
400        assert!(contains_folded("Новини", &fold("новини")));
401        assert!(contains_folded("über uns", &fold("ÜBER")));
402        assert!(contains_folded("Ελληνικά", &fold("ΕΛΛΗΝΙΚΆ")));
403        assert!(!contains_folded("News", &fold("новини")));
404    }
405}