#[cfg(feature = "cassandra")]
mod cassandra;
mod cursor;
mod error;
mod group;
mod handler;
mod offset_store;
#[cfg(feature = "postgres")]
mod postgres;
mod runtime;
mod source;
pub mod testkit;
use std::{fmt, sync::Arc, time::Duration};
use crate::query::QueryMode;
#[cfg(feature = "cassandra")]
pub use cassandra::{
CassandraProjectionOffsetStore, CassandraProjectionOffsetStoreConfig,
CassandraProjectionTableNames,
};
pub use cursor::{
BoundaryEvent, CursorPosition, DeduplicationBoundary, ProjectionCursor, ProviderManifest,
};
pub use error::{ProjectionError, ProjectionErrorKind, ProjectionResult};
pub use group::{ProjectionGroup, ProjectionGroupHandle};
#[cfg(feature = "postgres")]
pub use handler::{
ExactlyOncePostgresHandler, GroupedExactlyOncePostgresHandler, PostgresProjectionTx,
};
pub use handler::{GroupedHandler, Handler};
pub use offset_store::{MemoryProjectionOffsetStore, ProjectionGeneration, ProjectionOffsetStore};
#[cfg(feature = "postgres")]
pub use postgres::{
PostgresProjectionOffsetStore, PostgresProjectionOffsetStoreConfig,
PostgresProjectionTableNames,
};
pub use runtime::{
BackoffRng, ProjectionHandle, ProjectionRuntime, ProjectionStatus, StatusObserver,
restart_delay,
};
pub use source::{
EventsBySlicesSourceProvider, ProjectionSource, SliceRangeCursor, SourceProvider,
seed_resharded_slice_range, slice_projection_key,
};
pub use testkit::{
CrashSaveRequest, DurableProjectionOffsetStoreHarness, ManualPaceProbe, ProjectionTestKit,
SaveCrashOutcome, SaveCrashPoint, TestEnvelope, TestSourceProvider,
assert_cursor_codec_conformance, assert_projection_offset_store_durable_conformance,
assert_projection_offset_store_semantic_conformance,
};
const DEFAULT_SAVE_AFTER_ENVELOPES: usize = 100;
const DEFAULT_SAVE_AFTER_DURATION: Duration = Duration::from_millis(500);
const DEFAULT_GROUP_AFTER_ENVELOPES: usize = 20;
const DEFAULT_GROUP_AFTER_DURATION: Duration = Duration::from_millis(500);
const DEFAULT_RECOVERY_RETRIES: usize = 5;
const DEFAULT_RECOVERY_DELAY: Duration = Duration::from_secs(1);
const DEFAULT_MIN_BACKOFF: Duration = Duration::from_secs(3);
const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(30);
const DEFAULT_RANDOM_FACTOR: f64 = 0.2;
const DEFAULT_MAX_RESTARTS_WITHIN: Duration = DEFAULT_MIN_BACKOFF;
type SingleHandlerFactory<Envelope> =
dyn Fn() -> Box<dyn Handler<Envelope>> + Send + Sync + 'static;
type GroupedHandlerFactory<Envelope> =
dyn Fn() -> Box<dyn GroupedHandler<Envelope>> + Send + Sync + 'static;
#[cfg(feature = "postgres")]
type ExactlyOncePostgresHandlerFactory<Envelope> =
dyn Fn() -> Box<dyn ExactlyOncePostgresHandler<Envelope>> + Send + Sync + 'static;
#[cfg(feature = "postgres")]
type GroupedExactlyOncePostgresHandlerFactory<Envelope> =
dyn Fn() -> Box<dyn GroupedExactlyOncePostgresHandler<Envelope>> + Send + Sync + 'static;
pub(crate) enum ProjectionHandlerFactory<Envelope> {
Single(Arc<SingleHandlerFactory<Envelope>>),
Grouped(Arc<GroupedHandlerFactory<Envelope>>),
#[cfg(feature = "postgres")]
ExactlyOncePostgres(Arc<ExactlyOncePostgresHandlerFactory<Envelope>>),
#[cfg(feature = "postgres")]
GroupedExactlyOncePostgres(Arc<GroupedExactlyOncePostgresHandlerFactory<Envelope>>),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DeliverySemantics {
AtLeastOnce,
AtMostOnce,
}
pub struct Projection<Envelope> {
pub(crate) projection_id: ProjectionId,
pub(crate) source_provider: Arc<dyn SourceProvider<Envelope>>,
pub(crate) handler_factory: ProjectionHandlerFactory<Envelope>,
pub(crate) delivery: DeliverySemantics,
pub(crate) query_mode: QueryMode,
pub(crate) save_offset: SaveOffsetConfig,
pub(crate) group: GroupConfig,
pub(crate) recovery_strategy: RecoveryStrategy,
pub(crate) restart_backoff: RestartBackoff,
pub(crate) status_observer: Arc<dyn StatusObserver<Envelope>>,
}
impl<Envelope> Projection<Envelope>
where
Envelope: Send + Sync + 'static,
{
#[must_use]
pub fn at_least_once<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: Handler<Envelope>,
{
Self::new(
projection_id,
source_provider,
handler_factory,
DeliverySemantics::AtLeastOnce,
)
}
#[must_use]
pub fn grouped_at_least_once<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: GroupedHandler<Envelope>,
{
Self {
projection_id,
source_provider: Arc::new(source_provider),
handler_factory: ProjectionHandlerFactory::Grouped(Arc::new(move || {
Box::new(handler_factory()) as Box<dyn GroupedHandler<Envelope>>
})),
delivery: DeliverySemantics::AtLeastOnce,
query_mode: QueryMode::Live,
save_offset: SaveOffsetConfig::default(),
group: GroupConfig::default(),
recovery_strategy: RecoveryStrategy::default(),
restart_backoff: RestartBackoff::default(),
status_observer: Arc::new(runtime::NoopStatusObserver),
}
}
#[cfg(feature = "postgres")]
#[must_use]
pub fn exactly_once_postgres<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: ExactlyOncePostgresHandler<Envelope>,
{
Self {
projection_id,
source_provider: Arc::new(source_provider),
handler_factory: ProjectionHandlerFactory::ExactlyOncePostgres(Arc::new(move || {
Box::new(handler_factory()) as Box<dyn ExactlyOncePostgresHandler<Envelope>>
})),
delivery: DeliverySemantics::AtLeastOnce,
query_mode: QueryMode::Live,
save_offset: SaveOffsetConfig::default(),
group: GroupConfig::default(),
recovery_strategy: RecoveryStrategy::default(),
restart_backoff: RestartBackoff::default(),
status_observer: Arc::new(runtime::NoopStatusObserver),
}
}
#[cfg(feature = "postgres")]
#[must_use]
pub fn grouped_exactly_once_postgres<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: GroupedExactlyOncePostgresHandler<Envelope>,
{
Self {
projection_id,
source_provider: Arc::new(source_provider),
handler_factory: ProjectionHandlerFactory::GroupedExactlyOncePostgres(Arc::new(
move || {
Box::new(handler_factory())
as Box<dyn GroupedExactlyOncePostgresHandler<Envelope>>
},
)),
delivery: DeliverySemantics::AtLeastOnce,
query_mode: QueryMode::Live,
save_offset: SaveOffsetConfig::default(),
group: GroupConfig::default(),
recovery_strategy: RecoveryStrategy::default(),
restart_backoff: RestartBackoff::default(),
status_observer: Arc::new(runtime::NoopStatusObserver),
}
}
#[must_use]
pub fn at_most_once<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: Handler<Envelope>,
{
Self::new(
projection_id,
source_provider,
handler_factory,
DeliverySemantics::AtMostOnce,
)
}
fn new<P, F, H>(
projection_id: ProjectionId,
source_provider: P,
handler_factory: F,
delivery: DeliverySemantics,
) -> Self
where
P: SourceProvider<Envelope>,
F: Fn() -> H + Send + Sync + 'static,
H: Handler<Envelope>,
{
Self {
projection_id,
source_provider: Arc::new(source_provider),
handler_factory: ProjectionHandlerFactory::Single(Arc::new(move || {
Box::new(handler_factory()) as Box<dyn Handler<Envelope>>
})),
delivery,
query_mode: QueryMode::Live,
save_offset: SaveOffsetConfig::default(),
group: GroupConfig::default(),
recovery_strategy: RecoveryStrategy::default(),
restart_backoff: RestartBackoff::default(),
status_observer: Arc::new(runtime::NoopStatusObserver),
}
}
#[must_use]
pub fn projection_id(&self) -> &ProjectionId {
&self.projection_id
}
#[must_use]
pub fn with_query_mode(mut self, mode: QueryMode) -> Self {
self.query_mode = mode;
self
}
#[must_use]
pub fn with_save_offset(mut self, config: SaveOffsetConfig) -> Self {
self.save_offset = config;
self
}
#[must_use]
pub fn with_group(mut self, config: GroupConfig) -> Self {
self.group = config;
self
}
#[must_use]
pub fn with_recovery_strategy(mut self, strategy: RecoveryStrategy) -> Self {
self.recovery_strategy = strategy;
self
}
#[must_use]
pub fn with_restart_backoff(mut self, backoff: RestartBackoff) -> Self {
self.restart_backoff = backoff;
self
}
#[must_use]
pub fn with_status_observer<O>(mut self, observer: O) -> Self
where
O: StatusObserver<Envelope>,
{
self.status_observer = Arc::new(observer);
self
}
pub async fn spawn(self, runtime: ProjectionRuntime) -> ProjectionResult<ProjectionHandle> {
runtime::spawn(self, runtime).await
}
pub async fn run_on(self, runtime: ProjectionRuntime) -> ProjectionResult<ProjectionHandle> {
self.spawn(runtime).await
}
pub(crate) fn validate(&self) -> ProjectionResult<()> {
self.projection_id.validate()?;
self.source_provider
.validate_projection_id(&self.projection_id)?;
if self.is_grouped() {
self.group.validate()?;
} else if self.delivery == DeliverySemantics::AtLeastOnce {
self.save_offset.validate()?;
}
self.restart_backoff.validate()
}
pub(crate) const fn is_grouped(&self) -> bool {
match &self.handler_factory {
ProjectionHandlerFactory::Grouped(_) => true,
#[cfg(feature = "postgres")]
ProjectionHandlerFactory::GroupedExactlyOncePostgres(_) => true,
_ => false,
}
}
#[cfg(feature = "postgres")]
pub(crate) const fn is_exactly_once_postgres(&self) -> bool {
matches!(
&self.handler_factory,
ProjectionHandlerFactory::ExactlyOncePostgres(_)
| ProjectionHandlerFactory::GroupedExactlyOncePostgres(_)
)
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ProjectionId {
name: String,
key: String,
}
impl ProjectionId {
#[must_use]
pub fn new(name: impl Into<String>, key: impl Into<String>) -> Self {
Self {
name: name.into(),
key: key.into(),
}
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub fn key(&self) -> &str {
&self.key
}
pub fn validate(&self) -> ProjectionResult<()> {
if self.name.trim().is_empty() {
return Err(ProjectionError::invalid_config(
"projection_id.name",
"projection name must not be blank",
));
}
if self.key.trim().is_empty() {
return Err(ProjectionError::invalid_config(
"projection_id.key",
"projection key must not be blank",
));
}
Ok(())
}
}
impl fmt::Display for ProjectionId {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "{}:{}", self.name, self.key)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SaveOffsetConfig {
pub after_envelopes: usize,
pub after_duration: Duration,
}
impl SaveOffsetConfig {
pub fn validate(&self) -> ProjectionResult<()> {
validate_positive_count("save_offset.after_envelopes", self.after_envelopes)?;
validate_positive_duration("save_offset.after_duration", self.after_duration)
}
}
impl Default for SaveOffsetConfig {
fn default() -> Self {
Self {
after_envelopes: DEFAULT_SAVE_AFTER_ENVELOPES,
after_duration: DEFAULT_SAVE_AFTER_DURATION,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GroupConfig {
pub group_after_envelopes: usize,
pub group_after_duration: Duration,
}
impl GroupConfig {
pub fn validate(&self) -> ProjectionResult<()> {
validate_positive_count("group.group_after_envelopes", self.group_after_envelopes)?;
validate_positive_duration("group.group_after_duration", self.group_after_duration)
}
}
impl Default for GroupConfig {
fn default() -> Self {
Self {
group_after_envelopes: DEFAULT_GROUP_AFTER_ENVELOPES,
group_after_duration: DEFAULT_GROUP_AFTER_DURATION,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum RecoveryStrategy {
#[default]
Fail,
Skip,
RetryAndFail {
retries: usize,
delay: Duration,
},
RetryAndSkip {
retries: usize,
delay: Duration,
},
}
impl RecoveryStrategy {
#[must_use]
pub const fn retry_and_fail() -> Self {
Self::RetryAndFail {
retries: DEFAULT_RECOVERY_RETRIES,
delay: DEFAULT_RECOVERY_DELAY,
}
}
#[must_use]
pub const fn retry_and_skip() -> Self {
Self::RetryAndSkip {
retries: DEFAULT_RECOVERY_RETRIES,
delay: DEFAULT_RECOVERY_DELAY,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RestartBackoff {
pub min_backoff: Duration,
pub max_backoff: Duration,
pub random_factor: f64,
pub max_restarts: Option<usize>,
pub max_restarts_within: Duration,
}
impl RestartBackoff {
pub fn validate(&self) -> ProjectionResult<()> {
if self.min_backoff > self.max_backoff {
return Err(ProjectionError::invalid_config(
"restart_backoff",
"min_backoff must not exceed max_backoff",
));
}
if !self.random_factor.is_finite() || !(0.0..=1.0).contains(&self.random_factor) {
return Err(ProjectionError::invalid_config(
"restart_backoff.random_factor",
"random_factor must be finite and between 0.0 and 1.0",
));
}
Ok(())
}
}
impl Default for RestartBackoff {
fn default() -> Self {
Self {
min_backoff: DEFAULT_MIN_BACKOFF,
max_backoff: DEFAULT_MAX_BACKOFF,
random_factor: DEFAULT_RANDOM_FACTOR,
max_restarts: None,
max_restarts_within: DEFAULT_MAX_RESTARTS_WITHIN,
}
}
}
fn validate_positive_count(setting: &'static str, count: usize) -> ProjectionResult<()> {
if count == 0 {
return Err(ProjectionError::invalid_config(
setting,
"value must be greater than zero",
));
}
Ok(())
}
fn validate_positive_duration(setting: &'static str, duration: Duration) -> ProjectionResult<()> {
if duration.is_zero() {
return Err(ProjectionError::invalid_config(
setting,
"duration must be greater than zero",
));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn configuration_defaults_match_akka_projection() {
assert_eq!(
SaveOffsetConfig::default(),
SaveOffsetConfig {
after_envelopes: 100,
after_duration: Duration::from_millis(500),
}
);
assert_eq!(
GroupConfig::default(),
GroupConfig {
group_after_envelopes: 20,
group_after_duration: Duration::from_millis(500),
}
);
assert_eq!(RecoveryStrategy::default(), RecoveryStrategy::Fail);
assert_eq!(
RecoveryStrategy::retry_and_fail(),
RecoveryStrategy::RetryAndFail {
retries: 5,
delay: Duration::from_secs(1),
}
);
assert_eq!(
RecoveryStrategy::retry_and_skip(),
RecoveryStrategy::RetryAndSkip {
retries: 5,
delay: Duration::from_secs(1),
}
);
assert_eq!(
RestartBackoff::default(),
RestartBackoff {
min_backoff: Duration::from_secs(3),
max_backoff: Duration::from_secs(30),
random_factor: 0.2,
max_restarts: None,
max_restarts_within: Duration::from_secs(3),
}
);
}
#[test]
fn invalid_configuration_is_fatal() {
let error = ProjectionId::new("", "key")
.validate()
.expect_err("blank projection names must fail validation");
assert_eq!(error.kind(), ProjectionErrorKind::Fatal);
let error = RestartBackoff {
random_factor: f64::NAN,
..RestartBackoff::default()
}
.validate()
.expect_err("NaN jitter must fail validation");
assert!(error.is_fatal());
}
}