fastly 0.13.1

//! Backend server.
mod builder;

#[cfg(target_env = "p1")]
use crate::abi::{self, FastlyStatus};
pub use builder::*;
use fastly_shared::SslVersion;
#[cfg(not(target_env = "p1"))]
use fastly_sys::service0_1_0::fastly::compute as wit;
use http::HeaderValue;
use std::{str::FromStr, time::Duration};

/// The maximum length in characters of a backend name.
pub(crate) const MAX_BACKEND_NAME_LEN: usize = 255;

/// A named backend.
///
/// This represents a backend associated with a service that we can send requests to, potentially
/// caching the responses received.
///
/// Backends come in one of two flavors:
///   * **Static Backends**: These backends are created using the Fastly UI or API,
///     and are predefined by the user. Static backends have short names (see the
///     precise naming rules in [`Backend::from_name`]) that are usable across every
///     session of a service.
///   * **Dynamic Backends**: These backends are created programmatically using the
///     [`Backend::builder`] API. They are defined at runtime, and may or may not be
///     shared across sessions depending on how they are configured.
///
/// To use a backend, pass it to the [`crate::Request::send`] method. Alternatively, the following
/// values can be automatically coerced into a backend for you, without the need to explicitly
/// create a `Backend` object, although they may all induce panics:
///
///   * Any string type ([`&str`][`str`], [`String`, or `&String`][`String`]) will
///     be automatically turned into the static backend of the same name.
///
/// ## Using Static Backends
///
/// As stated at the top level, the following snippet is a minimal program that resends
/// a request to a static backend named "example_backend":
///
/// ```no_run
/// use fastly::{Error, Request, Response};
///
/// #[fastly::main]
/// fn main(ds_req: Request) -> Result<Response, Error> {
///     Ok(ds_req.send("example_backend")?)
/// }
/// ```
///
/// A safer alternative to this example would be the following:
///
/// ```no_run
/// use fastly::{Backend, Error, Request, Response};
///
/// #[fastly::main]
/// fn main(ds_req: Request) -> Result<Response, Error> {
///     match Backend::from_name("example_backend") {
///        Ok(backend) => Ok(ds_req.send(backend)?),
///        Err(_) => {
///             // custom backend failure response
///             unimplemented!()
///        }
///     }
/// }
/// ```
///
/// as this version allows you to handle backend errors more cleanly.
///
/// ## Validating Support for Dynamic Backends
///
/// Since dynamic backends are only enabled for some services, it may be particularly
/// useful to ensure that dynamic backends are supported in your Compute service.
/// The easiest way to do so is to try to create a dynamic backend, and then explicitly
/// check for the [`crate::backend::BackendCreationError::Disallowed`] code, as follows:
///
/// ```no_run
/// use fastly::{Backend, Error, Request, Response};
/// use fastly::backend::BackendCreationError;
///
/// #[fastly::main]
/// fn main(ds_req: Request) -> Result<Response, Error> {
///     match Backend::builder("custom_backend", "example.org:993").finish() {
///         Ok(backend) => Ok(ds_req.send(backend)?),
///         Err(BackendCreationError::Disallowed) => {
///            // custom code ofr handling when dynamic backends aren't supported
///            unimplemented!()
///         }
///         Err(err) => {
///            // more specific logging/handling for backend misconfigurations
///            unimplemented!()
///         }
///     }
/// }
/// ```
///
///
///
#[derive(Debug)]
#[cfg_attr(target_env = "p1", derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd))]
pub struct Backend {
    name: String,
    #[cfg(not(target_env = "p1"))]
    handle: wit::backend::Backend,
}

impl Backend {
    /// Get a backend by its name.
    ///
    /// This function will return a [`BackendError`] if an invalid name was given.
    ///
    /// Backend names:
    ///   * cannot be empty
    ///   * cannot be longer than 255 characters
    ///   * cannot ASCII control characters such as `'\n'` or `DELETE`.
    ///   * cannot contain special Unicode characters
    ///   * should only contain visible ASCII characters or spaces
    ///
    /// Future versions of this function may return an error if your service does not have a backend
    /// with this name.
    pub fn from_name(s: &str) -> Result<Self, BackendError> {
        s.parse()
    }

