1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
//! How the public router resolves which locale a request is asking for.
//!
//! Three modes; query mode is the v0.1/v0.2 default for back-compat.
//! Path mode puts the locale code as the first URL
//! segment, with the default locale living at the unprefixed root.
//!
//! - `/about` → default locale (regardless of mode)
//! - `/es/about` → recognized only when mode includes Path
//! - `/about?lang=es` → recognized only when mode includes Query
//!
//! In `PathOrQuery` mode, an explicit `?lang=` wins over the path
//! prefix — the query parameter is read as an explicit override
//! (handy for testing) and the path prefix becomes the default
//! external-link shape.
//!
//! When no explicit locale is given (no `?lang=`, no path prefix), the
//! request's `Accept-Language` header is negotiated against the active
//! locales before falling through to the tenant default. So
//! precedence is: explicit query > explicit path > Accept-Language >
//! default.
use rustango::core::Column as _;
use crate::locale::Locale;
/// Locale-resolution strategy for [`crate::router`](mod@crate::router) builders.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LocaleMode {
/// `?lang=es` only. The v0.1 / v0.2 default — no path
/// recognition, no extra DB hit per request.
#[default]
Query,
/// `/es/...` only. The first URL segment is matched against
/// `cms_locale.code`; if it hits, it's stripped and used as the
/// active locale for rendering.
Path,
/// Both. Query wins when both are present, so a stale link
/// `/es/about?lang=fr` renders French. The path prefix is the
/// canonical external-link shape; the query parameter is the
/// explicit override.
PathOrQuery,
}
impl LocaleMode {
/// Whether the router should inspect URL path segments for a
/// locale prefix on every request.
#[must_use]
pub fn reads_path(self) -> bool {
matches!(self, Self::Path | Self::PathOrQuery)
}
/// Whether the router should inspect `?lang=` on every request.
#[must_use]
pub fn reads_query(self) -> bool {
matches!(self, Self::Query | Self::PathOrQuery)
}
}
/// Cookie that persists a visitor's chosen locale across navigation so
/// links that don't carry the locale (bare nav paths, in-content links)
/// stay in the selected language. Lower precedence than an explicit
/// `?lang=` / `/<code>/` so a fresh explicit choice always wins.
pub const LOCALE_COOKIE: &str = "rcms_locale";
/// What [`resolve_request_locale`] returns: the active locale code
/// (if any) plus the URL path with the locale segment removed (so
/// downstream slug resolution sees the same `/about` whether the
/// request came in as `/about?lang=es` or `/es/about`).
#[derive(Debug, Clone)]
pub struct RequestLocale {
/// Locale code resolved from the request, in `mode`'s priority
/// order. `None` means "fall through to the tenant default".
pub code: Option<String>,
/// The request path with any locale prefix stripped.
pub stripped_path: String,
/// `true` when `code` came from an EXPLICIT source (`?lang=` or a
/// `/<code>/` path prefix), as opposed to the persistence cookie or
/// `Accept-Language`. The router (re)writes the locale cookie only on
/// an explicit choice, so a plain nav click never churns it.
pub explicit: bool,
}
/// BCP-47-ish tag shape gate (ASCII alphanumeric + `-`, ≤16 chars) —
/// keeps a malformed cookie/query value from poisoning the cache key or
/// a `/<code>/` lookup.
#[must_use]
pub fn code_shaped(s: &str) -> bool {
!s.is_empty() && s.len() <= 16 && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
}
/// Pull the `rcms_locale` value out of a raw `Cookie` header. Returns
/// `None` when absent or malformed.
#[must_use]
pub fn locale_cookie_value(cookie_header: Option<&str>) -> Option<String> {
let raw = cookie_header?;
for part in raw.split(';') {
if let Some(v) = part.trim().strip_prefix("rcms_locale=") {
let v = v.trim();
return if code_shaped(v) {
Some(v.to_owned())
} else {
None
};
}
}
None
}
/// Resolve the request's locale code by inspecting path + query (as
/// `mode` permits) and the `Accept-Language` header.
///
/// Precedence: **explicit `?lang=` > explicit `/<code>/` path prefix >
/// `Accept-Language` negotiation > tenant default** (`None`). An
/// explicit choice always wins; the header is a fallback for
/// first-visit/unlinked requests.
///
/// At most two DB queries, both conditional: the path-segment lookup
/// (only in path mode when the first segment looks like a code) and the
/// active-locale list for `Accept-Language` matching (only when no
/// explicit locale was given AND a header is present).
pub async fn resolve_request_locale(
pool: &rustango::sql::Pool,
mode: LocaleMode,
path: &str,
query: Option<&str>,
cookie_code: Option<&str>,
accept_language: Option<&str>,
) -> RequestLocale {
let query_code = if mode.reads_query() {
query.and_then(parse_lang_param)
} else {
None
};
let (path_code, stripped_path) = if mode.reads_path() {
// Query wins, so a `/es/about?lang=fr` renders French — but the
// segment is still stripped from the path either way.
try_strip_locale_segment(pool, path).await
} else {
(None, path.to_owned())
};
// Precedence: explicit query > explicit path > persistence cookie >
// Accept-Language > tenant default. The cookie keeps the chosen
// language sticky across links that don't carry it; an explicit
// choice always overrides it.
let explicit_code = query_code.or(path_code);
let explicit = explicit_code.is_some();
let code = if let Some(c) = explicit_code {
Some(c)
} else if let Some(c) = cookie_code.filter(|c| code_shaped(c)) {
Some(c.to_owned())
} else {
negotiate_accept_language(pool, accept_language).await
};
RequestLocale {
code,
stripped_path,
explicit,
}
}
/// Negotiate `Accept-Language` against the active `cms_locale.code`s.
/// Returns the highest-quality match (exact, then base-language —
/// `fr-CA` matches an active `fr`), or `None`. One DB query, only when
/// a non-empty header is present.
async fn negotiate_accept_language(
pool: &rustango::sql::Pool,
header: Option<&str>,
) -> Option<String> {
use rustango::sql::FetcherPool as _;
let prefs = parse_accept_language(header?);
if prefs.is_empty() {
return None;
}
let active: Vec<String> = Locale::objects()
.where_(Locale::active.eq(true))
.fetch(pool)
.await
.ok()?
.into_iter()
.map(|l| l.code)
.collect();
if active.is_empty() {
return None;
}
for pref in &prefs {
// Exact (case-insensitive) match first.
if let Some(m) = active.iter().find(|c| c.eq_ignore_ascii_case(pref)) {
return Some(m.clone());
}
// Base-language fallback: `fr-CA` → an active `fr` (or `fr-FR`).
let pref_base = base_lang(pref);
if let Some(m) = active
.iter()
.find(|c| base_lang(c).eq_ignore_ascii_case(pref_base))
{
return Some(m.clone());
}
}
None
}
fn base_lang(tag: &str) -> &str {
tag.split('-').next().unwrap_or(tag)
}
/// Parse an `Accept-Language` header into BCP-47 tags ordered by
/// quality (descending; ties keep header order). Drops `*`, `q=0`, and
/// malformed tags so a bad value can't poison the cache key.
fn parse_accept_language(header: &str) -> Vec<String> {
let mut items: Vec<(f32, String)> = Vec::new();
for part in header.split(',') {
let part = part.trim();
if part.is_empty() {
continue;
}
let mut bits = part.split(';');
let tag = bits.next().unwrap_or("").trim();
if tag.is_empty()
|| tag == "*"
|| !tag.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
{
continue;
}
let mut q = 1.0f32;
for b in bits {
if let Some(v) = b.trim().strip_prefix("q=") {
q = v.trim().parse().unwrap_or(1.0);
}
}
if q <= 0.0 {
continue;
}
items.push((q, tag.to_owned()));
}
// Stable sort by quality desc keeps header order for equal-q tags.
items.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
items.into_iter().map(|(_, t)| t).collect()
}
/// Peek the first path segment. If it looks like a BCP-47 tag AND
/// matches an active `cms_locale.code`, return `(Some(code),
/// path_without_segment)`. Otherwise `(None, original_path)`.
async fn try_strip_locale_segment(
pool: &rustango::sql::Pool,
path: &str,
) -> (Option<String>, String) {
use rustango::sql::FetcherPool as _;
let trimmed = path.trim_start_matches('/');
let mut iter = trimmed.splitn(2, '/');
let head = iter.next().unwrap_or("");
if head.is_empty()
|| head.len() > 16
|| !head.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
{
return (None, path.to_owned());
}
let exists = Locale::objects()
.where_(Locale::code.eq(head.to_owned()))
.where_(Locale::active.eq(true))
.fetch(pool)
.await
.ok()
.and_then(|mut v| v.pop())
.is_some();
if !exists {
return (None, path.to_owned());
}
let rest = iter.next().unwrap_or("");
let stripped = if rest.is_empty() {
"/".to_owned()
} else {
format!("/{rest}")
};
(Some(head.to_owned()), stripped)
}
/// Pull `?lang=<code>` out of a raw query string. Restricts to ASCII
/// alphanumeric + `-` (BCP-47 tag shape) so a malformed value can't
/// poison the cache key.
fn parse_lang_param(q: &str) -> Option<String> {
for pair in q.split('&') {
if let Some(rest) = pair.strip_prefix("lang=") {
let trimmed = rest.trim();
if trimmed.is_empty() {
return None;
}
if trimmed
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '-')
{
return Some(trimmed.to_owned());
}
return None;
}
}
None
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_lang_param_extracts_value() {
assert_eq!(parse_lang_param("lang=es"), Some("es".to_owned()));
assert_eq!(parse_lang_param("lang=es&foo=bar"), Some("es".to_owned()));
assert_eq!(parse_lang_param("foo=bar&lang=fr"), Some("fr".to_owned()));
}
#[test]
fn parse_lang_param_rejects_garbage() {
assert_eq!(parse_lang_param(""), None);
assert_eq!(parse_lang_param("lang="), None);
assert_eq!(parse_lang_param("lang=../etc/passwd"), None);
assert_eq!(parse_lang_param("lang=<script>"), None);
assert_eq!(parse_lang_param("foo=bar"), None);
}
#[test]
fn accept_language_orders_by_quality() {
// Default q=1 for the unweighted tag; explicit q orders the rest.
assert_eq!(
parse_accept_language("de;q=0.7, en;q=0.8, fr"),
vec!["fr", "en", "de"]
);
}
#[test]
fn accept_language_keeps_header_order_for_ties() {
assert_eq!(
parse_accept_language("en-US, en;q=0.9, fr;q=0.9"),
vec!["en-US", "en", "fr"]
);
}
#[test]
fn accept_language_drops_wildcard_zero_q_and_garbage() {
assert_eq!(
parse_accept_language("*;q=0.5, xx;q=0, en, ../bad, fr-CA"),
vec!["en", "fr-CA"]
);
assert!(parse_accept_language("").is_empty());
assert!(parse_accept_language("*").is_empty());
}
#[test]
fn base_lang_strips_region() {
assert_eq!(base_lang("fr-CA"), "fr");
assert_eq!(base_lang("en"), "en");
}
}