Module http 

HTTP layer and REST endpoint implementations

This module provides generic HTTP/REST components for the Backbone CRUD system:

• CrudService trait: Core async trait for entity CRUD operations
• BackboneCrudHandler: Generic Axum router builder for all 11 endpoints
• Response types: ApiResponse, PaginatedResponse, BulkResponse

Re-exports

pub use crate::permission::guarded;

pub use crate::permission::guarded_all;

pub use crate::permission::permission_refusal;

pub use crate::permission::unauthenticated_refusal;

pub use crate::permission::CrudPermissions;

pub use crate::service::MAX_BATCH_SIZE;

Structs

ApiResponse

Standard API response wrapper

BackboneCrudHandler

Generic Backbone CRUD handler that provides all 11 endpoints as an Axum router.

BatchIdsRequest

Request body carrying a list of entity ids — used by bulk soft-delete, bulk restore, and bulk permanent-delete endpoints.

BulkCreateRequest

Bulk request for multiple entities

BulkPatchItem

One element of the per-id form of a bulk PATCH request.

BulkPreview

The answer of POST {resource}/bulk/preview: what a bulk PATCH would do.

BulkPreviewRow

One row of a bulk partial update’s dry run: the record as it is and as the patch would leave it, or the error the write would refuse it with.

BulkResponse

Bulk response

BulkUpdateItem

One element of the PUT {resource}/bulk array: an id plus the (flattened) full update DTO for that row.

FieldChange

One field’s value before and after a previewed write.

FilterOptions

Filtering and sorting options

HistoryEntry

Parse the reserved fields key (comma-separated) into trimmed field names. Absent/empty → empty vec, meaning “no projection — return every field”. One recorded change to a record.

ListQuery

The list query extractor every generic list-shaped route takes: ListQueryParams read off the query string, where a paging value that is not a number is refused by NAME, as an invalid_query violation on the parameter (page, limit), instead of axum’s bare “Failed to deserialize query string”.

ListQueryParams

Generic list query parameters

ListRequest

Extended pagination request with filtering and sorting

PaginatedApiResponse

Paginated API response with success flag, data array, and metadata at top level This is the preferred response format for list endpoints

PaginatedResponse

Generic paginated response (without success wrapper)

PaginationRequest

Pagination request (legacy)

PaginationResponse

Pagination response metadata

PreviewChange

A row a bulk PATCH would change.

PreviewRefusal

A row a bulk PATCH would refuse.

UpsertRequest

Upsert request (update or insert)

Enums

AccessScope

Per-request access scope, injected by the application’s auth middleware as an axum Extension. Platform sees everything (a superadmin / root caller); Company(id) is scoped to one tenant.

BulkPatchRequest

Body for PATCH {resource}/bulk. Accepts either a single patch applied to many ids, or a distinct patch per id. Shape is auto-detected.

SortOrder

Sort order enum

Constants

INTERNAL_ERROR_MESSAGE

The sentence a 500 answers with. The real error is logged, never sent: it can carry SQL, table names and driver text a client has no use for and an attacker does.

MAX_PAGINATION_OFFSET

Maximum number of rows offset pagination is allowed to skip. Requests that would page deeper than this are rejected with 400 so clients narrow their query with filters instead of deep-scanning the table (OFFSET cost grows with depth). At MAX_PER_PAGE this allows ~100 pages.

MAX_PER_PAGE

Hard cap on page size. Mirrors the clamp in backbone_orm::PaginationParams::new (per_page.clamp(1, 100)); kept here so the offset-depth check below computes the same effective offset the DB uses.

NOT_FOUND_MESSAGE

The sentence a 404 answers with.

Traits

BackboneHttpHandler

Synchronous trait for HTTP handlers implementing Backbone CRUD operations.

CrudService

Core trait that application services must implement for generic CRUD operations.

HistoryProvider

Supplies a record’s change history to the generic CRUD router.

Functions

correlation_middleware

Bind the request’s correlation id for the writes it makes, so the events they stage (and the logs and audit rows of the request) share one id.

service_error_response

The response for a failed ServiceError, for handlers outside the generic CRUD handler (a generated state-machine transition, a custom route) that call the service directly — the same answer the generic handler gives (see service_error_status). A 500 carries INTERNAL_ERROR_MESSAGE; the error itself is logged.

service_error_status

The status a ServiceError answers with, by variant.

without_secrets

A response body for a hand-written or generated route outside the generic handler (a state transition, a verb) that returns an entity’s response DTO: the entity’s secrets stripped, and its private fields kept from every caller, as the generic write responses do.