    #[doc = include_str!("../docs/snippets/dynamic-backend-builder.md")]
    pub fn builder(name: impl ToString, target: impl ToString) -> BackendBuilder {
        BackendBuilder::new(name.to_string(), target.to_string())
    }

    /// Get the name of this backend.
    pub fn name(&self) -> &str {
        self.name.as_str()
    }

    /// Turn the backend into its name as a string.
    pub fn into_string(self) -> String {
        self.name
    }

    /// Return the low-level backend handle.
    #[cfg(not(target_env = "p1"))]
    pub fn as_handle(&self) -> &wit::backend::Backend {
        &self.handle
    }

    /// Construct a `Backend` from a low-level backend handle.
    #[cfg(not(target_env = "p1"))]
    pub fn from_handle(handle: wit::backend::Backend) -> Self {
        Self {
            name: handle.get_name(),
            handle,
        }
    }

    /// Returns true if a backend with this name exists.
    pub fn exists(&self) -> bool {
        #[cfg(target_env = "p1")]
        {
            let mut exists = 0;
            unsafe { abi::fastly_backend::exists(self.name.as_ptr(), self.name.len(), &mut exists) }
                .result()
                .map(|_| exists == 1)
                .expect("fastly_backend::exists failed")
        }

        #[cfg(not(target_env = "p1"))]
        {
            // We tested for existence in `FromStr::from_str`.
            true
        }
    }

