use std::collections::HashMap;
use bollard::models::{Mount, MountTypeEnum, MountVolumeOptions, MountVolumeOptionsDriverConfig};
use crate::error::SubstrateError;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VolumeMount {
pub name: String,
pub target: String,
pub read_only: bool,
pub driver: Option<VolumeDriver>,
}
const FORBIDDEN_DRIVER_OPTION_KEYS: [&str; 3] = ["device", "o", "type"];
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VolumeDriver {
pub name: String,
pub options: HashMap<String, String>,
}
impl VolumeMount {
pub fn named(name: impl Into<String>, target: impl Into<String>) -> Self {
Self {
name: name.into(),
target: target.into(),
read_only: false,
driver: None,
}
}
pub fn read_only(mut self) -> Self {
self.read_only = true;
self
}
pub fn with_driver(
mut self,
driver: impl Into<String>,
options: HashMap<String, String>,
) -> Self {
self.driver = Some(VolumeDriver {
name: driver.into(),
options,
});
self
}
pub fn validate(&self) -> Result<(), SubstrateError> {
if !is_valid_volume_name(&self.name) {
return Err(SubstrateError::InvalidSpec(format!(
"volume name {:?} is not a valid Docker volume name \
(must start with a letter or digit and contain only [a-zA-Z0-9_.-]; \
host paths are not accepted)",
self.name
)));
}
if !self.target.starts_with('/') {
return Err(SubstrateError::InvalidSpec(format!(
"volume {:?} target {:?} must be an absolute container path",
self.name, self.target
)));
}
if let Some(driver) = &self.driver {
if driver.name.is_empty() {
return Err(SubstrateError::InvalidSpec(format!(
"volume {:?} has an empty driver name",
self.name
)));
}
if driver.name.trim().eq_ignore_ascii_case("local") {
return Err(SubstrateError::InvalidSpec(format!(
"volume {:?}: driver `local` is not accepted (it can bind-mount a host \
path via driver options); omit the driver to use the default",
self.name
)));
}
if let Some(key) = driver.options.keys().find(|k| {
FORBIDDEN_DRIVER_OPTION_KEYS.contains(&k.trim().to_ascii_lowercase().as_str())
}) {
return Err(SubstrateError::InvalidSpec(format!(
"volume {:?}: driver option {:?} is not accepted (it can name a host \
path or mount type)",
self.name, key
)));
}
}
Ok(())
}
pub(crate) fn to_docker(&self) -> Mount {
let volume_options = self.driver.as_ref().map(|d| MountVolumeOptions {
driver_config: Some(MountVolumeOptionsDriverConfig {
name: Some(d.name.clone()),
options: Some(d.options.clone()),
}),
..Default::default()
});
Mount {
target: Some(self.target.clone()),
source: Some(self.name.clone()),
typ: Some(MountTypeEnum::VOLUME),
read_only: Some(self.read_only),
volume_options,
..Default::default()
}
}
}
fn is_valid_volume_name(name: &str) -> bool {
let mut chars = name.chars();
match chars.next() {
Some(c) if c.is_ascii_alphanumeric() => {}
_ => return false,
}
chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '-'))
}
pub fn resolve_mount_namespace(pid: u32) -> Result<String, SubstrateError> {
let link = std::fs::read_link(format!("/proc/{pid}/ns/mnt"))?;
link.into_os_string().into_string().map_err(|_| {
SubstrateError::Resolve(format!("non-utf8 mount namespace handle for pid {pid}"))
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn named_volume_maps_to_a_docker_volume_mount() {
let m = VolumeMount::named("jellyfin-config", "/config")
.read_only()
.to_docker();
assert_eq!(m.typ, Some(MountTypeEnum::VOLUME));
assert_eq!(m.source.as_deref(), Some("jellyfin-config"));
assert_eq!(m.target.as_deref(), Some("/config"));
assert_eq!(m.read_only, Some(true));
assert!(m.volume_options.is_none());
assert!(m.bind_options.is_none());
}
#[test]
fn driver_selection_maps_to_volume_options_driver_config() {
let mut opts = HashMap::new();
opts.insert("pool".to_string(), "pool-a".to_string());
let m = VolumeMount::named("state", "/state")
.with_driver("example-driver", opts.clone())
.to_docker();
let cfg = m.volume_options.unwrap().driver_config.unwrap();
assert_eq!(cfg.name.as_deref(), Some("example-driver"));
assert_eq!(cfg.options, Some(opts));
}
#[test]
fn validate_accepts_a_plain_named_volume() {
VolumeMount::named("data_1.x-y", "/data")
.validate()
.unwrap();
}
#[test]
fn validate_rejects_host_paths_and_bad_names() {
for bad in ["", "/etc", "./rel", "../up", "-lead", "has space", "a/b"] {
let err = VolumeMount::named(bad, "/data").validate().expect_err(bad);
assert!(matches!(err, SubstrateError::InvalidSpec(_)), "{bad}");
}
}
#[test]
fn validate_rejects_a_relative_target() {
let err = VolumeMount::named("data", "data").validate().unwrap_err();
assert!(matches!(err, SubstrateError::InvalidSpec(_)));
}
#[test]
fn validate_rejects_an_empty_driver_name() {
let err = VolumeMount::named("data", "/data")
.with_driver("", HashMap::new())
.validate()
.unwrap_err();
assert!(matches!(err, SubstrateError::InvalidSpec(_)));
}
fn bind_options(pairs: &[(&str, &str)]) -> HashMap<String, String> {
pairs
.iter()
.map(|(k, v)| (k.to_string(), v.to_string()))
.collect()
}
#[test]
fn validate_rejects_a_local_driver_bind_of_a_host_path() {
let err = VolumeMount::named("data", "/data")
.with_driver(
"local",
bind_options(&[("type", "none"), ("o", "bind"), ("device", "/etc")]),
)
.validate()
.unwrap_err();
assert!(matches!(err, SubstrateError::InvalidSpec(_)));
}
#[test]
fn validate_rejects_the_local_driver_in_any_spelling() {
for name in ["local", "Local", "LOCAL", " local ", "local\t"] {
let err = VolumeMount::named("data", "/data")
.with_driver(name, HashMap::new())
.validate()
.expect_err(name);
assert!(matches!(err, SubstrateError::InvalidSpec(_)), "{name:?}");
}
}
#[test]
fn validate_rejects_host_path_option_keys_on_any_driver() {
for key in [
"device", "Device", "DEVICE", "o", "O", "type", "Type", " type ",
] {
let err = VolumeMount::named("data", "/data")
.with_driver("example-driver", bind_options(&[(key, "x")]))
.validate()
.expect_err(key);
assert!(matches!(err, SubstrateError::InvalidSpec(_)), "{key:?}");
}
}
#[test]
fn validate_still_accepts_a_plugin_driver_with_ordinary_options() {
VolumeMount::named("state", "/state")
.with_driver("example-driver", bind_options(&[("pool", "pool-a")]))
.validate()
.unwrap();
}
#[test]
#[cfg(target_os = "linux")]
fn resolve_mount_namespace_resolves_this_process_own_handle_for_real() {
let pid = std::process::id();
let handle = resolve_mount_namespace(pid).expect("resolve own mount namespace");
assert!(
handle.starts_with("mnt:["),
"expected an `mnt:[...]` handle, got: {handle}"
);
}
#[test]
fn resolve_mount_namespace_fails_cleanly_for_a_nonexistent_pid() {
let bogus_pid = u32::MAX;
let err = resolve_mount_namespace(bogus_pid).expect_err("nonexistent pid must fail");
assert!(matches!(err, SubstrateError::Io(_)));
}
}