Struct AppState 

pub struct AppState(/* private fields */);

Shared state available to every handler through State<AppState>.

One Arc around AppStateInner: every middleware layer, the request’s extensions and each handler’s State clone it, so a clone is one atomic increment (it was a struct of about 35 fields, cloned tens of times per request: #334). Read its parts as fields, through Deref: state.db, state.config, state.queue…

Implementations

impl AppState

pub fn broadcast(&self, event: &str, data: impl Serialize) -> Result

Sends the DOM event event, with data as its detail, to every page open in this process with a notification stream (the UI kit’s notification_bell or event_stream(), which need Auth::new().notifications()), whoever is logged in there.

Pages listen as to any DOM event on document: htmx with hx-trigger="order-updated from:document", Alpine with x-on:order-updated.document="…", a script with document.addEventListener("order-updated", e => e.detail). The event renox:toast with {"toasts": [toast]} shows toasts.

It is fire-and-forget: nothing is stored, and pages that aren’t connected at that moment (closed, reconnecting, open on another server, or a queue:work process sent it) never get it. Use a database notification (AppState::notify) for what must arrive.

state.broadcast("order-updated", json!({ "id": 7, "status": "paid" }))?;
// Only Ana's pages (any tab, any device on this server):
state.broadcast_to(user.id, "renox:toast", json!({ "toasts": [Toast::info("Export ready")] }))?;

pub fn broadcast_to( &self, user_id: i64, event: &str, data: impl Serialize, ) -> Result

AppState::broadcast to the pages of one user (by id) only.

pub async fn notify( &self, to: impl Into<Recipient>, notification: &impl Notification, ) -> Result

Delivers notification now to a user (&user) or to addresses (a Recipient), on each of its channels. The database row is written first and mail sent last, so a failure doesn’t leave a message behind that a retry would send again.

pub async fn notify_later( &self, to: impl Into<Recipient>, notification: &impl Notification, ) -> Result

Like notify, but mail and the app’s channels are sent by queue workers, each channel as its own job with its own retries. The messages are built now; the database row is written now.

impl AppState

pub async fn emit<E: Event>(&self, event: E) -> Result

Runs every listener of E in registration order: those added with App::listen first, then modules’ (registered at boot). All of them run even if one fails; the first error is returned.

impl AppState

pub fn lang(&self, locale: &str) -> Lang

The texts of locale, for code without a request (a job, a mail to someone in another language).

pub fn current_lang(&self) -> Lang

The texts of the current_locale.

impl AppState

pub fn mail_view( &self, to: impl Into<String>, subject: impl Into<String>, view: &str, ctx: impl Serialize, ) -> Result<Mail>

Renders {view}.html into a mail, with {view}.txt as the text version when it exists (otherwise text made from the HTML). Templates see app (app.locale too) and t(key, …) in the current_locale besides ctx, can extend renox/mail/layout.html and import renox/mail/components.html (button, panel, table).

pub fn mail_view_in( &self, locale: &str, to: impl Into<String>, subject: impl Into<String>, view: &str, ctx: impl Serialize, ) -> Result<Mail>

mail_view in locale (the recipient’s language).

pub async fn queue_mail(&self, mail: Mail) -> Result<i64>

Sends mail from a queue worker, retrying up to five times.

pub fn mailer_named(&self, name: &str) -> Result<&Mailer>

A mailer the app added with App::mailer, e.g. state.mailer_named("newsletter")?.send(mail); an unknown name is an error (500).

pub async fn queue_mail_via(&self, mailer: &str, mail: Mail) -> Result<i64>

Like queue_mail, through the mailer named mailer.

impl AppState

pub fn provided<T: Send + Sync + 'static>(&self) -> Option<Arc<T>>

A value given to App::provide, if one of type T was.

impl AppState

pub async fn dispatch<J: Job>(&self, job: J) -> Result<i64>

Shorthand for state.queue.dispatch(job).

pub async fn dispatch_sync<J: Job>(&self, job: J) -> Result

Runs job now, in this task, instead of queueing it (no retries, middleware or failed hook): the error, if any, is returned.

impl AppState

pub fn signed_url( &self, name: &str, params: &[&dyn Display], ttl: Duration, ) -> Result<String>

An absolute URL to a named route, valid for ttl and signed with APP_KEY.

pub fn sign_path(&self, path: &str, ttl: Duration) -> Result<String>

Like signed_url, for an already-encoded path such as /_renox/files/a.pdf.

pub fn absolute_url( &self, name: &str, params: &[&dyn Display], ) -> Result<String>

An absolute URL to a named route.

impl AppState

pub fn url(&self, name: &str, params: &[&dyn Display]) -> Result<String>

The URL path of a named route, e.g. state.url("products.show", &[&id]).

pub fn encrypt(&self, plain: &str) -> String

Encrypts plain with APP_KEY (AES-256-GCM), e.g. an API secret a user saves, before storing it. The result is base64 text; only AppState::decrypt with the same key reads it back, and any change to it is detected. Rotating APP_KEY makes old values unreadable.

let sealed = state.encrypt("sk_live_123");
assert_eq!(state.decrypt(&sealed)?, "sk_live_123");

pub fn decrypt(&self, sealed: &str) -> Result<String>

Reads a value from AppState::encrypt. Fails if it was changed or sealed with another key.

impl AppState

pub fn disk_named(&self, name: &str) -> Result<&Storage>

A disk the app added with App::disk, e.g. state.disk_named("backups")?; an unknown name is an error (500).

Trait Implementations

impl Clone for AppState

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for AppState

type Target = AppStateInner

The resulting type after dereferencing.

fn deref(&self) -> &AppStateInner

Dereferences the value.

impl FromRef<AppState> for Db

fn from_ref(state: &AppState) -> Self

Converts to this type from a reference to the input type.

impl<T> FromRequest<AppState> for Valid<T>

where T: DeserializeOwned + Validate + Send,

type Rejection = Response<Body>

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request(req: Request, state: &AppState) -> Result<Self, Response>

Perform the extraction.

impl FromRequestParts<AppState> for Cookies

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Infallible>

Perform the extraction.

impl<T: Send + Sync + 'static> FromRequestParts<AppState> for Provided<T>

type Rejection = Error

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( _: &mut Parts, state: &AppState, ) -> Result<Self, Error>

Perform the extraction.