Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat!: container-centric API with refactored underlying layer #575

Merged
merged 15 commits into from
Apr 22, 2024
Merged

Conversation

DDtKey
Copy link
Collaborator

@DDtKey DDtKey commented Apr 18, 2024

Quite large refactoring as part of project revamp #563, and also the long-awaited refactoring #386

Now it's really simple API, e.g:

let container = GenericImage::new("redis", "7.2.4")
        .with_exposed_port(6379)
        .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
        .start();

I find this new API much easier to use, solves a lot of problems, and seems flexible enough to be extended.
This also works regardless of the tokio runtime flavor (multi-thread vs current-thread). And the sync API is still available, right under blocking feature (just like reqwest does).

From a maintainer's perspective this also simplifies the code, we don't have to worry about two different clients and their differences.

Docker host resolution

The host is resolved in the following order:

  1. Docker host from the tc.host property in the ~/.testcontainers.properties file.
  2. DOCKER_HOST environment variable.
  3. Docker host from the "docker.host" property in the ~/.testcontainers.properties file.
  4. Else, the default Docker socket will be returned.

Notes

  • MSRV was bumped to 1.70 in order to use std::sync::OnceLock. This should NOT be a problem, tests usually executed on more recent versions (also see this ref).
  • Cli client is removed, instead we provide sync (under blocking feature) and async impls based on HTTP client (bollard)
  • tested with modules

Migration guide

  • Sync API migration (Cli client)
    • Add blocking feature
    • Drop all usages of clients::Cli
    • Add use testcontainers::runners::SyncRunner;
    • Replace client.run(image) with image.start()
  • Async API migration (Http client)
    • Remove experimental feature
    • Drop all usages of clients::Http
    • Add use testcontainers::runners::AsyncRunner;
    • Replace client.run(image) with image.start()
  • ENV variable TESTCONTAINERS was renamed to TESTCONTAINERS_COMMAND and still accepts either remove (default to remove containers on drop) or keep
  • ExecCommand interface was changed to builder-like:
    • use ExecCommand::new(cmd) instead of ExecCommand { ... }
    • cmd is Vec<String> now, so make sure your commands are separated
    • use any of the new methods to check the result with_container_ready_conditions & with_cmd_ready_condition

References

Closes #386
Closes #326
Closes #475
Closes #508
Closes #392
Closes #561
Closes #559
Closes #564
Closes #538
Closes #507
Closes #89
Closes #198

Quite large refactoring as part of project revamp #563, and also the long-awaited refactoring #386

Closes #386
Closes #326
Closes #475
Closes #508
Closes #392
Closes #561
Closes #559

