#[cfg(all(feature = "blocking", target_arch = "wasm32"))]
compile_error!(
"neotales-dbapi's blocking feature is unsupported on wasm32; disable it and consult your provider's supported APIs"
);
#[cfg(all(feature = "blocking", not(target_arch = "wasm32")))]
pub mod blocking;
pub mod local;
pub mod paging;
pub mod sync;
pub use neotales_resilience::{Cancellation, Delay};
use neotales_resilience::{
RetryOutcome, RetryPolicy as ResilienceRetryPolicy, execute_idempotent_retry,
};
use std::{
collections::VecDeque,
error::Error,
fmt,
future::{Future, poll_fn},
panic::{AssertUnwindSafe, catch_unwind},
pin::Pin,
sync::{
Arc, Mutex, Weak,
atomic::{AtomicBool, Ordering},
},
task::{Context, Poll},
time::{Duration, Instant},
};
pub type DbFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, DbError>> + Send + 'a>>;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DbType {
Bool,
I64,
F64,
Text,
Bytes,
}
#[derive(Clone, Debug, PartialEq)]
pub enum Value {
Null(DbType),
Bool(bool),
I64(i64),
F64(f64),
Text(String),
Bytes(Vec<u8>),
}
impl Value {
pub fn validate(&self) -> Result<(), DbError> {
if matches!(self, Self::F64(value) if !value.is_finite()) {
Err(DbError::invalid(InvalidArgumentReason::NonFiniteFloat))
} else {
Ok(())
}
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct Parameter {
db_type: DbType,
value: Value,
}
impl Parameter {
pub fn new(db_type: DbType, value: Value) -> Result<Self, DbError> {
let matches = matches!((&value, db_type), (Value::Null(t), expected) if *t == expected)
|| matches!(
(&value, db_type),
(Value::Bool(_), DbType::Bool)
| (Value::I64(_), DbType::I64)
| (Value::F64(_), DbType::F64)
| (Value::Text(_), DbType::Text)
| (Value::Bytes(_), DbType::Bytes)
);
if !matches {
return Err(DbError::invalid(
InvalidArgumentReason::ParameterTypeMismatch,
));
}
value.validate()?;
Ok(Self { db_type, value })
}
#[must_use]
pub const fn db_type(&self) -> DbType {
self.db_type
}
#[must_use]
pub fn value(&self) -> &Value {
&self.value
}
}
#[allow(clippy::struct_excessive_bools)] #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct Capabilities {
pub transactions: bool,
pub isolation_level: bool,
pub read_only_transactions: bool,
pub trusted_scripts: bool,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IsolationLevel {
Serializable,
RepeatableRead,
ReadCommitted,
ReadUncommitted,
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct TxOptions {
pub isolation: Option<IsolationLevel>,
pub read_only: Option<bool>,
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ExecuteOptions {
pub timeout_ms: Option<u64>,
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum QuerySetting {
#[default]
Inherit,
Off,
On,
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum ReplaySafety {
#[default]
Never,
ExplicitlyReplaySafe,
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum RetryPolicy {
#[default]
Disabled,
Enabled {
policy: ResilienceRetryPolicy,
retry_timeouts: bool,
},
}
impl RetryPolicy {
pub fn new(
max_attempts: u32,
delay: Delay,
retry_timeouts: bool,
) -> Result<Self, InvalidRetryPolicy> {
let policy =
ResilienceRetryPolicy::new(max_attempts, delay).map_err(|_| InvalidRetryPolicy)?;
Ok(Self::Enabled {
policy,
retry_timeouts,
})
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct InvalidRetryPolicy;
impl fmt::Display for InvalidRetryPolicy {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("retry policy requires at least one attempt")
}
}
impl Error for InvalidRetryPolicy {}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum RetrySetting {
#[default]
Inherit,
Off,
Use(RetryPolicy),
}
pub struct RetryRuntime {
cancellation: Arc<Cancellation>,
timer: Arc<dyn Fn() -> RetryWait + Send + Sync>,
sleep: Arc<dyn Fn(Duration) -> RetryWait + Send + Sync>,
random: Arc<dyn Fn() -> u64 + Send + Sync>,
dispatch: Option<Weak<RetryDispatch>>,
}
impl Clone for RetryRuntime {
fn clone(&self) -> Self {
Self {
cancellation: Arc::clone(&self.cancellation),
timer: Arc::clone(&self.timer),
sleep: Arc::clone(&self.sleep),
random: Arc::clone(&self.random),
dispatch: self.dispatch.clone(),
}
}
}
pub type RetryWait = Pin<Box<dyn Future<Output = ()> + Send>>;
impl RetryRuntime {
pub fn new(
cancellation: Arc<Cancellation>,
timer: impl Fn() -> RetryWait + Send + Sync + 'static,
sleep: impl Fn(Duration) -> RetryWait + Send + Sync + 'static,
random: impl Fn() -> u64 + Send + Sync + 'static,
) -> Self {
Self {
cancellation,
timer: Arc::new(timer),
sleep: Arc::new(sleep),
random: Arc::new(random),
dispatch: None,
}
}
}
impl fmt::Debug for RetryRuntime {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("RetryRuntime")
.field("cancelled", &self.cancellation.is_cancelled())
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TelemetryOutcome {
Success,
Error(ErrorKind),
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Operation {
Execute,
Fetch,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct DbEvent {
pub operation: Operation,
pub duration: Duration,
pub outcome: TelemetryOutcome,
pub sql: Option<String>,
}
pub type SqlCaptureHook = Arc<dyn Fn(&str) -> Option<String> + Send + Sync>;
pub type DbObserver = Arc<dyn Fn(&DbEvent) + Send + Sync>;
#[derive(Clone)]
pub struct PoolPolicy {
pub telemetry_enabled: bool,
pub sql_capture_enabled: bool,
pub sql_hook: Option<SqlCaptureHook>,
pub observer: Option<DbObserver>,
pub retry: RetryPolicy,
pub retry_runtime: Option<RetryRuntime>,
pub default_timeout: Option<Duration>,
pub default_limit: RowLimit,
}
impl Default for PoolPolicy {
fn default() -> Self {
let defaults = PoolDefaults::default();
Self {
telemetry_enabled: defaults.telemetry_enabled,
sql_capture_enabled: defaults.sql_capture_enabled,
sql_hook: None,
observer: None,
retry: defaults.retry,
retry_runtime: None,
default_timeout: defaults.timeout,
default_limit: defaults.limit,
}
}
}
fn policy_defaults(policy: &PoolPolicy) -> PoolDefaults {
PoolDefaults {
timeout: policy.default_timeout,
limit: policy.default_limit,
telemetry_enabled: policy.telemetry_enabled,
sql_capture_enabled: policy.sql_capture_enabled,
retry: policy.retry,
}
}
impl fmt::Debug for PoolPolicy {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PoolPolicy")
.field("telemetry_enabled", &self.telemetry_enabled)
.field("sql_capture_enabled", &self.sql_capture_enabled)
.field("has_sql_hook", &self.sql_hook.is_some())
.field("has_observer", &self.observer.is_some())
.field("retry", &self.retry)
.field("has_retry_runtime", &self.retry_runtime.is_some())
.field("default_timeout", &self.default_timeout)
.field("default_limit", &self.default_limit)
.finish()
}
}
#[derive(Clone, Default)]
pub struct QueryOptions {
pub parameters: Vec<Parameter>,
pub timeout: TimeoutSetting,
pub limit: LimitSetting,
execute: ExecuteOptions,
pub telemetry: QuerySetting,
pub sql_capture: QuerySetting,
pub sql_hook: Option<SqlCaptureHook>,
pub retry: RetrySetting,
pub replay_safety: ReplaySafety,
pub retry_runtime: Option<RetryRuntime>,
policy_applied: bool,
}
impl fmt::Debug for QueryOptions {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("QueryOptions")
.field("parameter_count", &self.parameters.len())
.field("timeout", &self.timeout)
.field("limit", &self.limit)
.field("execute", &self.execute)
.field("telemetry", &self.telemetry)
.field("sql_capture", &self.sql_capture)
.field("has_sql_hook", &self.sql_hook.is_some())
.field("retry", &self.retry)
.field("replay_safety", &self.replay_safety)
.field("has_retry_runtime", &self.retry_runtime.is_some())
.finish_non_exhaustive()
}
}
impl QueryOptions {
#[must_use]
pub fn provider_execute_options(&self) -> ExecuteOptions {
self.execute
}
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn bind(mut self, parameter: Parameter) -> Self {
self.parameters.push(parameter);
self
}
#[must_use]
pub fn bind_all(mut self, parameters: &[Parameter]) -> Self {
self.parameters.extend_from_slice(parameters);
self
}
pub fn bind_f64(mut self, value: f64) -> Result<Self, DbError> {
self.parameters
.push(Parameter::new(DbType::F64, Value::F64(value))?);
Ok(self)
}
#[must_use]
pub fn bind_null(mut self, db_type: DbType) -> Self {
self.parameters.push(Parameter {
db_type,
value: Value::Null(db_type),
});
self
}
#[must_use]
pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = TimeoutSetting::Set(timeout);
self
}
#[must_use]
pub fn no_timeout(mut self) -> Self {
self.timeout = TimeoutSetting::Disabled;
self
}
#[must_use]
pub fn limit(mut self, limit: RowLimit) -> Self {
self.limit = LimitSetting::Set(limit);
self
}
#[must_use]
pub fn telemetry(mut self, setting: QuerySetting) -> Self {
self.telemetry = setting;
self
}
#[must_use]
pub fn sql_capture(mut self, setting: QuerySetting) -> Self {
self.sql_capture = setting;
self
}
#[must_use]
pub fn retry(mut self, setting: RetrySetting) -> Self {
self.retry = setting;
self
}
#[must_use]
pub fn sql_hook(mut self, hook: SqlCaptureHook) -> Self {
self.sql_hook = Some(hook);
self
}
#[must_use]
pub fn retry_runtime(mut self, runtime: RetryRuntime) -> Self {
self.retry_runtime = Some(runtime);
self
}
#[must_use]
pub fn replay_safe(mut self) -> Self {
self.replay_safety = ReplaySafety::ExplicitlyReplaySafe;
self
}
#[must_use]
pub fn resolved_timeout(&self, defaults: PoolDefaults) -> Option<Duration> {
match self.timeout {
TimeoutSetting::Inherit => defaults.timeout,
TimeoutSetting::Disabled => None,
TimeoutSetting::Set(timeout) => Some(timeout),
}
}
#[must_use]
pub fn resolved_limit(&self, defaults: PoolDefaults) -> RowLimit {
match self.limit {
LimitSetting::Inherit => defaults.limit,
LimitSetting::Set(limit) => limit,
}
}
pub fn prepare_provider(&mut self, defaults: PoolDefaults) -> Result<RowLimit, DbError> {
if !self.policy_applied {
reject_unhandled_pool_options(self)?;
}
let limit = self.resolved_limit(defaults);
self.limit = LimitSetting::Set(limit);
resolve_provider_timeout(self, defaults.timeout)?;
Ok(limit)
}
pub fn validate_execute(&self) -> Result<(), DbError> {
if matches!(self.limit, LimitSetting::Set(_)) {
return Err(DbError::new(ErrorKind::InvalidArgument));
}
Ok(())
}
pub fn prepare_execute_provider(&mut self, defaults: PoolDefaults) -> Result<(), DbError> {
self.validate_execute()?;
self.prepare_provider(defaults)?;
Ok(())
}
pub fn validate_script(&self) -> Result<(), DbError> {
if !self.parameters.is_empty() || !matches!(self.limit, LimitSetting::Inherit) {
return Err(DbError::new(ErrorKind::InvalidArgument));
}
Ok(())
}
pub fn prepare_script_provider(&mut self, defaults: PoolDefaults) -> Result<(), DbError> {
self.validate_script()?;
self.prepare_provider(defaults)?;
Ok(())
}
}
fn resolve_provider_timeout(
options: &mut QueryOptions,
default: Option<Duration>,
) -> Result<(), DbError> {
let timeout = match options.timeout {
TimeoutSetting::Inherit => default,
TimeoutSetting::Disabled => None,
TimeoutSetting::Set(timeout) => Some(timeout),
};
options.timeout = timeout.map_or(TimeoutSetting::Disabled, TimeoutSetting::Set);
options.execute.timeout_ms = timeout
.map(|value| {
u64::try_from(
value
.as_millis()
.saturating_add(u128::from(value.subsec_nanos() % 1_000_000 != 0)),
)
.map_err(|_| DbError::new(ErrorKind::InvalidArgument))
})
.transpose()?;
Ok(())
}
fn reject_unhandled_pool_options(options: &QueryOptions) -> Result<(), DbError> {
if options.telemetry == QuerySetting::On
|| options.sql_capture == QuerySetting::On
|| options.sql_hook.is_some()
|| matches!(
options.retry,
RetrySetting::Use(RetryPolicy::Enabled { .. })
)
|| options.retry_runtime.is_some()
{
return Err(DbError::new(ErrorKind::Unsupported));
}
Ok(())
}
fn reject_session_retry(options: &QueryOptions) -> Result<(), DbError> {
if !options.policy_applied
&& (matches!(
options.retry,
RetrySetting::Use(RetryPolicy::Enabled { .. })
) || options.retry_runtime.is_some())
{
return Err(DbError::new(ErrorKind::Unsupported));
}
Ok(())
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RowLimit {
rows: usize,
bytes: usize,
max_sets: usize,
}
impl RowLimit {
pub fn new(rows: usize, bytes: usize) -> Result<Self, DbError> {
Self::with_max_sets(rows, bytes, 1)
}
pub fn with_max_sets(rows: usize, bytes: usize, max_sets: usize) -> Result<Self, DbError> {
if rows == 0 {
return Err(DbError::invalid(InvalidArgumentReason::ZeroFetchRowLimit));
}
if bytes == 0 {
return Err(DbError::invalid(InvalidArgumentReason::ZeroByteLimit));
}
if max_sets == 0 {
return Err(DbError::invalid(InvalidArgumentReason::ZeroSetLimit));
}
Ok(Self {
rows,
bytes,
max_sets,
})
}
#[must_use]
pub const fn rows(self) -> usize {
self.rows
}
#[must_use]
pub const fn bytes(self) -> usize {
self.bytes
}
#[must_use]
pub const fn max_sets(self) -> usize {
self.max_sets
}
}
impl Default for RowLimit {
fn default() -> Self {
Self {
rows: 1_000,
bytes: 1_048_576,
max_sets: 1,
}
}
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum TimeoutSetting {
#[default]
Inherit,
Disabled,
Set(Duration),
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum LimitSetting {
#[default]
Inherit,
Set(RowLimit),
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PoolDefaults {
pub timeout: Option<Duration>,
pub limit: RowLimit,
pub telemetry_enabled: bool,
pub sql_capture_enabled: bool,
pub retry: RetryPolicy,
}
impl Default for PoolDefaults {
fn default() -> Self {
Self {
timeout: None,
limit: RowLimit::default(),
telemetry_enabled: false,
sql_capture_enabled: false,
retry: RetryPolicy::Disabled,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ErrorKind {
InvalidArgument,
Constraint,
Busy,
Timeout,
Cancelled,
Unsupported,
Reentrant,
Decode,
Connection,
WriteOutcomeUnknown,
CommitOutcomeUnknown,
Missing,
NoRows,
TooManyRows,
Ambiguous,
Null,
Overflow,
WrongType,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DbError {
kind: ErrorKind,
reason: Option<InvalidArgumentReason>,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InvalidArgumentReason {
ParameterTypeMismatch,
NonFiniteFloat,
ZeroFetchRowLimit,
ZeroByteLimit,
ZeroSetLimit,
}
impl DbError {
#[must_use]
pub const fn new(kind: ErrorKind) -> Self {
Self { kind, reason: None }
}
#[must_use]
pub const fn invalid(reason: InvalidArgumentReason) -> Self {
Self {
kind: ErrorKind::InvalidArgument,
reason: Some(reason),
}
}
#[must_use]
pub const fn reason(self) -> Option<InvalidArgumentReason> {
self.reason
}
#[must_use]
pub const fn kind(self) -> ErrorKind {
self.kind
}
}
impl fmt::Display for DbError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self.reason {
Some(reason) => write!(f, "invalid database argument ({reason:?})"),
None => write!(f, "database operation failed ({:?})", self.kind),
}
}
}
impl Error for DbError {}
#[derive(Clone, Debug, PartialEq)]
pub struct Row {
columns: Vec<(String, Value)>,
}
impl Row {
pub fn new(columns: Vec<(String, Value)>) -> Result<Self, DbError> {
for (_, value) in &columns {
value.validate()?;
}
Ok(Self { columns })
}
#[must_use]
pub fn len(&self) -> usize {
self.columns.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.columns.is_empty()
}
pub fn get_ordinal<T: FromValue>(&self, ordinal: usize) -> Result<T, DbError> {
let (_, value) = self
.columns
.get(ordinal)
.ok_or_else(|| DbError::new(ErrorKind::Missing))?;
T::from_value(value)
}
pub fn get<T: FromValue>(&self, name: &str) -> Result<T, DbError> {
let mut found = self.columns.iter().filter(|(column, _)| column == name);
let (_, value) = found
.next()
.ok_or_else(|| DbError::new(ErrorKind::Missing))?;
if found.next().is_some() {
return Err(DbError::new(ErrorKind::Ambiguous));
}
T::from_value(value)
}
pub fn read<T: FromValue>(&self, name: &str) -> Result<T, DbError> {
self.get(name)
}
pub fn read_at<T: FromValue>(&self, ordinal: usize) -> Result<T, DbError> {
self.get_ordinal(ordinal)
}
pub fn value_at(&self, ordinal: usize) -> Result<Value, DbError> {
self.columns
.get(ordinal)
.map(|(_, value)| value.clone())
.ok_or_else(|| DbError::new(ErrorKind::Missing))
}
pub fn encoded_bytes(&self) -> Result<usize, DbError> {
self.columns
.iter()
.try_fold(0usize, |total, (name, value)| {
let payload = match value {
Value::Null(_) => 0,
Value::Bool(_) => 1,
Value::I64(_) | Value::F64(_) => 8,
Value::Text(value) => value.len(),
Value::Bytes(value) => value.len(),
};
total
.checked_add(name.len())
.and_then(|total| total.checked_add(payload))
.ok_or_else(|| DbError::new(ErrorKind::Overflow))
})
}
pub fn require<T: FromValue>(&self, name: &str) -> Result<T, DbError> {
let mut found = self.columns.iter().filter(|(column, _)| column == name);
let (_, value) = found
.next()
.ok_or_else(|| DbError::new(ErrorKind::Missing))?;
if found.next().is_some() {
return Err(DbError::new(ErrorKind::Ambiguous));
}
if let Value::Null(actual_type) = value {
return Err(DbError::new(if *actual_type == T::DB_TYPE {
ErrorKind::Null
} else {
ErrorKind::WrongType
}));
}
T::from_value(value)
}
pub fn require_ordinal<T: FromValue>(&self, ordinal: usize) -> Result<T, DbError> {
let (_, value) = self
.columns
.get(ordinal)
.ok_or_else(|| DbError::new(ErrorKind::Missing))?;
if let Value::Null(actual_type) = value {
return Err(DbError::new(if *actual_type == T::DB_TYPE {
ErrorKind::Null
} else {
ErrorKind::WrongType
}));
}
T::from_value(value)
}
}
pub trait FromValue: Sized {
const DB_TYPE: DbType;
fn from_value(value: &Value) -> Result<Self, DbError>;
}
macro_rules! exact_from {
($ty:ty, $variant:ident, $db:ident) => {
impl FromValue for $ty {
const DB_TYPE: DbType = DbType::$db;
fn from_value(value: &Value) -> Result<Self, DbError> {
match value {
Value::Null(DbType::$db) => Err(DbError::new(ErrorKind::Null)),
Value::Null(_) => Err(DbError::new(ErrorKind::WrongType)),
Value::$variant(value) => Ok(value.clone()),
_ => Err(DbError::new(ErrorKind::WrongType)),
}
}
}
};
}
impl<T: FromValue> FromValue for Option<T> {
const DB_TYPE: DbType = T::DB_TYPE;
fn from_value(value: &Value) -> Result<Self, DbError> {
match value {
Value::Null(db_type) if *db_type == T::DB_TYPE => Ok(None),
Value::Null(_) => Err(DbError::new(ErrorKind::WrongType)),
non_null => T::from_value(non_null).map(Some),
}
}
}
exact_from!(bool, Bool, Bool);
exact_from!(i64, I64, I64);
exact_from!(f64, F64, F64);
exact_from!(String, Text, Text);
exact_from!(Vec<u8>, Bytes, Bytes);
impl FromValue for i32 {
const DB_TYPE: DbType = DbType::I64;
fn from_value(value: &Value) -> Result<Self, DbError> {
match value {
Value::Null(DbType::I64) => Err(DbError::new(ErrorKind::Null)),
Value::I64(value) => {
i32::try_from(*value).map_err(|_| DbError::new(ErrorKind::Overflow))
}
_ => Err(DbError::new(ErrorKind::WrongType)),
}
}
}
pub trait Reader: Send {
fn next_row_async(&mut self) -> DbFuture<'_, Option<Row>>;
fn has_next_set_async(&mut self) -> DbFuture<'_, bool>;
fn finish_async(&mut self) -> DbFuture<'_, ()>;
fn read_all_async(&mut self) -> DbFuture<'_, Vec<Row>> {
Box::pin(async move {
Ok(self
.read_sets_async()
.await?
.into_iter()
.flatten()
.collect())
})
}
fn read_sets_async(&mut self) -> DbFuture<'_, Vec<Vec<Row>>> {
Box::pin(async move {
let mut sets = Vec::new();
loop {
let mut set = Vec::new();
while let Some(row) = self.next_row_async().await? {
set.push(row);
}
sets.push(set);
if !self.has_next_set_async().await? {
break;
}
}
self.finish_async().await?;
Ok(sets)
})
}
}
#[derive(Debug)]
pub struct BufferedReader {
sets: VecDeque<VecDeque<Row>>,
done: bool,
}
impl BufferedReader {
#[must_use]
pub fn new(rows: Vec<Row>) -> Self {
Self::from_sets(vec![rows])
}
#[must_use]
pub fn from_sets(sets: Vec<Vec<Row>>) -> Self {
Self {
sets: sets.into_iter().map(VecDeque::from).collect(),
done: false,
}
}
}
impl Reader for BufferedReader {
fn next_row_async(&mut self) -> DbFuture<'_, Option<Row>> {
let row = if self.done {
None
} else {
self.sets
.front_mut()
.and_then(std::collections::VecDeque::pop_front)
};
Box::pin(async move { Ok(row) })
}
fn has_next_set_async(&mut self) -> DbFuture<'_, bool> {
if self.done {
return Box::pin(async { Ok(false) });
}
self.sets.pop_front();
let more = !self.sets.is_empty();
if !more {
self.done = true;
}
Box::pin(async move { Ok(more) })
}
fn finish_async(&mut self) -> DbFuture<'_, ()> {
self.sets.clear();
self.done = true;
Box::pin(async { Ok(()) })
}
}
fn row_cardinality_error(more_than_one: bool) -> DbError {
DbError::new(if more_than_one {
ErrorKind::TooManyRows
} else {
ErrorKind::NoRows
})
}
pub trait Pool: Send + Sync {
fn capabilities(&self) -> Capabilities;
fn defaults(&self) -> PoolDefaults {
PoolDefaults::default()
}
fn acquire_async(&self) -> DbFuture<'_, Box<dyn Session>>;
fn execute_async<'a>(&'a self, sql: &'a str, mut options: QueryOptions) -> DbFuture<'a, u64> {
Box::pin(async move {
options.validate_execute()?;
reject_unhandled_pool_options(&options)?;
resolve_provider_timeout(&mut options, self.defaults().timeout)?;
let mut session = self.acquire_async().await?;
session.execute_async(sql, options).await
})
}
fn fetch_async<'a>(
&'a self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
Box::pin(async move {
reject_unhandled_pool_options(&options)?;
let limit = options.resolved_limit(self.defaults());
options.limit = LimitSetting::Set(limit);
resolve_provider_timeout(&mut options, self.defaults().timeout)?;
let mut session = self.acquire_async().await?;
let mut reader = session.fetch_async(sql, options).await?;
let sets = collect_sets(reader.as_mut(), limit).await?;
Ok(Box::new(BufferedReader::from_sets(sets)) as Box<dyn Reader + 'a>)
})
}
fn fetch_all_async<'a>(
&'a self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Vec<Row>> {
Box::pin(async move {
let limit = options.resolved_limit(self.defaults());
let mut reader = self.fetch_async(sql, options).await?;
let sets = collect_sets(reader.as_mut(), limit).await?;
Ok(sets.into_iter().flatten().collect())
})
}
fn fetch_first_async<'a>(
&'a self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Option<Row>> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
reader.finish_async().await?;
Ok(first)
})
}
fn fetch_one_async<'a>(&'a self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, Row> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
let more = reader.next_row_async().await?.is_some();
reader.finish_async().await?;
match first {
None => Err(row_cardinality_error(false)),
Some(_) if more => Err(row_cardinality_error(true)),
Some(row) => Ok(row),
}
})
}
fn fetch_scalar_async<'a>(
&'a self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Value> {
Box::pin(async move {
let row = self.fetch_one_async(sql, options).await?;
row.value_at(0)
})
}
}
pub trait Session: Send {
fn defaults(&self) -> PoolDefaults {
PoolDefaults::default()
}
fn execute_async<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, u64>;
fn fetch_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>>;
fn fetch_all_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Vec<Row>> {
let limit = options.resolved_limit(self.defaults());
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let sets = collect_sets(reader.as_mut(), limit).await?;
Ok(sets.into_iter().flatten().collect())
})
}
fn fetch_first_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Option<Row>> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
reader.finish_async().await?;
Ok(first)
})
}
fn fetch_one_async<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, Row> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
let more = reader.next_row_async().await?.is_some();
reader.finish_async().await?;
match first {
None => Err(row_cardinality_error(false)),
Some(_) if more => Err(row_cardinality_error(true)),
Some(row) => Ok(row),
}
})
}
fn fetch_scalar_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Value> {
Box::pin(async move {
let row = self.fetch_one_async(sql, options).await?;
row.value_at(0)
})
}
fn execute_trusted_script_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, ()>;
fn begin_async<'a>(
&'a mut self,
options: TxOptions,
) -> DbFuture<'a, Box<dyn Transaction<'a> + 'a>>;
}
pub trait Transaction<'session>: Send {
fn defaults(&self) -> PoolDefaults {
PoolDefaults::default()
}
fn execute_async<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, u64>;
fn fetch_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>>;
fn fetch_all_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Vec<Row>> {
let limit = options.resolved_limit(self.defaults());
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let sets = collect_sets(reader.as_mut(), limit).await?;
Ok(sets.into_iter().flatten().collect())
})
}
fn fetch_first_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Option<Row>> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
reader.finish_async().await?;
Ok(first)
})
}
fn fetch_one_async<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, Row> {
Box::pin(async move {
let mut reader = self.fetch_async(sql, options).await?;
let first = reader.next_row_async().await?;
let more = reader.next_row_async().await?.is_some();
reader.finish_async().await?;
match first {
None => Err(row_cardinality_error(false)),
Some(_) if more => Err(row_cardinality_error(true)),
Some(row) => Ok(row),
}
})
}
fn fetch_scalar_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Value> {
Box::pin(async move {
let row = self.fetch_one_async(sql, options).await?;
row.value_at(0)
})
}
fn execute_trusted_script_async<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, ()>;
fn commit_async(self: Box<Self>) -> DbFuture<'session, ()>;
fn rollback_async(self: Box<Self>) -> DbFuture<'session, ()>;
}
pub trait ImmediateTransaction: Session {
fn begin_immediate_async<'a>(&'a mut self) -> DbFuture<'a, Box<dyn Transaction<'a> + 'a>>;
}
pub trait SqlitePool: Pool {
fn busy_timeout(&self) -> Duration;
fn acquire_sqlite_async(&self) -> DbFuture<'_, Box<dyn ImmediateTransaction>>;
}
pub struct PolicyPool {
inner: Arc<dyn Pool>,
policy: Arc<PoolPolicy>,
}
impl fmt::Debug for PolicyPool {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PolicyPool")
.field("policy", &self.policy)
.finish_non_exhaustive()
}
}
impl PolicyPool {
pub fn new<P: Pool + 'static>(pool: P, policy: PoolPolicy) -> Self {
Self::from_shared(Arc::new(pool), policy)
}
#[must_use]
pub fn from_shared(pool: Arc<dyn Pool>, mut policy: PoolPolicy) -> Self {
if policy.default_timeout.is_none() {
policy.default_timeout = pool.defaults().timeout;
}
Self {
inner: pool,
policy: Arc::new(policy),
}
}
}
impl Pool for PolicyPool {
fn capabilities(&self) -> Capabilities {
self.inner.capabilities()
}
fn defaults(&self) -> PoolDefaults {
policy_defaults(&self.policy)
}
fn acquire_async(&self) -> DbFuture<'_, Box<dyn Session>> {
let inner = Arc::clone(&self.inner);
let policy = Arc::clone(&self.policy);
Box::pin(async move {
let session = inner.acquire_async().await?;
Ok(Box::new(PolicySession { session, policy }) as Box<dyn Session>)
})
}
fn execute_async<'a>(&'a self, sql: &'a str, mut options: QueryOptions) -> DbFuture<'a, u64> {
let pool = Arc::clone(&self.inner);
let policy = Arc::clone(&self.policy);
Box::pin(async move {
options.validate_execute()?;
resolve_provider_timeout(&mut options, policy.default_timeout)?;
let retry = resolve_retry(options.retry, policy.retry);
if options.replay_safety == ReplaySafety::ExplicitlyReplaySafe
&& let RetryPolicy::Enabled {
policy: retry_policy,
retry_timeouts,
} = retry
{
let Some(mut runtime) = options
.retry_runtime
.clone()
.or_else(|| policy.retry_runtime.clone())
else {
return Err(DbError::new(ErrorKind::Unsupported));
};
let dispatch = RetryDispatch::for_operation(&mut runtime);
let cancellation = Arc::clone(&dispatch.cancellation);
let deadline = dispatch.deadline.clone();
let attempt_state = Arc::clone(&dispatch.state);
let mut options = options;
options.retry_runtime = Some(runtime.clone());
let retry_if = |error: &DbError| {
retry_allowed(*error, retry_timeouts, &cancellation, &deadline)
};
let outcome = execute_idempotent_retry(
retry_policy,
&cancellation,
deadline.clone(),
|| {
let pool = Arc::clone(&pool);
let policy = Arc::clone(&policy);
let cancellation = Arc::clone(&cancellation);
let deadline = deadline.clone();
let attempt_state = Arc::clone(&attempt_state);
let options = options.clone();
async move {
attempt_state.reset();
deadline.check(&cancellation).await?;
let mut session = pool.acquire_async().await?;
let result = execute_observed(
session.as_mut(),
sql,
options,
Arc::clone(&policy),
)
.await;
drop(session);
result
}
},
retry_if,
|| (runtime.random)(),
|delay| (runtime.sleep)(delay),
)
.await;
drop(dispatch);
return retry_result_with_interrupt(outcome, &attempt_state);
}
let mut session = pool.acquire_async().await?;
let result = execute_observed(session.as_mut(), sql, options, policy).await;
drop(session);
result
})
}
fn fetch_async<'a>(
&'a self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
let pool = Arc::clone(&self.inner);
let policy = Arc::clone(&self.policy);
Box::pin(async move {
let limit = match options.limit {
LimitSetting::Inherit => policy.default_limit,
LimitSetting::Set(limit) => limit,
};
options.limit = LimitSetting::Set(limit);
resolve_provider_timeout(&mut options, policy.default_timeout)?;
let retry = resolve_retry(options.retry, policy.retry);
if options.replay_safety == ReplaySafety::ExplicitlyReplaySafe
&& let RetryPolicy::Enabled {
policy: retry_policy,
retry_timeouts,
} = retry
{
let Some(mut runtime) = options
.retry_runtime
.clone()
.or_else(|| policy.retry_runtime.clone())
else {
return Err(DbError::new(ErrorKind::Unsupported));
};
let dispatch = RetryDispatch::for_operation(&mut runtime);
let cancellation = Arc::clone(&dispatch.cancellation);
let deadline = dispatch.deadline.clone();
let attempt_state = Arc::clone(&dispatch.state);
let mut options = options;
options.retry_runtime = Some(runtime.clone());
let retry_if = |error: &DbError| {
retry_allowed(*error, retry_timeouts, &cancellation, &deadline)
};
let outcome = execute_idempotent_retry(
retry_policy,
&cancellation,
deadline.clone(),
|| {
let pool = Arc::clone(&pool);
let policy = Arc::clone(&policy);
let cancellation = Arc::clone(&cancellation);
let deadline = deadline.clone();
let attempt_state = Arc::clone(&attempt_state);
let options = options.clone();
async move {
attempt_state.reset();
deadline.check(&cancellation).await?;
let mut session = pool.acquire_async().await?;
let result = fetch_observed(
session.as_mut(),
sql,
limit,
options,
Arc::clone(&policy),
)
.await;
drop(session);
result
}
},
retry_if,
|| (runtime.random)(),
|delay| (runtime.sleep)(delay),
)
.await;
drop(dispatch);
return retry_result_with_interrupt(outcome, &attempt_state)
.map(|reader| Box::new(reader) as Box<dyn Reader + 'a>);
}
let mut session = pool.acquire_async().await?;
let result = fetch_observed(session.as_mut(), sql, limit, options, policy).await;
drop(session);
result.map(|reader| Box::new(reader) as Box<dyn Reader + 'a>)
})
}
}
fn resolve_retry(setting: RetrySetting, default: RetryPolicy) -> RetryPolicy {
match setting {
RetrySetting::Inherit => default,
RetrySetting::Off => RetryPolicy::Disabled,
RetrySetting::Use(policy) => policy,
}
}
fn retry_allowed(
error: DbError,
retry_timeouts: bool,
cancellation: &Cancellation,
deadline: &RetryDeadline,
) -> bool {
!cancellation.is_cancelled()
&& !deadline.is_expired()
&& (matches!(error.kind(), ErrorKind::Busy | ErrorKind::Connection)
|| (retry_timeouts && error.kind() == ErrorKind::Timeout))
}
fn retry_result<T>(outcome: RetryOutcome<T, DbError>) -> Result<T, DbError> {
match outcome {
RetryOutcome::Success { value, .. } => Ok(value),
RetryOutcome::Failure { error, .. } => Err(error),
RetryOutcome::Cancelled { .. } => Err(DbError::new(ErrorKind::Cancelled)),
RetryOutcome::TimedOut { .. } => Err(DbError::new(ErrorKind::Timeout)),
}
}
fn mutex_lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
#[derive(Default)]
struct RetryAttemptState {
dispatch_in_flight: AtomicBool,
last_error: Mutex<Option<ErrorKind>>,
dispatch_rejection: Mutex<Option<DbError>>,
}
impl RetryAttemptState {
fn reset(&self) {
self.dispatch_in_flight.store(false, Ordering::Release);
*mutex_lock(&self.last_error) = None;
*mutex_lock(&self.dispatch_rejection) = None;
}
}
#[derive(Clone)]
struct RetryDeadline(Arc<Mutex<Option<RetryWait>>>);
impl RetryDeadline {
fn new(timer: RetryWait) -> Self {
Self(Arc::new(Mutex::new(Some(timer))))
}
fn is_expired(&self) -> bool {
mutex_lock(&self.0).is_none()
}
async fn check(&self, cancellation: &Cancellation) -> Result<(), DbError> {
if cancellation.is_cancelled() {
return Err(DbError::new(ErrorKind::Cancelled));
}
let mut deadline = self.clone();
let expired = poll_fn(|cx| Poll::Ready(Pin::new(&mut deadline).poll(cx).is_ready())).await;
if cancellation.is_cancelled() {
Err(DbError::new(ErrorKind::Cancelled))
} else if expired {
Err(DbError::new(ErrorKind::Timeout))
} else {
Ok(())
}
}
}
impl Future for RetryDeadline {
type Output = ();
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
let mut timer = mutex_lock(&self.0);
if let Some(wait) = timer.as_mut() {
if wait.as_mut().poll(cx).is_pending() {
return Poll::Pending;
}
*timer = None;
}
Poll::Ready(())
}
}
struct RetryDispatch {
deadline: RetryDeadline,
cancellation: Arc<Cancellation>,
state: Arc<RetryAttemptState>,
}
impl RetryDispatch {
fn for_operation(runtime: &mut RetryRuntime) -> Arc<Self> {
let dispatch = Arc::new(Self {
deadline: RetryDeadline::new((runtime.timer)()),
cancellation: Arc::clone(&runtime.cancellation),
state: Arc::new(RetryAttemptState::default()),
});
runtime.dispatch = Some(Arc::downgrade(&dispatch));
dispatch
}
async fn start(&self) -> Result<(), DbError> {
self.state
.dispatch_in_flight
.store(false, Ordering::Release);
if let Err(error) = self.deadline.check(&self.cancellation).await {
*mutex_lock(&self.state.dispatch_rejection) = Some(error);
return Err(error);
}
self.state.dispatch_in_flight.store(true, Ordering::Release);
Ok(())
}
fn rejection(&self) -> Option<DbError> {
*mutex_lock(&self.state.dispatch_rejection)
}
fn finish(&self, result: Result<(), DbError>) {
self.state
.dispatch_in_flight
.store(false, Ordering::Release);
if let Err(error) = result {
*mutex_lock(&self.state.last_error) = Some(error.kind());
}
}
}
fn retry_result_with_interrupt<T>(
outcome: RetryOutcome<T, DbError>,
state: &RetryAttemptState,
) -> Result<T, DbError> {
match outcome {
RetryOutcome::Cancelled { .. } => Err(interruption_error(state, ErrorKind::Cancelled)),
RetryOutcome::TimedOut { .. } => Err(interruption_error(state, ErrorKind::Timeout)),
other => retry_result(other),
}
}
fn interruption_error(state: &RetryAttemptState, interruption: ErrorKind) -> DbError {
if state.dispatch_in_flight.load(Ordering::Acquire) {
return DbError::new(ErrorKind::WriteOutcomeUnknown);
}
let last_error = *mutex_lock(&state.last_error);
match last_error {
Some(kind @ (ErrorKind::WriteOutcomeUnknown | ErrorKind::CommitOutcomeUnknown)) => {
DbError::new(kind)
}
_ => DbError::new(interruption),
}
}
pub struct SqlitePolicyPool {
inner: Arc<dyn SqlitePool>,
policy_pool: PolicyPool,
}
impl fmt::Debug for SqlitePolicyPool {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("SqlitePolicyPool")
.field("policy", &self.policy_pool.policy)
.finish_non_exhaustive()
}
}
impl SqlitePolicyPool {
pub fn new<P: SqlitePool + 'static>(pool: P, policy: PoolPolicy) -> Self {
Self::from_shared(Arc::new(pool), policy)
}
#[must_use]
pub fn from_shared(inner: Arc<dyn SqlitePool>, policy: PoolPolicy) -> Self {
let pool: Arc<dyn Pool> = inner.clone();
Self {
inner,
policy_pool: PolicyPool::from_shared(pool, policy),
}
}
}
impl Pool for SqlitePolicyPool {
fn capabilities(&self) -> Capabilities {
self.policy_pool.capabilities()
}
fn defaults(&self) -> PoolDefaults {
self.policy_pool.defaults()
}
fn acquire_async(&self) -> DbFuture<'_, Box<dyn Session>> {
self.policy_pool.acquire_async()
}
fn execute_async<'a>(&'a self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, u64> {
self.policy_pool.execute_async(sql, options)
}
fn fetch_async<'a>(
&'a self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
self.policy_pool.fetch_async(sql, options)
}
}
impl SqlitePool for SqlitePolicyPool {
fn busy_timeout(&self) -> Duration {
self.inner.busy_timeout()
}
fn acquire_sqlite_async(&self) -> DbFuture<'_, Box<dyn ImmediateTransaction>> {
let inner = Arc::clone(&self.inner);
let policy = Arc::clone(&self.policy_pool.policy);
Box::pin(async move {
let session = inner.acquire_sqlite_async().await?;
Ok(Box::new(PolicySqliteSession { session, policy }) as Box<dyn ImmediateTransaction>)
})
}
}
struct PolicySession {
session: Box<dyn Session>,
policy: Arc<PoolPolicy>,
}
impl Session for PolicySession {
fn defaults(&self) -> PoolDefaults {
policy_defaults(&self.policy)
}
fn execute_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, u64> {
Box::pin(async move {
options.validate_execute()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
execute_observed(
self.session.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn fetch_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
Box::pin(async move {
reject_session_retry(&options)?;
let limit = options.resolved_limit(policy_defaults(&self.policy));
options.limit = LimitSetting::Set(limit);
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
let reader = fetch_observed(
self.session.as_mut(),
sql,
limit,
options,
Arc::clone(&self.policy),
)
.await?;
Ok(Box::new(reader) as Box<dyn Reader + 'a>)
})
}
fn execute_trusted_script_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, ()> {
Box::pin(async move {
options.validate_script()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
script_observed(
self.session.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn begin_async<'a>(
&'a mut self,
options: TxOptions,
) -> DbFuture<'a, Box<dyn Transaction<'a> + 'a>> {
let session = &mut self.session;
let policy = Arc::clone(&self.policy);
Box::pin(async move {
let transaction = session.begin_async(options).await?;
Ok(Box::new(PolicyTransaction {
transaction,
policy,
}) as Box<dyn Transaction<'a> + 'a>)
})
}
}
struct PolicySqliteSession {
session: Box<dyn ImmediateTransaction>,
policy: Arc<PoolPolicy>,
}
impl Session for PolicySqliteSession {
fn defaults(&self) -> PoolDefaults {
policy_defaults(&self.policy)
}
fn execute_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, u64> {
Box::pin(async move {
options.validate_execute()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
execute_observed(
self.session.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn fetch_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
Box::pin(async move {
reject_session_retry(&options)?;
let limit = options.resolved_limit(policy_defaults(&self.policy));
options.limit = LimitSetting::Set(limit);
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
let reader = fetch_observed(
self.session.as_mut(),
sql,
limit,
options,
Arc::clone(&self.policy),
)
.await?;
Ok(Box::new(reader) as Box<dyn Reader + 'a>)
})
}
fn execute_trusted_script_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, ()> {
Box::pin(async move {
options.validate_script()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
script_observed(
self.session.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn begin_async<'a>(
&'a mut self,
options: TxOptions,
) -> DbFuture<'a, Box<dyn Transaction<'a> + 'a>> {
let session = &mut self.session;
let policy = Arc::clone(&self.policy);
Box::pin(async move {
let transaction = session.begin_async(options).await?;
Ok(Box::new(PolicyTransaction {
transaction,
policy,
}) as Box<dyn Transaction<'a> + 'a>)
})
}
}
impl ImmediateTransaction for PolicySqliteSession {
fn begin_immediate_async<'a>(&'a mut self) -> DbFuture<'a, Box<dyn Transaction<'a> + 'a>> {
let session = &mut self.session;
let policy = Arc::clone(&self.policy);
Box::pin(async move {
let transaction = session.begin_immediate_async().await?;
Ok(Box::new(PolicyTransaction {
transaction,
policy,
}) as Box<dyn Transaction<'a> + 'a>)
})
}
}
struct PolicyTransaction<'session> {
transaction: Box<dyn Transaction<'session> + 'session>,
policy: Arc<PoolPolicy>,
}
impl<'session> Transaction<'session> for PolicyTransaction<'session> {
fn defaults(&self) -> PoolDefaults {
policy_defaults(&self.policy)
}
fn execute_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, u64> {
Box::pin(async move {
options.validate_execute()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
execute_observed(
self.transaction.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn fetch_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
Box::pin(async move {
reject_session_retry(&options)?;
let limit = options.resolved_limit(policy_defaults(&self.policy));
options.limit = LimitSetting::Set(limit);
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
let reader = fetch_observed(
self.transaction.as_mut(),
sql,
limit,
options,
Arc::clone(&self.policy),
)
.await?;
Ok(Box::new(reader) as Box<dyn Reader + 'a>)
})
}
fn execute_trusted_script_async<'a>(
&'a mut self,
sql: &'a str,
mut options: QueryOptions,
) -> DbFuture<'a, ()> {
Box::pin(async move {
options.validate_script()?;
reject_session_retry(&options)?;
resolve_provider_timeout(&mut options, self.policy.default_timeout)?;
script_observed(
self.transaction.as_mut(),
sql,
options,
Arc::clone(&self.policy),
)
.await
})
}
fn commit_async(self: Box<Self>) -> DbFuture<'session, ()> {
let transaction = self.transaction;
transaction.commit_async()
}
fn rollback_async(self: Box<Self>) -> DbFuture<'session, ()> {
let transaction = self.transaction;
transaction.rollback_async()
}
}
fn resolve_setting(setting: QuerySetting, pool_default: bool) -> bool {
match setting {
QuerySetting::Inherit => pool_default,
QuerySetting::Off => false,
QuerySetting::On => true,
}
}
fn captured_sql(sql: &str, policy: &PoolPolicy, options: &QueryOptions) -> Option<String> {
if !resolve_setting(options.sql_capture, policy.sql_capture_enabled)
|| !resolve_setting(options.telemetry, policy.telemetry_enabled)
{
return None;
}
policy.observer.as_ref()?;
let hook = options.sql_hook.as_ref().or(policy.sql_hook.as_ref());
match hook {
Some(hook) => {
contain_callback_panic(catch_unwind(AssertUnwindSafe(|| hook(sql)))).flatten()
}
None => Some(sql.to_owned()),
}
}
fn contain_callback_panic<T>(result: Result<T, Box<dyn std::any::Any + Send>>) -> Option<T> {
match result {
Ok(value) => Some(value),
Err(payload) => {
std::mem::forget(payload);
None
}
}
}
fn emit(
operation: Operation,
started: Instant,
result: Result<(), DbError>,
sql: Option<String>,
policy: &PoolPolicy,
options: &QueryOptions,
) {
if !resolve_setting(options.telemetry, policy.telemetry_enabled) {
return;
}
let Some(observer) = &policy.observer else {
return;
};
let outcome = match result {
Ok(()) => TelemetryOutcome::Success,
Err(error) => TelemetryOutcome::Error(error.kind()),
};
let event = DbEvent {
operation,
duration: started.elapsed(),
outcome,
sql,
};
let _ = contain_callback_panic(catch_unwind(AssertUnwindSafe(|| observer(&event))));
}
struct ObservationGuard {
operation: Operation,
started: Instant,
captured: Option<String>,
policy: Arc<PoolPolicy>,
options: QueryOptions,
active: bool,
}
impl ObservationGuard {
fn new(
operation: Operation,
started: Instant,
captured: Option<String>,
policy: Arc<PoolPolicy>,
options: QueryOptions,
) -> Self {
Self {
operation,
started,
captured,
policy,
options,
active: true,
}
}
fn finish(&mut self, result: Result<(), DbError>) {
if self.active {
self.active = false;
emit(
self.operation,
self.started,
result,
self.captured.take(),
&self.policy,
&self.options,
);
}
}
fn disarm(&mut self) {
self.active = false;
}
}
impl Drop for ObservationGuard {
fn drop(&mut self) {
if self.active {
self.finish(Err(DbError::new(ErrorKind::WriteOutcomeUnknown)));
}
}
}
trait StatementExecutor: Send {
fn execute_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, u64>;
fn fetch_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>>;
fn execute_script<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, ()>;
}
impl StatementExecutor for dyn Session + '_ {
fn execute_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, u64> {
self.execute_async(sql, options)
}
fn fetch_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
self.fetch_async(sql, options)
}
fn execute_script<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, ()> {
self.execute_trusted_script_async(sql, options)
}
}
impl StatementExecutor for dyn ImmediateTransaction + '_ {
fn execute_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, u64> {
self.execute_async(sql, options)
}
fn fetch_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
self.fetch_async(sql, options)
}
fn execute_script<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, ()> {
self.execute_trusted_script_async(sql, options)
}
}
impl StatementExecutor for dyn Transaction<'_> + '_ {
fn execute_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, u64> {
self.execute_async(sql, options)
}
fn fetch_statement<'a>(
&'a mut self,
sql: &'a str,
options: QueryOptions,
) -> DbFuture<'a, Box<dyn Reader + 'a>> {
self.fetch_async(sql, options)
}
fn execute_script<'a>(&'a mut self, sql: &'a str, options: QueryOptions) -> DbFuture<'a, ()> {
self.execute_trusted_script_async(sql, options)
}
}
fn script_observed<'a, S: StatementExecutor + ?Sized>(
session: &'a mut S,
sql: &'a str,
query_options: QueryOptions,
policy: Arc<PoolPolicy>,
) -> DbFuture<'a, ()> {
Box::pin(async move {
let captured = captured_sql(sql, &policy, &query_options);
let started = Instant::now();
let mut observation = ObservationGuard::new(
Operation::Execute,
started,
captured,
Arc::clone(&policy),
query_options.clone(),
);
let mut provider_options = query_options.clone();
provider_options.policy_applied = true;
let result = session.execute_script(sql, provider_options).await;
let observer_result = match &result {
Ok(()) => Ok(()),
Err(error) => Err(DbError::new(error.kind())),
};
observation.finish(observer_result);
result
})
}
fn operation_dispatch(options: &QueryOptions) -> Option<Arc<RetryDispatch>> {
options.retry_runtime.as_ref()?.dispatch.as_ref()?.upgrade()
}
fn execute_observed<'a, S: StatementExecutor + ?Sized>(
session: &'a mut S,
sql: &'a str,
options: QueryOptions,
policy: Arc<PoolPolicy>,
) -> DbFuture<'a, u64> {
Box::pin(async move {
let dispatch = operation_dispatch(&options);
let captured = captured_sql(sql, &policy, &options);
if let Some(dispatch) = &dispatch {
dispatch.start().await?;
}
let started = Instant::now();
let mut observation = ObservationGuard::new(
Operation::Execute,
started,
captured,
Arc::clone(&policy),
options.clone(),
);
let mut provider_options = options.clone();
provider_options.policy_applied = true;
let result = session.execute_statement(sql, provider_options).await;
if let Some(error) = dispatch.as_ref().and_then(|dispatch| dispatch.rejection()) {
observation.disarm();
return Err(error);
}
let result = result.map_err(normalize_write_outcome);
if let Some(dispatch) = &dispatch {
dispatch.finish(result.as_ref().map(|_| ()).map_err(|error| *error));
}
observation.finish(result.as_ref().map(|_| ()).map_err(|error| *error));
result
})
}
fn normalize_write_outcome(error: DbError) -> DbError {
match error.kind() {
ErrorKind::Connection | ErrorKind::Timeout | ErrorKind::Cancelled => {
DbError::new(ErrorKind::WriteOutcomeUnknown)
}
_ => error,
}
}
async fn collect_sets(reader: &mut dyn Reader, limit: RowLimit) -> Result<Vec<Vec<Row>>, DbError> {
let mut sets = Vec::new();
let mut rows = 0usize;
let mut bytes = 0usize;
loop {
let mut set = Vec::new();
while let Some(row) = reader.next_row_async().await? {
if rows == limit.rows() {
return Err(DbError::new(ErrorKind::Overflow));
}
let size = row.encoded_bytes()?;
bytes = bytes
.checked_add(size)
.ok_or_else(|| DbError::new(ErrorKind::Overflow))?;
if bytes > limit.bytes() {
return Err(DbError::new(ErrorKind::Overflow));
}
rows = rows
.checked_add(1)
.ok_or_else(|| DbError::new(ErrorKind::Overflow))?;
set.push(row);
}
sets.push(set);
if !reader.has_next_set_async().await? {
break;
}
if sets.len() == limit.max_sets() {
return Err(DbError::new(ErrorKind::Overflow));
}
}
reader.finish_async().await?;
Ok(sets)
}
fn fetch_observed<'a, S: StatementExecutor + ?Sized>(
session: &'a mut S,
sql: &'a str,
limit: RowLimit,
options: QueryOptions,
policy: Arc<PoolPolicy>,
) -> DbFuture<'a, BufferedReader> {
Box::pin(async move {
let dispatch = operation_dispatch(&options);
let captured = captured_sql(sql, &policy, &options);
if let Some(dispatch) = &dispatch {
dispatch.start().await?;
}
let started = Instant::now();
let mut observation = ObservationGuard::new(
Operation::Fetch,
started,
captured,
Arc::clone(&policy),
options.clone(),
);
let result = async {
let mut provider_options = options.clone();
provider_options.policy_applied = true;
let mut reader = session.fetch_statement(sql, provider_options).await?;
collect_sets(reader.as_mut(), limit).await
}
.await;
if let Some(error) = dispatch.as_ref().and_then(|dispatch| dispatch.rejection()) {
observation.disarm();
return Err(error);
}
if let Some(dispatch) = &dispatch {
dispatch.finish(result.as_ref().map(|_| ()).map_err(|error| *error));
}
observation.finish(result.as_ref().map(|_| ()).map_err(|error| *error));
result.map(BufferedReader::from_sets)
})
}