musli_web/

api.rs

//! Shared traits for defining API types.
//!
//! # Wire format
//!
//! Every websocket message consists of a fixed *envelope* followed by an
//! optional *body*:
//!
//! ```text
//! +--------------------------+--------------------------------+
//! | envelope (api::Mode)     | body (negotiated api::Format)  |
//! +--------------------------+--------------------------------+
//! ```
//!
//! The envelope is a block of *headers*: a [`RequestHeader`] for messages sent
//! by the client and a [`ResponseHeader`] for messages sent by the server. How
//! it is spelled is decided by the [`Mode`] the socket runs in and never
//! changes with the negotiated format. This is what makes the format negotiable
//! at all, since both peers can always read the envelope regardless of what
//! they have agreed on for bodies.
//!
//! The body is encoded with the [`Format`] identified by the `format` header of
//! the envelope, so every message is self-describing in this respect. A `format`
//! of zero means the message carries no body.
//!
//! # The protocol version
//!
//! Every envelope states the version of the wire protocol it was written
//! against in its `version` header, and a peer refuses an envelope which states
//! anything other than [`VERSION`]. The very first message each side sees
//! carries it — [`MessageId::SERVER_HELLO`] for the client and
//! [`MessageId::NEGOTIATE`] for the server — so a session between peers which
//! do not speak the same protocol is rejected before either of them has acted
//! on anything the other said.
//!
//! This is what a header being unknown is measured against. A version bump is
//! the deliberate way to change what the envelope may contain, so an unknown
//! header arriving under a version we do accept means something has gone wrong
//! that neither peer planned for, which is why it is refused outright rather
//! than skipped.
//!
//! # Headers
//!
//! Every header carries an unsigned integer and is addressed by a name. A
//! header which is absent reads as zero, and headers may arrive in any order,
//! so a message which has no use for a header simply does not write one.
//!
//! Both spellings are *self-delimiting*: a reader can find the end of a header
//! it has never seen without understanding what it means. That is deliberate,
//! and it is what makes the next rule possible.
//!
//! **A header which this build does not know about is refused.** It is read,
//! stepped over so that the position of everything after it is still known, and
//! then reported as an error which tears the connection down. A peer writing a
//! header we have never seen is a peer speaking a protocol we do not have, and
//! acting on the part of the message we happen to recognize would mean acting
//! on a message we have not actually understood.
//!
//! A version which does not match is reported ahead of an unknown header, since
//! the version is what explains the header.
//!
//! # The binary envelope
//!
//! In [`Mode::Binary`] each header is a tag byte followed by its value, and a
//! tag byte of zero ends the block:
//!
//! ```text
//! +-----+---------------+     +-----+
//! | tag | value (1/2/4) | ... |  0  |
//! +-----+---------------+     +-----+
//! ```
//!
//! The low six bits of the tag are the header's id, which is never zero. The
//! top two bits say how wide the value is — `0` for one byte, `1` for two and
//! `2` for four, little endian — which is what lets an unknown header be
//! stepped over. A value is written in the narrowest of those which holds it,
//! so a small value costs no more than it has to. The remaining class is
//! reserved, and a header which uses it cannot be skipped, so it is refused.
//!
//! # The text envelope
//!
//! In [`Mode::Text`] the envelope is instead a block of `<key>: <value>` lines
//! terminated by an empty line, carried in a text frame:
//!
//! ```text
//! version: 2
//! serial: 1
//! id: 1
//! format: 5
//! channel: 0
//! app: 0
//!
//! {"message":"Hello!"}
//! ```
//!
//! Every header is written, in the order it is declared, with its value in
//! decimal. Being explicit is worth more than being terse in a spelling meant
//! to be read by people, so a header which is zero is written out too.
//!
//! Nothing about the message is otherwise different, which means the mode only
//! decides how the frame is *spelled*. Since a text frame has to be valid UTF-8
//! in its entirety the body has to be human readable too, so [`Mode::Text`]
//! requires a [`Format`] for which [`Format::is_human_readable`] holds. This is
//! what [`Mode::accepts`] tests.
//!
//! # Negotiating the mode
//!
//! Unlike the format, the mode is never carried in a field. The frame type
//! *is* the mode, so a peer can always tell which envelope it is looking at,
//! and a message can be read before anything has been agreed on.
//!
//! A client sends its [`MessageId::NEGOTIATE`] request in the mode it wants,
//! and the server replies in the mode it settled on. A server which is asked
//! for [`Mode::Text`] together with a format it cannot carry that way settles
//! on [`Mode::DEFAULT`], exactly like it does for a format it does not support.
//! The client adopts whichever mode the reply arrived in, and the mode is then
//! fixed for the lifetime of the connection.
//!
//! The one message which precedes all of this is
//! [`MessageId::SERVER_HELLO`], which is always sent in [`Mode::DEFAULT`] since
//! the server has not heard from the client yet.
//!
//! # Negotiating the format
//!
//! A client picks the [`Format`] it wants to use, defaulting to
//! [`Format::DEFAULT`]. The exchange is:
//!
//! 1. The server sends [`MessageId::SERVER_HELLO`] as soon as the connection is
//!    established. This carries no body.
//! 2. The client responds with a [`MessageId::NEGOTIATE`] request whose
//!    envelope carries the desired [`Format`]. This carries no body.
//! 3. If the server supports that format it records it for the connection and
//!    replies with an empty response whose envelope carries the format that was
//!    accepted. If it does not, it replies with an error listing the formats it
//!    does support, and the connection settles on [`Format::DEFAULT`].
//!
//! Both peers are forced through this before anything else can happen:
//!
//! * A client only reports itself as connected once step 3 has resolved.
//! * A server has no way to write a message until then either, since
//!   [`ws::Connect::connect`] is what produces the [`ws::Server`] which can, and
//!   it does not resolve until step 3 has been flushed. Any other message
//!   arriving in place of step 2 is a protocol violation which closes the
//!   connection.
//!
//! Together this guarantees that server-initiated messages such as broadcasts
//! are encoded with a format the client understands. The format is fixed for
//! the lifetime of a connection, so a second negotiation is refused — a client
//! which wants a different one reconnects.
//!
//! Requests additionally carry their own format in the envelope, so the server
//! decodes each request body with the format that request declares and replies
//! in the same format. Negotiation therefore only matters for messages the
//! server sends on its own initiative.
//!
//! Since formats are gated behind [features], a server may genuinely be unable
//! to speak a format a client asks for, which is why step 3 can fail.
//!
//! # Application versions
//!
//! [`VERSION`] only covers the envelope. The requests and broadcasts an
//! application defines with [`define!`] are its own protocol, and a page which
//! was loaded before the server was upgraded keeps speaking the old one for as
//! long as it stays open. An upgrade safe [`Format`] tolerates added and
//! missing fields, but not every change is like that.
//!
//! To find out, both peers can state an *application version* in the
//! handshake: a number the application bumps whenever its API changes in a
//! way an older peer cannot cope with, kept in a crate both sides depend on.
//! The server states it with [`ws::Connect::app_version`] and a client with
//! `ServiceBuilder::app_version`, in [`web`] or in [`client`].
//!
//! 1. The server states its version in the `app` header of
//!    [`MessageId::SERVER_HELLO`].
//! 2. The client compares it with its own. It always sends its
//!    [`MessageId::NEGOTIATE`] request, stating its own version in the same
//!    header, so that the server can tell why it goes away.
//! 3. If the two differ the client closes the connection and reports it as
//!    incompatible, with both versions, instead of opening it. It does not
//!    reconnect, since that reaches the same server. A page usually responds
//!    by reloading, which fetches the page the server is built with.
//! 4. A server which is negotiated with by a client stating another version
//!    refuses it with a close frame, and [`ws::Connect::connect`] fails with an
//!    error for which [`ws::Error::is_incompatible`] holds.
//!
//! Zero means that no version is stated, and is what both sides default to.
//! Versions are only compared when both peers state one, so a peer which does
//! not opt in behaves exactly as it would without this, whatever the other
//! one does. Every other message leaves the header at zero, which a binary
//! envelope does not write at all.
//!
//! [`web`]: <https://docs.rs/musli-web/latest/musli_web/web/>
//! [`client`]: <https://docs.rs/musli-web/latest/musli_web/client/>
//! [`ws::Connect::app_version`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.Connect.html#method.app_version>
//! [`ws::Error::is_incompatible`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.Error.html#method.is_incompatible>
//!
//! # Error responses
//!
//! A request which fails is answered with a response whose `error` header is
//! non-zero, and whose body is encoded with the format the connection
//! negotiated (rather than the one the request declared, since the request
//! might have failed precisely because its format is not supported):
//!
//! * [`MessageId::ERROR_MESSAGE`] - the body is an [`ErrorMessage`], which
//!   carries a human readable message and nothing else. This is what the server
//!   sends when it fails a request on its own, such as one it does not support,
//!   and for a handler error which is plain text.
//! * [`MessageId::TYPED_ERROR_MESSAGE`] - the body is an [`ErrorMessage`]
//!   followed by a second value, the *payload*, which is the error the handler
//!   returned encoded the same way a response body would be. The message is
//!   still there so that a client which does not know the type of the payload
//!   can show something.
//!
//! Any other non-zero value is an error the client has no message for, which
//! it reports as an unsupported request (or broadcast).
//!
//! On the server a handler opts into the typed form by failing with a
//! [`ws::TypedError`]. A client reads the payload back with
//! `web::Error::server_error` or `client::Error::server_error`.
//!
//! [features]: <https://docs.rs/musli-web/latest/musli_web/#features>
//! [`ws::Connect::connect`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.Connect.html#method.connect>
//! [`ws::TypedError`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.TypedError.html>
//! [`ws::Server`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.Server.html>

