Enum SqlxBrokerError 

#[non_exhaustive]
pub enum SqlxBrokerError {
    Connect {
        source: Error,
    },
    Backend {
        backend: String,
    },
    Sqlx {
        subscription: String,
        table: String,
        row: &'static str,
        statement: &'static str,
        source: Box<Error>,
    },
    Schema {
        subscription: String,
        table: String,
        row: &'static str,
        statement: &'static str,
        source: Box<Error>,
    },
    Dialect {
        subscription: String,
        table: String,
        row: &'static str,
        source: StatementError,
    },
    ServerTooOld {
        subscription: String,
        table: String,
        row: &'static str,
        server: String,
        required: &'static str,
    },
    Declaration {
        subscription: String,
        table: String,
        row: &'static str,
        reason: String,
    },
    ConnectionLimit {
        subscription: String,
        limit: u32,
        pool: u64,
        threads: u64,
    },
    AlreadySubscribed {
        subscription: String,
        table: String,
        row: &'static str,
    },
    BatchRolledBack {
        subscription: String,
        table: String,
        row: &'static str,
    },
    LeaseLost {
        subscription: String,
        table: String,
        row: &'static str,
        id: String,
    },
    TransactionHeld {
        subscription: String,
        table: String,
        row: &'static str,
        id: String,
    },
    Listen {
        subscription: String,
        table: String,
        row: &'static str,
        source: Box<Error>,
    },
    Publish {
        name: String,
        table: String,
        row: &'static str,
        source: Box<Error>,
    },
    Header {
        name: String,
        table: String,
        row: &'static str,
        header: String,
    },
    NoRoute {
        name: String,
    },
    Closed,
}

What can go wrong in the inbox broker.

Every variant about a subscription names the subscription, the table and the row type, so one line of a log says where to look.

Examples

use ruststream::runtime::PublishError;
use ruststream_sqlx::prelude::*;
use ruststream_sqlx::{RepositoryPublisher, SqlxBrokerError};
use serde::Serialize;
use sqlx::Postgres;

#[derive(Serialize, Outgoing)]
#[outgoing(name = "exports")]
pub struct Export {
    account: u64,
}

/// The status the service's HTTP endpoint answers when it schedules an export.
pub async fn schedule(exports: &RepositoryPublisher<Postgres, ExportJob>, export: &Export) -> u16 {
    match exports.message(export).publish().await {
        Ok(()) => 202,
        // The service is shutting down: the client tries again later.
        Err(PublishError::Publish(SqlxBrokerError::Closed)) => 503,
        Err(error) => {
            tracing::error!(%error, "the export was not scheduled");
            500
        }
    }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Connect

connect could not take a connection from the pool.

Fields

source: Error

The pool’s error.

Backend

connect found the pool on a database no built-in dialect serves: an AnyPool’s backend whose feature is off.

Fields

backend: String

The backend’s name, as its sqlx driver reports it.

Sqlx

A statement failed while the subscription ran.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

statement: &'static str

The statement, or the event a service’s own impl ran.

source: Box<Error>

The database’s error.

Schema

A statement failed to prepare at startup: the table does not match the struct.

Preparing checks the names of the table and its columns, not the column types; a claimed row whose columns do not decode goes to the subscription’s decode-failure policy instead.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

statement: &'static str

The statement that failed to prepare.

source: Box<Error>

The database’s error.

Dialect

The dialect refused to build a statement for the table.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

source: StatementError

What the dialect could not build.

ServerTooOld

The server is older than the statements of the subscription’s form need.

A subscription reads the server’s version when it opens, where its dialect asks for it: MySQL claims rows with SKIP LOCKED in the row lock and lease forms, which MySQL 8.0.1 and MariaDB 10.6 added, and a table in the advisory lock form shares that floor.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

server: String

The version the server reports.

required: &'static str

The oldest server the subscription’s statements run on.

Declaration

The registration declared what the table cannot carry: a retry, or transactional mode at an isolation level its form cannot keep it at.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

reason: String

What to change.

ConnectionLimit

A subscription on dedicated threads whose connections would take the service past the broker’s connection_limit: the subscription does not open, and the service does not start.

Fields

subscription: String

The subscription that would pass the limit.

limit: u32

The limit the broker sets.

pool: u64

The size of the service’s pool.

threads: u64

The connections of the dedicated threads of every subscription so far, this one’s included.

AlreadySubscribed

The connection already reads this queue: two subscriptions would compete for its rows.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

BatchRolledBack

A settlement of a batch whose transaction an earlier settlement’s failure rolls back.

A batch that holds a row whose statement always fails rolls back and returns all of its rows on every attempt, until the service’s SQL or schema is fixed.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

LeaseLost

A settlement in the lease form found its row under another lease, so it took no effect.

Ownership of a leased row ends with its lease, not with its holder. The subscription extends the lease of every delivery in work each half lease, so a lease runs out under a running handler only when its extensions fail or stop (the database out of reach, the subscription closed or the broker shut down). The handler then shares the row with the next claim, and the lease, the ownership token, only stops the late holder from settling.

A settlement whose statement fails keeps the row under its lease until the lease runs out, as a crash does; a delivery dropped unsettled releases its row at once.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

id: String

The row’s id, as logs name it.

TransactionHeld

A settlement in transactional mode found the delivery’s transaction still lent to its handler’s Tx, which the handler moved somewhere that outlived it.

The settlement took no effect. The transaction ends when that Tx drops: its connection closes, the server rolls back what the handler wrote, and the row returns to the queue. In the lease form the row returns once its lease runs out, which the broker extends no more.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

id: String

The row’s id, as logs name it.

Listen

The broker with listen_notify could not listen on the channel of the subscription’s table as it opened.

Fields

subscription: String

The subscription.

table: String

The table, qualified with its schema: the channel.

row: &'static str

The row type.

source: Box<Error>

The database’s error.

Publish

The service’s Publish failed.

Fields

name: String

The name published to.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

source: Box<Error>

The database’s error.

Header

The publish carries a header the table cannot hold byte for byte, so it was refused.

Fields

name: String

The name published to.

table: String

The table, qualified with its schema.

row: &'static str

The row type.

header: String

The header.

NoRoute

No route leads the name to a table.

Fields

name: String

The name published to.

Closed

The broker was shut down; the handle outlived it.

Trait Implementations

impl Debug for SqlxBrokerError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SqlxBrokerError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SqlxBrokerError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.