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