use core::fmt;
use core::num::NonZeroU16;
use core::str::FromStr;
use core::sync::atomic::{AtomicU16, Ordering};

use musli::alloc::Global;
use musli::mode::{Binary, Text};
use musli::{Decode, Encode};

#[doc(inline)]
pub use musli_web_macros::define;

/// The version of the wire protocol this build speaks.
///
/// It is stated by every envelope and checked by every peer, see [the protocol
/// version]. A peer which states anything else is refused, since there is no
/// way to know which parts of what it said still mean what they used to.
///
/// [the protocol version]: crate::api#the-protocol-version
///
/// # History
///
/// * `2` - a request may fail with a typed error, see [error responses], and
///   the handshake carries an [application version].
/// * `1` - the first versioned protocol.
///
/// [error responses]: crate::api#error-responses
/// [application version]: crate::api#application-versions
///
/// # Examples
///
/// ```
/// use musli_web::api::VERSION;
///
/// assert_eq!(VERSION, 2);
/// ```
pub const VERSION: u32 = 2;

/// The serialization format used for message bodies.
///
/// The format is negotiated per connection, see the [negotiation protocol] for the
/// details of how. Message *headers* are never affected by this and always use
/// a fixed envelope, which is what makes negotiation possible in the first
/// place.
///
/// The variants are ordered from least to most capable. Each capability that is
/// dropped makes the encoding more compact:
///
/// | | `reorder` | `missing` | `unknown` | `self` |
/// |-|-|-|-|-|
/// | [`Packed`] | ✗ | ✗ | ✗ | ✗ |
/// | [`Storage`] | ✔ | ✔ | ✗ | ✗ |
/// | [`Wire`] | ✔ | ✔ | ✔ | ✗ |
/// | [`Descriptive`] | ✔ | ✔ | ✔ | ✔ |
/// | [`Json`] | ✔ | ✔ | ✔ | ✔ |
///
/// * `reorder` determines whether fields may be reordered in the model.
/// * `missing` determines whether decoding tolerates missing fields, which is
///   what allows new optional fields to be added.
/// * `unknown` determines whether decoding can skip fields it does not know
///   about. A format which can do this is *fully upgrade safe*, since an old
///   peer can talk to a new one.
/// * `self` determines whether the format is self-descriptive, so that the data
///   can be decoded without the model.
///
/// [`Packed`]: Format::Packed
/// [`Storage`]: Format::Storage
/// [`Wire`]: Format::Wire
/// [`Descriptive`]: Format::Descriptive
/// [`Json`]: Format::Json
///
/// # Examples
///
/// ```
/// use musli_web::api::Format;
///
/// assert_eq!(Format::default(), Format::Wire);
/// assert!(Format::Wire.is_upgrade_safe());
/// assert!(!Format::Storage.is_upgrade_safe());
/// assert!(Format::Json.is_human_readable());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum Format {
    /// The [`musli::packed`] format.
    ///
    /// The most compact format, but it requires that both peers use exactly the
    /// same model. Suitable when client and server are deployed together.
    Packed,
    /// The [`musli::storage`] format.
    ///
    /// Tolerates missing fields, but cannot skip fields it does not know about.
    Storage,
    /// The [`musli::wire`] format.
    ///
    /// Fully upgrade safe, so peers built against different versions of the
    /// model can talk to each other. This is the default.
    Wire,
    /// The [`musli::descriptive`] format.
    ///
    /// Fully upgrade safe and self-descriptive, at the cost of a larger
    /// payload.
    Descriptive,
    /// The [`musli::json`] format.
    ///
    /// Human readable, which is useful when the traffic has to be inspected by
    /// hand. Encoded using the [`Text`] mode so that fields are keyed by name.
    ///
    /// [`Text`]: musli::mode::Text
    Json,
}

