logo
pub struct Host {
    pub name: String,
    pub alternative_names: Vec<String>,
    pub certificate: Option<Arc<CertifiedKey>>,
    pub path: PathBuf,
    pub extensions: Extensions,
    pub file_cache: Option<FileCache>,
    pub response_cache: Option<ResponseCache>,
    pub limiter: LimitManager,
    pub vary: Vary,
    pub options: Options,
    pub compression_options: CompressionOptions,
}
Expand description

A set of settings for a virtual host, allowing multiple DNS entries (domain names) to share a single IP address.

This is an integral part of Kvarn; the ability to host multiple webpages on a single instance without crosstalk and with high performance makes it a viable option.

Let’s talk about the relations of Host::unsecure and PortDescriptor::unsecure. A host can be secure and contain a certificate (if the https feature is enabled). A PortDescriptor can accept HTTPS or HTTP requests. PortDescriptor::new will set up the descriptor to accept only HTTP requests if none of the hosts contains a certificate. It accepts only HTTPS messages if any of the hosts have a certificate. Then, connections to all the other hosts with no certificate are rejected.

For example, in the reference implementation, I use PortDescriptor::unsecure to bind port 80 and PortDescriptor::new to bind port 443. Then, all hosts are reachable on port 80, but only the ones with a certificate on port 443.

Examples

See RunConfig::execute().

Fields

name: String

The name of the host, will be used in matching the requests SNI hostname and host header to get the requested host to handle the request.

alternative_names: Vec<String>

The alternative names this host is recognized by. This should probably be empty unless your certificate also covers these names.

certificate: Option<Arc<CertifiedKey>>
Available on crate feature https only.

The certificate of this host, if any.

path: PathBuf

Base path of all data for this host.

If you enabled the fs feature (enabled by default), the public files are in the directory <path>/public (public by default; see Options::public_data_dir).

Also, all extensions should use this to access data on disk.

extensions: Extensions

The extensions of this host.

file_cache: Option<FileCache>

The file cache of this host.

The caches are separated to limit the performance fluctuations of multiple hosts on the same instance.

Can be used to clear the cache and to pass to the read functions in read.

response_cache: Option<ResponseCache>

The response cache of this host. See comprash and Host::file_cache for more info.

limiter: LimitManager

The LimitManager checking for spam attacks for this host.

Having this host-specific enables different virtual hosts to have varying degrees of strictness.

vary: Vary

Settings for handling caching of responses with the vary header.

options: Options

Other settings.

compression_options: CompressionOptions

Preferences and options for compression.

Implementations

Available on crate feature https only.

Creates a new Host. Will read PEM encoded certificates in the specified locations and return an non-secure host if parsing fails.

To achieve greater security, use Host::with_http_to_https_redirect and call Host::with_hsts.

See Host::unsecure for a non-failing function, available regardless of features.

Errors

Will return any error from get_certified_key() with a Host containing no certificates.

Available on crate features https and auto-hostname only.

Same as Self::try_read_fs, but extracts the host name from the certificate. This also doesn’t fall back to Self::unsecure, as we don’t know the name if the certificate couldn’t be parsed.

Panics

Panics if the parsed certificate .is_empty() or if the first certificate in the parsed chain is invalid.

Errors

Will return any error from get_certified_key().

Available on crate feature https only.

Creates a new Host from the [rustls] cert and pk. When they are in files, consider Self::new which reads from files.

See the considerations of Self::new for security.

Examples
let certificate =
    rcgen::generate_simple_self_signed(vec!["localhost".to_string()]).unwrap();
let cert = vec![rustls::Certificate(certificate.serialize_der().unwrap())];
let pk = rustls::PrivateKey(certificate.serialize_private_key_der());
let pk = Arc::new(rustls::sign::any_supported_type(&pk).unwrap());

Host::new(
    "localhost",
    cert,
    pk,
    "tests",
    Extensions::default(),
    host::Options::default(),
);
Available on crate features https and auto-hostname only.

Same as Self::new, but extracts the host name from the certificate.

Panics

Panics if cert.is_empty() or if the first certificate in cert is invalid.

Creates a new Host without a certificate.

This host will only support non-encrypted HTTP/1 connections. Consider enabling the https feature and use a self-signed certificate or one from Let’s Encrypt.

Available on crate feature https only.

Same as Host::try_read_fs with Host::with_http_to_https_redirect. This does however consider the error from Host::try_read_fs to be ok. We log it as an log::Level::Error and continue without encryption.

Consider running Host::try_read_fs with Host::with_http_to_https_redirect and Host::with_hsts to harden the system.

Available on crate feature https only.

Adds extensions to redirect unsecure HTTP requests to the secure HTTPS URI.

See Extensions::with_http_to_https_redirect.

Available on crate feature https only.

Enables HSTS on this Host.

The Package extension has a priority of 8.

You should be careful using this feature. If you do not plan to have a certificate for your domain for at least the following two years, take a look in the source code, copy paste it and lower the max-age.

Also see hstspreload.org

Add an alternative name to this host.

See the fiels for more details.

Disables client cache on this host.

This makes all comprash::ClientCachePreferences no-store. Use Kvarn extensions’ force_cache to force certain files to cache.

Disables the file system cache for this host. This can cause degraded performance under heavy load, but reduces the memoy used.

Disables the response cache for this host. This can cause degraded performance under heavy load, but reduces the memoy used.

Disables all server caches. This can cause degraded performance under heavy load, but reduces the memoy used.

Right now calls Self::disable_fs_cache and Self::disable_response_cache.

Available on crate feature https only.

Whether or not this this host is secured with a certificate.

See Host::certificate.

Available on crate feature br only.

Set the brotli compression level. 1-10, lower values are faster, but compress less.

See some benchmarks for more context.

Available on crate feature gzip only.

Set the gzip compression level. 1-10, lower values are faster, but compress less.

See some benchmarks for more context.

Trait Implementations

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more