footing 0.1.12

Feature-gated foundations for Rust backend services
Documentation
use utoipa::{
    IntoParams,
    openapi::{
        Required,
        path::{Parameter, ParameterBuilder, ParameterIn},
        schema::{ObjectBuilder, Type},
    },
};

use crate::{
    http::{
        CursorPagination, CursorPaginationQuery, IDEMPOTENCY_KEY_HEADER_NAME,
        IdempotencyRequestPolicy, MAX_IDEMPOTENCY_KEY_LENGTH, OffsetPagination,
        OffsetPaginationQuery, QueryParams, RequiredIdempotencyKey,
    },
    pagination::PageLimits,
};

fn page_size(limits: PageLimits) -> Parameter {
    query_parameter(
        "page_size",
        "Maximum number of items returned.",
        ObjectBuilder::new()
            .schema_type(Type::Integer)
            .minimum(Some(1))
            .maximum(Some(limits.max_page_size()))
            .default(Some(limits.default_page_size().into())),
    )
}

/// Describes cursor query parameters using the validated limits installed on a route.
#[must_use]
pub fn cursor_pagination_parameters(limits: PageLimits) -> Vec<Parameter> {
    vec![
        page_size(limits),
        query_parameter(
            "cursor",
            "Opaque cursor from the previous page.",
            ObjectBuilder::new()
                .schema_type(Type::String)
                .min_length(Some(1))
                .max_length(Some(limits.max_cursor_length()))
                .pattern(Some(r"^[A-Za-z0-9_.-]+$")),
        ),
        query_parameter(
            "include_total",
            "Whether to request the total item count.",
            ObjectBuilder::new()
                .schema_type(Type::Boolean)
                .default(Some(false.into())),
        ),
    ]
}

/// Describes offset query parameters using the validated limits installed on a route.
#[must_use]
pub fn offset_pagination_parameters(limits: PageLimits) -> Vec<Parameter> {
    vec![
        query_parameter(
            "page",
            "One-based page number.",
            ObjectBuilder::new()
                .schema_type(Type::Integer)
                .minimum(Some(1))
                .maximum(Some(u32::MAX))
                .default(Some(1.into())),
        ),
        page_size(limits),
    ]
}

fn query_parameter(name: &str, description: &str, schema: ObjectBuilder) -> Parameter {
    ParameterBuilder::new()
        .name(name)
        .parameter_in(ParameterIn::Query)
        .required(Required::False)
        .description(Some(description))
        .schema(Some(schema))
        .build()
}

/// Describes the idempotency header when enabled for a route.
/// Disabled policies do not introduce a header into the document.
#[must_use]
pub fn idempotency_key_parameter(policy: IdempotencyRequestPolicy) -> Option<Parameter> {
    let required = match policy {
        IdempotencyRequestPolicy::Disabled => return None,
        IdempotencyRequestPolicy::HeaderOptional => Required::False,
        IdempotencyRequestPolicy::Required => Required::True,
    };
    let schema = ObjectBuilder::new()
        .schema_type(Type::String)
        .min_length(Some(1))
        .max_length(Some(MAX_IDEMPOTENCY_KEY_LENGTH))
        .pattern(Some(r"^[A-Za-z0-9_.:-]+$"));
    Some(
        ParameterBuilder::new()
            .name(IDEMPOTENCY_KEY_HEADER_NAME)
            .parameter_in(ParameterIn::Header)
            .required(required)
            .description(Some(
                "Identifies one operation within its scope. Reuse only for an identical request.",
            ))
            .schema(Some(schema))
            .build(),
    )
}

impl IntoParams for CursorPaginationQuery {
    fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        cursor_pagination_parameters(PageLimits::default())
    }
}

impl IntoParams for CursorPagination {
    fn into_params(provider: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        CursorPaginationQuery::into_params(provider)
    }
}

impl IntoParams for OffsetPaginationQuery {
    fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        offset_pagination_parameters(PageLimits::default())
    }
}

impl IntoParams for OffsetPagination {
    fn into_params(provider: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        OffsetPaginationQuery::into_params(provider)
    }
}

impl<T: IntoParams> IntoParams for QueryParams<T> {
    fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        T::into_params(|| Some(ParameterIn::Query))
    }
}

impl IntoParams for RequiredIdempotencyKey {
    fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
        idempotency_key_parameter(IdempotencyRequestPolicy::Required)
            .into_iter()
            .collect()
    }
}