Slim down schema agreement API

[wprzytula]

Schema agreement API is another place in the driver's code that can be polished towards API stability.

What's done

1. fetch_schema_version() is removed.
   It can be a nasty source of race bugs when schema version is fetched without awaiting for schema agreement. It is especially risky when one awaits schema agreement and subsequently fetches schema version, because the schema version can change in the meantime and schema may no longer be in agreement. To cope with the problem, await_schema_agreement() now returns the agreed schema version, and fetch_schema_version() is removed alltogether.

2. await_schema_agreement() gets implicit timeout.
   Similarly to

   • what Java driver 3 does in regard to awaiting schema agreement's API,
   • what was recently done in Rust driver in regard to tracing info's API,

   the API of awaiting schema agreement is altered so that:

   • await_timed_schema_agreement(), which takes explicit timeout, is
     removed,
   • await_schema_agreement() is now bound with a timeout that is set
     globally per-Session in SessionConfig.

   The motivation is that it could lead to application's deadlock when await_schema_agreement() was called with no timeout given and the cluster stoped synchronising (so schema agreement would be never reached), It is rarely desirable to block the calling application for arbitrarily long time, especially that some extreme situations are possible, such as a network partition between nodes.

3. SessionBuilders API is accomodated to the changes. Docs are updated as well.

Bonus

• missing docstrings were added for AddressTranslator.

Refs: #660

Pre-review checklist

• I have split my patch into logically separate commits.
• All commit messages clearly explain what they change and why.
• [ ] I added relevant tests for new features and bug fixes.
• All commits compile, pass static checks and pass test.
• PR description sums up the changes and reasons why they should be introduced.
• I have provided docstrings for the public items that I want to introduce.
• I have adjusted the documentation in ./docs/source/.
• [ ] I added appropriate Fixes: annotations to PR description.

[avelanarius]

Suggested change

	) -> Result<Option<Uuid>, QueryError> {
	) -> Result<Uuid, QueryError> {

maybe the timeout should be represented as a timeout QueryError?

[wprzytula]

Good idea!

[wprzytula]

The only problem I see here is that we lose a way to conveniently distinguish cases of timeout (not yet in agreement) from cases of server-side or connection-related errors.

In version with Option<Uuid>:

if session
        .await_schema_agreement(Duration::from_secs(5))
        .await?
        .is_some()
    {
        println!("Schema is in agreement in time");
    } else {
        println!("Schema is NOT in agreement in time");
    }

whereas in the version you proposed:

match session
    .await_schema_agreement(Duration::from_secs(5))
    .await {
    Ok(_schema_version) => println!("Schema is in agreement in time"),
    Err(QueryError::RequestTimeout(_)) => println!("Schema is NOT in agreement in time"),
    err => return err,
};

[wprzytula]

I've implemented it anyway.

[wprzytula]

I've documented automatic schema agreement awaiting.

[piodul]

Requires a rebase and dropping one of the commits, but otherwise LGTM.

[wprzytula]

Rebased and got rid of irrelevant commit.

[piodul]

Thanks. I'll merge after the CI checks finish.