kynos_openapi/model/response/

mod.rs

//! The Responses and Response Objects.

pub mod status;

// Private, because it declares no item of its own that a path could point at:
// [`Responses::union_from`]'s rule is what it holds, and that rule is reachable
// only through the method stating it.
mod union;

use std::fmt;

use serde::{
    Deserialize, Deserializer, Serialize, Serializer,
    de::{Error as DeError, MapAccess, Visitor},
    ser::SerializeMap,
};
use serde_json::Value;

use crate::{
    Map,
    model::{
        body::media_type::MediaType, extensions::Extensions, link::Link, parameter::header::Header,
        reference::RefOr, response::status::StatusPattern, response::union::unioned,
    },
};

/// The responses an operation may return.
///
/// Serializes with [`default_response`](Responses::default_response) under the
/// `default` key, each entry of [`responses`](Responses::responses) under its
/// status pattern, and extensions alongside them.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Responses {
    /// The response used for status codes not otherwise covered.
    pub default_response: Option<RefOr<Response>>,

    /// Responses keyed by status code or wildcard.
    pub responses: Map<RefOr<Response>>,

    /// Specification extensions.
    pub extensions: Extensions,
}

impl Responses {
    /// Creates an empty set of responses.
    ///
    /// A description must not keep it empty: the specification requires at
    /// least one response, and [`crate::validate`] reports the omission.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Declares a response for an exact status code.
    #[must_use]
    pub fn with(mut self, status: u16, response: Response) -> Self {
        self.responses.insert(
            StatusPattern::Code(status).to_string(),
            RefOr::Item(response),
        );
        self
    }

    /// Declares a response for a status pattern.
    #[must_use]
    pub fn with_pattern(mut self, pattern: StatusPattern, response: RefOr<Response>) -> Self {
        self.responses.insert(pattern.to_string(), response);
        self
    }

    /// Sets the fallback response.
    #[must_use]
    pub fn with_default(mut self, response: Response) -> Self {
        self.default_response = Some(RefOr::Item(response));
        self
    }

    /// Returns `true` when nothing at all is declared.
    ///
    /// Extensions count. `Operation.responses` is skipped when this is true,
    /// so ignoring them would silently drop a `Responses` that carries only
    /// `x-` fields — which is exactly the drop a round trip must not make.
    ///
    /// This is therefore *not* the question the specification's "MUST contain
    /// at least one response code" asks. [`declares_a_response`] is.
    ///
    /// [`declares_a_response`]: Responses::declares_a_response
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.default_response.is_none() && self.responses.is_empty() && self.extensions.is_empty()
    }

    /// Returns `true` when a status code or `default` is declared.
    ///
    /// The distinction from [`is_empty`](Responses::is_empty) is the whole
    /// point: an extension is not a response, so a Responses Object carrying
    /// only `x-` fields is *not* empty and still declares nothing.
    #[must_use]
    pub fn declares_a_response(&self) -> bool {
        self.default_response.is_some() || !self.responses.is_empty()
    }

    /// Looks up the response declared for an exact status code.
    ///
    /// Only exact keys are considered; wildcard resolution is a consumer
    /// concern and depends on precedence rules this method does not apply.
    #[must_use]
    pub fn get(&self, status: u16) -> Option<&RefOr<Response>> {
        self.responses.get(&StatusPattern::Code(status).to_string())
    }

    /// Merges another set into this one, keeping existing entries on conflict.
    ///
    /// This is how an interceptor's declared responses join an operation's own.
    pub fn merge_from(&mut self, other: &Self) {
        if self.default_response.is_none() {
            self.default_response.clone_from(&other.default_response);
        }
        for (key, response) in &other.responses {
            if !self.responses.contains_key(key) {
                self.responses.insert(key.clone(), response.clone());
            }
        }
    }

    /// Merges another set into this one, unioning two problem responses that
    /// meet on one status.
    ///
    /// [`merge_from`](Responses::merge_from) with one exception, and the
    /// exception is the only reason this exists. A status is one key and a
    /// response is what a client is told about it, so where two contributors
    /// both name a status — an extractor's rejection and the handler's error
    /// type is the case that motivates this — keeping whichever arrived first
    /// publishes half of what the operation can send.
    ///
    /// The exception is deliberately narrow. It applies where both entries
    /// declare an `application/problem+json` schema, because two problem
    /// documents under one status are two branches of a choice over the same
    /// component — which merging two arbitrary responses is not. Anything else
    /// keeps the entry already declared, exactly as `merge_from` would.
    ///
    /// # What the union is
    ///
    /// The entry already declared, with two of its fields replaced, so
    /// everything else it carries — a `WWW-Authenticate` header, a link, an
    /// extension — survives a contributor arriving after it.
    ///
    /// * **The schema.** A *narrowed* problem schema constrains `type` to a
    ///   `const` on every branch, which is the shape `#[derive(ApiError)]`
    ///   emits: one `allOf` for a single type, a `oneOf` of them for several.
    ///   Where both sides are narrowed the branches are flattened, deduplicated
    ///   by the URI they publish and rebuilt — a single `allOf` where one
    ///   survives, a `oneOf` where several do. The dedup is what keeps `oneOf`
    ///   sound: two branches repeating a `const` are satisfied at once, which
    ///   is exactly what the keyword forbids.
    ///
    ///   Where one side instead admits *everything* — `true`, or a bare `$ref`
    ///   to the shared component, which every problem document satisfies — that
    ///   side is the union: it already admits every document the other
    ///   describes, and narrowing to the other would declare less than the
    ///   operation sends.
    ///
    ///   A side that is neither is not read as either. A schema satisfied by
    ///   nothing, an empty `oneOf`, and a `oneOf` whose branches overlap all
    ///   fail the narrowing read while admitting strictly *less* than a
    ///   narrowed side, so adopting one would declare a schema the operation's
    ///   own bodies fail. Those keep the entry already declared, as
    ///   `merge_from` would.
    ///
    /// * **The description.** Both, joined with `"; "`, dropping a sentence
    ///   already written word for word. Prose is under no exactly-one rule, so
    ///   a status two contributors reach says what each of them means.
    pub fn union_from(&mut self, other: &Self) {
        if self.default_response.is_none() {
            self.default_response.clone_from(&other.default_response);
        }
        for (key, incoming) in &other.responses {
            // Resolved to an owned entry before anything is inserted, so the
            // read of the declared response ends where the write begins.
            let replacement = match (self.responses.get(key), incoming) {
                (None, incoming) => Some(incoming.clone()),
                (Some(RefOr::Item(declared)), RefOr::Item(incoming)) => {
                    unioned(declared, incoming).map(RefOr::Item)
                }
                // A response held as a `$ref` is not reached into, on either
                // side: what it refers to is not this document's to read.
                (Some(_), _) => None,
            };

            if let Some(response) = replacement {
                self.responses.insert(key.clone(), response);
            }
        }
    }
}