impl Format {
    /// The default format, which is [`Format::Wire`].
    ///
    /// This is used by a client which has not picked a format, and by a server
    /// for a connection which has not negotiated one.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!(Format::DEFAULT, Format::Wire);
    /// ```
    pub const DEFAULT: Self = Self::Wire;

    /// Every format in order of increasing capability.
    ///
    /// Note that this includes formats which the crate might not have been
    /// built with support for, see [`Format::is_supported`].
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert!(Format::ALL.contains(&Format::Json));
    /// ```
    pub const ALL: &'static [Format] = &[
        Format::Packed,
        Format::Storage,
        Format::Wire,
        Format::Descriptive,
        Format::Json,
    ];

    /// Get the stable identifier used for this format on the wire.
    ///
    /// Zero is never used, so it is available to indicate an absent format.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!(Format::Wire.to_u8(), 3);
    /// assert_eq!(Format::from_u8(3), Some(Format::Wire));
    /// ```
    #[inline]
    pub const fn to_u8(self) -> u8 {
        match self {
            Format::Packed => 1,
            Format::Storage => 2,
            Format::Wire => 3,
            Format::Descriptive => 4,
            Format::Json => 5,
        }
    }

    /// Construct a format from the stable identifier used on the wire.
    ///
    /// Returns `None` if the identifier is not known, which is how a peer
    /// built against an older version of this crate reports a format it has
    /// never heard of.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!(Format::from_u8(1), Some(Format::Packed));
    /// assert_eq!(Format::from_u8(0), None);
    /// assert_eq!(Format::from_u8(200), None);
    /// ```
    #[inline]
    pub const fn from_u8(id: u8) -> Option<Self> {
        match id {
            1 => Some(Format::Packed),
            2 => Some(Format::Storage),
            3 => Some(Format::Wire),
            4 => Some(Format::Descriptive),
            5 => Some(Format::Json),
            _ => None,
        }
    }

    /// The name of the format.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!(Format::Wire.name(), "wire");
    /// ```
    #[inline]
    pub const fn name(self) -> &'static str {
        match self {
            Format::Packed => "packed",
            Format::Storage => "storage",
            Format::Wire => "wire",
            Format::Descriptive => "descriptive",
            Format::Json => "json",
        }
    }

    /// Test if the format can skip over unknown fields, making it fully upgrade
    /// safe.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert!(Format::Wire.is_upgrade_safe());
    /// assert!(!Format::Packed.is_upgrade_safe());
    /// ```
    #[inline]
    pub const fn is_upgrade_safe(self) -> bool {
        matches!(self, Format::Wire | Format::Descriptive | Format::Json)
    }

    /// Test if the format is self-descriptive, so that data can be decoded
    /// without access to the model.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert!(Format::Descriptive.is_self_descriptive());
    /// assert!(!Format::Wire.is_self_descriptive());
    /// ```
    #[inline]
    pub const fn is_self_descriptive(self) -> bool {
        matches!(self, Format::Descriptive | Format::Json)
    }

    /// Test if the format produces output which is meant to be read by humans.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert!(Format::Json.is_human_readable());
    /// assert!(!Format::Wire.is_human_readable());
    /// ```
    #[inline]
    pub const fn is_human_readable(self) -> bool {
        matches!(self, Format::Json)
    }
}

impl Default for Format {
    /// Construct the default format, which is [`Format::DEFAULT`].
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!(Format::default(), Format::Wire);
    /// ```
    #[inline]
    fn default() -> Self {
        Self::DEFAULT
    }
}

impl fmt::Display for Format {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// The error returned when parsing a [`Format`] from a string which is not the
/// [`name`] of any format.
///
/// [`name`]: Format::name
///
/// # Examples
///
/// ```
/// use musli_web::api::Format;
///
/// let error = "yaml".parse::<Format>().unwrap_err();
/// assert_eq!(error.to_string(), "unknown format, expected one of: packed, storage, wire, descriptive, json");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct ParseFormatError;

impl fmt::Display for ParseFormatError {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("unknown format, expected one of: packed, storage, wire, descriptive, json")
    }
}

impl core::error::Error for ParseFormatError {}

impl FromStr for Format {
    type Err = ParseFormatError;

