RFC: add fallible result-based API

[DDtKey]

At the moment, testcontainers panics in case of any error. It makes it easier to use, but complicates the flexibility of the code and the ability to customize errors.

I suggest refactoring this and returning meaningful errors. This greatly expands the possibilities of use.

We can preserve panicking API by using a common pattern: providing fallible methods with a try_ prefix and keep existing ones as delegates that unwraps the Result.

For example:

// current api without changes:
let container = GenericImage::new("redis", "7.2.4")
        .with_exposed_port(6379)
        .start()
        .await;
        
// new fallible api
let container = GenericImage::new("redis", "7.2.4")
        .with_exposed_port(6379)
        .try_start()
        .await?; // you can handle the error any way you want

[mervyn-mccreight]

I'd say we should let the users decide whether they want to handle errors or not. Meaning that the fallible API could be the only existing API IMO and if the users want to just panic on error they are free to do so.

WDYT?

We might need to find a way to be able to do that API change gracefully with deprecations though.

[DDtKey]

That was just a proposal to start with try_ methods, quite common way to move towards fallible API. I definitely prefer to have a single aligned fallible API.

Graceful switch is a bit complicated if we want to preserve method names, however I see several ways to do that, mostly by using wrappers, like: FallibleContainer and etc, where the same methods returns Results

I can provide more examples a bit later, but that's definitely possible. However I'm not totally sure if we really need to be crazy about compatibility, because it's anyway breaking change at the end. Probably, good migration guide is enough. Moreover, it will be perfectly highlighted by linters and compiler - methods will start to return a Result which is unused.

After some major changes we can release version 1.0 and provide more guarantees about compatibilities

[mervyn-mccreight]

However I'm not totally sure if we really need to be crazy about compatibility, because it's anyway breaking change at the end. Probably, good migration guide is enough.

That sounds about right now that I think about it again.