use core::{future::Future, marker::PhantomData, time::Duration};
use std::{
collections::{BTreeMap, HashSet},
sync::Arc,
time::SystemTime,
};
#[cfg(feature = "sqlite")]
use smol_bytes::Utf8Bytes;
use super::{
ItemId, Rings,
channel::Outbox,
journal::{Attributes, JournalRow},
lifecycle::{LifecycleTap, Taps},
message::{Delivery, Item, Payload, ack_channel},
progress::{PositionKey, Positions, Track},
registry::{Counting, Registries, RootKey},
window::Outbound,
};
pub struct Hint<M = ()> {
tx: flume::Sender<M>,
}
impl Hint {
#[inline]
pub fn ring(&self) -> bool {
!matches!(
self.tx.try_send(()),
Err(flume::TrySendError::Disconnected(()))
)
}
}
impl Rings for Hint {
#[inline]
fn ring(&self) -> bool {
Self::ring(self)
}
}
impl<M> Clone for Hint<M> {
#[inline]
fn clone(&self) -> Self {
Self {
tx: self.tx.clone(),
}
}
}
impl<M> core::fmt::Debug for Hint<M> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Hint").finish_non_exhaustive()
}
}
pub struct Doorbell<M = ()> {
rx: flume::Receiver<M>,
}
impl<M> Doorbell<M> {
#[inline]
pub fn wait(&self, sweep: Duration) -> Rung {
match self.rx.recv_timeout(sweep) {
Ok(_) => Rung::Rung,
Err(flume::RecvTimeoutError::Timeout) => Rung::Swept,
Err(flume::RecvTimeoutError::Disconnected) => Rung::Silent,
}
}
#[inline]
pub async fn rung(&self) -> Rung {
match self.rx.recv_async().await {
Ok(_) => Rung::Rung,
Err(flume::RecvError::Disconnected) => Rung::Silent,
}
}
#[inline]
pub fn take(&self) -> Rung {
match self.rx.try_recv() {
Ok(_) => Rung::Rung,
Err(flume::TryRecvError::Empty) => Rung::Swept,
Err(flume::TryRecvError::Disconnected) => Rung::Silent,
}
}
}
impl<M> core::fmt::Debug for Doorbell<M> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Doorbell").finish_non_exhaustive()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum Rung {
Rung,
Swept,
Silent,
}
impl Rung {
#[inline]
#[must_use]
pub const fn as_str(&self) -> &'static str {
match self {
Self::Rung => "rung",
Self::Swept => "swept",
Self::Silent => "silent",
}
}
}
#[inline]
#[must_use]
pub fn doorbell() -> (Hint, Doorbell) {
let (tx, rx) = flume::bounded(1);
(Hint { tx }, Doorbell { rx })
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Page<T, K> {
items: Vec<Item<T, K>>,
}
impl<T, K> Page<T, K> {
#[inline]
#[must_use]
pub const fn new(items: Vec<Item<T, K>>) -> Self {
Self { items }
}
#[inline]
#[must_use]
pub fn items(&self) -> &[Item<T, K>] {
&self.items
}
#[inline]
#[must_use]
pub const fn len(&self) -> usize {
self.items.len()
}
#[inline]
#[must_use]
pub const fn is_empty(&self) -> bool {
self.items.is_empty()
}
#[inline]
#[must_use]
pub fn into_items(self) -> Vec<Item<T, K>> {
self.items
}
}
impl<T, K> FromIterator<Item<T, K>> for Page<T, K> {
#[inline]
fn from_iter<I: IntoIterator<Item = Item<T, K>>>(items: I) -> Self {
Self::new(items.into_iter().collect())
}
}
impl<T, K> IntoIterator for Page<T, K> {
type IntoIter = std::vec::IntoIter<Item<T, K>>;
type Item = Item<T, K>;
#[inline]
fn into_iter(self) -> Self::IntoIter {
self.items.into_iter()
}
}
#[diagnostic::on_unimplemented(
message = "`{Self}` publishes no change feed on `{Db}`",
label = "not listenable",
note = "a store is listenable where it has change data capture or an ORDERED PULL — a record \
store on a backend that can answer `WHERE key > p ORDER BY key LIMIT n`. A fulltext, \
vector or blob store publishes neither, so `listen(changes)` at one has nothing to \
subscribe to; listen to the record store that feeds it instead",
note = "the portable floor is `SqliteFeed`, which gives any ordered SQLite table a feed. A \
backend with a native feed implements this trait over its own"
)]
pub trait AsyncChanges<Db> {
type Key;
type Item;
type Message;
type Error;
fn doorbell(&self) -> &Doorbell<Self::Message>;
fn pull(
&mut self,
after: Option<&Self::Key>,
limit: usize,
) -> impl Future<Output = Result<Page<Self::Item, Self::Key>, Self::Error>> + Send;
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Pulled {
pulled: usize,
delivered: usize,
retracted: usize,
recorded: usize,
advanced: bool,
}
impl Pulled {
#[inline]
#[must_use]
pub const fn pulled(&self) -> usize {
self.pulled
}
#[inline]
#[must_use]
pub const fn delivered(&self) -> usize {
self.delivered
}
#[inline]
#[must_use]
pub const fn retracted(&self) -> usize {
self.retracted
}
#[inline]
#[must_use]
pub const fn recorded(&self) -> usize {
self.recorded
}
#[inline]
#[must_use]
pub const fn advanced(&self) -> bool {
self.advanced
}
}
#[derive(Debug, derive_more::Display, derive_more::IsVariant)]
pub enum IntakeError<F, P> {
#[display("the change feed refused a pull: {_0}")]
Feed(F),
#[display("the positions map refused: {_0}")]
Positions(P),
#[display("the consumer's inbox has hung up")]
Disconnected,
}
impl<F, P> core::error::Error for IntakeError<F, P>
where
F: core::error::Error + 'static,
P: core::error::Error + 'static,
{
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::Feed(e) => Some(e),
Self::Positions(e) => Some(e),
Self::Disconnected => None,
}
}
}
#[derive(Debug)]
pub struct ChangeIntake<Db, F, P, A = ()>
where
F: AsyncChanges<Db>,
A: Attributes<F::Item>,
{
feed: F,
positions: P,
track: Track,
outbox: Outbox<ItemId, F::Item>,
window: Outbound<ItemId>,
keys: BTreeMap<ItemId, F::Key>,
roots: BTreeMap<ItemId, A::Root>,
registries: Option<Arc<Registries>>,
next: u64,
page: usize,
taps: Taps,
attribution: A,
durable: Option<F::Key>,
cursor: Option<F::Key>,
loaded: bool,
_db: PhantomData<fn() -> Db>,
}
impl<Db, F, P> ChangeIntake<Db, F, P, ()>
where
F: AsyncChanges<Db>,
{
pub const PAGE: usize = 256;
#[must_use]
pub fn new(track: Track, feed: F, positions: P, outbox: Outbox<ItemId, F::Item>) -> Self {
Self {
feed,
positions,
track,
outbox,
window: Outbound::new(),
keys: BTreeMap::new(),
roots: BTreeMap::new(),
registries: None,
next: 0,
page: Self::PAGE,
taps: Taps::new(),
attribution: (),
durable: None,
cursor: None,
loaded: false,
_db: PhantomData,
}
}
}
impl<Db, F, P, A> ChangeIntake<Db, F, P, A>
where
F: AsyncChanges<Db>,
A: Attributes<F::Item>,
{
#[must_use]
pub fn attributing<B>(self, attribution: B) -> ChangeIntake<Db, F, P, B>
where
B: Attributes<F::Item>,
{
ChangeIntake {
feed: self.feed,
positions: self.positions,
track: self.track,
outbox: self.outbox,
window: self.window,
keys: self.keys,
roots: BTreeMap::new(),
registries: self.registries,
next: self.next,
page: self.page,
taps: self.taps,
attribution,
durable: self.durable,
cursor: self.cursor,
loaded: self.loaded,
_db: PhantomData,
}
}
#[inline]
#[must_use]
pub const fn with_page(mut self, page: usize) -> Self {
self.set_page(page);
self
}
#[inline]
pub const fn set_page(&mut self, page: usize) -> &mut Self {
self.page = page;
self
}
#[inline]
#[must_use]
pub fn with_taps(mut self, taps: Taps) -> Self {
self.set_taps(taps);
self
}
#[inline]
pub fn set_taps(&mut self, taps: Taps) -> &mut Self {
self.taps = taps;
self
}
#[inline]
#[must_use]
pub fn with_registries(mut self, registries: Arc<Registries>) -> Self {
self.set_registries(registries);
self
}
#[inline]
pub fn set_registries(&mut self, registries: Arc<Registries>) -> &mut Self {
self.registries = Some(registries);
self
}
#[inline]
#[must_use]
pub fn registries(&self) -> Option<&Registries> {
self.registries.as_deref()
}
#[inline]
#[must_use]
pub fn doorbell(&self) -> &Doorbell<F::Message> {
self.feed.doorbell()
}
#[inline]
#[must_use]
pub const fn position(&self) -> Option<&F::Key> {
self.durable.as_ref()
}
#[inline]
#[must_use]
pub const fn feed(&self) -> &F {
&self.feed
}
#[inline]
#[must_use]
pub const fn positions(&self) -> &P {
&self.positions
}
#[inline]
#[must_use]
pub const fn track(&self) -> &Track {
&self.track
}
#[inline]
#[must_use]
pub const fn page(&self) -> usize {
self.page
}
#[inline]
#[must_use]
pub const fn taps(&self) -> &Taps {
&self.taps
}
#[inline]
#[must_use]
pub const fn attribution(&self) -> &A {
&self.attribution
}
#[inline]
#[must_use]
pub fn into_feed(self) -> F {
self.feed
}
}
impl<Db, F, P, A> ChangeIntake<Db, F, P, A>
where
F: AsyncChanges<Db>,
F::Key: PositionKey,
P: Positions<F::Key>,
P::Row: JournalRow<A::Root>,
A: Attributes<F::Item>,
A::Root: RootKey,
{
fn counting(&self) -> Option<Counting<A::Root>> {
Counting::open(self.registries.as_ref(), A::FAMILY)
}
pub async fn drain(&mut self) -> Result<Pulled, IntakeError<F::Error, P::Error>> {
if !self.loaded {
self.durable = self
.positions
.position_async(&self.track)
.await
.map_err(IntakeError::Positions)?;
self.cursor = self.durable.clone();
self.loaded = true;
}
let mut report = self.settle().await?;
let counting = self.counting();
loop {
let page = self
.feed
.pull(self.cursor.as_ref(), self.page)
.await
.map_err(IntakeError::Feed)?;
if page.is_empty() {
break;
}
report.pulled += page.len();
report.delivered += 1;
let mut ids = Vec::with_capacity(page.len());
let mut items = Vec::with_capacity(page.len());
for change in page {
let (key, value) = change.into_parts();
let id = ItemId::new(self.next);
self.next += 1;
self.cursor = Some(key.clone());
self.keys.insert(id, key);
let root = self.attribution.root(&value);
if let Some(counting) = counting.as_ref() {
counting.dispatched(&root);
}
self.roots.insert(id, root);
ids.push(id);
items.push(Item::new(id, value));
}
let (ack, answers) = ack_channel();
self.window.record(ids, answers);
self
.outbox
.deliver_async(Delivery::new(Payload::Batch(items), ack))
.await
.map_err(|_| IntakeError::Disconnected)?;
}
let settled = self.settle().await?;
report.retracted += settled.retracted;
report.advanced |= settled.advanced;
Ok(report)
}
async fn settle(&mut self) -> Result<Pulled, IntakeError<F::Error, P::Error>> {
let mut report = Pulled::default();
let counting = if self.roots.is_empty() {
None
} else {
self.counting()
};
let harvest = self.window.harvest();
let now = SystemTime::now();
let mut journal: Vec<P::Row> = Vec::new();
for answer in harvest.answers() {
self.taps.observe(answer.worker(), answer.observation());
let mut seen: HashSet<A::Root> = HashSet::new();
let Some(arrival) = answer.observation().arrival() else {
continue;
};
let settled = arrival.station().is_settled();
for id in answer.covered() {
let Some(root) = self.roots.remove(id) else {
continue;
};
if let Some(counting) = counting.as_ref() {
counting.observed(&root);
}
if !seen.insert(root.clone()) {
continue;
}
if settled {
journal.push(P::Row::of(&root, answer.worker(), arrival, now));
}
self.attribution.observe(&root, answer.worker(), arrival);
}
}
if let Some(&watermark) = self.window.position() {
let mut settled = self.keys.split_off(&ItemId::new(watermark.seq() + 1));
core::mem::swap(&mut self.keys, &mut settled);
if let Some((_, key)) = settled.into_iter().next_back()
&& self.durable.as_ref() != Some(&key)
{
self
.positions
.advance_async(&self.track, key.clone(), &journal)
.await
.map_err(IntakeError::Positions)?;
self.durable = Some(key);
report.advanced = true;
report.recorded += journal.len();
journal.clear();
}
}
if !journal.is_empty() {
self
.positions
.record_async(&journal)
.await
.map_err(IntakeError::Positions)?;
report.recorded += journal.len();
}
if self.window.lost() > 0 {
let retracted = self.window.rewind();
report.retracted = retracted.len();
for id in retracted {
self.keys.remove(&id);
let credited = self.roots.remove(&id);
if let (Some(counting), Some(root)) = (counting.as_ref(), credited) {
counting.observed(&root);
}
}
self.cursor = self.durable.clone();
}
Ok(report)
}
pub async fn run(&mut self) -> Result<(), IntakeError<F::Error, P::Error>> {
self.drain().await?;
while !self.feed.doorbell().rung().await.is_silent() {
self.drain().await?;
}
Ok(())
}
}
#[cfg(feature = "sqlite")]
#[derive(Debug)]
pub struct SqliteFeed<T> {
conn: sqlx::SqliteConnection,
key: String,
from_start: String,
after: String,
doorbell: Doorbell,
row: PhantomData<fn() -> T>,
}
#[cfg(feature = "sqlite")]
impl<T> SqliteFeed<T> {
pub fn new(
conn: sqlx::SqliteConnection,
table: &str,
key: &str,
doorbell: Doorbell,
) -> Result<Self, SqliteFeedError> {
for name in [table, key] {
if !crate::slot::is_identifier(name.as_bytes()) {
return Err(SqliteFeedError::Identifier(Utf8Bytes::from(
name.to_owned(),
)));
}
}
Ok(Self {
conn,
key: key.to_owned(),
from_start: format!("SELECT * FROM {table} ORDER BY {key} LIMIT ?"),
after: format!("SELECT * FROM {table} WHERE {key} > ? ORDER BY {key} LIMIT ?"),
doorbell,
row: PhantomData,
})
}
#[inline]
#[must_use]
pub fn into_connection(self) -> sqlx::SqliteConnection {
self.conn
}
}
#[cfg(feature = "sqlite")]
#[derive(Debug, derive_more::Display, derive_more::IsVariant)]
pub enum SqliteFeedError {
#[display("`{_0}` is not a bare identifier, so it cannot name a table or a key column")]
Identifier(Utf8Bytes),
#[display("the change feed's pull failed: {_0}")]
Pull(sqlx::Error),
}
#[cfg(feature = "sqlite")]
impl core::error::Error for SqliteFeedError {
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::Identifier(_) => None,
Self::Pull(e) => Some(e),
}
}
}
#[cfg(feature = "sqlite")]
impl<T> AsyncChanges<sqlx::Sqlite> for SqliteFeed<T>
where
T: for<'r> sqlx::FromRow<'r, sqlx::sqlite::SqliteRow> + Send + Unpin,
{
type Error = SqliteFeedError;
type Item = T;
type Key = i64;
type Message = ();
#[inline]
fn doorbell(&self) -> &Doorbell {
&self.doorbell
}
async fn pull(
&mut self,
after: Option<&i64>,
limit: usize,
) -> Result<Page<T, i64>, SqliteFeedError> {
use sqlx::Row as _;
let limit = i64::try_from(limit).unwrap_or(i64::MAX);
let rows = match after {
Some(after) => {
sqlx::query(sqlx::AssertSqlSafe(self.after.clone()))
.bind(*after)
.bind(limit)
.fetch_all(&mut self.conn)
.await
}
None => {
sqlx::query(sqlx::AssertSqlSafe(self.from_start.clone()))
.bind(limit)
.fetch_all(&mut self.conn)
.await
}
}
.map_err(SqliteFeedError::Pull)?;
rows
.into_iter()
.map(|row| {
let key = row
.try_get::<i64, _>(self.key.as_str())
.map_err(SqliteFeedError::Pull)?;
let item = T::from_row(&row).map_err(SqliteFeedError::Pull)?;
Ok(Item::new(key, item))
})
.collect()
}
}
#[cfg(test)]
mod tests;