footing 0.1.19

Feature-gated foundations for Rust backend services
Documentation
//! Axum and Tower rate-limit enforcement.

use std::{
    future::Future,
    pin::Pin,
    task::{Context, Poll},
    time::Duration,
};

use axum::{
    body::Body,
    http::{HeaderValue, Request, header::RETRY_AFTER},
    middleware::Next,
    response::{IntoResponse, Response},
};
use tower::{Layer, Service};

use crate::{
    http::{ApiProblem, HttpRequestPolicy, ProblemCode},
    observability::{MetricLabels, metric_labels, metric_names, metric_outcomes},
};

use super::runtime::RateLimitRuntime;

/// Applies rate limiting using runtime state stored in request extensions.
pub async fn rate_limit_middleware(request: Request<Body>, next: Next) -> Response {
    let Some(runtime) = request.extensions().get::<RateLimitRuntime>() else {
        return next.run(request).await;
    };

    match enforce_rate_limit(runtime, &request).await {
        Ok(()) => next.run(request).await,
        Err(rejection) => rejection.into_response(),
    }
}

#[derive(Debug, Clone)]
#[non_exhaustive]
/// Tower layer that applies rate limit.
pub struct RateLimitLayer {
    runtime: RateLimitRuntime,
    request_policy: HttpRequestPolicy,
}

impl RateLimitLayer {
    #[must_use]
    /// Creates a new instance.
    pub fn new(runtime: RateLimitRuntime) -> Self {
        Self {
            runtime,
            request_policy: HttpRequestPolicy::default(),
        }
    }

    #[must_use]
    /// Configures request policy and returns the updated value.
    pub fn with_request_policy(mut self, request_policy: HttpRequestPolicy) -> Self {
        self.request_policy = request_policy;
        self
    }

    #[must_use]
    /// Returns the runtime.
    pub const fn runtime(&self) -> &RateLimitRuntime {
        &self.runtime
    }

    #[must_use]
    /// Returns the request policy.
    pub const fn request_policy(&self) -> &HttpRequestPolicy {
        &self.request_policy
    }
}

impl<S> Layer<S> for RateLimitLayer {
    type Service = RateLimitService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        RateLimitService {
            inner,
            runtime: self.runtime.clone(),
            request_policy: self.request_policy.clone(),
        }
    }
}

#[derive(Debug, Clone)]
#[non_exhaustive]
/// Service for rate limit.
pub struct RateLimitService<S> {
    inner: S,
    runtime: RateLimitRuntime,
    request_policy: HttpRequestPolicy,
}

impl<S> Service<Request<Body>> for RateLimitService<S>
where
    S: Service<Request<Body>, Response = Response> + Clone + Send + 'static,
    S::Future: Send + 'static,
    S::Error: Send + 'static,
{
    type Response = Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, context: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(context)
    }

    fn call(&mut self, mut request: Request<Body>) -> Self::Future {
        let enabled = self
            .request_policy
            .resolve(&mut request)
            .rate_limit()
            .enabled();
        if !enabled {
            return Box::pin(self.inner.call(request));
        }
        let enforcement = enforce_rate_limit(&self.runtime, &request);
        let clone = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            if let Err(rejection) = enforcement.await {
                return Ok(rejection.into_response());
            }

            inner.call(request).await
        })
    }
}

/// Evaluates a rate-limit key and returns the request or a rejection.
pub fn enforce_rate_limit<B>(
    runtime: &RateLimitRuntime,
    request: &Request<B>,
) -> impl Future<Output = Result<(), RateLimitRejection>> + Send + 'static + use<B> {
    let runtime = runtime.clone();
    let key = runtime.key_source().key_for(request);
    async move {
        let key = key.ok_or(RateLimitRejection::MissingKey)?;
        enforce_rate_limit_key(&runtime, key).await
    }
}

async fn enforce_rate_limit_key(
    runtime: &RateLimitRuntime,
    key: String,
) -> Result<(), RateLimitRejection> {
    let decision = runtime
        .store()
        .check(key, runtime.config(), runtime.clock().now())
        .await
        .map_err(|_| RateLimitRejection::Unavailable)?;

    if let Some(retry_after) = decision.retry_after() {
        record_rate_limit_metric(runtime, metric_outcomes::DENIED);
        Err(RateLimitRejection::Limited { retry_after })
    } else {
        record_rate_limit_metric(runtime, metric_outcomes::ALLOWED);
        Ok(())
    }
}

fn record_rate_limit_metric(runtime: &RateLimitRuntime, outcome: &'static str) {
    if let Some(metrics) = runtime.metrics() {
        let _ = metrics.increment_counter(
            metric_names::RATE_LIMIT_DECISIONS_TOTAL,
            1,
            MetricLabels::from_lossy([(metric_labels::OUTCOME, outcome)]),
        );
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
/// Enumerates the supported rate limit rejection values.
pub enum RateLimitRejection {
    /// Indicates limited.
    Limited {
        #[doc = "The delay before retrying."]
        retry_after: Duration,
    },
    /// The configured stable bucket key was not present on the request.
    MissingKey,
    /// Indicates unavailable.
    Unavailable,
}

impl IntoResponse for RateLimitRejection {
    fn into_response(self) -> Response {
        match self {
            Self::Limited { retry_after } => {
                let retry_after_seconds = retry_after_header_seconds(retry_after);
                let mut response =
                    ApiProblem::too_many_requests(ProblemCode::RATE_LIMITED, "too many requests")
                        .with_details(serde_json::json!({
                            "retry_after_seconds": retry_after_seconds,
                        }))
                        .into_response();
                if let Ok(value) = HeaderValue::from_str(&retry_after_seconds.to_string()) {
                    response.headers_mut().insert(RETRY_AFTER, value);
                }
                response
            }
            Self::MissingKey => ApiProblem::service_unavailable(
                ProblemCode::RATE_LIMIT_KEY_UNAVAILABLE,
                "rate limit key is unavailable",
            )
            .into_response(),
            Self::Unavailable => ApiProblem::service_unavailable(
                ProblemCode::RATE_LIMIT_UNAVAILABLE,
                "rate limit is unavailable",
            )
            .into_response(),
        }
    }
}

pub(super) fn retry_after_header_seconds(retry_after: Duration) -> u64 {
    let seconds = retry_after.as_secs();
    if retry_after.is_zero() || retry_after.subsec_nanos() == 0 {
        seconds
    } else {
        seconds.saturating_add(1)
    }
}