mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The time budget of one phase, and telling the server when it runs out.
//!
//! # Why giving up is not enough
//!
//! Dropping the future that is waiting for an answer stops this process caring
//! about the answer. It does not stop the server producing it. The heavy scan
//! the caller gave up on keeps holding the same locks and burning the same
//! disk for as long as it would have taken anyway, and the caller who set a
//! five second limit has no idea.
//!
//! So when the budget runs out the server is asked to stop as well. That ask
//! cannot travel on the connection that is busy waiting, so it needs a second
//! one, and a second connection on every invocation would double the sessions
//! this product opens for the sake of a case that usually never happens. The
//! second connection is therefore opened only at the moment the budget runs
//! out, through [`ServerAbort`], which the connection layer implements.
//!
//! # What the ask cannot reach
//!
//! The ask does not reach work running inside a stored routine. When the
//! budget runs out there, the outcome says so rather than claiming the work
//! stopped.

use crate::error::{Failure, Result};
use std::future::Future;
use std::pin::Pin;
use std::time::Duration;

/// Which part of the invocation the budget covers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Phase {
    /// Reaching the server.
    Connect,
    /// Having the credential accepted.
    Authenticate,
    /// Running the caller's statement.
    Query,
}

impl Phase {
    /// The stable identifier this phase carries in a failure.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Connect => "connect",
            Self::Authenticate => "authenticate",
            Self::Query => "query",
        }
    }
}

/// What became of the ask to stop the work on the server.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AbortOutcome {
    /// The server confirmed the work is no longer running.
    Confirmed,
    /// The ask did not reach the server, so the work may still be running.
    NotReached,
}

/// The future an implementation of [`ServerAbort`] hands back.
pub type AbortFuture<'a> = Pin<Box<dyn Future<Output = Result<AbortOutcome>> + Send + 'a>>;

/// Asking the server to stop work this process has given up on.
///
/// The implementation opens a second connection at the moment it is called and
/// closes it before returning, so an invocation that never runs out of time
/// never opens one.
pub trait ServerAbort {
    /// Asks the server to stop the work of the given session, and confirms it.
    ///
    /// # Errors
    ///
    /// Returns a failure when the second connection could not be opened or the
    /// ask could not be sent, which the caller reports as work that may still
    /// be running on the server.
    fn abort(&self, session: u64) -> AbortFuture<'_>;
}

/// The failure a phase that went past its budget produces.
///
/// The phase and the limit are both in the message, because a caller who set
/// several limits needs to know which one was reached.
#[must_use]
pub fn exceeded(phase: Phase, limit: Duration) -> Failure {
    Failure::timeout(
        "timeout.phase_exceeded",
        format!(
            "the {} phase went past its limit of {} s",
            phase.as_str(),
            limit.as_secs_f64()
        ),
    )
    .with_detail(
        "detail",
        format!("{}, {} s", phase.as_str(), limit.as_secs_f64()),
    )
    .with_hint("raise the limit, or narrow the work so it fits inside it")
}

/// Runs the work, giving up when the budget runs out.
///
/// Nothing is asked of the server here. This is for phases where there is no
/// session to ask about yet, such as reaching the server in the first place.
///
/// # Errors
///
/// Returns a timeout failure naming the phase and the limit when the budget
/// runs out, and whatever the work itself failed with otherwise.
pub async fn within<T, Fut>(phase: Phase, limit: Duration, work: Fut) -> Result<T>
where
    Fut: Future<Output = Result<T>>,
{
    let Ok(outcome) = tokio::time::timeout(limit, work).await else {
        crate::i18n::report::budget_exceeded(phase.as_str(), limit.as_secs());
        return Err(exceeded(phase, limit));
    };
    outcome
}

