Struct GenericCrudService 

pub struct GenericCrudService<E, C, U, R>
where
    E: PersistentEntity + Clone,
    R: CrudRepository<E>,
{ /* private fields */ }

A fully generic CRUD service.

Type parameters:

• E — entity type (must implement PersistentEntity)
• C — create DTO (entity implements FromCreateDto<C>)
• U — update DTO (entity implements ApplyUpdateDto<U>)
• R — repository (implements CrudRepository<E>)

The service always holds an Arc<dyn CrudEventPublisher<E>>. When no publisher is needed, NoOpCrudEventPublisher is used (zero overhead). Event-publish errors are fire-and-forget — they never fail the operation.

Implementations

impl<E, C, U, R> GenericCrudService<E, C, U, R>

where E: PersistentEntity + Clone + FromCreateDto<C> + ApplyUpdateDto<U>, C: Send + Sync + 'static, U: Send + Sync + 'static, R: CrudRepository<E>,

pub fn new( repository: Arc<R>, lifecycle: Arc<dyn ServiceLifecycle<E>>, event_publisher: Arc<dyn CrudEventPublisher<E>>, ) -> Self

Full constructor — supply all three dependencies.

pub fn with_guard(self, guard: Arc<dyn WriteGuard<E>>) -> Self

Check every write against guard: its refusals refuse the write, its shadowed violations are logged and the write proceeds.

pub fn with_write_hooks(self, hooks: Arc<dyn WriteHooks<E>>) -> Self

Run hooks inside every write’s transaction, before and after the repository write (see crate::write_hooks). Declared events are staged by the hooks the schema generator emits for a model.

pub fn with_lifecycle( repository: Arc<R>, lifecycle: Arc<dyn ServiceLifecycle<E>>, ) -> Self

Create with a custom lifecycle and the no-op event publisher.

pub fn with_repository(repository: Arc<R>) -> Self

Create with the no-op lifecycle and no-op event publisher (generated default).

pub fn with_event_publisher( self, publisher: Arc<dyn CrudEventPublisher<E>>, ) -> Self

Replace the event publisher on an existing service (builder pattern).

pub fn repository(&self) -> &R

Access the underlying repository for custom query extensions.

