shared-framework 0.0.17

//! Query building, per-request options, and paginated results.
//!
//! Provides [`QueryData`] (a SeaORM `Select` wrapper with pagination and
//! relation-hydration steps), [`DeleteQueryData`] for bulk deletes,
//! [`RepositoryOptions`] for limit/cursor/user/correlation settings,
//! [`PageResult`] for cursor pages, and [`CursorData`] for opaque cursors.
//!
//! Build a [`QueryData`], optionally attach hydration with
//! [`QueryData::with_traverser`], then run it through
//! [`crate::data::PersistentRepository`] (`get_all`/`get_many`/`get_one`/
//! `get_paginated_view` and the `*_traversed` variants).
//!
//! Cursors are base64-encoded JSON holding a `limit` and an `id` cursor.
//! Selects filter on `id` in the direction recorded by the ordering
//! (ascending uses `id > cursor`, descending uses `id < cursor`);
//! deletes always use `id > cursor`.

use crate::data::BaseEntity;
use crate::logging::correlation::CorrelationContext;
use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
use chrono::Utc;
use sea_orm::prelude::DateTimeWithTimeZone;
use sea_orm::{entity::EntityLoaderTrait, DatabaseTransaction, EntityTrait};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

/// Default user type used when no caller identity is supplied.
///
/// Implements [`BaseEntity`] with `id` 0, a nil UUID, and current timestamps.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct NoUser;

impl BaseEntity for NoUser {
    type LoaderType = ();

    fn load() -> Self::LoaderType {}

    fn id(&self) -> i64 {
        0
    }
    fn uid(&self) -> uuid::Uuid {
        uuid::Uuid::nil()
    }
    fn created_at(&self) -> DateTimeWithTimeZone {
        Utc::now().into()
    }
    fn updated_at(&self) -> DateTimeWithTimeZone {
        Utc::now().into()
    }
}

/// Opaque pagination cursor carrying the page size and last-seen `id`.
///
/// Encoded as base64 JSON by [`CursorData::encode`]; decoded back by
/// [`CursorData::decode`], which returns `None` for malformed input.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CursorData {
    /// Page size the cursor was issued for.
    pub limit: usize,
    /// Last-seen row `id`; the next page continues after (or before) it.
    pub cursor: i64,
}

impl CursorData {
    /// Encodes this cursor as a base64 JSON string.
    pub fn encode(&self) -> String {
        let json = serde_json::to_string(self).unwrap_or_default();
        BASE64.encode(json.as_bytes())
    }
    /// Decodes a string produced by [`CursorData::encode`].
    ///
    /// Returns `None` when the input is not valid base64, not valid UTF-8,
    /// or not valid cursor JSON.
    pub fn decode(s: &str) -> Option<Self> {
        let bytes = BASE64.decode(s).ok()?;
        let json = String::from_utf8(bytes).ok()?;
        serde_json::from_str(&json).ok()
    }
}

/// Per-request settings for repository queries.
///
/// `U` is the caller identity type and must implement [`BaseEntity`]; it
/// defaults to [`NoUser`]. An identity can be supplied either as a full
/// entity (`user`) or as a raw id (`user_id`).
///
/// An optional database transaction can be attached via
/// [`RepositoryOptions::with_transaction`]. When present, repository
/// operations run against that transaction; otherwise they use the
/// repository's own connection.
#[derive(Debug, Clone)]
pub struct RepositoryOptions<U = NoUser>
where
    U: BaseEntity + Clone + Send + Sync + 'static,
{
    /// Maximum rows for limited reads; default is 15.
    pub limit: usize,
    /// Opaque cursor from a previous page, if continuing pagination.
    pub cursor: Option<String>,
    /// Whether selects use `SELECT DISTINCT`.
    pub distinct: bool,
    /// Detach flag carried alongside the query; default is `true`.
    pub detach: bool,
    /// Caller identity as an entity, if supplied.
    pub user: Option<U>,
    /// Caller identity as a raw id, if supplied.
    pub user_id: Option<i64>,
    /// Request correlation propagated with the query, if supplied.
    pub correlation: Option<Arc<CorrelationContext>>,
    /// Optional transaction used as the query executor when set.
    ///
    /// Held behind an [`Arc`] so the options stay cheaply cloneable even
    /// though [`DatabaseTransaction`] itself is neither `Clone` nor `Send`-free
    /// to move. Share with `Arc::new(txn)` — note a begun transaction cannot
    /// be cloned out of SeaORM, so callers typically wrap it at begin time
    /// (see [`RepositoryOptions::with_transaction`]).
    pub txn: Option<Arc<DatabaseTransaction>>,
}

