bookclerk_db_exec::proxy_txn

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Fail-closed acknowledgements for SeaORM's infallible proxy transaction hooks.

ProxyDatabaseTrait::{begin, commit, rollback} return (). A failed BEGIN that is only logged leaves later statements in autocommit; a failed COMMIT still looks like success to sea_orm::DatabaseTransaction::commit. Proxies record a per-task fault instead and refuse subsequent statements.

Item Kind Summary
ExecBudget struct Request-scoped deadline and query row cap for one atomic attempt.
ExecuteRowCapGuard struct Restores ExecBudget::raw_query_row_cap and ExecBudget::raw_query_byte_cap when dropped.
AtomicInterruptPhase enum Phase at which an injected atomic interrupt fires.
AtomicInterruptKind enum Kind of injected atomic interrupt.
note_begin_failed function Record that BEGIN failed so later statements cannot autocommit.
note_commit_failed function Record that COMMIT failed so the caller cannot treat the txn as durable.
is_txn_broken function Whether this task has a sticky begin/commit fault.
txn_broken_err function DbErr for refusing statements after a failed begin/commit.
take_txn_fault function Take and clear this task's sticky fault (after SeaORM commit/rollback).
inject_begin_failures function Queue n injected BEGIN failures for this task.
inject_commit_failures function Queue n injected COMMIT failures for this task.
inject_savepoint_release_failures function Queue n injected nested-savepoint RELEASE failures for this task.
inject_savepoint_rollback_failures function Queue n injected nested-savepoint ROLLBACK TO failures for this task.
consume_begin_injection function Consume one injected begin failure if any remain for this task.
consume_commit_injection function Consume one injected commit failure if any remain for this task.
consume_savepoint_release_injection function Consume one injected savepoint RELEASE failure if any remain for this task.
consume_savepoint_rollback_injection function Consume one injected savepoint ROLLBACK TO failure if any remain for this task.
inject_atomic_interrupt function Queue an atomic session interrupt for this task (cancel or deadline at phase).
inject_atomic_interrupt_after function Like inject_atomic_interrupt, ignoring skip observations of phase first.
consume_atomic_interrupt function Consume an injected interrupt when the executor reaches phase.
with_exec_budget function Runs fut with budget as the request-scoped execution budget.
current_exec_budget function Request-scoped budget for the current Tokio task, if an atomic attempt armed one.
suspend_execute_row_cap function Suspends the execute-request row and result byte caps until the guard is dropped.
record_query_rows_seen function Records seen for query_rows_seen after an atomic attempt completes.
arm_exec_budget function Legacy no-op. Budgets are request-scoped via with_exec_budget.
clear_exec_budget function Legacy no-op. Budgets are request-scoped via with_exec_budget.
exec_deadline_expired function True when the current task's armed deadline has elapsed.
exec_deadline_remaining_ms function Remaining milliseconds until the current task's deadline (None if unlimited).
query_row_cap function Advertised query row cap for the current task (None if unlimited).
note_query_row function Records one materialized query row against the current task budget.
query_rows_seen function Rows materialized by the last completed capped query (tests).

Structs

ExecBudget

pub struct ExecBudget {
    /* private fields */
}

Request-scoped deadline and query row cap for one atomic attempt.

Stored on the Tokio task that owns the attempt and copied onto the engine connection after it acquires the exclusive lease, so concurrent attempts cannot overwrite each other.

ExecBudget::new

pub fn new(deadline_unix_ms: Option<u64>, query_row_cap: u32) -> Arc<Self>

Builds a budget for one atomic attempt.

ExecBudget::with_cancel

pub fn with_cancel(
    deadline_unix_ms: Option<u64>,
    query_row_cap: u32,
    cancel: Option<Arc<AtomicBool>>,
) -> Arc<Self>

Builds a budget for one atomic attempt that also carries the session's host cancel flag, so engine retry loops can stop when it is raised.

Arguments
  • deadline_unix_ms - Guest-visible deadline (None = none).
  • query_row_cap - Advertised query row cap (0 = unlimited).
  • cancel - Host cancel flag of the atomic session, if any.

