feat!: container-centric API with refactored underlying layer

[DDtKey]

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

[kaspar-p]

The CHANGELOG that references this PR:

[❗] Container-centric API with refactored underlying layer (https://github.com/testcontainers/testcontainers-rs/pull/575)

does not contain enough information. The main way users were starting containers (Cli) was entirely removed, and the upgrade path had to be discovered in the comment of this PR.

[DDtKey]

Hi @kaspar-p 👋

All the changes has been planned and performed more than year ago.
The description of the PR has been duplicated in the release notes. But not in changelog - that's true.

I apologize if it's not clear enough, but we had, at least:

• migration guides in release descriptions
  • https://github.com/testcontainers/testcontainers-rs/releases/tag/0.16.0
  • https://github.com/testcontainers/testcontainers-rs/releases/tag/0.17.0
  • https://github.com/testcontainers/testcontainers-rs/releases/tag/0.18.0
• all examples and tests has been updated
• all pre-cooked images has been updated in https://github.com/testcontainers/testcontainers-rs-modules-community

The thing is that changelog is automatically generated based on conventional commits and it highlights breaking changes. So the description of the PR is still relevant place too, because changelog refers to it.

[kaspar-p]

That's fine, just giving an experience of how I was driven to these changes. I did cargo upgrade and -i on a few dependencies, which bumped me all the way from 0.14. The build broke, so looked into the changelog to see what changed, and didn't find much there.

I think for folks new to testcontainers, your existing paths are good coverage, just giving an anecdote on how already-using users might see.

Maybe the migration guide could be ported to the changelog? That would have been perfect for me. But if you feel most users know that that's where to look, I'm OK being the odd one out :).

[DDtKey]

This is all fair, ofc.
At least it's not weird that the migration guides are "hidden" after a year, and the release notes are no longer visible on the front page. Changelog is source of truth after all.

I think we can add links to the migration guides in the changelog. That way it's clear that there is a separate guide
Migration guides can be added to the docs site as well.

However, I have limited bandwidth and can't prioritize this ASAP, so any PRs are welcome 🙏