    /// Parse a format from exactly what its [`Display`] implementation and
    /// [`Format::name`] produce.
    ///
    /// Matching is case sensitive and does not trim whitespace.
    ///
    /// [`Display`]: fmt::Display
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Format;
    ///
    /// assert_eq!("wire".parse::<Format>(), Ok(Format::Wire));
    /// assert!("Wire".parse::<Format>().is_err());
    ///
    /// for format in Format::ALL {
    ///     assert_eq!(format.to_string().parse::<Format>(), Ok(*format));
    /// }
    /// ```
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        for &format in Self::ALL {
            if format.name() == s {
                return Ok(format);
            }
        }

        Err(ParseFormatError)
    }
}

/// How a socket frames the messages it carries.
///
/// This picks between the two shapes a message can have on the wire. It is
/// orthogonal to the [`Format`] which bodies are encoded with, except that
/// [`Mode::Text`] requires a human readable one, see the [text envelope].
///
/// [text envelope]: crate::api#the-text-envelope
///
/// # Examples
///
/// ```
/// use musli_web::api::Mode;
///
/// assert_eq!(Mode::default(), Mode::Binary);
/// assert!(Mode::Text.is_text());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum Mode {
    /// Messages are binary frames whose envelope is encoded with
    /// [`musli::packed`].
    ///
    /// This is the compact representation and the default.
    Binary,
    /// Messages are text frames whose envelope is a block of
    /// `<key>: <value>` lines.
    ///
    /// The whole frame is human readable, which is what makes it possible to
    /// read the traffic in a browser inspector or a proxy. Since the body is
    /// part of that frame it has to be human readable too, so this requires a
    /// [`Format`] for which [`Format::is_human_readable`] holds.
    Text,
}

impl Mode {
    /// The default mode, which is [`Mode::Binary`].
    ///
    /// This is used by a client which has not picked a mode, and by a server
    /// for a connection which has not negotiated one.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert_eq!(Mode::DEFAULT, Mode::Binary);
    /// ```
    pub const DEFAULT: Self = Self::Binary;

    /// Every mode a socket can run in.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert!(Mode::ALL.contains(&Mode::Text));
    /// ```
    pub const ALL: &'static [Mode] = &[Mode::Binary, Mode::Text];

    /// The name of the mode.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert_eq!(Mode::Text.name(), "text");
    /// ```
    #[inline]
    pub const fn name(self) -> &'static str {
        match self {
            Mode::Binary => "binary",
            Mode::Text => "text",
        }
    }

    /// Test if the mode uses text frames.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert!(Mode::Text.is_text());
    /// assert!(!Mode::Binary.is_text());
    /// ```
    #[inline]
    pub const fn is_text(self) -> bool {
        matches!(self, Mode::Text)
    }

    /// Test if `format` can be used for message bodies in this mode.
    ///
    /// A text frame has to be valid UTF-8 in its entirety, so a mode which
    /// uses them can only carry bodies which are human readable.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::{Format, Mode};
    ///
    /// assert!(Mode::Binary.accepts(Format::Wire));
    /// assert!(Mode::Text.accepts(Format::Json));
    /// assert!(!Mode::Text.accepts(Format::Wire));
    /// ```
    #[inline]
    pub const fn accepts(self, format: Format) -> bool {
        match self {
            Mode::Binary => true,
            Mode::Text => format.is_human_readable(),
        }
    }

    /// A dense index for the mode, so that it can be kept in an atomic.
    ///
    /// This is not a wire representation, the frame type is what carries the
    /// mode between peers.
    #[inline]
    #[cfg_attr(not(feature = "client"), allow(dead_code))]
    pub(crate) const fn to_index(self) -> u8 {
        match self {
            Mode::Binary => 0,
            Mode::Text => 1,
        }
    }

    /// Recover a mode from [`Mode::to_index`].
    #[inline]
    #[cfg_attr(not(feature = "client"), allow(dead_code))]
    pub(crate) const fn from_index(index: u8) -> Option<Self> {
        match index {
            0 => Some(Mode::Binary),
            1 => Some(Mode::Text),
            _ => None,
        }
    }
}

impl Default for Mode {
    /// Construct the default mode, which is [`Mode::DEFAULT`].
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert_eq!(Mode::default(), Mode::Binary);
    /// ```
    #[inline]
    fn default() -> Self {
        Self::DEFAULT
    }
}

impl fmt::Display for Mode {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// The error returned when parsing a [`Mode`] from a string which is not the
/// [`name`] of any mode.
///
/// [`name`]: Mode::name
///
/// # Examples
///
/// ```
/// use musli_web::api::Mode;
///
/// let error = "both".parse::<Mode>().unwrap_err();
/// assert_eq!(error.to_string(), "unknown mode, expected one of: binary, text");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct ParseModeError;

impl fmt::Display for ParseModeError {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("unknown mode, expected one of: binary, text")
    }
}

impl core::error::Error for ParseModeError {}

impl FromStr for Mode {
    type Err = ParseModeError;

    /// Parse a mode from exactly what its [`Display`] implementation and
    /// [`Mode::name`] produce.
    ///
    /// Matching is case sensitive and does not trim whitespace.
    ///
    /// [`Display`]: fmt::Display
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::Mode;
    ///
    /// assert_eq!("text".parse::<Mode>(), Ok(Mode::Text));
    /// assert!("Text".parse::<Mode>().is_err());
    ///
    /// for mode in Mode::ALL {
    ///     assert_eq!(mode.to_string().parse::<Mode>(), Ok(*mode));
    /// }
    /// ```
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        for &mode in Self::ALL {
            if mode.name() == s {
                return Ok(mode);
            }
        }

        Err(ParseModeError)
    }
}

/// Types which can be encoded in every mode that this crate supports.
///
/// This is a blanket trait covering [`Encode`] in both the [`Binary`] and
/// [`Text`] modes, which is what allows a message body to be encoded with any
/// [`Format`] including [`Format::Json`].
///
/// Deriving [`Encode`] implements every mode, so this is implemented
/// automatically unless the type has been restricted to a specific mode.
pub trait EncodeBody
where
    Self: Encode<Binary> + Encode<Text>,
{
}