ExecBudget::with_result_caps

pub fn with_result_caps(
    deadline_unix_ms: Option<u64>,
    query_row_cap: u32,
    query_byte_cap: u32,
    cancel: Option<Arc<AtomicBool>>,
) -> Arc<Self>

Builds a budget for one atomic attempt with both result caps.

Arguments
  • deadline_unix_ms - Guest-visible deadline (None = none).
  • query_row_cap - Advertised query row cap (0 = unlimited).
  • query_byte_cap - Advertised per-statement result byte cap (0 = unlimited); an inline attempt passes maxResultBytes, a streamed attempt maxStreamedResultBytes.
  • cancel - Host cancel flag of the atomic session, if any.

ExecBudget::unlimited

pub fn unlimited() -> Arc<Self>

No deadline and no row cap.

ExecBudget::deadline_expired

pub fn deadline_expired(&self) -> bool

True when an armed deadline has elapsed.

ExecBudget::cancelled

pub fn cancelled(&self) -> bool

True when the owning session's host cancel flag is raised.

ExecBudget::remaining_ms

pub fn remaining_ms(&self) -> Option<u64>

Remaining milliseconds until the armed deadline (None if unlimited).

ExecBudget::cap

pub fn cap(&self) -> Option<usize>

Advertised query row cap (None if unlimited).

ExecBudget::set_query_row_cap

pub fn set_query_row_cap(&self, cap: usize)

Sets the query row cap (0 = unlimited).

ExecBudget::raw_query_row_cap

pub fn raw_query_row_cap(&self) -> usize

Raw cap including 0 for unlimited.

ExecBudget::raw_query_byte_cap

pub fn raw_query_byte_cap(&self) -> u32

Per-statement result byte cap, 0 for unlimited.

ExecBudget::set_query_byte_cap

pub fn set_query_byte_cap(&self, cap: u32)

Sets the per-statement result byte cap (0 = unlimited).

ExecBudget::reset_rows_seen

pub fn reset_rows_seen(&self)

Clears the per-query row counter.

ExecBudget::note_row

pub fn note_row(&self) -> bool

Records one materialized query row; true when the caller should stop.

ExecBudget::rows_seen

pub fn rows_seen(&self) -> usize

Rows materialized by the current capped query.

ExecBudget::set_positional_columns

pub fn set_positional_columns(&self, columns: Vec<DbColumn>)

Records rusqlite/engine column metadata for the in-flight statement.

ExecBudget::take_positional_columns

pub fn take_positional_columns(&self) -> Option<Vec<DbColumn>>

Takes engine column metadata recorded for this request, if any.

Implements: Debug

ExecuteRowCapGuard

pub struct ExecuteRowCapGuard {
    /* private fields */
}

Restores ExecBudget::raw_query_row_cap and ExecBudget::raw_query_byte_cap when dropped.

Implements: Drop

Enums

AtomicInterruptPhase

pub enum AtomicInterruptPhase {
    BeforeBegin,
    BetweenStatements,
    AroundCommit,
}

Phase at which an injected atomic interrupt fires.

Variants

  • BeforeBegin: Before BEGIN / HTTP batch.
  • BetweenStatements: Between statements during the transaction.
  • AroundCommit: Around COMMIT / HTTP return (ambiguous).

Implements: Clone, Copy, Debug, Eq, PartialEq

AtomicInterruptKind

pub enum AtomicInterruptKind {
    Cancel,
    Deadline,
}

Kind of injected atomic interrupt.

Variants

  • Cancel: Session cancel.
  • Deadline: Deadline elapsed.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

note_begin_failed

pub fn note_begin_failed(err: impl Display)

Record that BEGIN failed so later statements cannot autocommit.

note_commit_failed

pub fn note_commit_failed(err: impl Display)

Record that COMMIT failed so the caller cannot treat the txn as durable.

is_txn_broken

pub fn is_txn_broken() -> bool

Whether this task has a sticky begin/commit fault.

txn_broken_err

pub fn txn_broken_err() -> DbErr

DbErr for refusing statements after a failed begin/commit.

take_txn_fault