    /// Returns true if this is a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn is_dynamic(&self) -> bool {
        #[cfg(target_env = "p1")]
        {
            let mut is = 0;
            unsafe { abi::fastly_backend::is_dynamic(self.name.as_ptr(), self.name.len(), &mut is) }
                .result()
                .map(|_| is == 1)
                .expect("fastly_backend::is_dynamic failed")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle
                .is_dynamic()
                .expect("fastly:compute/backend.[method]backend.is-dynamic failed")
        }
    }

    /// Returns the hostname for this backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_host(&self) -> String {
        #[cfg(target_env = "p1")]
        {
            // First, ask the host how long our buffer will need to be. Provide a null pointer, with
            // a maximum length of 0. We should get back a `BUFLEN` code, with `nwritten` set to the
            // length of the host.
            let mut nwritten = 0;
            let length = match unsafe {
                abi::fastly_backend::get_host(
                    self.name.as_ptr(),
                    self.name.len(),
                    std::ptr::null_mut(),
                    0,
                    &mut nwritten,
                )
            } {
                FastlyStatus::BUFLEN => nwritten,
                status => {
                    panic!("fastly_backend::get_host returned an unexpected result: {status:?}")
                }
            };

            // Now, call once more with a sufficiently long buffer.
            let mut buf = Vec::with_capacity(length);
            unsafe {
                abi::fastly_backend::get_host(
                    self.name.as_ptr(),
                    self.name.len(),
                    buf.as_mut_ptr(),
                    buf.capacity(),
                    &mut nwritten,
                )
            }
            .result()
            .expect("fastly_backend::get_host returned an unexpected result");

            assert!(
                nwritten <= buf.capacity(),
                "fastly_backend::get_host wrote too many bytes"
            );
            unsafe {
                // Safety:
                // - We assert above that `nwritten` is less than or equal to `capacity`.
                // - We assume that the host did write to `old_len..new_len`.
                buf.set_len(nwritten);
            }

            String::from_utf8(buf).expect("fastly_backend::get_host returns valid UTF-8 bytes")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.get_host(u64::MAX).expect(
                "fastly:compute/backend.[method]backend.get-host returned an unexpected result",
            )
        }
    }

    /// Returns the host header override when contacting this backend.
    ///
    /// This method returns `None` if no host header override is configured for this backend.
    ///
    /// This is used to change the `Host` header sent to the backend. For more information, see
    /// the Fastly documentation on host overrides here:
    /// <https://docs.fastly.com/en/guides/specifying-an-override-host>
    ///
    /// Use
    /// [`BackendBuilder::override_host`][self::builder::BackendBuilder::override_host]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_host_override(&self) -> Option<HeaderValue> {
        #[cfg(target_env = "p1")]
        {
            // First, ask the host how long our buffer will need to be. Provide a null pointer, with
            // a maximum length of 0. We should get back a `BUFLEN` code, with `nwritten` set to the
            // length of the host.
            let mut nwritten = 0;
            let length = match unsafe {
                abi::fastly_backend::get_override_host(
                    self.name.as_ptr(),
                    self.name.len(),
                    std::ptr::null_mut(),
                    0,
                    &mut nwritten,
                )
            } {
                // If a `NONE` code is returned, there is no host override. We are finished!
                FastlyStatus::NONE => return None,
                FastlyStatus::BUFLEN => nwritten,
                status => panic!(
                    "fastly_backend::get_override_host returned an unexpected result: {status:?}"
                ),
            };
            // Now, call once more with a sufficiently long buffer.
            let mut buf = Vec::with_capacity(length);
            unsafe {
                abi::fastly_backend::get_override_host(
                    self.name.as_ptr(),
                    self.name.len(),
                    buf.as_mut_ptr(),
                    buf.capacity(),
                    &mut nwritten,
                )
            }
            .result()
            .expect("fastly_backend::get_override_host returned an unexpected result");

            assert!(
                nwritten <= buf.capacity(),
                "fastly_backend::get_override_host wrote too many bytes"
            );
            unsafe {
                // Safety:
                // - We assert above that `nwritten` is less than or equal to `capacity`.
                // - We assume that the host did write to `old_len..new_len`.
                buf.set_len(nwritten);
            }

            Some(
                HeaderValue::try_from(buf)
                    .expect("fastly_backend::get_override_host returns valid header value bytes"),
            )
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.get_override_host(u64::MAX)
                .expect("fastly:compute/backend.[method]backend.get-override-host returned an unexpected result")
                .map(|override_host| HeaderValue::try_from(override_host)
                .expect("fastly:compute/backend.[method]backend.get-override-host returns valid header value bytes"))
        }
    }

    /// Get the port number of the backend's address.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_port(&self) -> u16 {
        #[cfg(target_env = "p1")]
        {
            let mut port = 0;
            unsafe { abi::fastly_backend::get_port(self.name.as_ptr(), self.name.len(), &mut port) }
                .result()
                .map(|_| port)
                .expect("fastly_backend::get_port returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.get_port().expect(
                "fastly:compute/backend.[method]backend.get-port returned an unexpected result",
            )
        }
    }

    /// Returns the connection timeout for this backend.
    ///
    /// Use
    /// [`BackendBuilder::connect_timeout`][self::builder::BackendBuilder::connect_timeout]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_connect_timeout(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_connect_timeout_ms(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_millis)
            .expect("fastly_backend::get_connect_timeout_ms returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_millis(u64::from(self.handle.get_connect_timeout_ms()
                .expect("fastly:compute/backend.[method]backend.get-connect-timeout-ms returned an unexpected result")))
        }
    }

    /// Returns the "first byte" timeout for this backend.
    ///
    /// This timeout applies between the time of connection and the time we get the first byte back.
    ///
    /// Use
    /// [`BackendBuilder::first_byte_timeout`][self::builder::BackendBuilder::first_byte_timeout]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_first_byte_timeout(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_first_byte_timeout_ms(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_millis)
            .expect("fastly_backend::get_first_byte_timeout returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_millis(u64::from(self.handle.get_first_byte_timeout_ms()
                .expect("fastly:compute/backend.[method]backend.get-first-byte-timeout-ms returned an unexpected result")))
        }
    }

    /// Returns the "between bytes" timeout for this backend.
    ///
    /// This timeout applies between any two bytes we receive across the wire.
    ///
    /// Use
    /// [`BackendBuilder::between_bytes_timeout`][self::builder::BackendBuilder::between_bytes_timeout]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_between_bytes_timeout(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_between_bytes_timeout_ms(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_millis)
            .expect("fastly_backend::get_between_bytes_timeout returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_millis(u64::from(self.handle.get_between_bytes_timeout_ms()
                .expect("fastly:compute/backend.[method]backend.get-between-bytes-timeout-ms returned an unexpected result")))
        }
    }

    /// Returns the time to hold onto an idle HTTP keepalive connection after it was last used
    /// before closing it.
    ///
    /// Use
    /// [`BackendBuilder::http_keepalive_time`][self::builder::BackendBuilder::http_keepalive_time]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_http_keepalive_time(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_http_keepalive_time(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_millis)
            .expect("fastly_backend::get_http_keepalive_time returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_millis(u64::from(self.handle.get_tcp_keepalive_time()
                .expect("fastly:compute/backend.[method]backend.get-tcp-keepalive-time returned an unexpected result")))
        }
    }

    /// Returns `true` if TCP keepalives have been enabled for this backend.
    ///
    /// Use
    /// [`BackendBuilder::tcp_keepalive_enable`][self::builder::BackendBuilder::tcp_keepalive_enable]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_tcp_keepalive_enable(&self) -> bool {
        #[cfg(target_env = "p1")]
        {
            let mut enabled = 0;
            unsafe {
                abi::fastly_backend::get_tcp_keepalive_enable(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut enabled,
                )
            }
            .result()
            .map(|_| enabled != 0)
            .expect("fastly_backend::get_tcp_keepalive_enable returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.get_tcp_keepalive_enable()
                .expect("fastly:compute/backend.[method]backend.get-tcp-keepalive-enable returned an unexpected result")
        }
    }

    /// Returns the time to wait in between sending each TCP keepalive probe to this backend.
    ///
    /// Use
    /// [`BackendBuilder::tcp_keepalive_interval_secs`][self::builder::BackendBuilder::tcp_keepalive_interval_secs]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_tcp_keepalive_interval(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_tcp_keepalive_interval(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_secs)
            .expect("fastly_backend::get_tcp_keepalive_interval returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_secs(u64::from(self.handle.get_tcp_keepalive_interval()
                .expect("fastly:compute/backend.[method]backend.get-tcp-keepalive-internal returned an unexpected result")))
        }
    }

    /// Returns the time to wait after the last data was sent before starting to send TCP keepalive
    /// probes to this backend.
    ///
    /// Use
    /// [`BackendBuilder::tcp_keepalive_probes`][self::builder::BackendBuilder::tcp_keepalive_probes]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_tcp_keepalive_probes(&self) -> u32 {
        #[cfg(target_env = "p1")]
        {
            let mut count = 0;
            unsafe {
                abi::fastly_backend::get_tcp_keepalive_probes(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut count,
                )
            }
            .result()
            .map(|_| count)
            .expect("fastly_backend::get_tcp_keepalive_probes returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.get_tcp_keepalive_probes()
                .expect("fastly:compute/backend.[method]backend.get-tcp-keepalive-probes returned an unexpected result")
        }
    }

    /// Returns the time to wait after the last data was sent before starting to send TCP keepalive
    /// probes to this backend.
    ///
    /// Use
    /// [`BackendBuilder::tcp_keepalive_time_secs`][self::builder::BackendBuilder::tcp_keepalive_time_secs]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_tcp_keepalive_time(&self) -> Duration {
        #[cfg(target_env = "p1")]
        {
            let mut timeout = 0;
            unsafe {
                abi::fastly_backend::get_tcp_keepalive_time(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut timeout,
                )
            }
            .result()
            .map(|_| timeout)
            .map(u64::from)
            .map(Duration::from_secs)
            .expect("fastly_backend::get_tcp_keepalive_time returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            Duration::from_secs(u64::from(self.handle.get_tcp_keepalive_time()
                .expect("fastly:compute/backend.[method]backend.get-tcp-keepalive-time returned an unexpected result")))
        }
    }

    /// Returns `true` if SSL/TLS is used to connect to the backend.
    ///
    /// Use
    /// [`BackendBuilder::enable_ssl`][self::builder::BackendBuilder::enable_ssl] or
    /// [`BackendBuilder::disable_ssl`][self::builder::BackendBuilder::disable_ssl]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn is_ssl(&self) -> bool {
        #[cfg(target_env = "p1")]
        {
            let mut is = 0;
            unsafe { abi::fastly_backend::is_ssl(self.name.as_ptr(), self.name.len(), &mut is) }
                .result()
                .map(|_| is == 1)
                .expect("fastly_backend::is_ssl returned an unexpected result")
        }

        #[cfg(not(target_env = "p1"))]
        {
            self.handle.is_tls().expect(
                "fastly:compute/backend.[method]backend.is-tls returned an unexpected result",
            )
        }
    }

    /// Returns the minimum TLS version for connecting to the backend.
    ///
    /// This method returns `None` if SSL/TLS is not enabled for this backend.
    ///
    /// Use
    /// [`BackendBuilder::set_min_tls_version`][self::builder::BackendBuilder::set_min_tls_version]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_ssl_min_version(&self) -> Option<SslVersion> {
        #[cfg(target_env = "p1")]
        {
            let mut min = 0;
            match unsafe {
                abi::fastly_backend::get_ssl_min_version(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut min,
                )
            }
            .result()
            {
                Ok(_) => Some(min.try_into().unwrap()),
                Err(FastlyStatus::NONE) => None,
                other => {
                    panic!("backend::get_tls_min_version returned an unexpected result: {other:?}")
                }
            }
        }

        #[cfg(not(target_env = "p1"))]
        {
            match self.handle.get_tls_min_version() {
                Ok(Some(0x0301)) => Some(SslVersion::TLS1),
                Ok(Some(0x0302)) => Some(SslVersion::TLS1_1),
                Ok(Some(0x0303)) => Some(SslVersion::TLS1_2),
                Ok(Some(0x0304)) => Some(SslVersion::TLS1_3),
                Ok(None) => None,
            other => panic!(
                    "fastly:compute/backend.[method]backend.get-tls-min-version returned an unexpected result: {other:?}"
                )
            }
        }
    }

    /// Returns the maximum TLS version for connecting to the backend.
    ///
    /// This method returns `None` if SSL/TLS is not enabled for this backend.
    ///
    /// Use
    /// [`BackendBuilder::set_max_tls_version`][self::builder::BackendBuilder::set_max_tls_version]
    /// to set this for a dynamic backend.
    ///
    /// # Panics
    ///
    #[doc = include_str!("../docs/snippets/panics-backend-must-exist.md")]
    pub fn get_ssl_max_version(&self) -> Option<SslVersion> {
        #[cfg(target_env = "p1")]
        {
            let mut max = 0;
            match unsafe {
                abi::fastly_backend::get_ssl_max_version(
                    self.name.as_ptr(),
                    self.name.len(),
                    &mut max,
                )
            }
            .result()
            {
                Ok(_) => Some(max.try_into().unwrap()),
                Err(FastlyStatus::NONE) => None,
                other => panic!(
                    "fastly_backend::get_ssl_max_version returned an unexpected result: {other:?}"
                ),
            }
        }

        #[cfg(not(target_env = "p1"))]
        {
            match self.handle.get_tls_max_version() {
                Ok(Some(0x0301)) => Some(SslVersion::TLS1),
                Ok(Some(0x0302)) => Some(SslVersion::TLS1_1),
                Ok(Some(0x0303)) => Some(SslVersion::TLS1_2),
                Ok(Some(0x0304)) => Some(SslVersion::TLS1_3),
                Ok(None) => None,
                other => panic!(
                    "fastly:compute/backend.[method]backend.get-tls-max-version returned an unexpected result: {other:?}"
                )
            }
        }
    }
}