impl<T> EncodeBody for T where T: ?Sized + Encode<Binary> + Encode<Text> {}

/// Types which can be decoded in every mode that this crate supports.
///
/// This is a blanket trait covering [`Decode`] in both the [`Binary`] and
/// [`Text`] modes, which is what allows a message body to be decoded with any
/// [`Format`] including [`Format::Json`].
///
/// Deriving [`Decode`] implements every mode, so this is implemented
/// automatically unless the type has been restricted to a specific mode.
pub trait DecodeBody<'de>
where
    Self: Decode<'de, Binary, Global> + Decode<'de, Text, Global>,
{
}

impl<'de, T> DecodeBody<'de> for T where T: Decode<'de, Binary, Global> + Decode<'de, Text, Global> {}

/// A trait for constructing identifiers.
///
/// This is implemented by the `Request` and `Event` enums generated by
/// [`define!`], and by [`ws::Either`] for a [`ws::Or`] handler.
///
/// [`ws::Either`]: <https://docs.rs/musli-web/latest/musli_web/ws/enum.Either.html>
/// [`ws::Or`]: <https://docs.rs/musli-web/latest/musli_web/ws/struct.Or.html>
pub trait Id
where
    Self: 'static + Send + Sized + fmt::Debug,
{
    /// The message ids this type knows.
    ///
    /// For a `Request` enum generated by [`define!`] these are the ids of its
    /// endpoints, and for an `Event` enum those of its broadcasts, in both
    /// cases along with those of every list it [includes]. An id outside of
    /// this set is what [`Id::from_id`] constructs an unknown identifier for.
    ///
    /// [includes]: define#including-other-lists
    ///
    /// # Examples
    ///
    /// ```
    /// use musli::{Decode, Encode};
    /// use musli_web::api::{self, Id};
    ///
    /// #[derive(Encode, Decode)]
    /// pub struct HelloRequest;
    ///
    /// #[derive(Encode, Decode)]
    /// pub struct TickEvent;
    ///
    /// api::define! {
    ///     pub type Hello;
    ///
    ///     impl Endpoint for Hello {
    ///         impl Request for HelloRequest;
    ///         type Response<'de> = ();
    ///     }
    ///
    ///     pub type Tick;
    ///
    ///     impl Broadcast for Tick {
    ///         impl Event for TickEvent;
    ///     }
    /// }
    ///
    /// assert!(Request::IDS.contains(Hello::ID));
    /// assert!(!Request::IDS.contains(Tick::ID));
    /// assert!(Event::IDS.contains(Tick::ID));
    /// ```
    const IDS: IdSet;

    /// Get the raw message identifier for this type.
    fn id(&self) -> MessageId;

    /// Construct an identifier from a raw message identifier.
    ///
    /// An id which is not in [`Id::IDS`] constructs an unknown identifier,
    /// such as the `Unknown` variant of a `Request` enum generated by
    /// [`define!`].
    fn from_id(id: MessageId) -> Self;

    /// Construct an identifier from a raw message identifier, or `None` if
    /// the id is not in [`Id::IDS`].
    ///
    /// # Examples
    ///
    /// ```
    /// use musli::{Decode, Encode};
    /// use musli_web::api::{self, Id, MessageId};
    ///
    /// #[derive(Encode, Decode)]
    /// pub struct HelloRequest;
    ///
    /// api::define! {
    ///     pub type Hello;
    ///
    ///     impl Endpoint for Hello {
    ///         impl Request for HelloRequest;
    ///         type Response<'de> = ();
    ///     }
    /// }
    ///
    /// assert_eq!(Request::try_from_id(Hello::ID), Some(Request::Hello));
    ///
    /// let unknown = MessageId::new(1000).unwrap();
    /// assert_eq!(Request::try_from_id(unknown), None);
    /// assert_eq!(Request::from_id(unknown), Request::Unknown(unknown));
    /// ```
    fn try_from_id(id: MessageId) -> Option<Self>;

    #[doc(hidden)]
    fn __do_not_implement_id();
}

/// A set of message ids, such as the ids an [`Id`] type knows, see
/// [`Id::IDS`].
///
/// A set is built at compile time out of the ids of one [`define!`] list and
/// the sets of the lists it includes, so it is cheap to construct but looking
/// an id up in it is a linear scan. It is used to check, at compile time, that
/// two lists which share a connection never use the same id.
///
/// # Examples
///
/// Checking in a test (or a `const` item) that two lists which are never
/// included into one another, but are carried on the same connection, do not
/// share an id:
///
/// ```
/// use musli::{Decode, Encode};
/// use musli_web::api::Id;
///
/// mod app {
///     # use musli::{Decode, Encode};
///     # use musli_web::api;
///     #[derive(Encode, Decode)]
///     pub struct HelloRequest;
///
///     api::define! {
///         pub type Hello;
///
///         impl Endpoint for Hello {
///             impl Request for HelloRequest;
///             type Response<'de> = ();
///         }
///     }
/// }
///
/// mod lib {
///     # use musli::{Decode, Encode};
///     # use musli_web::api;
///     #[derive(Encode, Decode)]
///     pub struct LoginRequest;
///
///     api::define! {
///         #[musli(id = 32000)]
///         pub type Login;
///
///         impl Endpoint for Login {
///             impl Request for LoginRequest;
///             type Response<'de> = ();
///         }
///     }
/// }
///
/// const _: () = assert!(app::Request::IDS.is_disjoint(&lib::Request::IDS));
/// assert_eq!(app::Request::IDS.first_shared(&lib::Request::IDS), None);
/// ```
#[derive(Clone, Copy)]
pub struct IdSet {
    #[doc(hidden)]
    pub __ids: &'static [MessageId],
    #[doc(hidden)]
    pub __includes: &'static [&'static IdSet],
}

impl IdSet {
    /// The empty set.
    pub const EMPTY: Self = Self {
        __ids: &[],
        __includes: &[],
    };

