Skip to main content

Storage

Trait Storage 

Source
pub trait Storage<R>: Validators {
    type Error: Display + Send;

    // Provided methods
    fn classify(&self, err: &Self::Error, ctx: &Context) -> Option<JsonApiError> { ... }
    fn sortable(&self) -> Option<&[&str]> { ... }
}
Available on crate features http and validation only.
Expand description

What a resource’s operations fail with.

Split from the operation traits so an implementation names its error once rather than in each of the four.

The error reaches the client as a 500 carrying only the correlation id — the Display output is logged, never serialized — so it is safe to return whatever your data layer produces.

Required Associated Types§

Source

type Error: Display + Send

Whatever your storage fails with.

Provided Methods§

Source

fn classify(&self, err: &Self::Error, ctx: &Context) -> Option<JsonApiError>

Report a failure that is the client’s fault, not the server’s.

Storage errors are 500s by default, and deliberately opaque: the Display output is logged, never serialized, so a connection string in an error message cannot reach a client.

Some failures are not the server’s fault, though — a ?sort= field the table cannot order on, a cursor that has expired, a page beyond what the backend will serve. Returning 500 for those tells the client to retry something that will never work. Override this to classify them:

ⓘ
fn classify(&self, err: &Self::Error, ctx: &Context) -> Option<JsonApiError> {
    match err {
        Error::UnsortableField(field) => Some(
            JsonApiError::in_request(ErrorCode::InvalidParameter, ctx)
                .detail(format!("cannot sort on `{field}`"))
                .parameter("sort"),
        ),
        // Everything else stays a logged 500.
        _ => None,
    }
}

None — the default — keeps whatever you return out of the response body. Whatever you do return is sent to the client, so return only what you would put in a log anyone can read. ctx is the request’s, so the error carries the same correlation id as everything else it will be read beside.

Note that the most common reason to reach for this — a ?sort= field you cannot order by — is already handled: declare sortable and the request is refused with a 400 before list is ever called.

Source

fn sortable(&self) -> Option<&[&str]>

The attributes ?sort= may name, or None for “anything goes”.

Declaring this closes the gap that classify otherwise leaves open. A ?sort= naming something absent from this list is the client’s mistake, and without the list it reaches list, comes back as a storage error, and — unless classify recognises it — is answered with a 500 telling the client to retry a request that can never succeed.

With the list, the same request is refused with a 400 naming the sort parameter, before storage is touched:

ⓘ
impl Storage<Todo> for App {
    type Error = StoreError;

    fn sortable(&self) -> Option<&[&str]> {
        Some(&["id", "message", "done"])
    }
}

None — the default — preserves the old behaviour for storage that can order by anything, or that would rather decide for itself.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§