#[cfg(not(target_env = "p1"))]
impl Clone for Backend {
    fn clone(&self) -> Self {
        Self {
            name: self.name.clone(),
            handle: wit::backend::Backend::open(&self.name).unwrap(),
        }
    }
}

/// [`Backend`]-related errors.
#[derive(Copy, Clone, Debug, thiserror::Error, PartialEq, Eq)]
pub enum BackendError {
    /// The backend name was empty.
    #[error("an empty string is not a valid backend")]
    EmptyName,
    /// The backend name was too long.
    #[error("backend names must be <= 255 characters")]
    TooLong,
    /// The backend name contained invalid characters.
    #[error("backend names must only contain visible ASCII characters or spaces")]
    InvalidName,
}

impl FromStr for Backend {
    type Err = BackendError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        validate_backend(s)?;

        #[cfg(target_env = "p1")]
        {
            Ok(Self { name: s.to_owned() })
        }

        #[cfg(not(target_env = "p1"))]
        {
            let handle = wit::backend::Backend::open(s).map_err(|err| match err {
                wit::types::OpenError::NameTooLong => BackendError::TooLong,
                _ => BackendError::InvalidName,
            })?;
            Ok(Self {
                name: s.to_owned(),
                handle,
            })
        }
    }
}

impl std::fmt::Display for Backend {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.name.as_str())
    }
}

