Skip to main content

rustango_cms/
search_elasticsearch.rs

1//! Elasticsearch full-text [`SearchBackend`].
2//!
3//! Opt-in (the `search_elasticsearch` cargo feature pulls the
4//! framework's reqwest-based HTTP client). When installed via
5//! [`crate::search::set_backend`], search queries + page indexing route
6//! to Elasticsearch instead of the built-in Postgres FTS path.
7//!
8//! One index per tenant (`<prefix><tenant_slug>`); each page is a
9//! document keyed by its id. Search uses `multi_match` with field
10//! boosting (title ≫ seo_title ≫ description) + `fuzziness: AUTO`, so
11//! results are relevance-ranked and typo-tolerant. Indexing / deletion
12//! are best-effort (logged on failure) — a search-index hiccup must
13//! never block a content save.
14
15use std::sync::Arc;
16
17use rustango::http_client::HttpClient;
18
19use crate::search::{SearchBackend, SearchDoc};
20
21/// Elasticsearch-backed search. Build with [`Self::new`] and install
22/// via [`crate::search::set_backend`].
23pub struct ElasticsearchBackend {
24    http: HttpClient,
25    /// Base URL, no trailing slash — e.g. `http://localhost:9200`.
26    base_url: String,
27    /// Index-name prefix; the per-tenant index is `<prefix><slug>`.
28    index_prefix: String,
29}
30
31impl ElasticsearchBackend {
32    /// Connect to the cluster at `base_url` (trailing slash trimmed),
33    /// naming per-tenant indices `<index_prefix><tenant_slug>`.
34    ///
35    /// # Errors
36    /// Fails only if the underlying HTTP client can't be built.
37    pub fn new(
38        base_url: impl Into<String>,
39        index_prefix: impl Into<String>,
40    ) -> Result<Self, rustango::http_client::HttpError> {
41        let http = HttpClient::builder()
42            .timeout(std::time::Duration::from_secs(10))
43            .build()?;
44        Ok(Self {
45            http,
46            base_url: base_url.into().trim_end_matches('/').to_owned(),
47            index_prefix: index_prefix.into(),
48        })
49    }
50
51    fn index_name(&self, tenant_slug: &str) -> String {
52        format!("{}{}", self.index_prefix, sanitize_index(tenant_slug))
53    }
54
55    /// Bulk-(re)index every published page for `tenant_slug`. A one-shot
56    /// way to populate the index (the auto-on-save path is the
57    /// search-index background job).
58    ///
59    /// # Errors
60    /// Driver / query failures fetching the pages.
61    pub async fn reindex_all(
62        &self,
63        pool: &rustango::sql::Pool,
64        tenant_slug: &str,
65    ) -> Result<usize, rustango::sql::ExecError> {
66        use rustango::core::Column as _;
67        use rustango::sql::FetcherPool as _;
68        // #556 — index public statuses (published + archived); archived
69        // pages stay findable. Expired/draft/scheduled are excluded.
70        let pages: Vec<crate::page::Page> = crate::page::Page::objects()
71            .where_(crate::page::Page::status.is_in([
72                crate::page::PageStatus::Published.as_str().to_owned(),
73                crate::page::PageStatus::Archived.as_str().to_owned(),
74            ]))
75            .fetch(pool)
76            .await?;
77        let mut n = 0;
78        for p in &pages {
79            let Some(page_id) = p.id.get().copied() else {
80                continue;
81            };
82            self.index(
83                tenant_slug,
84                &SearchDoc {
85                    page_id,
86                    title: p.title.clone(),
87                    seo_title: p.seo_title.clone(),
88                    seo_description: p.seo_description.clone(),
89                    url_path: p.url_path.clone(),
90                    status: p.status.clone(),
91                },
92            )
93            .await;
94            n += 1;
95        }
96        Ok(n)
97    }
98}
99
100/// ES index names must be lowercase + can't contain certain chars;
101/// tenant slugs are already slug-shaped, but normalise defensively.
102fn sanitize_index(slug: &str) -> String {
103    slug.chars()
104        .map(|c| {
105            if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
106                c.to_ascii_lowercase()
107            } else {
108                '_'
109            }
110        })
111        .collect()
112}
113
114#[async_trait::async_trait]
115impl SearchBackend for ElasticsearchBackend {
116    async fn search(&self, tenant_slug: &str, query: &str, limit: i64) -> Vec<i64> {
117        let url = format!("{}/{}/_search", self.base_url, self.index_name(tenant_slug));
118        let body = serde_json::json!({
119            "size": limit.max(0),
120            "_source": false,
121            "query": {
122                "multi_match": {
123                    "query": query,
124                    "fields": ["title^3", "seo_title^2", "seo_description"],
125                    "fuzziness": "AUTO"
126                }
127            }
128        });
129        let resp = match self.http.post(url.as_str()).json(&body) {
130            Ok(req) => req.send().await,
131            Err(e) => Err(e),
132        };
133        let json: serde_json::Value = match resp {
134            Ok(r) => match r.json().await {
135                Ok(v) => v,
136                Err(e) => {
137                    tracing::warn!(target: "rustango_cms::search", error = %e, "ES search: decode failed");
138                    return Vec::new();
139                }
140            },
141            Err(e) => {
142                tracing::warn!(target: "rustango_cms::search", error = %e, "ES search request failed");
143                return Vec::new();
144            }
145        };
146        parse_hit_ids(&json)
147    }
148
149    async fn index(&self, tenant_slug: &str, doc: &SearchDoc) {
150        let url = format!(
151            "{}/{}/_doc/{}",
152            self.base_url,
153            self.index_name(tenant_slug),
154            doc.page_id
155        );
156        let send = match self.http.put(url.as_str()).json(doc) {
157            Ok(req) => req.send().await,
158            Err(e) => Err(e),
159        };
160        if let Err(e) = send {
161            tracing::warn!(target: "rustango_cms::search", page_id = doc.page_id, error = %e, "ES index failed (best-effort)");
162        }
163    }
164
165    async fn delete(&self, tenant_slug: &str, page_id: i64) {
166        let url = format!(
167            "{}/{}/_doc/{}",
168            self.base_url,
169            self.index_name(tenant_slug),
170            page_id
171        );
172        if let Err(e) = self.http.delete(url.as_str()).send().await {
173            tracing::warn!(target: "rustango_cms::search", page_id, error = %e, "ES delete failed (best-effort)");
174        }
175    }
176}
177
178/// Pull `hits.hits[]._id` (the page ids) out of an ES `_search`
179/// response, in the order ES returned them (relevance). Pure — unit
180/// tested without a cluster.
181fn parse_hit_ids(json: &serde_json::Value) -> Vec<i64> {
182    json.get("hits")
183        .and_then(|h| h.get("hits"))
184        .and_then(|h| h.as_array())
185        .map(|hits| {
186            hits.iter()
187                .filter_map(|h| h.get("_id"))
188                .filter_map(|id| {
189                    id.as_str()
190                        .and_then(|s| s.parse::<i64>().ok())
191                        .or_else(|| id.as_i64())
192                })
193                .collect()
194        })
195        .unwrap_or_default()
196}
197
198/// Wrap an [`ElasticsearchBackend`] in the `Arc<dyn SearchBackend>` the
199/// registry expects. Convenience for `search::set_backend(...)`.
200#[must_use]
201pub fn boxed(backend: ElasticsearchBackend) -> Arc<dyn SearchBackend> {
202    Arc::new(backend)
203}
204
205#[cfg(test)]
206mod tests {
207    use super::*;
208
209    #[test]
210    fn parses_hit_ids_in_order() {
211        let json = serde_json::json!({
212            "hits": { "hits": [
213                { "_id": "42", "_score": 9.1 },
214                { "_id": "7",  "_score": 3.2 }
215            ]}
216        });
217        assert_eq!(parse_hit_ids(&json), vec![42, 7]);
218        // Missing/empty hits → empty.
219        assert!(parse_hit_ids(&serde_json::json!({})).is_empty());
220    }
221
222    #[test]
223    fn sanitizes_index_names() {
224        assert_eq!(sanitize_index("Acme-Co"), "acme-co");
225        assert_eq!(sanitize_index("a.b/c"), "a_b_c");
226    }
227
228    /// Real-Elasticsearch round-trip. Gated on `RCMS_TEST_ES_URL`
229    /// (e.g. `http://localhost:9201`); skips cleanly otherwise.
230    /// Indexes 3 docs, refreshes, searches, asserts ranking + fuzzy
231    /// match + filtering, then drops the throwaway index.
232    #[tokio::test]
233    async fn es_round_trip_ranks_and_filters() {
234        let Ok(url) = std::env::var("RCMS_TEST_ES_URL") else {
235            eprintln!("skip es_round_trip: set RCMS_TEST_ES_URL");
236            return;
237        };
238        let es = ElasticsearchBackend::new(&url, "rcmstest_").unwrap();
239        let slug = "esrt";
240        let index = es.index_name(slug);
241        // Clean slate.
242        let _ = es
243            .http
244            .delete(format!("{}/{index}", es.base_url).as_str())
245            .send()
246            .await;
247
248        for (id, title, desc) in [
249            (1_i64, "Rust web framework guide", ""),
250            (2, "Cooking with cast iron", "a rust-free skillet"),
251            (3, "Knitting patterns", "wool and yarn"),
252        ] {
253            es.index(
254                slug,
255                &SearchDoc {
256                    page_id: id,
257                    title: title.to_owned(),
258                    seo_title: String::new(),
259                    seo_description: desc.to_owned(),
260                    url_path: format!("/{id}"),
261                    status: "published".to_owned(),
262                },
263            )
264            .await;
265        }
266        // Make the writes searchable.
267        let _ = es
268            .http
269            .post(format!("{}/{index}/_refresh", es.base_url).as_str())
270            .send()
271            .await;
272
273        let ids = es.search(slug, "rust", 10).await;
274        // Fuzzy typo still matches the title.
275        let fuzzy = es.search(slug, "rüst", 10).await;
276        es.delete(slug, 1).await;
277        let after_delete = {
278            let _ = es
279                .http
280                .post(format!("{}/{index}/_refresh", es.base_url).as_str())
281                .send()
282                .await;
283            es.search(slug, "rust", 10).await
284        };
285        // Cleanup.
286        let _ = es
287            .http
288            .delete(format!("{}/{index}", es.base_url).as_str())
289            .send()
290            .await;
291
292        assert!(
293            ids.contains(&1) && ids.contains(&2),
294            "both rust docs: {ids:?}"
295        );
296        assert!(!ids.contains(&3), "knitting excluded: {ids:?}");
297        assert_eq!(ids.first(), Some(&1), "title match ranks first: {ids:?}");
298        assert!(!fuzzy.is_empty(), "fuzzy 'rüst' matches: {fuzzy:?}");
299        assert!(
300            !after_delete.contains(&1),
301            "deleted doc gone: {after_delete:?}"
302        );
303    }
304}