pub fn take_txn_fault() -> Option<String>

Take and clear this task's sticky fault (after SeaORM commit/rollback).

inject_begin_failures

pub fn inject_begin_failures(n: u32)

Queue n injected BEGIN failures for this task.

inject_commit_failures

pub fn inject_commit_failures(n: u32)

Queue n injected COMMIT failures for this task.

inject_savepoint_release_failures

pub fn inject_savepoint_release_failures(n: u32)

Queue n injected nested-savepoint RELEASE failures for this task.

Also arms a process-wide counter so a txn worker (different Tokio task) can observe the fault.

inject_savepoint_rollback_failures

pub fn inject_savepoint_rollback_failures(n: u32)

Queue n injected nested-savepoint ROLLBACK TO failures for this task.

Also arms a process-wide counter so a txn worker (different Tokio task) can observe the fault.

consume_begin_injection

pub fn consume_begin_injection() -> bool

Consume one injected begin failure if any remain for this task.

consume_commit_injection

pub fn consume_commit_injection() -> bool

Consume one injected commit failure if any remain for this task.

consume_savepoint_release_injection

pub fn consume_savepoint_release_injection() -> bool

Consume one injected savepoint RELEASE failure if any remain for this task.

consume_savepoint_rollback_injection

pub fn consume_savepoint_rollback_injection() -> bool

Consume one injected savepoint ROLLBACK TO failure if any remain for this task.

inject_atomic_interrupt

pub fn inject_atomic_interrupt(phase: AtomicInterruptPhase, kind: AtomicInterruptKind)

Queue an atomic session interrupt for this task (cancel or deadline at phase).

inject_atomic_interrupt_after

pub fn inject_atomic_interrupt_after(
    phase: AtomicInterruptPhase,
    kind: AtomicInterruptKind,
    skip: u32,
)

Like inject_atomic_interrupt, ignoring skip observations of phase first.

consume_atomic_interrupt

pub fn consume_atomic_interrupt(
    phase: AtomicInterruptPhase,
) -> Option<AtomicInterruptKind>

Consume an injected interrupt when the executor reaches phase.

with_exec_budget

pub async fn with_exec_budget<F, Fut, T>(budget: Arc<ExecBudget>, fut: F) -> T
where
    F: FnOnce() -> Fut,
    Fut: Future<Output = T>,

Runs fut with budget as the request-scoped execution budget.

current_exec_budget

pub fn current_exec_budget() -> Option<Arc<ExecBudget>>

Request-scoped budget for the current Tokio task, if an atomic attempt armed one.

suspend_execute_row_cap

pub fn suspend_execute_row_cap() -> Option<ExecuteRowCapGuard>

Suspends the execute-request row and result byte caps until the guard is dropped.

Catalog / sqlite_master loads are not guest result rows; they must not fail a tight maxResultRows or maxResultBytes on the surrounding execute. An adapter advertising the host minimum of 4,096 result bytes still has to read its own catalog, which is larger than that.

record_query_rows_seen

pub fn record_query_rows_seen(seen: usize)

Records seen for query_rows_seen after an atomic attempt completes.

arm_exec_budget

pub fn arm_exec_budget(_deadline_unix_ms: Option<u64>, _query_row_cap: u32)

Legacy no-op. Budgets are request-scoped via with_exec_budget.

clear_exec_budget

pub fn clear_exec_budget()

Legacy no-op. Budgets are request-scoped via with_exec_budget.

exec_deadline_expired

pub fn exec_deadline_expired() -> bool

True when the current task's armed deadline has elapsed.

exec_deadline_remaining_ms

pub fn exec_deadline_remaining_ms() -> Option<u64>

Remaining milliseconds until the current task's deadline (None if unlimited).

query_row_cap

pub fn query_row_cap() -> Option<usize>

Advertised query row cap for the current task (None if unlimited).

note_query_row

pub fn note_query_row() -> bool

Records one materialized query row against the current task budget.

query_rows_seen

pub fn query_rows_seen() -> usize

Rows materialized by the last completed capped query (tests).

Generated from crates/bookclerk-db-exec at main · View as Markdown