    /// Test if the set contains `id`.
    pub const fn contains(&self, id: MessageId) -> bool {
        let mut n = 0;

        while n < self.__ids.len() {
            if self.__ids[n].get() == id.get() {
                return true;
            }

            n += 1;
        }

        let mut n = 0;

        while n < self.__includes.len() {
            if self.__includes[n].contains(id) {
                return true;
            }

            n += 1;
        }

        false
    }

    /// Test if the set has no id in common with `other`.
    #[inline]
    pub const fn is_disjoint(&self, other: &IdSet) -> bool {
        self.first_shared(other).is_none()
    }

    /// Find the first id in this set which is also in `other`, if any.
    pub const fn first_shared(&self, other: &IdSet) -> Option<MessageId> {
        let mut n = 0;

        while n < self.__ids.len() {
            let id = self.__ids[n];

            if other.contains(id) {
                return Some(id);
            }

            n += 1;
        }

        let mut n = 0;

        while n < self.__includes.len() {
            if let Some(id) = self.__includes[n].first_shared(other) {
                return Some(id);
            }

            n += 1;
        }

        None
    }

    /// Test if the set is empty.
    pub const fn is_empty(&self) -> bool {
        if !self.__ids.is_empty() {
            return false;
        }

        let mut n = 0;

        while n < self.__includes.len() {
            if !self.__includes[n].is_empty() {
                return false;
            }

            n += 1;
        }

        true
    }
}

impl fmt::Debug for IdSet {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fn entries(set: &IdSet, list: &mut fmt::DebugSet<'_, '_>) {
            list.entries(set.__ids.iter().map(MessageId::get));

            for include in set.__includes {
                entries(include, list);
            }
        }

        let mut list = f.debug_set();
        entries(self, &mut list);
        list.finish()
    }
}

/// A unique and opaque identifier for a channel over the websocket.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Encode, Decode)]
#[musli(transparent)]
pub struct ChannelId {
    repr: u16,
}

impl ChannelId {
    /// The channel id used for an invalid channel.
    pub const NONE: Self = Self::from_u16(0);

    /// Construct a new channel id from a raw `u16` representation.
    ///
    /// Note that this does not guarantee that the internal representation of a
    /// channel identifier is exactly a `u16`, only that at least `u16` unique
    /// identifiers can be constructed.
    ///
    /// Using `0` is equivalent to [`ChannelId::NONE`]. When implementing a
    /// custom [`ChannelAllocator`] the allocator must avoid constructor
    /// identifiers with this value since it is equivalent to no channel.
    ///
    /// [`ChannelAllocator`]: crate::ws::ChannelAllocator
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::ChannelId;
    /// let id = ChannelId::from_u16(0);
    /// assert_eq!(id, ChannelId::NONE);
    /// ```
    #[inline]
    pub const fn from_u16(repr: u16) -> Self {
        Self { repr }
    }

    /// Get the raw channel identifier.
    #[inline]
    #[cfg_attr(
        not(any(feature = "ws", feature = "client", feature = "web03")),
        allow(dead_code)
    )]
    pub(crate) const fn raw(&self) -> u16 {
        self.repr
    }
}

impl fmt::Debug for ChannelId {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.repr == 0 {
            f.write_str("NONE")
        } else {
            write!(f, "{:04x}", self.repr)
        }
    }
}

/// A [`ChannelId`] which can be shared and updated atomically.
///
/// This behaves like an atomic variable holding a [`ChannelId`], where the
/// value can be read, set, replaced, or taken. Each operation takes an
/// [`Ordering`] which is passed through to the underlying atomic.
///
/// [`Ordering`]: core::sync::atomic::Ordering
///
/// # Examples
///
/// ```
/// use core::sync::atomic::Ordering;
///
/// use musli_web::api::{AtomicChannelId, ChannelId};
///
/// let channel = AtomicChannelId::NONE;
/// assert_eq!(channel.load(Ordering::Acquire), ChannelId::NONE);
///
/// channel.store(ChannelId::from_u16(42), Ordering::Release);
/// assert_eq!(channel.load(Ordering::Acquire), ChannelId::from_u16(42));
///
/// assert_eq!(channel.take(Ordering::AcqRel), ChannelId::from_u16(42));
/// assert_eq!(channel.load(Ordering::Acquire), ChannelId::NONE);
/// ```
#[repr(transparent)]
pub struct AtomicChannelId {
    repr: AtomicU16,
}

