Struct fastly::backend::Backend

pub struct Backend { /* private fields */ }

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, String, or &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”:

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:

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:

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!()
        }
    }
}

Implementations

impl Backend

pub fn from_name(s: &str) -> Result<Self, BackendError>

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 builder(name: impl ToString, target: impl ToString) -> BackendBuilder

Create a new dynamic backend builder.

The arguments are the name of the new backend to use, along with a string describing the backend host. The latter can be of the form:

• "<ip address>"
• "<hostname>"
• "<ip address>:<port>"
• "<hostname>:<port>"

The name can be whatever you would like, as long as it does not match the name of any of the static service backends nor match any other dynamic backends built during this session. (Names can overlap between different sessions of the same service – they will be treated as completely separate entities and will not be pooled – but you cannot, for example, declare a dynamic backend named “dynamic-backend” twice in the same session.)

The builder will start with default values for all other possible fields for the backend, which can be overridden using the other methods provided. Call finish() to complete the construction of the dynamic backend.

Dynamic backends must be enabled for this Compute service. You can determine whether or not dynamic backends have been allowed for the current service by using this builder, and then checking for the BackendCreationError::Disallowed error result. This error only arises when attempting to use dynamic backends with a service that has not had dynamic backends enabled, or dynamic backends have been administratively prohibited for the node in response to an ongoing incident.

pub fn name(&self) -> &str

Get the name of this backend.

pub fn into_string(self) -> String

Turn the backend into its name as a string.

pub fn exists(&self) -> bool

Returns true if a backend with this name exists.

pub fn is_dynamic(&self) -> bool

Returns true if this is a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_host(&self) -> String

Returns the hostname for this backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_host_override(&self) -> Option<HeaderValue>

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 to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_port(&self) -> u16

Get the port number of the backend’s address.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_connect_timeout(&self) -> Duration

Returns the connection timeout for this backend.

Use BackendBuilder::connect_timeout to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_first_byte_timeout(&self) -> Duration

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 to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_between_bytes_timeout(&self) -> Duration

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 to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn is_ssl(&self) -> bool

Returns true if SSL/TLS is used to connect to the backend.

Use BackendBuilder::enable_ssl or BackendBuilder::disable_ssl to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_ssl_min_version(&self) -> Option<SslVersion>

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 to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

pub fn get_ssl_max_version(&self) -> Option<SslVersion>

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 to set this for a dynamic backend.

Panics

If the name() of this backend does not match any of the backends associated with this service, this function will panic. Use exists() to explicitly check that this backend exists.

Trait Implementations

impl BackendExt for Backend

fn is_healthy(&self) -> Result<BackendHealth, Error>

Return the health of the backend if configured and currently known.

impl Clone for Backend

fn clone(&self) -> Backend

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Backend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Backend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for Backend

type Err = BackendError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Backend

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Backend

fn cmp(&self, other: &Backend) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Backend

fn eq(&self, other: &Backend) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Backend

fn partial_cmp(&self, other: &Backend) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Backend

impl StructuralPartialEq for Backend

impl<'a> ToBackend for &'a Backend

impl ToBackend for Backend