/// Validate that a string looks like an acceptable [`Backend`] value.
///
/// Note that this is *not* meant to be a filter for things that could cause security issues, it is
/// only meant to catch errors before the hostcalls do in order to yield friendlier error messages.
///
/// This function will return a [`BackendError`] if an invalid name was given.
///
/// Backend names:
///   * cannot be empty
///   * cannot be longer than 255 characters
///   * cannot ASCII control characters such as `'\n'` or `DELETE`.
///   * cannot contain special Unicode characters
///   * should only contain visible ASCII characters or spaces
//
// TODO KTM 2020-03-10: We should not allow VCL keywords like `if`, `now`, `true`, `urldecode`, and
// so on. Once we have better errors, let's make sure that these are caught in a pleasant manner.
pub fn validate_backend(backend: &str) -> Result<(), BackendError> {
    if backend.is_empty() {
        Err(BackendError::EmptyName)
    } else if backend.len() > MAX_BACKEND_NAME_LEN {
        Err(BackendError::TooLong)
    } else if backend.chars().any(is_invalid_char) {
        Err(BackendError::InvalidName)
    } else {
        Ok(())
    }
}

/// Return true if a character is not allowed in a [`Backend`] name.
///
/// This is used to enforce the rules described in the documentation of [`Backend::from_name()`]. A
/// backend name should only contain visible ASCII characters, or spaces.
#[inline]
fn is_invalid_char(c: char) -> bool {
    c != ' ' && !c.is_ascii_graphic()
}

