oxigeo_server/

server.rs

//! HTTP server implementation
//!
//! Sets up the Axum web server with all routes and middleware for serving tiles.

use crate::cache::{TileCache, TileCacheConfig};
use crate::config::Config;
use crate::dataset_registry::DatasetRegistry;
use crate::handlers::{
    TileState, WmsState, WmtsState, get_feature_info, get_map, get_tile, get_tile_kvp,
    get_tile_rest, get_tilejson, wms_get_capabilities, wmts_get_capabilities,
};
use crate::metrics::{AppMetrics, metrics_handler, track_http_metrics};
use axum::{
    Router,
    extract::{DefaultBodyLimit, Request},
    http::{Method, StatusCode, header},
    middleware::{self, Next},
    response::{Html, IntoResponse, Response},
    routing::get,
};
use std::sync::Arc;
use std::time::Duration;
use thiserror::Error;
use tower::ServiceBuilder;
use tower_http::{
    cors::{Any, CorsLayer},
    trace::TraceLayer,
};
use tracing::{error, info};

/// Server errors
#[derive(Debug, Error)]
pub enum ServerError {
    /// Configuration error
    #[error("Configuration error: {0}")]
    Config(String),

    /// Registry error
    #[error("Registry error: {0}")]
    Registry(#[from] crate::dataset_registry::RegistryError),

    /// HTTP server error
    #[error("HTTP server error: {0}")]
    Http(String),

    /// I/O error
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
}

/// Result type for server operations
pub type ServerResult<T> = Result<T, ServerError>;

/// Tile server instance
pub struct TileServer {
    /// Server configuration
    config: Config,

    /// Dataset registry
    registry: DatasetRegistry,

    /// Tile cache
    cache: TileCache,

    /// Prometheus metrics registry
    metrics: AppMetrics,
}

impl TileServer {
    /// Create a new tile server
    pub fn new(config: Config) -> ServerResult<Self> {
        // Create dataset registry
        let registry = DatasetRegistry::new();

        // Register all configured layers
        registry
            .register_layers(config.layers.clone())
            .map_err(ServerError::Registry)?;

        info!("Registered {} layers", registry.layer_count());

        // Create tile cache
        let cache_config = TileCacheConfig {
            max_memory_bytes: config.cache.memory_size_mb * 1024 * 1024,
            disk_cache_dir: config.cache.disk_cache.clone(),
            ttl: Duration::from_secs(config.cache.ttl_seconds),
            enable_stats: config.cache.enable_stats,
            compression: config.cache.compression,
        };

        let cache = TileCache::new(cache_config);

        Ok(Self {
            config,
            registry,
            cache,
            metrics: AppMetrics::new(),
        })
    }

    /// Build the Axum router
    pub fn build_router(&self) -> Router {
        let service_url = format!(
            "http://{}:{}",
            self.config.server.host, self.config.server.port
        );

        // Create shared state for WMS
        let wms_state = Arc::new(WmsState {
            registry: self.registry.clone(),
            cache: self.cache.clone(),
            service_url: service_url.clone(),
            service_title: self.config.metadata.title.clone(),
            service_abstract: self.config.metadata.abstract_.clone(),
        });

        // Create shared state for WMTS
        let wmts_state = Arc::new(WmtsState {
            registry: self.registry.clone(),
            cache: self.cache.clone(),
            service_url: service_url.clone(),
            service_title: self.config.metadata.title.clone(),
            service_abstract: self.config.metadata.abstract_.clone(),
        });

        // Create shared state for XYZ tiles
        let tile_state = Arc::new(TileState {
            registry: self.registry.clone(),
            cache: self.cache.clone(),
        });

        // Build CORS layer
        let cors = if self.config.server.enable_cors {
            let mut cors = CorsLayer::new()
                .allow_methods([Method::GET, Method::POST, Method::OPTIONS])
                .allow_headers([header::CONTENT_TYPE, header::ACCEPT]);

            cors = if self.config.server.cors_origins.is_empty() {
                cors.allow_origin(Any)
            } else {
                let origins: Vec<_> = self
                    .config
                    .server
                    .cors_origins
                    .iter()
                    .filter_map(|o| o.parse().ok())
                    .collect();
                cors.allow_origin(origins)
            };

            cors
        } else {
            CorsLayer::permissive()
        };

        // Build middleware stack
        let middleware = ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(cors)
            .layer(DefaultBodyLimit::max(self.config.server.max_request_size));

        // Build routes with timeout middleware
        let timeout_duration = Duration::from_secs(self.config.server.timeout_seconds);

        Router::new()
            // Home/landing page
            .route("/", get(home_handler))
            // Health check
            .route("/health", get(health_handler))
            // Cache stats (reads the real, shared TileCache statistics)
            .route("/stats", get(stats_handler).with_state(self.cache.clone()))
            // WMS endpoints
            .route("/wms", get(get_map).with_state(wms_state.clone()))
            .route(
                "/wms/capabilities",
                get(wms_get_capabilities).with_state(wms_state.clone()),
            )
            .route(
                "/wms/feature_info",
                get(get_feature_info).with_state(wms_state),
            )
            // WMTS endpoints
            .route("/wmts", get(get_tile_kvp).with_state(wmts_state.clone()))
            .route(
                "/wmts/capabilities",
                get(wmts_get_capabilities).with_state(wmts_state.clone()),
            )
            .route(
                // The file extension (e.g. `.png`) is part of the `{tile_col}` capture, not
                // a literal route suffix - matchit (axum's router) allows only one dynamic
                // parameter per path segment. See `handlers::wmts::parse_tile_col_and_format`.
                "/wmts/1.0.0/{layer}/{tile_matrix_set}/{tile_matrix}/{tile_row}/{tile_col}",
                get(get_tile_rest).with_state(wmts_state),
            )
            // XYZ tile endpoints
            .route(
                "/tiles/{layer}/{z}/{x}/{y}",
                get(get_tile).with_state(tile_state.clone()),
            )
            .route(
                "/tiles/{layer}/tilejson",
                get(get_tilejson).with_state(tile_state),
            )
            // Recorded after routing so `MatchedPath` (route template, not raw path with
            // high-cardinality tile coordinates) is available for metric labels.
            .route_layer(middleware::from_fn_with_state(
                self.metrics.clone(),
                track_http_metrics,
            ))
            .layer(middleware)
            .layer(middleware::from_fn(move |req, next| {
                timeout_middleware(req, next, timeout_duration)
            }))
    }

