pub struct Host {
pub name: CompactString,
pub alternative_names: Vec<CompactString>,
pub certificate: RwLock<Option<Arc<CertifiedKey>>>,
pub path: CompactString,
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_oneshot: CompressionOptions,
pub compression_options_cached: 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: CompactString
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<CompactString>
The alternative names this host is recognized by. This should probably be empty unless your certificate also covers these names.
certificate: RwLock<Option<Arc<CertifiedKey>>>
https
only.The certificate of this host, if any.
path: CompactString
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_oneshot: CompressionOptions
Preferences and options for compression when a response is not cached.
compression_options_cached: CompressionOptions
Preferences and options for compression when a response is cached.
Implementations§
source§impl Host
impl Host
sourcepub fn try_read_fs(
host_name: impl AsRef<str>,
cert_path: impl AsRef<str>,
private_key_path: impl AsRef<str>,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Result<Self, (CertificateError, Self)>
Available on crate feature https
only.
pub fn try_read_fs( host_name: impl AsRef<str>, cert_path: impl AsRef<str>, private_key_path: impl AsRef<str>, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Result<Self, (CertificateError, Self)>
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.
sourcepub fn read_fs_name_from_cert(
cert_path: impl AsRef<str>,
private_key_path: impl AsRef<str>,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Result<Self, CertificateError>
Available on crate feature https
only.
pub fn read_fs_name_from_cert( cert_path: impl AsRef<str>, private_key_path: impl AsRef<str>, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Result<Self, CertificateError>
https
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()
.
sourcepub fn new(
name: impl AsRef<str>,
key: CertifiedKey,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Self
Available on crate feature https
only.
pub fn new( name: impl AsRef<str>, key: CertifiedKey, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Self
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(),
);
sourcepub fn new_name_from_cert(
key: CertifiedKey,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Self
Available on crate feature https
only.
pub fn new_name_from_cert( key: CertifiedKey, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Self
https
only.sourcepub fn unsecure(
host_name: impl AsRef<str>,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Self
pub fn unsecure( host_name: impl AsRef<str>, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Self
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.
sourcepub fn http_redirect_or_unsecure(
host_name: impl AsRef<str>,
cert_path: impl AsRef<str>,
private_key_path: impl AsRef<str>,
path: impl AsRef<str>,
extensions: Extensions,
options: Options,
) -> Self
Available on crate feature https
only.
pub fn http_redirect_or_unsecure( host_name: impl AsRef<str>, cert_path: impl AsRef<str>, private_key_path: impl AsRef<str>, path: impl AsRef<str>, extensions: Extensions, options: Options, ) -> Self
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.
sourcepub fn with_http_to_https_redirect(&mut self) -> &mut Self
Available on crate feature https
only.
pub fn with_http_to_https_redirect(&mut self) -> &mut Self
https
only.Adds extensions to redirect unsecure HTTP requests to the secure HTTPS URI.
sourcepub fn with_hsts(&mut self) -> &mut Self
Available on crate feature https
only.
pub fn with_hsts(&mut self) -> &mut Self
https
only.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
sourcepub fn add_alternative_name(&mut self, name: impl AsRef<str>) -> &mut Self
pub fn add_alternative_name(&mut self, name: impl AsRef<str>) -> &mut Self
Add an alternative name to this host.
See the fiels for more details.
sourcepub fn disable_client_cache(&mut self) -> &mut Self
pub fn disable_client_cache(&mut self) -> &mut Self
Disables client cache on this host.
This makes all comprash::ClientCachePreference
s no-store
.
Use Kvarn extensions’ force_cache
to force certain files to cache.
sourcepub fn disable_fs_cache(&mut self) -> &mut Self
pub fn disable_fs_cache(&mut self) -> &mut Self
Disables the file system cache for this host. This can cause degraded performance under heavy load, but reduces the memoy used.
sourcepub fn disable_response_cache(&mut self) -> &mut Self
pub fn disable_response_cache(&mut self) -> &mut Self
Disables the response cache for this host. This can cause degraded performance under heavy load, but reduces the memoy used.
sourcepub fn disable_server_cache(&mut self) -> &mut Self
pub fn disable_server_cache(&mut self) -> &mut Self
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
.
sourcepub fn is_secure(&self) -> bool
Available on crate feature https
only.
pub fn is_secure(&self) -> bool
https
only.Whether or not this this host is secured with a certificate.
See Host::certificate
.
sourcepub fn set_brotli_level(&mut self, level: u32) -> &mut Self
Available on crate feature br
only.
pub fn set_brotli_level(&mut self, level: u32) -> &mut Self
br
only.Set the brotli compression level. 1-10, lower values are faster, but compress less. Default = 3.
See some benchmarks for more context.
sourcepub fn set_gzip_level(&mut self, level: u32) -> &mut Self
Available on crate feature gzip
only.
pub fn set_gzip_level(&mut self, level: u32) -> &mut Self
gzip
only.Set the gzip compression level. 1-10, lower values are faster, but compress less. Default = 1.
See some benchmarks for more context.
sourcepub fn set_zstd_level(&mut self, level: i32) -> &mut Self
Available on crate feature zstd
only.
pub fn set_zstd_level(&mut self, level: i32) -> &mut Self
zstd
only.Set the zstd compression level. Lower values are faster, but compress less. Negative values are allowed. See the link for more info. Default = 4. https://facebook.github.io/zstd/
sourcepub fn set_brotli_level_oneshot(&mut self, level: u32) -> &mut Self
Available on crate feature br
only.
pub fn set_brotli_level_oneshot(&mut self, level: u32) -> &mut Self
br
only.Like Host::set_brotli_level
but for responses which are not cached.
sourcepub fn set_gzip_level_oneshot(&mut self, level: u32) -> &mut Self
Available on crate feature gzip
only.
pub fn set_gzip_level_oneshot(&mut self, level: u32) -> &mut Self
gzip
only.Like Host::set_gzip_level
but for responses which are not cached.
sourcepub fn set_zstd_level_oneshot(&mut self, level: i32) -> &mut Self
Available on crate feature zstd
only.
pub fn set_zstd_level_oneshot(&mut self, level: i32) -> &mut Self
zstd
only.Like Host::set_zstd_level
but for responses which are not cached.
sourcepub fn live_set_certificate(&self, key: CertifiedKey)
Available on crate feature https
only.
pub fn live_set_certificate(&self, key: CertifiedKey)
https
only.Can be done while the server is running, since this only takes a reference to self
Sets the certificate if it was None
before. It’s however unclear what consequences that
will have while it’s running (if you only had unsecure hosts when starting Kvarn, it you
might not have bound 443
?).