evidentsource_core/

lib.rs

//! EvidentSource Core Library
//!
//! This crate provides the core domain types and traits for the EvidentSource
//! event sourcing platform.

pub mod domain;

use std::future::Future;

use chrono::{DateTime, Utc};
use futures::Stream;
use nonempty::NonEmpty;

// Re-export key event types from the domain
pub use domain::{Event, EventData, ExtensionValue, ProspectiveEvent};

use domain::{
    AppendCondition, CommandRequest, DatabaseError, DatabaseName, EventAttribute, EventSelector,
    QueryOptions, Revision, StateChangeError, StateChangeName, StateChangeVersion, StateView,
    StateViewError, StateViewName, StateViewVersion, Transaction, TransactionSummary,
};

/// Basic database identity information.
pub trait DatabaseIdentity: Send + Sync {
    /// Get the database name.
    fn name(&self) -> &DatabaseName;

    /// Get the timestamp when this database was created.
    fn created_at(&self) -> DateTime<Utc>;
}

/// Catalog of available databases.
pub trait DatabaseCatalog {
    /// The type returned when creating a database.
    type Identity: DatabaseIdentity;

    /// List all databases in the catalog.
    fn list_databases(&self) -> impl Stream<Item = DatabaseName>;

    /// Create a new database with the given name.
    fn create_database(
        &self,
        name: DatabaseName,
    ) -> impl Future<Output = Result<Self::Identity, DatabaseError>>;

    /// Delete a database by name.
    fn delete_database(
        &self,
        name: DatabaseName,
    ) -> impl Future<Output = Result<(), DatabaseError>>;
}

/// Provides access to database views at various revisions.
pub trait DatabaseProvider: DatabaseIdentity {
    /// The type of database view at a specific revision.
    type AtRevision: DatabaseAtRevision;

    /// Get the latest local database
    fn local_database(&self) -> Self::AtRevision;

    /// Get the latest revision on the server committed to storage.
    fn latest_database(&self) -> impl Future<Output = Result<Self::AtRevision, DatabaseError>>;

    /// Get the database at a specific revision, awaiting if necessary.
    fn database_at_revision(
        &self,
        revision: Revision,
    ) -> impl Future<Output = Result<Self::AtRevision, DatabaseError>>;

    /// Get the database at the revision effective at a specific timestamp.
    fn database_at_timestamp(
        &self,
        revision_timestamp: DateTime<Utc>,
    ) -> impl Future<Output = Result<Self::AtRevision, DatabaseError>>;
}

/// A database connection capable of performing transactions.
pub trait DatabaseConnection: DatabaseProvider {
    /// Transact events with append conditions.
    ///
    /// The transaction must contain at least one event. Conditions are checked
    /// against the current database state before committing.
    ///
    /// See: <https://dcb.events/specification/> for the DCB append condition spec.
    fn transact(
        &self,
        events: NonEmpty<ProspectiveEvent>,
        conditions: Vec<AppendCondition>,
    ) -> impl Future<Output = Result<Self::AtRevision, DatabaseError>>;

    /// Transact events with a custom transaction ID.
    ///
    /// This is useful for idempotency - if a transaction with the same ID has
    /// already been committed, the existing result is returned.
    fn transact_with_id(
        &self,
        transaction_id: &str,
        events: NonEmpty<ProspectiveEvent>,
        conditions: Vec<AppendCondition>,
    ) -> impl Future<Output = Result<Self::AtRevision, DatabaseError>>;

    /// Execute a state change.
    ///
    /// This invokes the named state change component with the given request
    /// and commits any resulting events.
    fn execute_state_change(
        &self,
        name: &StateChangeName,
        version: StateChangeVersion,
        request: CommandRequest,
    ) -> impl Future<Output = Result<Self::AtRevision, StateChangeError>>;

    /// Get the transaction log (summary only).
    fn log(&self) -> impl Stream<Item = TransactionSummary>;

    /// Get the transaction log with full event details.
    fn log_detail(&self) -> impl Stream<Item = Transaction>;

    /// Get the transaction log starting from a specific revision.
    ///
    /// This returns transaction summaries for all transactions committed at or
    /// after the specified revision.
    fn log_from(&self, from_revision: Revision) -> impl Stream<Item = TransactionSummary>;

