Breaking changes in 0.7.0

[jan-kantert]

Updating to 0.7.0 broke quite a bit of code on our end. In my opinion this should only happen in major versions.

A few questions regarding migrating to 0.7.0:

• What is the new Error::ResponseParse. Is Error::ParseUrl the same thing?
• Client::metric_metadata lost its parameters. Is there a replacement or migration guide?

[puetzp]

According to semantic versioning the usual conventions regarding API changes do not apply during the "initial development" (version 0.y.z) phase. However I would certainly agree that at some point a 1.0.0 release should be cut instead of remaining forever in this "initial development" phase. This problem applies to a lot of Rust crates on crates.io.

Regarding your questions:

1. Error::ResponseParse is thrown when the JSON response from the Prometheus server cannot be parsed (is not as expected). Error::ParseUrl on the other hand is thrown when you create a Client and pass an invalid base URL.
2. Client::metric_metadata lost its parameters but now returns a builder type. This type has methods that enable you to set the parameters that you would have passed to Client::metric_metadata directly in the 0.6.x versions of this crate. There is no migration guide as I had hoped that the documentation on docs.rs and the latest Changelog would suffice to explain the changes.

There are other Client methods that return builder types now (e.g. Client::rules. My reasoning for this is that the Prometheus HTTP API keeps evolving quite a bit and at some point the number of parameters that you add to a request becomes unwieldy. I think building a request to the API with a "builder" type is in some cases just better than having functions with a lot of optional parameters like metric_metadata(None, None, None, None).

Let me know if there is anything else!

[jan-kantert]

Thanks for your fast reply and thanks for the library :-).

We currently use Error::Client and Error::ResponseParse to catch any kind of connection reset/timeout or underlying network rrors and retry those (using the awesome backoff crate). Where would those errors end up now? I want to retry any transport errors.

[puetzp]

First of all I actually made in error in my first reply. The Error::ResponseParse variant is not included in v0.7.0 anymore. The Error enum looks like this now:

#[non_exhaustive]
pub enum Error {
    Client(ClientError),
    Prometheus(PrometheusError),
    EmptySeriesSelector,
    ParseUrl(ParseUrlError),
}

The parsing of the JSON response from Prometheus is now completely handled by the underlying reqwest::Client. Thus errors related to deserialization/parsing as well as timeouts are handled and returned by the reqwest crate. The Error::Client(ClientError) variant is a wrapper around those errors.
So in order to obtain the underlying reqwest::Error and determine the reason a request failed you would need to do the following:

(sample code, not tested)

if let Err(e) = match client.metric_metadata().get().await {
    if let Some(inner)  = e.source().map(|source| source.downcast_ref::<reqwest::Error>()) {
        // Error related to parsing.
        if inner.is_decode() {
            todo!();
        // Error related to network timeout.
        } else if inner.is_timeout() {
            todo!();
        } else {
            todo!();
        }
    }
}

See also:
reqwest::Error

[puetzp]

Actually I thought a bit about it and will add amongst others a ClientError:inner() method to get to the inner reqwest::Error without downcasting.
The downcasting is necessary because Error::source() returns &(dyn Error) and the source() method needs to be implemented for libraries like anyhow to work properly.
But there is no reason why we cannot make life easier by adding a "shortcut" to the inner error.
Then you could just do:

match client.metric_metadata().get().await {
    Ok(_) => println!("happy path"),
    Err(e) => match e {
        Error::Client(e) => if e.inner().is_timeout() {
            todo!();
        }
    }
}

Will be added in v0.7.1!

[puetzp]

Methods to retrieve underlying errors more quickly were added in v0.7.1. See for example this.

I think this addresses your last question and will close this issue now!