impl<U> Default for RepositoryOptions<U>
where
    U: BaseEntity + Clone + Send + Sync + 'static,
{
    fn default() -> Self {
        Self {
            limit: 15,
            cursor: None,
            distinct: false,
            detach: true,
            user: None,
            user_id: None,
            correlation: None,
            txn: None,
        }
    }
}

impl<U> RepositoryOptions<U>
where
    U: BaseEntity + Clone + Send + Sync + 'static,
{
    /// Creates options with defaults: limit 15, no cursor, `distinct` false, `detach` true.
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the maximum rows for limited reads.
    pub fn with_limit(mut self, limit: usize) -> Self {
        self.limit = limit;
        self
    }

    /// Sets the pagination cursor to continue from.
    pub fn with_cursor(mut self, cursor: impl Into<String>) -> Self {
        self.cursor = Some(cursor.into());
        self
    }

    /// Sets the caller identity as an entity; also records its `id` as `user_id`.
    pub fn with_user(mut self, user: U) -> Self {
        self.user_id = Some(user.id());
        self.user = Some(user);
        self
    }

    /// Sets the caller identity as a raw id without an entity.
    pub fn with_user_id(mut self, user_id: i64) -> Self {
        self.user_id = Some(user_id);
        self
    }

    /// Attaches request correlation context to the options.
    pub fn with_correlation(mut self, ctx: Arc<CorrelationContext>) -> Self {
        self.correlation = Some(ctx);
        self
    }

    /// Enables `SELECT DISTINCT` for the query.
    pub fn distinct(mut self) -> Self {
        self.distinct = true;
        self
    }

    /// Sets the detach flag carried alongside the query.
    pub fn with_detach(mut self, detach: bool) -> Self {
        self.detach = detach;
        self
    }

    /// Attaches a transaction used as the executor for database operations.
    ///
    /// When set, repository methods run against this transaction instead of
    /// the repository's own connection. When unset, they fall back to the
    /// repository connection.
    pub fn with_transaction(mut self, txn: Arc<DatabaseTransaction>) -> Self {
        self.txn = Some(txn);
        self
    }

    /// Alias for [`RepositoryOptions::with_transaction`].
    pub fn with_txn(mut self, txn: Arc<DatabaseTransaction>) -> Self {
        self.txn = Some(txn);
        self
    }

    /// Removes any attached transaction, restoring execution on the repository connection.
    pub fn without_transaction(mut self) -> Self {
        self.txn = None;
        self
    }

    /// Returns the attached transaction, if any.
    pub fn transaction(&self) -> Option<&DatabaseTransaction> {
        self.txn.as_deref()
    }

    /// Returns true when a transaction is attached.
    pub fn has_transaction(&self) -> bool {
        self.txn.is_some()
    }

    /// Returns the effective caller id: `user_id` when set, else the `user` entity id.
    pub fn user_id(&self) -> Option<i64> {
        self.user_id.or_else(|| self.user.as_ref().map(|u| u.id()))
    }

    /// Overlays `other` on top of `self`, joining two parameter sets as you please.
    ///
    /// Scalar fields (`limit`, `distinct`, `detach`) are taken from `other`;
    /// optional fields (`cursor`, `user`, `user_id`, `correlation`, `txn`) fall back
    /// to `self` when `other` leaves them unset. A replaced `user` entity
    /// clears a stale inherited `user_id` (the id is still derivable from the
    /// entity via [`RepositoryOptions::user_id`]).
    ///
    /// Typical use: request-derived base joined with caller overrides —
    /// `RepositoryOptions::from_ctx(ctx).join(RepositoryOptions::new().with_limit(50))`.
    pub fn join(mut self, other: Self) -> Self {
        self.limit = other.limit;
        self.distinct = other.distinct;
        self.detach = other.detach;
        self.cursor = other.cursor.or(self.cursor);
        if other.user.is_some() {
            self.user = other.user;
            // Keep the id consistent with the newly joined entity unless the
            // caller explicitly joined an id alongside it.
            if other.user_id.is_none() {
                self.user_id = None;
            } else {
                self.user_id = other.user_id;
            }
        } else {
            self.user_id = other.user_id.or(self.user_id);
        }
        self.correlation = other.correlation.or(self.correlation);
        self.txn = other.txn.or(self.txn);
        self
    }
}

