1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593
//! Represent a concrete instance of an Image, before it is ran as a Container.
use crate::image::Image;
use crate::waitfor::{NoWait, WaitFor};
use std::collections::HashMap;
use tracing::{event, Level};
/// Specifies the starting policy of a container specification.
///
/// - [StartPolicy::Strict] policy will enforce that the container is started in the order
/// it was added to [DockerTest].
/// - [StartPolicy::Relaxed] policy will not enforce any ordering,
/// all container specifications with a relaxed policy will be started concurrently.
/// These are all started asynchrously started before the strict policy containers
/// are started sequentially.
///
/// [DockerTest]: crate::DockerTest
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StartPolicy {
/// Concurrently start the Container with other Relaxed instances.
Relaxed,
/// Start Containers' sequentially in the order added to DockerTest.
Strict,
}
/// Specifies who is responsible for managing a static container.
///
/// - [StaticManagementPolicy::External] indicates that the user is responsible for managing the
/// container, DockerTest will never start or remove/stop the container. The container will
/// be available through its handle in [DockerOperations]. If no external network is
/// supplied, the test-scoped network will be added to the external network, and subsequently
/// removed once the test terminates.
/// The externally managed container is assumed to be in a running state when the test starts.
/// If DockerTest cannot locate the the container, the test will fail.
/// - [StaticManagementPolicy::Internal] indicates that DockerTest will handle the lifecycle of
/// the container between all DockerTest instances within the test binary.
/// - [StaticManagementPolicy::Dynamic] indicates that DockerTest will start the
/// container if it does not already exists and will not clean it up. This way the same
/// container can be re-used across multiple `cargo test` invocations.
/// If the `DOCKERTEST_DYNAMIC` environment variable is set to `INTERNAL` or `EXTERNAL`, the management policy
/// will instead be set accordingly (either [StaticManagementPolicy::Internal] or [StaticManagementPolicy::External].
/// The purpose of this is to facilitate running tests locally and in CI/CD pipelines without having to alter management policies.
/// If a container already exists in a non-running state with the same name as a container with this policy, the startup
/// procedure will fail.
///
/// [DockerOperations]: crate::DockerOperations
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StaticManagementPolicy {
/// The lifecycle of the container is managed by the user.
External,
/// DockerTest handles the lifecycle of the container.
Internal,
/// DockerTest starts the container if it does not exist and does not remove it, and will
/// re-use the container across `cargo test` invocations.
Dynamic,
}
/// Specifies how should dockertest should handle log output from this container.
#[derive(Clone, Debug)]
pub enum LogAction {
/// Forward all outputs to their respective output sources of the dockertest process.
Forward,
/// Forward [LogSource] outputs to a specified file.
ForwardToFile {
/// The filepath to output to.
path: String,
},
/// Forward [LogSource] outputs to stdout of the dockertest process.
ForwardToStdOut,
/// Forward [LogSource] outputs to stderr of the dockertest process.
ForwardToStdErr,
}
/// Specifies which log sources we want to read from containers.
#[derive(Clone, Debug)]
pub enum LogSource {
/// Read stderr only.
StdErr,
/// Read stdout only.
StdOut,
/// Read stdout and stderr.
Both,
}
/// Specifies when [LogAction] is applicable.
#[derive(Clone, Debug)]
pub enum LogPolicy {
/// [LogAction] is always applicable.
Always,
/// [LogAction] is applicable only if an error occures.
OnError,
/// [LogAction] is applicable only if a startup error occures.
OnStartupError,
}
/// Specifies how dockertest should handle logging output from this specific container.
#[derive(Clone, Debug)]
pub struct LogOptions {
/// The logging actions to be performed.
pub action: LogAction,
/// Under which conditions should we perform the log actions?
pub policy: LogPolicy,
/// Specifies log sources we want to read from container.
pub source: LogSource,
}
impl Default for LogOptions {
fn default() -> LogOptions {
LogOptions {
action: LogAction::Forward,
policy: LogPolicy::OnError,
source: LogSource::StdErr,
}
}
}
/// Represents an instance of an [Image].
///
/// The Composition is used to specialize an image whose name, version, tag and source is known,
/// but before one can create a [crate::container:: OperationalContainer] from an image,
/// it must be augmented with information about how to start it, how to ensure it has been
/// started, environment variables and runtime commands.
/// Thus, this structure represents the concrete instance of an [Image] that will be started
/// and become a [crate::container::OperationalContainer].
///
/// NOTE: This is an internal implementation detail. This used to be a public interface.
#[derive(Clone, Debug)]
pub struct Composition {
/// User provided name of the container.
///
/// This will dictate the final container_name and the container_handle_key of the container
/// that will be created from this Composition.
user_provided_container_name: Option<String>,
/// Network aliases for the container.
pub(crate) network_aliases: Option<Vec<String>>,
/// The name of the container to be created by this Composition.
///
/// When the composition is created, this field defaults to the repository name of the
/// associated image. If the user provides an alternative container name, this will be stored
/// in its own dedicated field.
///
/// The final format of the container name we will create will be on the following format:
/// `{namespace}-{name}-{suffix}` where
/// - `{namespace}` is the configured namespace with [crate::DockerTest].
/// - `{name}` is either the user provided container name, or this default value.
/// - `{suffix}` randomly generated pattern.
pub(crate) container_name: String,
/// A trait object holding the implementation that indicate container readiness.
pub(crate) wait: Box<dyn WaitFor>,
/// The environmentable variables that will be passed to the container.
pub(crate) env: HashMap<String, String>,
/// The command to pass to the container.
pub(crate) cmd: Vec<String>,
/// The start policy of this container, codifing the inter-depdencies between containers.
pub(crate) start_policy: StartPolicy,
/// The base image that will be the container we will be starting.
image: Image,
/// Named volumes associated with this composition, are in the form of:
/// - "(VOLUME_NAME,CONTAINER_PATH)"
pub(crate) named_volumes: Vec<(String, String)>,
/// Final form of named volume names.
///
/// DockerTest is responsible for constructing the final names and adding them to this vector.
/// The final name will be on the form `VOLUME_NAME-RANDOM_SUFFIX/CONTAINER_PATH`.
pub(crate) final_named_volume_names: Vec<String>,
/// Bind mounts associated with this composition, are in the form of:
/// - `HOST_PATH:CONTAINER_PATH`
///
/// NOTE: As bind mounts do not outlive the container they are mounted in they do not need to
/// be cleaned up.
pub(crate) bind_mounts: Vec<String>,
/// All user specified container name injections as environment variables.
/// Tuple contains (handle, env).
pub(crate) inject_container_name_env: Vec<(String, String)>,
/// Port mapping (used for Windows-compatibility)
pub(crate) port: Vec<(String, String)>,
/// Allocates an ephemeral host port for all of a container’s exposed ports.
///
/// Port forwarding is useful on operating systems where there is no network connectivity
/// between system and the Docker Desktop VM.
pub(crate) publish_all_ports: bool,
/// Who is responsible for managing the lifecycle of the container.
///
/// A composition can be marked as static, where the lifecycle of the container outlives
/// the individual test.
management: Option<StaticManagementPolicy>,
/// Logging options for this specific container.
pub(crate) log_options: Option<LogOptions>,
/// Tmpfs mount paths to create.
///
/// These are destination paths within the container to create tmpfs filesystems for,
/// they require no source paths.
///
/// tmpfs details: <https://docs.docker.com/engine/storage/tmpfs/>
pub(crate) tmpfs: Vec<String>,
/// Whether this composition should be started in privileged mode.
/// Privileged mode is required for some images, such as the `docker:dind` image.
/// See https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
/// for more information.
/// Defaults to false.
/// NOTE: This is only supported on Linux.
/// NOTE: This is only supported on Docker 1.13 and above.
/// NOTE: This is only supported on Docker API 1.25 and above.
/// NOTE: This is only supported on Docker Engine 1.13 and above.
pub(crate) privileged: bool,
}
impl Composition {
/// Creates a [Composition] based on the [Image] repository name provided.
///
/// This will internally create the [Image] based on the provided repository name,
/// and default the tag to `latest`.
///
/// This is the shortcut method of constructing a [Composition].
/// See [with_image](Composition::with_image) to create one with a provided [Image].
pub fn with_repository<T: ToString>(repository: T) -> Composition {
let copy = repository.to_string();
Composition {
user_provided_container_name: None,
network_aliases: None,
image: Image::with_repository(©),
container_name: copy.replace('/', "-"),
wait: Box::new(NoWait {}),
env: HashMap::new(),
cmd: Vec::new(),
start_policy: StartPolicy::Relaxed,
bind_mounts: Vec::new(),
named_volumes: Vec::new(),
inject_container_name_env: Vec::new(),
final_named_volume_names: Vec::new(),
port: Vec::new(),
publish_all_ports: false,
management: None,
log_options: Some(LogOptions::default()),
privileged: false,
tmpfs: Vec::new(),
}
}
/// Creates a [Composition] with the provided [Image].
///
/// This is the long-winded way of defining a [Composition].
/// See [with_repository](Composition::with_repository) for the shortcut method.
pub fn with_image(image: Image) -> Composition {
Composition {
user_provided_container_name: None,
network_aliases: None,
container_name: image.repository().to_string().replace('/', "-"),
image,
wait: Box::new(NoWait {}),
env: HashMap::new(),
cmd: Vec::new(),
start_policy: StartPolicy::Relaxed,
bind_mounts: Vec::new(),
named_volumes: Vec::new(),
inject_container_name_env: Vec::new(),
final_named_volume_names: Vec::new(),
port: Vec::new(),
publish_all_ports: false,
management: None,
log_options: Some(LogOptions::default()),
privileged: false,
tmpfs: Vec::new(),
}
}
/// Adds the given tmpfs mount paths to this [Composition]
///
/// See [tmpfs] for details.
///
/// [tmpfs]: Composition::tmpfs
#[cfg(target_os = "linux")]
pub fn with_tmpfs(self, paths: Vec<String>) -> Composition {
Composition {
tmpfs: paths,
..self
}
}
/// Sets the [StartPolicy] for this [Composition].
///
/// Defaults to a [relaxed](StartPolicy::Relaxed) policy.
pub fn with_start_policy(self, start_policy: StartPolicy) -> Composition {
Composition {
start_policy,
..self
}
}
/// Assigns the full set of environmental variables available for the [OperationalContainer].
///
/// Each key in the map should be the environmental variable name
/// and its corresponding value will be set as its value.
///
/// This method replaces the entire existing env map provided.
///
/// [OperationalContainer]: crate::container::OperationalContainer
pub fn with_env(self, env: HashMap<String, String>) -> Composition {
Composition { env, ..self }
}
/// Sets the command of the container.
///
/// If no entries in the command vector is provided to the [Composition],
/// the command within the [Image] will be used, if any.
pub fn with_cmd(self, cmd: Vec<String>) -> Composition {
Composition { cmd, ..self }
}
/// Add a host port mapping to the container.
///
/// This is useful when the host environment running docker cannot support IP routing
/// within the docker network, such that test containers cannot communicate between themselves.
/// This escape hatch allows the host to be involved to route traffic.
/// This mechanism is not recommended, as concurrent tests utilizing the same host port
/// will fail since the port is already in use.
/// It is recommended to use [Composition::publish_all_ports].
///
/// If an port mapping on the exported port has already been issued on the [Composition],
/// it will be overidden.
pub fn port_map(&mut self, exported: u32, host: u32) -> &mut Composition {
self.port
.push((format!("{}/tcp", exported), format!("{}", host)));
self
}
/// Allocates an ephemeral host port for all of the container's exposed ports.
///
/// Mapped host ports can be found via [crate::container::OperationalContainer::host_port] method.
pub fn publish_all_ports(&mut self, publish: bool) -> &mut Composition {
self.publish_all_ports = publish;
self
}
/// Sets the name of the container that will eventually be started.
///
/// This is merely part of the final container name, and the full container name issued
/// to docker will be generated.
/// The container name assigned here is also used to resolve the `handle` concept used
/// by dockertest.
///
/// The container name defaults to the repository name.
///
/// NOTE: If the `Composition` is a static container with an
/// `External` management policy the container name *MUST* match the container_name of
/// the external container and is required to be set.
pub fn with_container_name<T: ToString>(self, container_name: T) -> Composition {
Composition {
user_provided_container_name: Some(container_name.to_string()),
..self
}
}
/// Sets network aliases for this `Composition`.
pub fn with_alias(self, aliases: Vec<String>) -> Composition {
Composition {
network_aliases: Some(aliases),
..self
}
}
/// Adds network alias to this `Composition`
pub fn alias(&mut self, alias: String) -> &mut Composition {
match self.network_aliases {
Some(ref mut network_aliases) => network_aliases.push(alias),
None => self.network_aliases = Some(vec![alias]),
};
self
}
/// Sets the `WaitFor` trait object for this `Composition`.
///
/// The default `WaitFor` implementation used is [RunningWait].
///
/// [RunningWait]: crate::waitfor::RunningWait
pub fn with_wait_for(self, wait: Box<dyn WaitFor>) -> Composition {
Composition { wait, ..self }
}
/// Sets log options for this `Composition`.
/// By default `LogAction::Forward`, `LogPolicy::OnError`, and `LogSource::StdErr` is enabled.
/// To clear default log option pass `None` or specify your own log options.
pub fn with_log_options(self, log_options: Option<LogOptions>) -> Composition {
Composition {
log_options,
..self
}
}
/// Sets the environment variable to the given value.
///
/// NOTE: if [with_env] is called after a call to [env], all values added by [env] will be overwritten.
///
/// [env]: Composition::env
/// [with_env]: Composition::with_env
pub fn env<T: ToString, S: ToString>(&mut self, name: T, value: S) -> &mut Composition {
self.env.insert(name.to_string(), value.to_string());
self
}
/// Appends the command string to the current command vector.
///
/// If no entries in the command vector is provided to the [Composition],
/// the command within the [Image] will be used, if any.
///
/// NOTE: if [with_cmd] is called after a call to [cmd], all entries to the command vector
/// added with [cmd] will be overwritten.
///
/// [cmd]: Composition::cmd
/// [with_cmd]: Composition::with_cmd
pub fn cmd<T: ToString>(&mut self, cmd: T) -> &mut Composition {
self.cmd.push(cmd.to_string());
self
}
/// Appends the tmpfs mount path to the current set of tmpfs mount paths.
///
/// NOTE: if [with_tmpfs] is called after a call to [tmpfs], all entries to the tmpfs vector
/// added with [with_tmpfs] will be overwritten.
///
/// Details:
/// - Only available on linux.
/// - Size of the tmpfs mount defaults to 50% of the hosts total RAM.
/// - Defaults to file mode '1777' (world-writable).
///
/// [tmpfs]: Composition::tmpfs
/// [with_tmpfs]: Composition::with_tmpfs
#[cfg(target_os = "linux")]
pub fn tmpfs<T: ToString>(&mut self, path: T) -> &mut Composition {
self.tmpfs.push(path.to_string());
self
}
/// Adds the given named volume to the Composition.
/// Named volumes can be shared between containers, specifying the same named volume for
/// another Composition will give both access to the volume.
/// `path_in_container` has to be an absolute path.
pub fn named_volume<T: ToString, S: ToString>(
&mut self,
volume_name: T,
path_in_container: S,
) -> &mut Composition {
self.named_volumes
.push((volume_name.to_string(), path_in_container.to_string()));
self
}
/// Adds the given bind mount to the Composition.
/// A bind mount only exists for a single container and maps a given file or directory from the
/// host to the container.
/// Use named volumes if you want to share data between containers.
/// The `host_path` can either point to a directory or a file that MUST exist on the local host.
/// `path_in_container` has to be an absolute path.
pub fn bind_mount<T: ToString, S: ToString>(
&mut self,
host_path: T,
path_in_container: S,
) -> &mut Composition {
// The ':Z' is needed due to permission issues, see
// https://stackoverflow.com/questions/24288616/permission-denied-on-accessing-host-directory-in-docker
// for more details
self.bind_mounts.push(format!(
"{}:{}:Z",
host_path.to_string(),
path_in_container.to_string()
));
self
}
/// Inject the generated container name identified by `handle` into
/// this Composition environment variable `env`.
///
/// This is used to establish inter communication between running containers
/// controlled by dockertest. This is traditionally established through environment variables
/// for connection details, and thus the DNS resolving capabilities within docker will
/// map the container name into the correct IP address.
///
/// To correctly use this feature, the `StartPolicy` between the dependant containers
/// must be configured such that these connections can successfully be established.
/// Dockertest will not make any attempt to verify the integrity of these dependencies.
pub fn inject_container_name<T: ToString, E: ToString>(
&mut self,
handle: T,
env: E,
) -> &mut Composition {
self.inject_container_name_env
.push((handle.to_string(), env.to_string()));
self
}
/// Defines this as a static container which will will only be cleaned up after the full test
/// binary has executed.
/// If the static container is used across multiple tests in the same test binary, Dockertest can only guarantee that
/// the container will be started in its designated start order or earlier as other tests might
/// have already started it.
/// The container_name *MUST* be set to a unique value when using static containers.
/// To refer to the same container across `Dockertest` instances set the same container name for the
/// compostions.
///
/// NOTE: When the `External` management policy is used, the container_name must be set to the
/// name of the external container.
pub fn static_container(&mut self, management: StaticManagementPolicy) -> &mut Composition {
let management = match management {
StaticManagementPolicy::External | StaticManagementPolicy::Internal => management,
StaticManagementPolicy::Dynamic => match std::env::var("DOCKERTEST_DYNAMIC") {
Ok(val) => match val.as_str() {
"EXTERNAL" => StaticManagementPolicy::External,
"INTERNAL" => StaticManagementPolicy::Internal,
"DYNAMIC" => StaticManagementPolicy::Dynamic,
_ => {
event!(Level::WARN, "DOCKERTEST_DYNAMIC environment variable set to unknown value, defaulting to Dynamic policy");
StaticManagementPolicy::Dynamic
}
},
Err(_) => management,
},
};
self.management = Some(management);
self
}
/// Should this container be started with priviledged mode enabled?
/// This is required for some containers to run correctly.
/// See https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
/// for more details.
pub fn privileged(&mut self) -> &mut Composition {
self.privileged = true;
self
}
/// Fetch the assigned [StaticManagementPolicy], if any.
pub(crate) fn static_management_policy(&self) -> &Option<StaticManagementPolicy> {
&self.management
}
/// Query whether this Composition should be handled through static container checks.
pub(crate) fn is_static(&self) -> bool {
self.management.is_some()
}
// Configure the container's name with the given namespace as prefix
// and suffix.
// We do this to ensure that we do not have overlapping container names
// and make it clear which containers are run by DockerTest.
pub(crate) fn configure_container_name(&mut self, namespace: &str, suffix: &str) {
let name = match &self.user_provided_container_name {
None => self.image.repository(),
Some(n) => n,
};
if !self.is_static() {
// The docker daemon does not like '/' or '\' in container names
let stripped_name = name.replace('/', "_");
self.container_name = format!("{}-{}-{}", namespace, stripped_name, suffix);
} else {
self.container_name = name.to_string();
}
}
// Returns the Image associated with this Composition.
pub(crate) fn image(&self) -> &Image {
&self.image
}
/// Retrieve a copy of the applicable handle name for this composition.
///
/// NOTE: this value will be outdated if [Composition::with_container_name] is invoked
/// with a different name.
pub fn handle(&self) -> String {
match &self.user_provided_container_name {
None => self.image.repository().to_string(),
Some(n) => n.clone(),
}
}
}