/// Runs the work, and asks the server to stop it when the budget runs out.
///
/// The failure says plainly whether the server confirmed the work stopped. A
/// caller that must not leave heavy work behind can then decide what to do,
/// instead of assuming an abort that never arrived.
///
/// # Errors
///
/// Returns a timeout failure when the budget runs out, carrying either the
/// server's confirmation or the statement that the work may still be running
/// there. Returns whatever the work itself failed with otherwise.
pub async fn within_aborting<T, Fut, A>(
    phase: Phase,
    limit: Duration,
    session: u64,
    aborter: &A,
    work: Fut,
) -> Result<T>
where
    Fut: Future<Output = Result<T>>,
    A: ServerAbort + ?Sized,
{
    let Ok(outcome) = tokio::time::timeout(limit, work).await else {
        crate::i18n::report::budget_exceeded(phase.as_str(), limit.as_secs());
        return Err(with_abort_outcome(
            exceeded(phase, limit),
            aborter.abort(session).await,
        ));
    };
    outcome
}

/// Runs the work, asking the server to stop it when the budget runs out or the
/// caller cancels.
///
/// # Why cancelling has to reach the server too
///
/// The reason the budget asks the server to stop is the reason a signal has to:
/// a caller who gives up stops caring about the answer, and the server producing
/// it never hears about that. Until this existed, cancelling a slow statement
/// waited out the whole statement and then reported an interruption, which is
/// the one outcome that has neither the answer nor the time back.
///
/// # Why the work is dropped rather than awaited
///
/// The first shape of this sent the ask and then awaited the busy work, so that
/// the answer would be the server's own account of the statement it stopped.
/// Measured, that shape let the flow write the opening of its document and then
/// end without closing it: the primary channel came back as 161 bytes of JSON cut
/// mid-key. The budget path never had that problem because it drops the work, and
/// a channel nothing more writes to is a channel nothing can leave half-written.
///
/// So this drops first and asks second, exactly as the budget does. The two
/// paths differ only in what starts them.
///
/// # Errors
///
/// Returns an interruption failure carrying whether the server confirmed the
/// statement stopped. Returns a timeout failure when the budget runs out
/// instead, as [`within_aborting`] does.
pub async fn within_aborting_or_stopped<T, Fut, A>(
    phase: Phase,
    limit: Duration,
    session: u64,
    aborter: &A,
    stopping: &tokio_util::sync::CancellationToken,
    work: Fut,
) -> Result<T>
where
    Fut: Future<Output = Result<T>>,
    A: ServerAbort + ?Sized,
{
    tokio::select! {
        outcome = tokio::time::timeout(limit, work) => {
            let Ok(outcome) = outcome else {
                crate::i18n::report::budget_exceeded(phase.as_str(), limit.as_secs());
                return Err(with_abort_outcome(
                    exceeded(phase, limit),
                    aborter.abort(session).await,
                ));
            };
            outcome
        }
        () = stopping.cancelled() => {
            Err(with_abort_outcome(cancelled(), aborter.abort(session).await))
        }
    }
}

/// The failure a caller reads when their own cancellation ended the invocation.
fn cancelled() -> Failure {
    Failure::interrupted(
        "interrupted.by_caller",
        "the invocation was stopped by the caller",
    )
}