pub async fn list( &self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> ServiceResult<(Vec<E>, u64)>

pub async fn list_with_info( &self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> ServiceResult<(Vec<E>, PaginationInfo)>

list, carrying the pagination info (cursor positions included) so the HTTP layer can surface keyset paging on every generic route.

pub async fn aggregate( &self, spec: &AggregateSpec, filters: HashMap<String, String>, ) -> ServiceResult<AggregateResult>

Group and reduce the rows list would return, under the same filters.

pub async fn create(&self, dto: C) -> ServiceResult<E>

pub async fn get_by_id(&self, id: &str) -> ServiceResult<Option<E>>

pub async fn update(&self, id: &str, dto: U) -> ServiceResult<Option<E>>

pub async fn soft_delete(&self, id: &str) -> ServiceResult<bool>

pub async fn restore(&self, id: &str) -> ServiceResult<Option<E>>

pub async fn hard_delete(&self, id: &str) -> ServiceResult<bool>

pub async fn list_deleted( &self, page: u32, limit: u32, ) -> ServiceResult<(Vec<E>, u64)>

pub async fn empty_trash(&self) -> ServiceResult<u64>

Permanently delete everything in the trash (atomic).

The trashed rows are loaded first, at most MAX_BATCH_SIZE of them (a larger trash is refused: empty it in batches by id), and the write guard and lifecycle are asked about each one as a single permanent delete would. The delete then names exactly those ids and rolls back unless every one is still in the trash, so a row trashed after the check is never deleted unchecked.

pub async fn count(&self) -> ServiceResult<u64>

pub async fn count_active(&self) -> ServiceResult<u64>

pub async fn find_by_id(&self, id: &str) -> ServiceResult<Option<E>>

Alias for get_by_id — used by generated handlers.

pub async fn permanent_delete(&self, id: &str) -> ServiceResult<bool>

Alias for hard_delete — used by generated handlers.

pub async fn count_deleted(&self) -> ServiceResult<u64>

Count soft-deleted entities.

pub async fn get_deleted_by_id(&self, id: &str) -> ServiceResult<Option<E>>

Retrieve a soft-deleted entity by ID (includes deleted records).

pub async fn list_deleted_filtered( &self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> ServiceResult<(Vec<E>, u64)>

List deleted entities with the same filters and search the active list takes.

pub async fn upsert(&self, dto: C) -> ServiceResult<E>

Upsert is not available on the generic service, and refuses rather than guessing.

An upsert must match the record it would update, by id or by a natural key. A create DTO carries no id and the framework knows no natural key for an entity, so the only thing this could do is create — which is what it used to do, silently duplicating the record on every retry. The generic HTTP route answers 501 for the same reason. An entity with a real upsert implements it in its own service.

pub async fn partial_update( &self, id: &str, fields: HashMap<String, Value>, ) -> ServiceResult<Option<E>>

where E: Serialize + DeserializeOwned,

Apply a partial update from a JSON map of field values.

Fields not present in the map are left unchanged. A key the entity does not have, or a new value for a protected field, refuses the whole write.

pub async fn bulk_create(&self, dtos: Vec<C>) -> ServiceResult<Vec<E>>

where E: FromCreateDto<C>,

Create many entities, all or nothing.

Each item goes through what a single create does — the DTO conversion, the write guard, the before_create hook — before anything is written; then the repository inserts them in one transaction. A failure anywhere fails the whole batch and names the item: a violation’s path starts with the item’s index (3/name).

pub async fn bulk_soft_delete(&self, ids: Vec<String>) -> ServiceResult<u64>

Soft-delete many entities by id (atomic).

pub async fn bulk_restore(&self, ids: Vec<String>) -> ServiceResult<Vec<E>>

Restore many soft-deleted entities by id (atomic).

pub async fn restore_all(&self) -> ServiceResult<u64>

Restore every soft-deleted entity (atomic). Returns the number restored. Emits a Restored event per entity, mirroring bulk_restore.

Like empty_trash, the trashed rows are loaded first (at most MAX_BATCH_SIZE), each is put to the write guard and lifecycle as a single restore would be, and the restore names exactly those ids, all or nothing.

pub async fn bulk_permanent_delete( &self, ids: Vec<String>, ) -> ServiceResult<u64>

Permanently delete many soft-deleted entities by id (atomic).

pub async fn bulk_update( &self, items: Vec<(String, U)>, ) -> ServiceResult<Vec<E>>

Full-update many entities (atomic). Each item is (id, UpdateDto).

pub async fn bulk_partial_update( &self, items: Vec<(String, HashMap<String, Value>)>, ) -> ServiceResult<Vec<E>>

where E: Serialize + DeserializeOwned,

Partial-update many entities (atomic). Each item is (id, field_map).

pub async fn preview_bulk_partial_update( &self, items: Vec<(String, HashMap<String, Value>)>, ) -> ServiceResult<Vec<BulkPreviewRow<E, ServiceError>>>

where E: Serialize + DeserializeOwned,

What bulk_partial_update would do, with nothing written. Each row goes through the same steps the write takes — it is found, the patch is merged and checked against the protected fields, the write rules are consulted (quietly: a shadow rule logs on the real write, not here) and the update hook runs — and its outcome is kept instead of failing the batch, so one dialog can say which rows would change and which would be refused. Only a batch that is too large or names an id twice fails as a whole, as the write does.

Trait Implementations

impl<E, C, U, R> Clone for GenericCrudService<E, C, U, R>

where E: PersistentEntity + Clone, R: CrudRepository<E>,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E, C, U, R> CrudService<E, C, U> for GenericCrudService<E, C, U, R>

where E: PersistentEntity + Clone + Serialize + DeserializeOwned + FromCreateDto<C> + ApplyUpdateDto<U> + Send + Sync + 'static, C: Send + Sync + 'static, U: Send + Sync + 'static, R: CrudRepository<E> + Send + Sync + 'static,

Blanket impl so that any GenericCrudService<E, C, U, R> automatically satisfies CrudService<E, C, U> without generated adapter structs.

Generated code emits only a type alias: pub type UserService = GenericCrudService<User, CreateUserDto, UpdateUserDto, UserRepository>;

That alias now directly implements CrudService and can be passed to BackboneCrudHandler without any additional boilerplate.

type Error = ServiceError

Error type for service operations

fn violations_of(err: &ServiceError) -> Option<Vec<Violation>>

The named rules a refused write broke, when the error carries them, so the response can list them beside the sentence. None by default.

fn status_of(err: &ServiceError) -> Option<StatusCode>

The status a failed call answers with, decided by the error’s kind rather than by searching its message. None (the default) leaves each route its own fallback: 422 when violations_of names rules, else the route’s usual status. GenericCrudService answers by variant (see service_error_status).

fn supports_upsert() -> bool

Whether this service has a real upsert. true by default, so a hand-written service that implements one keeps its route; GenericCrudService answers false, and the generic POST {resource}/upsert route then answers 501 rather than creating a duplicate.

fn entity_name() -> &'static str

Entity name for error messages (e.g., “User”, “Role”)

fn fetch_related_json<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, table: &'life1 str, ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Vec<Value>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Hydrate ?include= relations: fetch rows from table by id list, as JSON. Default: no expansion. GenericCrudService delegates to its repository.

fn list<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<E>, u64), ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List entities with pagination and filters

fn list_with_info<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<E>, PaginationInfo), ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

list, carrying the pagination info (cursor positions included) so the HTTP layer can surface keyset paging. Default: the tuple form — generated services override this with the repository’s cursors.

fn aggregate<'life0, 'life1, 'async_trait>( &'life0 self, spec: &'life1 AggregateSpec, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<AggregateResult, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Group and reduce the rows list would return, under the same filters.

fn table_name(&self) -> Option<&str>

The schema-qualified table this service reads, when it has one.

fn create<'life0, 'async_trait>( &'life0 self, dto: C, ) -> Pin<Box<dyn Future<Output = Result<E, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Create a new entity

fn get_by_id<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get entity by ID

fn update<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, dto: U, ) -> Pin<Box<dyn Future<Output = Result<Option<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Full update of entity

fn partial_update<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, fields: HashMap<String, Value>, ) -> Pin<Box<dyn Future<Output = Result<Option<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Partial update with specific fields