    /// Build the dedicated metrics router, served on its own port (see
    /// `ServerConfig::metrics_port`) so it can be scraped independently of the public
    /// WMS/WMTS/tile surface, matching the `metrics` container/service port that
    /// `k8s/deployment.yaml` and `monitoring/prometheus.yml` already assume.
    fn build_metrics_router(&self) -> Router {
        Router::new()
            .route("/metrics", get(metrics_handler))
            .with_state((self.metrics.clone(), self.cache.clone()))
    }

    /// Start the server
    ///
    /// Binds the public WMS/WMTS/tile router and, when
    /// `ServerConfig::metrics_enabled` is set, a second listener carrying only
    /// `GET /metrics` on `ServerConfig::metrics_port`. Both listeners are served
    /// concurrently; if either one fails to bind or serve, `serve()` returns the first
    /// error observed and the other listener is dropped.
    pub async fn serve(self) -> ServerResult<()> {
        let bind_addr = self.config.bind_address();
        info!("Starting OxiGeo tile server on {}", bind_addr);
        info!("Service URL: {}", self.get_service_url());
        info!("Workers: {}", self.config.server.workers);
        info!("Cache: {} MB memory", self.config.cache.memory_size_mb);

        if let Some(ref disk_cache) = self.config.cache.disk_cache {
            info!("Disk cache: {}", disk_cache.display());
        }

        // Build router
        let app = self.build_router();

        // Create TCP listener
        let listener = tokio::net::TcpListener::bind(&bind_addr)
            .await
            .map_err(|e| ServerError::Http(format!("Failed to bind to {}: {}", bind_addr, e)))?;

        info!("Server listening on {}", bind_addr);
        info!("Available endpoints:");
        info!("  - WMS:  http://{}/wms", bind_addr);
        info!("  - WMTS: http://{}/wmts", bind_addr);
        info!(
            "  - XYZ:  http://{}/tiles/{{layer}}/{{z}}/{{x}}/{{y}}.png",
            bind_addr
        );
        info!("  - Health: http://{}/health", bind_addr);
        info!("  - Stats: http://{}/stats", bind_addr);

        let app_future = async {
            axum::serve(listener, app)
                .with_graceful_shutdown(shutdown_signal())
                .await
                .map_err(|e| ServerError::Http(e.to_string()))
        };

        if self.config.server.metrics_enabled {
            let metrics_bind_addr = format!(
                "{}:{}",
                self.config.server.host, self.config.server.metrics_port
            );
            let metrics_app = self.build_metrics_router();

            let metrics_listener = tokio::net::TcpListener::bind(&metrics_bind_addr)
                .await
                .map_err(|e| {
                    ServerError::Http(format!(
                        "Failed to bind metrics listener to {}: {}",
                        metrics_bind_addr, e
                    ))
                })?;

            info!("Metrics listening on http://{}/metrics", metrics_bind_addr);

            let metrics_future = async {
                axum::serve(metrics_listener, metrics_app)
                    .with_graceful_shutdown(shutdown_signal())
                    .await
                    .map_err(|e| ServerError::Http(e.to_string()))
            };

            let (app_result, metrics_result) = tokio::join!(app_future, metrics_future);
            app_result?;
            metrics_result?;
        } else {
            info!("Metrics endpoint disabled (server.metrics_enabled = false)");
            app_future.await?;
        }

        Ok(())
    }

    /// Get the service URL
    fn get_service_url(&self) -> String {
        format!(
            "http://{}:{}",
            self.config.server.host, self.config.server.port
        )
    }

    /// Get the dataset registry
    pub fn registry(&self) -> &DatasetRegistry {
        &self.registry
    }

    /// Get the tile cache
    pub fn cache(&self) -> &TileCache {
        &self.cache
    }