impl AtomicChannelId {
    /// An atomic channel id which contains [`ChannelId::NONE`].
    ///
    /// Since this is a constant every use of it constructs a new value, to
    /// share one it has to be bound to a `static` or a variable.
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::NONE;
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::NONE);
    /// ```
    #[allow(clippy::declare_interior_mutable_const)]
    pub const NONE: Self = Self::new(ChannelId::NONE);

    /// Construct a new atomic channel id containing `id`.
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::new(ChannelId::from_u16(1));
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::from_u16(1));
    /// ```
    #[inline]
    pub const fn new(id: ChannelId) -> Self {
        Self {
            repr: AtomicU16::new(id.repr),
        }
    }

    /// Read the current channel id.
    ///
    /// `ordering` describes the memory ordering of this operation. Possible
    /// values are [`SeqCst`], [`Acquire`] and [`Relaxed`].
    ///
    /// [`SeqCst`]: Ordering::SeqCst
    /// [`Acquire`]: Ordering::Acquire
    /// [`Relaxed`]: Ordering::Relaxed
    ///
    /// # Panics
    ///
    /// Panics if `ordering` is [`Release`] or [`AcqRel`].
    ///
    /// [`Release`]: Ordering::Release
    /// [`AcqRel`]: Ordering::AcqRel
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::new(ChannelId::from_u16(1));
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::from_u16(1));
    /// ```
    #[inline]
    pub fn load(&self, ordering: Ordering) -> ChannelId {
        ChannelId::from_u16(self.repr.load(ordering))
    }

    /// Set the current channel id to `id`, discarding the old value.
    ///
    /// `ordering` describes the memory ordering of this operation. Possible
    /// values are [`SeqCst`], [`Release`] and [`Relaxed`].
    ///
    /// [`SeqCst`]: Ordering::SeqCst
    /// [`Release`]: Ordering::Release
    /// [`Relaxed`]: Ordering::Relaxed
    ///
    /// # Panics
    ///
    /// Panics if `ordering` is [`Acquire`] or [`AcqRel`].
    ///
    /// [`Acquire`]: Ordering::Acquire
    /// [`AcqRel`]: Ordering::AcqRel
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::NONE;
    /// channel.store(ChannelId::from_u16(1), Ordering::Release);
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::from_u16(1));
    /// ```
    #[inline]
    pub fn store(&self, id: ChannelId, ordering: Ordering) {
        self.repr.store(id.repr, ordering);
    }

    /// Replace the current channel id with `id`, returning the old value.
    ///
    /// `ordering` describes the memory ordering of this operation. All
    /// orderings are possible. Note that using [`Acquire`] makes the store part
    /// of this operation [`Relaxed`], and using [`Release`] makes the load part
    /// [`Relaxed`].
    ///
    /// [`Acquire`]: Ordering::Acquire
    /// [`Release`]: Ordering::Release
    /// [`Relaxed`]: Ordering::Relaxed
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::new(ChannelId::from_u16(1));
    ///
    /// let old = channel.replace(ChannelId::from_u16(2), Ordering::AcqRel);
    /// assert_eq!(old, ChannelId::from_u16(1));
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::from_u16(2));
    /// ```
    #[inline]
    pub fn replace(&self, id: ChannelId, ordering: Ordering) -> ChannelId {
        ChannelId::from_u16(self.repr.swap(id.repr, ordering))
    }

    /// Take the current channel id, leaving [`ChannelId::NONE`] in its place.
    ///
    /// `ordering` describes the memory ordering of this operation. All
    /// orderings are possible, see [`replace`] for details.
    ///
    /// [`replace`]: AtomicChannelId::replace
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::new(ChannelId::from_u16(1));
    ///
    /// assert_eq!(channel.take(Ordering::AcqRel), ChannelId::from_u16(1));
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::NONE);
    /// assert_eq!(channel.take(Ordering::AcqRel), ChannelId::NONE);
    /// ```
    #[inline]
    pub fn take(&self, ordering: Ordering) -> ChannelId {
        self.replace(ChannelId::NONE, ordering)
    }

    /// Consume the atomic channel id, returning the contained value.
    ///
    /// Since this takes ownership no synchronization is needed.
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::new(ChannelId::from_u16(1));
    /// assert_eq!(channel.into_inner(), ChannelId::from_u16(1));
    /// ```
    #[inline]
    pub fn into_inner(self) -> ChannelId {
        ChannelId::from_u16(self.repr.into_inner())
    }
}

impl Default for AtomicChannelId {
    /// Construct an atomic channel id containing [`ChannelId::NONE`].
    ///
    /// # Examples
    ///
    /// ```
    /// use core::sync::atomic::Ordering;
    ///
    /// use musli_web::api::{AtomicChannelId, ChannelId};
    ///
    /// let channel = AtomicChannelId::default();
    /// assert_eq!(channel.load(Ordering::Acquire), ChannelId::NONE);
    /// ```
    #[inline]
    fn default() -> Self {
        Self::NONE
    }
}

impl From<ChannelId> for AtomicChannelId {
    #[inline]
    fn from(id: ChannelId) -> Self {
        Self::new(id)
    }
}

impl fmt::Debug for AtomicChannelId {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.load(Ordering::Relaxed).fmt(f)
    }
}

/// A raw identifier for a message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Encode, Decode)]
#[repr(transparent)]
#[musli(transparent)]
pub struct MessageId(NonZeroU16);

impl fmt::Display for MessageId {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl MessageId {
    /// The error id of a response whose body is an [`ErrorMessage`].
    ///
    /// See [error responses](crate::api#error-responses).
    pub const ERROR_MESSAGE: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 1) };

    /// A connect of a channel.
    pub const CONNECT: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 2) };

    /// A clean disconnect of a channel.
    pub const DISCONNECT: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 3) };

    /// The first message the server sends to indicat that a connection is open.
    pub const SERVER_HELLO: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 4) };

    /// A request from the client to use a particular [`Format`] for the
    /// remainder of the connection.
    ///
    /// See the [negotiation protocol] for how this is used.
    pub const NEGOTIATE: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 5) };

    /// The error id of a response whose body is an [`ErrorMessage`] followed by
    /// a typed payload.
    ///
    /// See [error responses](crate::api#error-responses).
    pub const TYPED_ERROR_MESSAGE: Self = unsafe { Self::new_unchecked((i16::MAX as u16) + 6) };

    /// The message id for an empty packet constructed using [`Packet::empty`]
    /// or [`RawPacket::empty`].
    ///
    /// [`Packet::empty`]: crate::web::Packet::empty
    /// [`RawPacket::empty`]: crate::web::RawPacket::empty
    ///
    /// # Examples
    ///
    /// ```
    /// use musli_web::api::MessageId;
    /// use musli_web::web::{RawPacket, Packet};
    ///
    /// let packet = RawPacket::empty();
    /// assert_eq!(packet.id(), MessageId::EMPTY);
    ///
    /// let packet = Packet::<()>::empty();
    /// assert_eq!(packet.id(), MessageId::EMPTY);
    /// ```
    pub const EMPTY: Self = unsafe { Self::new_unchecked(u16::MAX) };

    /// Construct a raw message id.
    #[inline]
    pub const fn new(id: u16) -> Option<Self> {
        let Some(value) = NonZeroU16::new(id) else {
            return None;
        };

        Some(Self(value))
    }

    /// Get a raw message identifier.
    #[inline]
    pub const fn get(&self) -> u16 {
        self.0.get()
    }

    /// Construct a new message ID.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the provided `id` is non-zero.
    #[inline]
    pub const unsafe fn new_unchecked(id: u16) -> Self {
        Self(unsafe { NonZeroU16::new_unchecked(id) })
    }
}