    /// Get the transaction log with full event details, starting from a specific revision.
    ///
    /// This returns full transaction details (including events) for all transactions
    /// committed at or after the specified revision.
    fn log_detail_from(&self, from_revision: Revision) -> impl Stream<Item = Transaction>;
}

/// A database view at a specific revision.
pub trait DatabaseAtRevision: DatabaseIdentity + Clone {
    /// The type returned when scoping to an effective timestamp.
    type EffectiveTimestampView: DatabaseAtRevisionAndEffectiveTimestamp;

    /// The type returned for speculative queries.
    type Speculative: SpeculativeDatabase;

    /// Get this view's revision number.
    fn revision(&self) -> Revision;

    /// Get the timestamp when this revision was committed.
    fn revision_timestamp(&self) -> DateTime<Utc>;

    /// Get a view scoped to a specific effective timestamp (for bi-temporal queries).
    fn at_effective_timestamp(
        &self,
        effective_timestamp: DateTime<Utc>,
    ) -> Self::EffectiveTimestampView;

    /// Get a view at a different revision.
    ///
    /// This allows navigating to an earlier or later revision of the database.
    fn at_revision(&self, revision: Revision) -> impl Future<Output = Self>;

    /// Create a speculative view with additional uncommitted events.
    fn speculate_with_transaction(&self, events: NonEmpty<ProspectiveEvent>) -> Self::Speculative;

    /// Query events matching a selector.
    fn query_events(&self, selector: &EventSelector) -> impl Stream<Item = Event>;

    /// Query events matching a selector with options.
    ///
    /// This allows controlling the query direction and limiting results.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use evidentsource_core::domain::{EventSelector, QueryOptions, QueryDirection};
    ///
    /// // Get the 10 most recent events
    /// let selector = EventSelector::stream_equals("my-stream").unwrap();
    /// let options = QueryOptions::new().reverse().limit(10);
    /// let events = db.query_events_with_options(&selector, options);
    /// ```
    fn query_events_with_options(
        &self,
        selector: &EventSelector,
        options: QueryOptions,
    ) -> impl Stream<Item = Event>;

    /// Fetch a state view.
    fn view_state(
        &self,
        name: &StateViewName,
        version: StateViewVersion,
    ) -> impl Future<Output = Result<StateView, StateViewError>>;

    /// Fetch a state view with parameter bindings.
    ///
    /// Parameters are used to filter state views by specific attributes.
    /// Common parameter patterns:
    /// - `("subject.account_id", EventAttribute::Subject(Some(...)))` - filter by subject
    /// - `("stream.processing_day_stream", EventAttribute::Stream(...))` - filter by stream
    fn view_state_with_params(
        &self,
        name: &StateViewName,
        version: StateViewVersion,
        params: &[(String, EventAttribute)],
    ) -> impl Future<Output = Result<StateView, StateViewError>>;
}

/// A database view at both a revision and effective timestamp.
///
/// This enables bi-temporal queries where you want to see the database
/// state as it was understood at a particular point in effective time.
pub trait DatabaseAtRevisionAndEffectiveTimestamp: DatabaseAtRevision {
    /// The type of the base revision view.
    type Basis: DatabaseAtRevision;

    /// Get the base database view (without effective timestamp scope).
    fn basis(&self) -> &Self::Basis;

    /// Get the effective timestamp this view is scoped to.
    fn effective_timestamp(&self) -> DateTime<Utc>;

    /// Get a view at a different revision while keeping the same effective timestamp.
    ///
    /// This is an async operation because fetching a different revision may require
    /// a remote call (e.g., gRPC) to retrieve the database state at that revision.
    fn at_revision_with_effective_timestamp(
        &self,
        revision: Revision,
    ) -> impl Future<Output = Result<Self, DatabaseError>>;
}

/// A speculative database view with uncommitted events.
///
/// This allows querying the database as if certain events had been committed,
/// useful for validation and preview scenarios.
pub trait SpeculativeDatabase: DatabaseAtRevision {
    /// The type of the committed view this speculation is based on.
    type Basis: DatabaseAtRevision;

    /// Get the committed view this speculation is based on.
    fn basis(&self) -> &Self::Basis;

    /// Get the speculated (uncommitted) event transactions.
    fn speculated_transactions(&self) -> &NonEmpty<NonEmpty<ProspectiveEvent>>;
}