    /// Get the configuration
    pub fn config(&self) -> &Config {
        &self.config
    }
}

/// Timeout middleware that wraps requests with a timeout
async fn timeout_middleware(
    req: Request,
    next: Next,
    duration: Duration,
) -> Result<Response, StatusCode> {
    match tokio::time::timeout(duration, next.run(req)).await {
        Ok(response) => Ok(response),
        Err(_) => {
            error!("Request timeout after {:?}", duration);
            Err(StatusCode::GATEWAY_TIMEOUT)
        }
    }
}

/// Home page handler
async fn home_handler() -> Html<&'static str> {
    Html(
        r#"<!DOCTYPE html>
<html>
<head>
    <title>OxiGeo Tile Server</title>
    <style>
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            max-width: 800px;
            margin: 50px auto;
            padding: 20px;
            line-height: 1.6;
        }
        h1 { color: #2c3e50; }
        h2 { color: #34495e; margin-top: 30px; }
        code {
            background: #f4f4f4;
            padding: 2px 6px;
            border-radius: 3px;
            font-family: 'Courier New', monospace;
        }
        .endpoint {
            background: #ecf0f1;
            padding: 10px;
            margin: 10px 0;
            border-left: 4px solid #3498db;
        }
        a { color: #3498db; text-decoration: none; }
        a:hover { text-decoration: underline; }
    </style>
</head>
<body>
    <h1>OxiGeo Tile Server</h1>
    <p>WMS/WMTS tile server powered by OxiGeo - Pure Rust geospatial data access library.</p>

    <h2>Available Endpoints</h2>

    <div class="endpoint">
        <h3>WMS (Web Map Service)</h3>
        <p><a href="/wms?SERVICE=WMS&REQUEST=GetCapabilities">GetCapabilities</a></p>
        <p>GetMap: <code>/wms?SERVICE=WMS&REQUEST=GetMap&LAYERS=layer&BBOX=...</code></p>
    </div>

    <div class="endpoint">
        <h3>WMTS (Web Map Tile Service)</h3>
        <p><a href="/wmts?SERVICE=WMTS&REQUEST=GetCapabilities">GetCapabilities</a></p>
        <p>GetTile: <code>/wmts/1.0.0/{layer}/{tileMatrixSet}/{z}/{x}/{y}.png</code></p>
    </div>

    <div class="endpoint">
        <h3>XYZ Tiles</h3>
        <p>Tiles: <code>/tiles/{layer}/{z}/{x}/{y}.png</code></p>
        <p>TileJSON: <code>/tiles/{layer}/tilejson</code></p>
    </div>

    <h2>Server Status</h2>
    <p><a href="/health">Health Check</a> | <a href="/stats">Cache Statistics</a></p>

    <h2>Documentation</h2>
    <p>For more information, visit the <a href="https://github.com/cool-japan/oxigeo">OxiGeo repository</a>.</p>
</body>
</html>
"#,
    )
}

/// Health check handler
async fn health_handler() -> Response {
    (
        StatusCode::OK,
        [(header::CONTENT_TYPE, "application/json")],
        r#"{"status":"healthy","service":"oxigeo-tile-server"}"#,
    )
        .into_response()
}

/// Cache statistics handler
///
/// Reports the real hit/miss/eviction/expiration counters, disk I/O counts,
/// entry count and memory usage from the shared [`TileCache`].
async fn stats_handler(axum::extract::State(cache): axum::extract::State<TileCache>) -> Response {
    let stats = cache.stats();

    let body = serde_json::json!({
        "status": "ok",
        "hits": stats.hits,
        "misses": stats.misses,
        "hit_rate": stats.hit_rate(),
        "entry_count": stats.entry_count,
        "total_size_bytes": stats.total_size,
        "avg_entry_size_bytes": stats.avg_entry_size(),
        "evictions": stats.evictions,
        "expirations": stats.expirations,
        "disk_reads": stats.disk_reads,
        "disk_writes": stats.disk_writes,
        "put_failures": stats.put_failures,
    });

    (
        StatusCode::OK,
        [(header::CONTENT_TYPE, "application/json")],
        serde_json::to_string_pretty(&body).unwrap_or_default(),
    )
        .into_response()
}

/// Build the shutdown-signal future used for graceful shutdown.
///
/// Resolves when the process receives SIGINT (ctrl-c) or, on Unix, SIGTERM
/// (sent by container orchestrators such as Kubernetes during a rollout). This
/// lets in-flight requests drain instead of being hard-killed mid-response.
async fn shutdown_signal() {
    let ctrl_c = async {
        if let Err(e) = tokio::signal::ctrl_c().await {
            error!("Failed to install ctrl-c handler: {}", e);
        }
    };

    #[cfg(unix)]
    let terminate = async {
        match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
            Ok(mut sig) => {
                sig.recv().await;
            }
            Err(e) => error!("Failed to install SIGTERM handler: {}", e),
        }
    };

    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }

    info!("Shutdown signal received; draining in-flight requests");
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_server_creation() {
        let config = Config::default_config();
        let result = TileServer::new(config);

        // Server creation should succeed with default config
        // (even though it has no layers)
        assert!(result.is_ok());
    }
}