feat(srv): Add HTTP 301 redirects for common URL mistakes

martin/src/srv/fonts.rs

@@ -2,13 +2,15 @@ use std::string::ToString;
 
 use actix_middleware_etag::Etag;
 use actix_web::error::{ErrorBadRequest, ErrorNotFound};
+use actix_web::http::header::LOCATION;
 use actix_web::middleware::Compress;
 use actix_web::web::{Data, Path};
 use actix_web::{HttpResponse, Result as ActixResult, route};
 use martin_core::fonts::{FontError, FontSources, OptFontCache};
 use serde::Deserialize;
+use tracing::warn;
 
-use crate::srv::server::map_internal_error;
+use crate::srv::server::{DebouncedWarning, map_internal_error};
 
 #[derive(Deserialize, Debug)]
 struct FontRequest {
@@ -43,6 +45,28 @@ async fn get_font(
         .body(data))
 }
 
+/// Redirect `/fonts/{fontstack}/{start}-{end}` to `/font/{fontstack}/{start}-{end}` (HTTP 301)
+#[route("/fonts/{fontstack}/{start}-{end}", method = "GET", method = "HEAD")]
+pub async fn redirect_fonts(path: Path<FontRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /fonts/{}/{}-{} caused unnecessary redirect. Use /font/{}/{}-{} to avoid extra round-trip latency.",
+                path.fontstack, path.start, path.end, path.fontstack, path.start, path.end
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((
+            LOCATION,
+            format!("/font/{}/{}-{}", path.fontstack, path.start, path.end),
+        ))
+        .finish()
+}
+
 pub fn map_font_error(e: FontError) -> actix_web::Error {
     match e {
         FontError::FontNotFound(_) => ErrorNotFound(e.to_string()),

martin/src/srv/server.rs

@@ -33,6 +33,46 @@ pub fn map_internal_error<T: std::fmt::Display>(e: T) -> actix_web::Error {
     actix_web::error::ErrorInternalServerError(e.to_string())
 }
 
+/// Helper struct for debounced warning messages in redirect handlers.
+/// Ensures warnings are logged no more than once per hour to avoid log spam.
+#[cfg(any(
+    feature = "_tiles",
+    feature = "fonts",
+    feature = "sprites",
+    feature = "styles"
+))]
+pub struct DebouncedWarning {
+    last_warning: std::sync::LazyLock<tokio::sync::Mutex<std::time::Instant>>,
+}
+
+#[cfg(any(
+    feature = "_tiles",
+    feature = "fonts",
+    feature = "sprites",
+    feature = "styles"
+))]
+impl DebouncedWarning {
+    /// Create a new `DebouncedWarning` instance
+    pub const fn new() -> Self {
+        Self {
+            last_warning: std::sync::LazyLock::new(|| {
+                tokio::sync::Mutex::new(std::time::Instant::now())
+            }),
+        }
+    }
+
+    /// Execute the provided closure at most once per hour.
+    /// This allows tracing's log filtering to work correctly by keeping the warn! call site
+    /// in the caller's context.
+    pub async fn once_per_hour<F: FnOnce()>(&self, f: F) {
+        let mut last = self.last_warning.lock().await;
+        if last.elapsed() >= Duration::from_secs(3600) {
+            *last = std::time::Instant::now();
+            f();
+        }
+    }
+}
+
 /// Return 200 OK if healthy. Used for readiness and liveness probes.
 #[route("/health", method = "GET", method = "HEAD")]
 async fn get_health() -> impl Responder {
@@ -56,20 +96,34 @@ fn register_services(cfg: &mut web::ServiceConfig, #[allow(unused_variables)] us
         .service(crate::srv::admin::get_catalog);
 
     #[cfg(feature = "_tiles")]
-    cfg.service(crate::srv::tiles::metadata::get_source_info)
-        .service(crate::srv::tiles::content::get_tile);
+    {
+        // Register tile format suffix redirects BEFORE the main tile route
+        // because Actix-Web matches routes in registration order
+        cfg.service(crate::srv::tiles::content::redirect_tile_ext)
+            .service(crate::srv::tiles::metadata::get_source_info)
+            .service(crate::srv::tiles::content::get_tile);
+
+        // Register /tiles/ prefix redirect after main tile route
+        cfg.service(crate::srv::tiles::content::redirect_tiles);
+    }
 
     #[cfg(feature = "sprites")]
     cfg.service(crate::srv::sprites::get_sprite_sdf_json)
+        .service(crate::srv::sprites::redirect_sdf_sprites_json)
         .service(crate::srv::sprites::get_sprite_json)
+        .service(crate::srv::sprites::redirect_sprites_json)
         .service(crate::srv::sprites::get_sprite_sdf_png)
-        .service(crate::srv::sprites::get_sprite_png);
+        .service(crate::srv::sprites::redirect_sdf_sprites_png)
+        .service(crate::srv::sprites::get_sprite_png)
+        .service(crate::srv::sprites::redirect_sprites_png);
 
     #[cfg(feature = "fonts")]
-    cfg.service(crate::srv::fonts::get_font);
+    cfg.service(crate::srv::fonts::get_font)
+        .service(crate::srv::fonts::redirect_fonts);
 
     #[cfg(feature = "styles")]
-    cfg.service(crate::srv::styles::get_style_json);
+    cfg.service(crate::srv::styles::get_style_json)
+        .service(crate::srv::styles::redirect_styles);
 
     #[cfg(all(feature = "unstable-rendering", target_os = "linux"))]
     cfg.service(crate::srv::styles_rendering::get_style_rendered);

martin/src/srv/sprites.rs

@@ -2,14 +2,15 @@ use std::string::ToString;
 
 use actix_middleware_etag::Etag;
 use actix_web::error::ErrorNotFound;
-use actix_web::http::header::ContentType;
+use actix_web::http::header::{ContentType, LOCATION};
 use actix_web::middleware::Compress;
 use actix_web::web::{Bytes, Data, Path};
 use actix_web::{HttpResponse, Result as ActixResult, route};
 use martin_core::sprites::{OptSpriteCache, SpriteError, SpriteSources};
 use serde::Deserialize;
+use tracing::warn;
 
-use crate::srv::server::map_internal_error;
+use crate::srv::server::{DebouncedWarning, map_internal_error};
 
 #[derive(Deserialize)]
 pub struct SourceIDsRequest {
@@ -42,6 +43,25 @@ async fn get_sprite_png(
         .body(png))
 }
 
+/// Redirect `/sprites/{source_ids}.png` to `/sprite/{source_ids}.png` (HTTP 301)
+#[route("/sprites/{source_ids}.png", method = "GET", method = "HEAD")]
+pub async fn redirect_sprites_png(path: Path<SourceIDsRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let SourceIDsRequest { source_ids } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /sprites/{source_ids}.png caused unnecessary redirect. Use /sprite/{source_ids}.png to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, format!("/sprite/{source_ids}.png")))
+        .finish()
+}
+
 #[route(
     "/sdf_sprite/{source_ids}.png",
     method = "GET",