#[cfg(test)]
mod validate_backend_tests {
    use super::*;

    #[test]
    fn valid_backend_names_are_accepted() {
        let valid_backend_names = [
            "valid_backend_1",
            "1_backend_with_leading_integer",
            "backend-with-kebab-case",
            "backend with spaces",
            "backend.with.periods",
            "123_456_789_000",
            "123.456.789.000",
            "tilde~backend",
            "(parens-backend)",
        ];
        for backend in valid_backend_names.iter() {
            match validate_backend(backend) {
                Ok(_) => {}
                x => panic!("backend string \"{backend}\" yielded unexpected result: {x:?}",),
            }
        }
    }

    #[test]
    fn empty_str_is_not_accepted() {
        let invalid_backend = "";
        match validate_backend(invalid_backend) {
            Err(BackendError::EmptyName) => {}
            x => panic!("unexpected result: {x:?}"),
        }
    }

    #[test]
    fn name_equal_to_character_limit_is_accepted() {
        use std::iter::FromIterator;
        let invalid_backend: String = String::from_iter(vec!['a'; 255]);
        match validate_backend(&invalid_backend) {
            Ok(_) => {}
            x => panic!("unexpected result: {x:?}"),
        }
    }

    #[test]
    fn name_longer_than_character_limit_are_not_accepted() {
        use std::iter::FromIterator;
        let invalid_backend: String = String::from_iter(vec!['a'; 256]);
        match validate_backend(&invalid_backend) {
            Err(BackendError::TooLong) => {}
            x => panic!("unexpected result: {x:?}"),
        }
    }

    #[test]
    fn unprintable_characters_are_not_accepted() {
        let invalid_backend = "\n";
        match validate_backend(invalid_backend) {
            Err(BackendError::InvalidName) => {}
            x => panic!("unexpected result: {x:?}"),
        }
    }

    #[test]
    fn unicode_is_not_accepted() {
        let invalid_backend = "♓";
        match validate_backend(invalid_backend) {
            Err(BackendError::InvalidName) => {}
            x => panic!("unexpected result: {x:?}"),
        }
    }
}