// Convenience for NoUser — with_user_id without entity
impl RepositoryOptions<NoUser> {
    /// Builds options from the request context: pagination limit and cursor,
    /// the numeric user id when the context carries one, and the correlation itself.
    /// Join caller overrides on top via [`RepositoryOptions::join`].
    pub fn from_ctx(ctx: Arc<CorrelationContext>) -> Self {
        Self {
            limit: ctx.pagination_limit(),
            cursor: ctx.pagination_cursor(),
            user_id: ctx.user_id().and_then(|s| s.parse().ok()),
            correlation: Some(ctx),
            ..Self::default()
        }
    }

    /// Replaces the [`NoUser`] identity with the given entity, keeping other settings.
    pub fn with_user_entity<U>(self, user: U) -> RepositoryOptions<U>
    where
        U: BaseEntity + Clone + Send + Sync + 'static,
    {
        RepositoryOptions {
            limit: self.limit,
            cursor: self.cursor,
            distinct: self.distinct,
            detach: self.detach,
            user: Some(user),
            user_id: None,
            correlation: self.correlation,
            txn: self.txn,
        }
    }
}

/// One cursor page of rows.
///
/// `T` is the row model type. `data` serializes as `items`, `has_next` as
/// `hasNext`, `next_cursor` as `next`, `total` as `count`, and `limit` as `limit`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PageResult<T> {
    /// Rows in this page, serialized as `items`.
    #[serde(rename = "items")]
    pub data: Vec<T>,

    /// Whether another page follows, serialized as `hasNext`.
    #[serde(rename = "hasNext")]
    pub has_next: bool,

    /// Cursor that produced this page, if any.
    #[serde(rename = "cursor", skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,

    /// Cursor for the next page (`None` when `has_next` is false), serialized as `next`.
    #[serde(rename = "next", skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<String>,

    /// Total matching rows ignoring cursor and limit, serialized as `count`.
    #[serde(rename = "count")]
    pub total: i64,

    /// Page size used for this page.
    #[serde(rename = "limit")]
    pub limit: usize,
}

impl<T> PageResult<T> {
    /// Returns the rows in this page.
    pub fn items(&self) -> &[T] {
        &self.data
    }
    /// Returns the page size recorded in the next-page cursor, if present and valid.
    pub fn limit(&self) -> Option<usize> {
        self.next_cursor
            .as_ref()
            .and_then(|c| CursorData::decode(c))
            .map(|d| d.limit)
    }
}