/// A trait implemented for types which can be decoded into something.
///
/// Do not implement manually, instead use the [`define!`] macro.
pub trait Decodable {
    /// The decodable type related to this.
    type Type<'de>: DecodeBody<'de>;

    #[doc(hidden)]
    fn __do_not_implement_decodable();
}

/// An endpoint marker trait.
///
/// Do not implement manually, instead use the [`define!`] macro.
pub trait Endpoint
where
    Self: 'static,
    for<'de> Self: Decodable<Type<'de> = Self::Response<'de>>,
{
    /// The kind of the endpoint.
    const ID: MessageId;

    /// The primary response type related to the endpoint.
    type Response<'de>: DecodeBody<'de>;

    #[doc(hidden)]
    fn __do_not_implement_endpoint();
}

/// The marker trait used for broadcasts.
///
/// Do not implement manually, instead use the [`define!`] macro.
pub trait Broadcast
where
    Self: 'static,
{
    /// The kind of the broadcast.
    const ID: MessageId;

    #[doc(hidden)]
    fn __do_not_implement_broadcast();
}

/// Trait implemented for broadcasts which have a primary event.
pub trait BroadcastWithEvent
where
    Self: Broadcast,
    for<'de> Self: Decodable<Type<'de> = Self::Event<'de>>,
{
    /// The event type related to the broadcast.
    type Event<'de>: Event<Broadcast = Self> + DecodeBody<'de>
    where
        Self: 'de;

    #[doc(hidden)]
    fn __do_not_implement_broadcast_with_event();
}

/// A marker indicating a request type.
///
/// Do not implement manually, instead use the [`define!`] macro.
pub trait Request
where
    Self: EncodeBody,
{
    /// The endpoint related to the request.
    type Endpoint: Endpoint;

    #[doc(hidden)]
    fn __do_not_implement_request();
}

/// The event of a broadcast.
///
/// Do not implement manually, instead use the [`define!`] macro.
pub trait Event
where
    Self: EncodeBody,
{
    /// The endpoint related to the broadcast.
    type Broadcast: Broadcast;

    #[doc(hidden)]
    fn __do_not_implement_event();
}

/// A request to connect.
#[derive(Debug, Clone, Copy, Encode, Decode)]
#[doc(hidden)]
#[musli(packed)]
pub struct Connect;

/// The header of a response.
///
/// This is the envelope of every message the server sends, see the [wire
/// format].
///
/// [wire format]: crate::api#wire-format
#[derive(Debug, Clone)]
#[doc(hidden)]
pub struct ResponseHeader {
    /// The version of the protocol this envelope was written against, which is
    /// always [`VERSION`].
    pub version: u32,
    /// The serial request this is a response to.
    pub serial: u32,
    /// This is a broadcast over the specified type. If this is non-empty the
    /// serial is 0.
    pub broadcast: u16,
    /// If non-zero, the response is an error and this says what its body
    /// carries, see [error responses](crate::api#error-responses).
    pub error: u16,
    /// The [`Format`] the body of this response is encoded with, as given by
    /// [`Format::to_u8`]. Zero if the response carries no body.
    pub format: u8,
    /// The channel over which the response will be sent.
    pub channel: ChannelId,
    /// The application version the server states, see [application
    /// versions]. Only [`MessageId::SERVER_HELLO`] carries it, and zero means
    /// that none is stated.
    ///
    /// [application versions]: crate::api#application-versions
    pub app: u32,
}

/// The body of an error response.
///
/// When the response carries [`MessageId::TYPED_ERROR_MESSAGE`] the typed
/// payload follows it in the same body, see [error
/// responses](crate::api#error-responses).
#[derive(Debug, Clone, Encode, Decode)]
#[doc(hidden)]
#[musli(packed)]
pub struct ErrorMessage<'de> {
    /// The error message.
    pub message: &'de str,
}

/// A request header.
///
/// This is the envelope of every message the client sends, see the [wire
/// format].
///
/// [wire format]: crate::api#wire-format
#[derive(Debug, Clone, Copy)]
#[doc(hidden)]
pub struct RequestHeader {
    /// The version of the protocol this envelope was written against, which is
    /// always [`VERSION`].
    pub version: u32,
    /// The serial of the request.
    pub serial: u32,
    /// The kind of the request.
    pub id: u16,
    /// The [`Format`] the body of this request is encoded with, as given by
    /// [`Format::to_u8`]. Zero if the request carries no body.
    pub format: u8,
    /// The channel over which the request was received.
    pub channel: ChannelId,
    /// The application version the client states, see [application
    /// versions]. Only [`MessageId::NEGOTIATE`] carries it, and zero means
    /// that none is stated.
    ///
    /// [application versions]: crate::api#application-versions
    pub app: u32,
}

#[cfg(test)]
mod from_str_tests {
    use crate::std::string::ToString;

    use super::{Format, Mode, ParseFormatError, ParseModeError};

    #[test]
    fn format_round_trips() {
        for &format in Format::ALL {
            assert_eq!(format.name().parse::<Format>(), Ok(format));
            assert_eq!(format.to_string().parse::<Format>(), Ok(format));
        }
    }

    #[test]
    fn mode_round_trips() {
        for &mode in Mode::ALL {
            assert_eq!(mode.name().parse::<Mode>(), Ok(mode));
            assert_eq!(mode.to_string().parse::<Mode>(), Ok(mode));
        }
    }

    #[test]
    fn format_rejects() {
        for s in [
            "", " wire", "wire ", "Wire", "WIRE", "json\n", "binary", "w", "wire\0",
        ] {
            assert_eq!(s.parse::<Format>(), Err(ParseFormatError), "{s:?}");
        }
    }

    #[test]
    fn mode_rejects() {
        for s in [
            "", " text", "text ", "Text", "BINARY", "wire", "bin", "text\0",
        ] {
            assert_eq!(s.parse::<Mode>(), Err(ParseModeError), "{s:?}");
        }
    }
}