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    // The substring match is Unicode case-folded in Rust (`fold`), which
219    // no SQL `LIKE` does the same way on every backend, so the public rows
220    // are read here and matched in memory. Only the exact filters run in
221    // SQL (#655).
222    let pages: Vec<Page> = Page::objects()
223        .where_(Page::status.is_in([
224            PageStatus::Published.as_str().to_owned(),
225            PageStatus::Archived.as_str().to_owned(),
226        ]))
227        .where_(Page::locale_variant_of.is_null())
228        .order_by(&[("id", false)])
229        .fetch(pool)
230        .await?;
231
232    // #members — drop gated pages before ranking, so search cannot be
233    // used to enumerate a member-only section by guessing words.
234    let access = crate::view_restriction::access_context(pool, viewer).await;
235
236    // The installed backend (Elasticsearch) when there is one, else
237    // Postgres full-text — the same ranking the pages list uses.
238    let ranked = crate::search::ranked_public_page_ids(pool, tenant_slug, needle, 1000).await;
239    let rank_of: std::collections::HashMap<i64, usize> = ranked
240        .as_ref()
241        .map(|ids| ids.iter().enumerate().map(|(i, id)| (*id, i)).collect())
242        .unwrap_or_default();
243
244    Ok(pages
245        .into_iter()
246        .filter(|p| access.can_view(&p.path, p.page_type_id))
247        .filter_map(|p| {
248            let id = p.id.get().copied().unwrap_or_default();
249            // A backend hit outranks a substring match, and its position
250            // in the hit list breaks ties within that band.
251            let s = match rank_of.get(&id) {
252                Some(pos) => 0.9 - (*pos as f64 / 10_000.0).min(0.25),
253                None => score(needle, &p.title, &[&p.slug, &p.url_path, &p.seo_description]),
254            };
255            (s > 0.0).then(|| {
256                hit(
257                    "page",
258                    id,
259                    &p.title,
260                    Some(if p.url_path.is_empty() {
261                        "/".to_owned()
262                    } else {
263                        p.url_path.clone()
264                    }),
265                    format!("/api/v2/pages/{id}/"),
266                    s,
267                )
268            })
269        })
270        .collect())
271}
272
273async fn media_hits(
274    pool: &rustango::sql::Pool,
275    viewer: Option<&rustango::tenancy::auth::User>,
276    needle: &str,
277    wanted: &[&str],
278) -> Result<Vec<serde_json::Value>, rustango::sql::ExecError> {
279    // #members — the same collection gating the media listings apply,
280    // in SQL; the collections table is small.
281    let collection_ids: Vec<i64> = crate::media::MediaCollection::objects()
282        .fetch(pool)
283        .await?
284        .iter()
285        .filter_map(|c| c.id.get().copied())
286        .collect();
287    let denied =
288        crate::collection_view_restriction::denied_collection_ids(pool, viewer, &collection_ids)
289            .await;
290    let mut qs = Media::objects();
291    match (wanted.contains(&"image"), wanted.contains(&"document")) {
292        (true, false) => qs = qs.where_(Media::kind.eq("image".to_owned())),
293        (false, true) => qs = qs.where_(Media::kind.ne("image".to_owned())),
294        _ => {}
295    }
296    if !denied.is_empty() {
297        qs = qs.where_(
298            Media::collection_id
299                .is_null()
300                .or(Media::collection_id.not_in(denied.iter().copied())),
301        );
302    }
303    // Matched in memory for the same reason as `page_hits`.
304    let rows: Vec<Media> = qs.fetch(pool).await?;
305
306    Ok(rows
307        .into_iter()
308        .filter_map(|m| {
309            let kind = if m.kind == "image" { "image" } else { "document" };
310            if !wanted.contains(&kind) {
311                return None;
312            }
313            let id = m.id.get().copied().unwrap_or_default();
314            let s = score(needle, &m.title, &[&m.filename, &m.alt_text]);
315            (s > 0.0).then(|| {
316                hit(
317                    kind,
318                    id,
319                    &m.title,
320                    None,
321                    format!("/api/v2/{kind}s/{id}/"),
322                    s,
323                )
324            })
325        })
326        .collect())
327}
328
329async fn snippet_hits(
330    pool: &rustango::sql::Pool,
331    needle: &str,
332) -> Result<Vec<serde_json::Value>, rustango::sql::ExecError> {
333    // Matched in memory for the same reason as `page_hits`.
334    let rows: Vec<Snippet> = Snippet::objects().fetch(pool).await?;
335    Ok(rows
336        .into_iter()
337        .filter_map(|sn| {
338            let id = sn.id.get().copied().unwrap_or_default();
339            let s = score(needle, &sn.title, &[&sn.slug, &sn.type_name, &sn.body_markdown]);
340            (s > 0.0).then(|| {
341                hit(
342                    "snippet",
343                    id,
344                    &sn.title,
345                    None,
346                    format!("/api/v2/snippets/{id}/"),
347                    s,
348                )
349            })
350        })
351        .collect())
352}
353
354#[cfg(test)]
355mod tests {
356    use super::*;
357
358    #[test]
359    fn an_exact_title_outranks_a_prefix_outranks_a_substring() {
360        assert!(score("docs", "Docs", &[]) > score("docs", "Docs and more", &[]));
361        assert!(score("docs", "Docs and more", &[]) > score("docs", "The Docs page", &[]));
362        assert!(score("docs", "The Docs page", &[]) > score("docs", "Unrelated", &["docs.pdf"]));
363    }
364
365    #[test]
366    fn a_secondary_field_still_scores() {
367        assert!(score("report", "Q4", &["annual-report.pdf"]) > 0.0);
368    }
369
370    #[test]
371    fn no_match_scores_zero() {
372        assert_eq!(score("zebra", "Docs", &["a.pdf", "body text"]), 0.0);
373    }
374
375    #[test]
376    fn matching_is_case_insensitive() {
377        assert_eq!(score("DOCS", "docs", &[]), 1.0);
378        assert!(score("dOcS", "The Docs", &[]) > 0.0);
379    }
380
381    #[test]
382    fn no_type_filter_means_every_type() {
383        assert_eq!(requested_types(None).unwrap(), ALL_TYPES.to_vec());
384        // An all-whitespace list is the same as absent, not "nothing".
385        assert_eq!(requested_types(Some(" , ")).unwrap(), ALL_TYPES.to_vec());
386    }
387
388    #[test]
389    fn a_type_filter_is_parsed_and_deduped() {
390        assert_eq!(
391            requested_types(Some("page, snippet ,page")).unwrap(),
392            vec!["page", "snippet"],
393        );
394    }
395
396    #[test]
397    fn an_unknown_type_is_an_error_not_an_empty_result() {
398        // A typo must not look identical to "no matches".
399        assert_eq!(requested_types(Some("pages")).unwrap_err(), "pages");
400        assert_eq!(requested_types(Some("page,widget")).unwrap_err(), "widget");
401    }
402}
403
404#[cfg(test)]
405mod fold_tests {
406    use super::{contains_folded, fold};
407
408    #[test]
409    fn non_latin_and_accented_text_folds() {
410        assert!(contains_folded("Новини", &fold("новини")));
411        assert!(contains_folded("über uns", &fold("ÜBER")));
412        assert!(contains_folded("Ελληνικά", &fold("ΕΛΛΗΝΙΚΆ")));
413        assert!(!contains_folded("News", &fold("новини")));
414    }
415}