@@ -68,6 +88,25 @@ async fn get_sprite_sdf_png(
         .body(png))
 }
 
+/// Redirect `/sdf_sprites/{source_ids}.png` to `/sdf_sprite/{source_ids}.png` (HTTP 301)
+#[route("/sdf_sprites/{source_ids}.png", method = "GET", method = "HEAD")]
+pub async fn redirect_sdf_sprites_png(path: Path<SourceIDsRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let SourceIDsRequest { source_ids } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /sdf_sprites/{source_ids}.png caused unnecessary redirect. Use /sdf_sprite/{source_ids}.png to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, format!("/sdf_sprite/{source_ids}.png")))
+        .finish()
+}
+
 #[route(
     "/sprite/{source_ids}.json",
     method = "GET",
@@ -95,6 +134,25 @@ async fn get_sprite_json(
         .body(json))
 }
 
+/// Redirect `/sprites/{source_ids}.json` to `/sprite/{source_ids}.json` (HTTP 301)
+#[route("/sprites/{source_ids}.json", method = "GET", method = "HEAD")]
+pub async fn redirect_sprites_json(path: Path<SourceIDsRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let SourceIDsRequest { source_ids } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /sprites/{source_ids}.json caused unnecessary redirect. Use /sprite/{source_ids}.json to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, format!("/sprite/{source_ids}.json")))
+        .finish()
+}
+
 #[route(
     "/sdf_sprite/{source_ids}.json",
     method = "GET",
@@ -122,6 +180,25 @@ async fn get_sprite_sdf_json(
         .body(json))
 }
 
+/// Redirect `/sdf_sprites/{source_ids}.json` to `/sdf_sprite/{source_ids}.json` (HTTP 301)
+#[route("/sdf_sprites/{source_ids}.json", method = "GET", method = "HEAD")]
+pub async fn redirect_sdf_sprites_json(path: Path<SourceIDsRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let SourceIDsRequest { source_ids } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /sdf_sprites/{source_ids}.json caused unnecessary redirect. Use /sdf_sprite/{source_ids}.json to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, format!("/sdf_sprite/{source_ids}.json")))
+        .finish()
+}
+
 async fn get_sprite(source_ids: &str, sprites: &SpriteSources, as_sdf: bool) -> ActixResult<Bytes> {
     let sheet = sprites
         .get_sprites(source_ids, as_sdf)

martin/src/srv/styles.rs

@@ -1,11 +1,13 @@
 use actix_middleware_etag::Etag;
-use actix_web::http::header::ContentType;
+use actix_web::http::header::{ContentType, LOCATION};
 use actix_web::middleware::Compress;
 use actix_web::web::{Data, Path};
 use actix_web::{HttpResponse, route};
 use martin_core::styles::StyleSources;
 use serde::Deserialize;
-use tracing::error;
+use tracing::{error, warn};
+
+use crate::srv::server::DebouncedWarning;
 
 #[derive(Deserialize, Debug)]
 struct StyleRequest {
@@ -48,3 +50,22 @@ async fn get_style_json(path: Path<StyleRequest>, styles: Data<StyleSources>) ->
         }
     }
 }
