footing 0.5.5

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::{
    http::{HeaderValue, Request, header::RETRY_AFTER},
    response::{IntoResponse, Response},
};
use tower::{Layer, Service};

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

use super::{RateLimitDecision, runtime::RateLimitRuntime};

#[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, B> Service<Request<B>> for RateLimitService<S>
where
    B: Send + 'static,
    S: Service<Request<B>, Response = Response> + Clone + Send + 'static,
    S::Future: 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<B>) -> 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())
        .await
        .map_err(|error| {
            if let Some(metrics) = runtime.metrics() {
                runtime.recording_failures.record(
                    MetricLabels::new([
                        (metric_labels::STAGE, "check"),
                        (metric_labels::ERROR_CODE, error.error_code().as_str()),
                    ])
                    .and_then(|labels| {
                        metrics.increment_counter(
                            metric_names::RATE_LIMIT_STORE_ERRORS_TOTAL,
                            1,
                            labels,
                        )
                    }),
                    "rate_limit",
                );
            }
            RateLimitRejection::Unavailable
        })?;

    match decision {
        RateLimitDecision::Allowed { .. } => {
            record_rate_limit_metric(runtime, metric_outcomes::ALLOWED);
            Ok(())
        }
        RateLimitDecision::Denied { retry_after } => {
            record_rate_limit_metric(runtime, metric_outcomes::DENIED);
            Err(RateLimitRejection::Limited { retry_after })
        }
    }
}

fn record_rate_limit_metric(runtime: &RateLimitRuntime, outcome: &'static str) {
    if let Some(metrics) = runtime.metrics() {
        runtime.recording_failures.record(
            MetricLabels::new([(metric_labels::OUTCOME, outcome)]).and_then(|labels| {
                metrics.increment_counter(metric_names::RATE_LIMIT_DECISIONS_TOTAL, 1, labels)
            }),
            "rate_limit",
        );
    }
}

#[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();
                response
                    .headers_mut()
                    .insert(RETRY_AFTER, HeaderValue::from(retry_after_seconds));
                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.subsec_nanos() == 0 {
        seconds
    } else {
        seconds.saturating_add(1)
    }
}