fn soft_delete<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Soft delete entity

fn bulk_create<'life0, 'async_trait>( &'life0 self, items: Vec<C>, ) -> Pin<Box<dyn Future<Output = Result<Vec<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Bulk create multiple entities

fn upsert<'life0, 'async_trait>( &'life0 self, dto: C, ) -> Pin<Box<dyn Future<Output = Result<E, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Upsert (create or update)

fn list_deleted<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, ) -> Pin<Box<dyn Future<Output = Result<(Vec<E>, u64), ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List deleted entities (trash)

fn restore<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Restore soft-deleted entity

fn empty_trash<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Permanently delete all soft-deleted entities

fn get_deleted_by_id<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get deleted entity by ID (from trash)

fn permanent_delete<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Permanently delete a single soft-deleted entity by ID

fn list_deleted_filtered<'life0, 'async_trait>( &'life0 self, page: u32, limit: u32, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<E>, u64), ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List deleted entities with filters

fn count_active<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count active (non-deleted) entities

fn count_deleted<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count deleted entities in trash

fn bulk_soft_delete<'life0, 'async_trait>( &'life0 self, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Soft-delete many entities by id. Returns the number affected.

fn bulk_restore<'life0, 'async_trait>( &'life0 self, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<Vec<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Restore many soft-deleted entities by id. Returns the restored rows.

fn bulk_permanent_delete<'life0, 'async_trait>( &'life0 self, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Permanently delete many soft-deleted entities by id.

fn restore_all<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Restore every soft-deleted entity. Returns the number restored.

fn bulk_update<'life0, 'async_trait>( &'life0 self, items: Vec<(String, U)>, ) -> Pin<Box<dyn Future<Output = Result<Vec<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Full-update many entities. Each item is (id, UpdateDto).

fn bulk_partial_update<'life0, 'async_trait>( &'life0 self, items: Vec<(String, HashMap<String, Value>)>, ) -> Pin<Box<dyn Future<Output = Result<Vec<E>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Partial-update many entities. Each item is (id, field_map).

fn preview_bulk_partial_update<'life0, 'async_trait>( &'life0 self, items: Vec<(String, HashMap<String, Value>)>, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<BulkPreviewRow<E, ServiceError>>>, ServiceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

What bulk_partial_update would do, with nothing written: each row as it is and as it would become, or why the write would refuse it. Ok(None) (the default) means this service has no dry run, and the route says so instead of guessing.

fn count_active_filtered<'life0, 'async_trait>( &'life0 self, filters: HashMap<String, String>, ) -> Pin<Box<dyn Future<Output = Result<u64, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count active entities MATCHING the caller’s filters.