impl Serialize for Responses {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let len = usize::from(self.default_response.is_some())
            + self.responses.len()
            + self.extensions.0.len();
        let mut map = serializer.serialize_map(Some(len))?;
        if let Some(default) = &self.default_response {
            map.serialize_entry("default", default)?;
        }
        for (key, response) in &self.responses {
            map.serialize_entry(key, response)?;
        }
        for (key, value) in &self.extensions.0 {
            map.serialize_entry(key, value)?;
        }
        map.end()
    }
}

impl<'de> Deserialize<'de> for Responses {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        struct ResponsesVisitor;

        impl<'de> Visitor<'de> for ResponsesVisitor {
            type Value = Responses;

            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str("a map of status patterns to responses")
            }

            fn visit_map<A: MapAccess<'de>>(self, mut access: A) -> Result<Responses, A::Error> {
                let mut responses = Responses::new();
                while let Some(key) = access.next_key::<String>()? {
                    if key == "default" {
                        responses.default_response = Some(access.next_value()?);
                    } else if key.starts_with(crate::model::extensions::EXTENSION_PREFIX) {
                        responses.extensions.0.insert(key, access.next_value()?);
                    } else {
                        // Reject a malformed key here rather than carrying it
                        // forward: an unparseable status is never meaningful.
                        key.parse::<StatusPattern>().map_err(A::Error::custom)?;
                        responses.responses.insert(key, access.next_value()?);
                    }
                }
                Ok(responses)
            }
        }

        deserializer.deserialize_map(ResponsesVisitor)
    }
}

/// A single response.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Response {
    /// A short summary of the response.
    ///
    /// Introduced in OpenAPI 3.2. Under 3.1 the first line of the description
    /// serves this purpose.
    #[cfg(feature = "openapi32")]
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub summary: Option<String>,

    /// A description of the response. [CommonMark] syntax may be used.
    ///
    /// **Required by 3.1, optional in 3.2.** 3.1 marks it `REQUIRED`; 3.2
    /// drops the marker, so a response stating only a
    /// [`summary`](Response::summary) is a legal 3.2 document. Modelling it as
    /// a `String` enforced 3.1's rule on both versions and made such a
    /// document unparseable, so the requirement lives in
    /// [`validate`](crate::validate) instead, where it is checked against the
    /// version the document claims.
    ///
    /// [`new`](Response::new) sets it, which is the common case and the only
    /// one 3.1 admits.
    ///
    /// [CommonMark]: https://spec.commonmark.org/
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Headers sent with the response.
    ///
    /// A `Content-Type` entry is ignored, since [`content`](Response::content)
    /// states it.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub headers: Map<RefOr<Header>>,

    /// The response body's representations, keyed by media type.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub content: Map<MediaType>,

    /// Design-time links to other operations.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub links: Map<RefOr<Link>>,

    /// Specification extensions.
    #[serde(flatten)]
    pub extensions: Extensions,
}

impl Response {
    /// Creates a response with no body.
    pub fn new(description: impl Into<String>) -> Self {
        Self {
            description: Some(description.into()),
            ..Self::default()
        }
    }

    /// Creates a response with one body representation.
    pub fn with_content(
        description: impl Into<String>,
        media_type: impl Into<String>,
        content: MediaType,
    ) -> Self {
        let mut response = Self::new(description);
        response.content.insert(media_type.into(), content);
        response
    }

    /// Declares a response header.
    #[must_use]
    pub fn with_header(mut self, name: impl Into<String>, header: Header) -> Self {
        self.headers.insert(name.into(), RefOr::Item(header));
        self
    }

    /// Declares a link to another operation.
    #[must_use]
    pub fn with_link(mut self, name: impl Into<String>, link: Link) -> Self {
        self.links.insert(name.into(), RefOr::Item(link));
        self
    }

    /// Attaches an extension field.
    #[must_use]
    pub fn with_extension(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
        self.extensions.insert(key, value);
        self
    }
}

#[cfg(test)]
mod tests;