+
+/// Redirect `/styles/{style_id}` to `/style/{style_id}` (HTTP 301)
+/// This handles common pluralization mistakes
+#[route("/styles/{style_id}", method = "GET", method = "HEAD")]
+pub(crate) async fn redirect_styles(path: Path<StyleRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let StyleRequest { style_id } = path.as_ref();
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /styles/{style_id} caused unnecessary redirect. Use /style/{style_id} to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, format!("/style/{style_id}")))
+        .finish()
+}

martin/src/srv/tiles/content.rs

@@ -3,7 +3,7 @@ use actix_http::header::Quality;
 use actix_web::error::{ErrorBadRequest, ErrorNotAcceptable, ErrorNotFound};
 use actix_web::http::header::{
     AcceptEncoding, CONTENT_ENCODING, ETAG, Encoding as HeaderEnc, EntityTag, IfNoneMatch,
-    Preference,
+    LOCATION, Preference,
 };
 use actix_web::web::{Data, Path, Query};
 use actix_web::{HttpMessage, HttpRequest, HttpResponse, Result as ActixResult, route};
@@ -14,10 +14,12 @@ use martin_tile_utils::{
     encode_gzip,
 };
 use serde::Deserialize;
+use tracing::warn;
 
 use crate::config::args::PreferredEncoding;
 use crate::config::file::srv::SrvConfig;
 use crate::source::TileSources;
+use crate::srv::server::DebouncedWarning;
 use crate::srv::server::map_internal_error;
 
 const SUPPORTED_ENC: &[HeaderEnc] = &[
@@ -61,6 +63,74 @@ async fn get_tile(
     .await
 }
 
+#[derive(Deserialize, Clone)]
+pub struct RedirectTileRequest {
+    ids: String,
+    z: u8,
+    x: u32,
+    y: u32,
+    ext: String,
+}
+
+/// Redirect `/{source_ids}/{z}/{x}/{y}.{extension}` to `/{source_ids}/{z}/{x}/{y}` (HTTP 301)
+/// Registered before main tile route to match more specific pattern first
+#[route("/{ids}/{z}/{x}/{y}.{ext}", method = "GET", method = "HEAD")]
+pub async fn redirect_tile_ext(req: HttpRequest, path: Path<RedirectTileRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let RedirectTileRequest { ids, z, x, y, ext } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /{ids}/{z}/{x}/{y}.{ext} caused unnecessary redirect. Use /{ids}/{z}/{x}/{y} to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    redirect_tile_with_query(ids, *z, *x, *y, req.query_string())
+}
+
+/// Redirect `/tiles/{source_ids}/{z}/{x}/{y}` to `/{source_ids}/{z}/{x}/{y}` (HTTP 301)
+#[route("/tiles/{source_ids}/{z}/{x}/{y}", method = "GET", method = "HEAD")]
+pub async fn redirect_tiles(req: HttpRequest, path: Path<TileRequest>) -> HttpResponse {
+    static WARNING: DebouncedWarning = DebouncedWarning::new();
+    let TileRequest {
+        source_ids,
+        z,
+        x,
+        y,
+    } = path.as_ref();
+
+    WARNING
+        .once_per_hour(|| {
+            warn!(
+                "Request to /tiles/{source_ids}/{z}/{x}/{y} caused unnecessary redirect. Use /{source_ids}/{z}/{x}/{y} to avoid extra round-trip latency."
+            );
+        })
+        .await;
+
+    redirect_tile_with_query(source_ids, *z, *x, *y, req.query_string())
+}
+
+/// Helper function to create a 301 redirect for tiles with query string preservation
+fn redirect_tile_with_query(
+    source_ids: &str,
+    z: u8,
+    x: u32,
+    y: u32,
+    query_string: &str,
+) -> HttpResponse {
+    let location = format!("/{source_ids}/{z}/{x}/{y}");
+    let location = if query_string.is_empty() {
+        location
+    } else {
+        format!("{location}?{query_string}")
+    };
+    HttpResponse::MovedPermanently()
+        .insert_header((LOCATION, location))
+        .finish()
+}
+
 pub struct DynTileSource<'a> {
     pub sources: Vec<BoxedSource>,
     pub info: TileInfo,