/// Builder wrapping a SeaORM entity loader with pagination and hydration settings.
///
/// `E` is the SeaORM entity being queried; its model must implement [`BaseEntity`]
/// so cursor pagination can use `id` comparisons. `order_asc` records the
/// cursor direction (`Some(true)` ascending, `Some(false)` descending).
pub struct QueryData<E>
where
    E: EntityTrait,
    E::ModelEx: BaseEntity,
    <E::ModelEx as BaseEntity>::LoaderType: EntityLoaderTrait<E, ModelEx = E::ModelEx>,
{
    /// The entity loader used to load relations for this entity type.
    pub loader: <E::ModelEx as BaseEntity>::LoaderType,

    /// Limit/cursor/distinct/detach settings applied at execution time.
    pub opts: RepositoryOptions<NoUser>,

    /// Recorded ordering direction for cursor filtering, if any ordering was set.
    pub order_asc: Option<bool>,
}

impl<E> QueryData<E>
where
    E: EntityTrait,
    E::ModelEx: BaseEntity,
    <E::ModelEx as BaseEntity>::LoaderType: EntityLoaderTrait<E, ModelEx = E::ModelEx>,
{
    /// Wraps an entity loader with default options and no ordering.
    pub fn new(loader: <E::ModelEx as BaseEntity>::LoaderType) -> Self {
        Self {
            loader,
            opts: RepositoryOptions::default(),
            order_asc: None,
        }
    }

    /// Copies limit, cursor, distinct, detach, correlation, and transaction settings from the given options.
    pub fn with_options<U>(mut self, opts: RepositoryOptions<U>) -> Self
    where
        U: BaseEntity + Clone + Send + Sync + 'static,
    {
        self.opts.limit = opts.limit;
        self.opts.cursor = opts.cursor;
        self.opts.distinct = opts.distinct;
        self.opts.detach = opts.detach;
        self.opts.correlation = opts.correlation;
        self.opts.txn = opts.txn;
        self
    }

    /// Orders by `id` and records the direction for cursor filtering.
    pub fn order_by(mut self, asc: bool) -> Self {
        if asc {
            self.loader = self.loader.order_by_id_asc();
        } else {
            self.loader = self.loader.order_by_id_desc();
        }
        self.order_asc = Some(asc);
        self
    }

    /// Orders by ascending `id` and records ascending cursor direction.
    pub fn order_by_asc(mut self) -> Self {
        self.loader = self.loader.order_by_id_asc();
        self.order_asc = Some(true);
        self
    }

    /// Orders by descending `id` and records descending cursor direction.
    pub fn order_by_desc(mut self) -> Self {
        self.loader = self.loader.order_by_id_desc();
        self.order_asc = Some(false);
        self
    }

    /// Marks the select distinct and records the distinct flag in options.
    pub fn distinct(mut self) -> Self {
        self.opts.distinct = true;
        self
    }

    /// Applies a filter to the loader via the given closure.
    pub fn filter<F>(mut self, f: F) -> Self
    where
        F: FnOnce(<E::ModelEx as BaseEntity>::LoaderType) -> <E::ModelEx as BaseEntity>::LoaderType,
    {
        self.loader = f(self.loader);
        self
    }

    /// Sets the select limit and records it in options.
    pub fn with_limit(mut self, limit: u64) -> Self {
        self.opts.limit = limit as usize;
        self
    }
}

/// Bulk-delete wrapper around a SeaORM `DeleteMany`.
///
/// `E` is the SeaORM entity being deleted. Cursor filtering for deletes
/// always uses `id > cursor`, regardless of ordering.
pub struct DeleteQueryData<E: EntityTrait> {
    /// The underlying delete being built.
    pub delete: sea_orm::DeleteMany<E>,
}

impl<E: EntityTrait> DeleteQueryData<E> {
    /// Wraps a SeaORM delete-many for repository execution.
    pub fn new(delete: sea_orm::DeleteMany<E>) -> Self {
        Self { delete }
    }

    /// Applies a filter to the delete via the given closure.
    pub fn filter<F>(mut self, f: F) -> Self
    where
        F: FnOnce(sea_orm::DeleteMany<E>) -> sea_orm::DeleteMany<E>,
    {
        self.delete = f(self.delete);
        self
    }
}