/// Attaches what became of the ask to stop the work to the timeout failure.
///
/// Kept apart from the round trip so the rule is provable without a server,
/// since it is the rule and not the network that decides what the caller reads.
#[must_use]
pub fn with_abort_outcome(failure: Failure, outcome: Result<AbortOutcome>) -> Failure {
    match outcome {
        Ok(AbortOutcome::Confirmed) => failure
            .with_cause("the server confirmed the work has stopped")
            .with_hint("the work is no longer running on the server"),
        Ok(AbortOutcome::NotReached) => failure
            .with_cause("the ask to stop did not reach the server")
            .with_hint("the work may still be running on the server"),
        Err(reason) => failure
            .with_cause(format!("the ask to stop failed: {reason}"))
            .with_hint("the work may still be running on the server"),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct Answering(AbortOutcome);

    impl ServerAbort for Answering {
        fn abort(&self, _session: u64) -> AbortFuture<'_> {
            let outcome = self.0;
            Box::pin(async move { Ok(outcome) })
        }
    }

    struct Unreachable;

    impl ServerAbort for Unreachable {
        fn abort(&self, _session: u64) -> AbortFuture<'_> {
            Box::pin(async {
                Err(Failure::network(
                    "network.unreachable",
                    "the second connection could not be opened",
                ))
            })
        }
    }

    #[test]
    fn every_phase_carries_its_own_identifier() {
        assert_eq!(Phase::Connect.as_str(), "connect");
        assert_eq!(Phase::Authenticate.as_str(), "authenticate");
        assert_eq!(Phase::Query.as_str(), "query");
    }

    #[test]
    fn a_budget_that_runs_out_names_the_phase_and_the_limit() {
        let failure = exceeded(Phase::Query, Duration::from_secs(5));
        assert_eq!(failure.exit_number().code(), 124);
        assert!(failure.message().contains("query"));
        assert!(failure.message().contains('5'));
    }

    #[test]
    fn a_confirmed_abort_says_the_work_is_no_longer_running() {
        let failure = with_abort_outcome(
            exceeded(Phase::Query, Duration::from_secs(1)),
            Ok(AbortOutcome::Confirmed),
        );
        assert!(failure
            .hint()
            .is_some_and(|hint| hint.contains("no longer running")));
    }

    #[test]
    fn an_abort_that_never_arrived_says_the_work_may_continue_there() {
        for outcome in [
            Ok(AbortOutcome::NotReached),
            Err(Failure::network("network.unreachable", "lost")),
        ] {
            let failure =
                with_abort_outcome(exceeded(Phase::Query, Duration::from_secs(1)), outcome);
            assert!(
                failure
                    .hint()
                    .is_some_and(|hint| hint.contains("may still be running")),
                "the caller must never assume an abort that did not arrive"
            );
            assert_eq!(failure.exit_number().code(), 124);
        }
    }

    #[tokio::test]
    async fn work_that_fits_inside_the_budget_is_handed_straight_through() {
        let value = within(Phase::Query, Duration::from_secs(30), async {
            Ok::<u8, Failure>(7)
        })
        .await
        .expect("fits");
        assert_eq!(value, 7);
    }

    #[tokio::test]
    async fn work_that_goes_past_the_budget_ends_in_the_published_number() {
        let failure = within(Phase::Connect, Duration::from_millis(10), async {
            tokio::time::sleep(Duration::from_secs(30)).await;
            Ok::<u8, Failure>(7)
        })
        .await
        .expect_err("must run out");
        assert_eq!(failure.exit_number().code(), 124);
        assert!(failure.message().contains("connect"));
    }

    #[tokio::test]
    async fn running_out_of_time_asks_the_server_to_stop_as_well() {
        let failure = within_aborting(
            Phase::Query,
            Duration::from_millis(10),
            42,
            &Answering(AbortOutcome::Confirmed),
            async {
                tokio::time::sleep(Duration::from_secs(30)).await;
                Ok::<u8, Failure>(7)
            },
        )
        .await
        .expect_err("must run out");
        assert!(failure
            .causes()
            .iter()
            .any(|cause| cause.contains("confirmed")));
    }

    #[tokio::test]
    async fn an_ask_that_fails_is_declared_rather_than_hidden() {
        let failure = within_aborting(
            Phase::Query,
            Duration::from_millis(10),
            42,
            &Unreachable,
            async {
                tokio::time::sleep(Duration::from_secs(30)).await;
                Ok::<u8, Failure>(7)
            },
        )
        .await
        .expect_err("must run out");
        assert!(failure
            .hint()
            .is_some_and(|hint| hint.contains("may still be running")));
    }

    #[tokio::test]
    async fn work_that_fits_never_opens_the_second_connection() {
        struct NeverCalled;
        impl ServerAbort for NeverCalled {
            fn abort(&self, _session: u64) -> AbortFuture<'_> {
                Box::pin(async {
                    Err(Failure::server(
                        "server.unclassified",
                        "the second connection must never be opened here",
                    ))
                })
            }
        }

        within_aborting(
            Phase::Query,
            Duration::from_secs(30),
            42,
            &NeverCalled,
            async { Ok::<u8, Failure>(7) },
        )
        .await
        .expect("fits inside the budget");
    }
}