MSRV was bumped to `1.70` in order to use `std::sync::OnceLock`. This should NOT be a problem, tests usually executed on more recent versions (also see [this ref](https://github.com/testcontainers/testcontainers-rs/pull/503/files#r1242651354)).
# Conflicts:
#	Cargo.toml
#	testcontainers/Cargo.toml
@DDtKey DDtKey marked this pull request as ready for review April 18, 2024 21:30
@DDtKey DDtKey changed the title feat!: container-centric API feat!: container-centric API with refactored client layer Apr 18, 2024
@DDtKey DDtKey changed the title feat!: container-centric API with refactored client layer feat!: container-centric API with refactored underlying layer Apr 18, 2024
DDtKey added a commit to testcontainers/testcontainers-rs-modules-community that referenced this pull request Apr 20, 2024
Update of underlying `testcontainers` core crate. It contains breaking changes of API, see testcontainers/testcontainers-rs#575
DDtKey added a commit to testcontainers/testcontainers-rs-modules-community that referenced this pull request Apr 20, 2024
Update of underlying `testcontainers` core crate. It contains breaking changes of API, see testcontainers/testcontainers-rs#575
README.md Outdated Show resolved Hide resolved
@DDtKey DDtKey enabled auto-merge April 22, 2024 10:09
@DDtKey DDtKey added this pull request to the merge queue Apr 22, 2024
Merged via the queue into dev with commit 9c65640 Apr 22, 2024
9 checks passed
@DDtKey DDtKey deleted the rework-api branch April 22, 2024 10:15
This was referenced Apr 22, 2024
DDtKey pushed a commit that referenced this pull request Apr 27, 2024
## 🤖 New release
* `testcontainers`: 0.15.0 -> 0.16.0 (⚠️ API breaking changes)

### ⚠️ `testcontainers` breaking changes

```
--- failure constructible_struct_adds_private_field: struct no longer constructible due to new private field ---

Description:
A struct constructible with a struct literal has a new non-public field. It can no longer be constructed using a struct literal outside of its crate.
        ref: https://doc.rust-lang.org/reference/expressions/struct-expr.html
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/constructible_struct_adds_private_field.ron

Failed in:
  field ExecCommand.cmd_ready_condition in /tmp/.tmp8FBROu/testcontainers-rs/testcontainers/src/core/image/exec_command.rs:6
  field ExecCommand.container_ready_conditions in /tmp/.tmp8FBROu/testcontainers-rs/testcontainers/src/core/image/exec_command.rs:7

--- failure enum_missing: pub enum removed or renamed ---

Description:
A publicly-visible enum cannot be imported by its prior path. A `pub use` may have been removed, or the enum itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/enum_missing.ron

Failed in:
  enum testcontainers::core::env::Command, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/env.rs:36

--- failure function_missing: pub fn removed or renamed ---

Description:
A publicly-visible function cannot be imported by its prior path. A `pub use` may have been removed, or the function itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/function_missing.ron

Failed in:
  function testcontainers::core::env::command, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/env.rs:4

--- failure inherent_method_missing: pub method removed or renamed ---

Description:
A publicly-visible method or associated fn is no longer available under its prior name. It may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/inherent_method_missing.ron

Failed in:
  ContainerAsync::get_host_port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/container_async.rs:68
  ContainerAsync::get_host_port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/container_async.rs:68
  Container::get_host_port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/container.rs:124
  Container::get_host_port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/container.rs:124
  ContainerState::host_port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:120
  GenericImage::with_volume, previously in file /tmp/.tmpkl2iBT/testcontainers/src/images/generic.rs:45
  RunnableImage::inner, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:163
  RunnableImage::volumes, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:183
  RunnableImage::with_volume, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:255
  RunnableImage::inner, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:163
  RunnableImage::volumes, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:183
  RunnableImage::with_volume, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:255

--- failure module_missing: pub module removed or renamed ---

Description:
A publicly-visible module cannot be imported by its prior path. A `pub use` may have been removed, or the module may have been renamed, removed, or made non-public.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/module_missing.ron

Failed in:
  mod testcontainers::core::env, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/env.rs:1
  mod testcontainers::clients, previously in file /tmp/.tmpkl2iBT/testcontainers/src/clients.rs:1

--- failure struct_missing: pub struct removed or renamed ---

Description:
A publicly-visible struct cannot be imported by its prior path. A `pub use` may have been removed, or the struct itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/struct_missing.ron

Failed in:
  struct testcontainers::core::env::Os, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/env.rs:26
  struct testcontainers::clients::Http, previously in file /tmp/.tmpkl2iBT/testcontainers/src/clients/http.rs:23
  struct testcontainers::core::Port, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:312
  struct testcontainers::clients::Cli, previously in file /tmp/.tmpkl2iBT/testcontainers/src/clients/cli.rs:22

--- failure struct_pub_field_missing: pub struct's pub field removed or renamed ---

Description:
A publicly-visible struct has at least one public field that is no longer available under its prior name. It may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/struct_pub_field_missing.ron

Failed in:
  field cmd of struct ExecCommand, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:101
  field ready_conditions of struct ExecCommand, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:103

--- failure struct_pub_field_now_doc_hidden: pub struct field is now #[doc(hidden)] ---

Description:
A pub field of a pub struct is now marked #[doc(hidden)] and is no longer part of the public API.
        ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/struct_pub_field_now_doc_hidden.ron

Failed in:
  field ExecCommand.cmd in file /tmp/.tmp8FBROu/testcontainers-rs/testcontainers/src/core/image/exec_command.rs:4

--- failure trait_method_missing: pub trait method removed or renamed ---

Description:
A trait method is no longer callable, and may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#major-any-change-to-trait-item-signatures
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/trait_method_missing.ron

Failed in:
  method volumes of trait Image, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:70
  method volumes of trait Image, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/image.rs:70

--- failure trait_missing: pub trait removed or renamed ---

Description:
A publicly-visible trait cannot be imported by its prior path. A `pub use` may have been removed, or the trait itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.31.0/src/lints/trait_missing.ron

Failed in:
  trait testcontainers::core::env::GetEnvValue, previously in file /tmp/.tmpkl2iBT/testcontainers/src/core/env.rs:20
```

<details><summary><i><b>Changelog</b></i></summary><p>

<blockquote>

## [0.16.0] - 2024-04-27

### Details
#### Bug Fixes
- Use the binds option instead of volumes for mounts
([#581](#581))

#### Documentation
- Mention a way to preserve running containers
([#586](#586))

#### Features
- Support for docker cli flag `--add-host`
([#547](#547))
- Allow to override args in a `RunnableImage`
([#558](#558))
- Add `name` parameter to `RunnableImage`
([#549](#549))
- [❗] Container-centric API with refactored underlying layer
([#575](#575))
- Add ability to pull-image explicitly
([#579](#579))

#### Miscellaneous Tasks
- Remove `spectral` from `dev-dependencies`
([#526](#526))
- Update reqwest requirement from 0.11.14 to 0.12.3
([#569](#569))
- Update bollard and bollard-stubs
([#574](#574))
- Reuse workspace level configs
([#568](#568))

#### Refactor
- [❗] Api for mounts and volumes
([#596](#596))

#### Styling
- Derive `Default` to fix clippy lint
([#525](#525))
- Actualize formatting configs
([#567](#567))
- Enable `StdExternalCrate` grouping
</blockquote>


</p></details>

---
This PR was generated with
[release-plz](https://github.com/MarcoIeni/release-plz/).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment