Struct AppState 

#[non_exhaustive]
pub struct AppState {
    pub pool: PgPool,
    pub schema_cache: RwLock<SchemaCache>,
    pub config: AppConfig,
    pub jwt_config: JwtConfig,
    pub jwt_cache: Option<JwtCache>,
}

Shared application state.

#[non_exhaustive] from 3.0.0: build one with AppState::new, then assign any field that should differ from what the configuration says.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

pool: PgPool

Database connection pool

schema_cache: RwLock<SchemaCache>

Cached schema metadata

config: AppConfig

Application configuration

jwt_config: JwtConfig

JWT configuration

jwt_cache: Option<JwtCache>

Cache of validated tokens, when jwt_cache_enabled asks for one.

Implementations

impl AppState

pub fn new( pool: PgPool, schema_cache: SchemaCache, config: AppConfig, ) -> Result<Self, JwtKeyError>

State for config, serving schema_cache through pool.

The JWT configuration and token cache are derived from config, as build derives them. Fails when the configured JWT secret does not parse; see postrust_engine::jwt_config. With PGRST_JWT_JWKS_URL set the keys are fetched when first needed, by the request that needs them; build also fetches them before serving, and keeps them fresh in the background.

pub async fn schema_cache(&self) -> RwLockReadGuard<'_, SchemaCache>

Get a read lock on the schema cache.

pub async fn reload_schema(&self) -> Result<(), Error>

Reload the schema cache. Used by the db_channel_enabled listener.

pub fn default_schema(&self) -> &str

Get the default schema.

pub fn schemas(&self) -> &[String]

Get exposed schemas.

pub async fn begin_as( &self, user: &User, ) -> Result<Transaction<'static, Postgres>, Error>

A transaction on the pool that runs as user, as a REST request would: read-write, at the isolation level the configuration gives the role, with db_pre_request run. See AppState::begin_as_with.

pub async fn begin_as_with( &self, user: &User, options: TxOptions, ) -> Result<Transaction<'static, Postgres>, Error>

A transaction on the pool that runs as user.

The pool is logged in as the authenticator, and a query sent on it runs as the authenticator: with every grant it has, and with no request.jwt.claims for a row-level security policy to read, so the policies written for the API’s roles do not apply. This makes the transaction the caller’s before you send anything on it. The same statements REST sends for a request, worked out by the same Session: SET TRANSACTION where one is asked for, the role, the claims, the facts about the request user carries, the search_path and app.settings.*, and db_pre_request.

Every one of them is local to the transaction. Commit it or drop it – a dropped one is rolled back – and the connection goes back to the pool as the authenticator, with nothing set.

What this does not do is make your handler untrusted code. It keeps what a request sends inside the policy: every statement you run with the caller’s values in it runs as the caller. But the handler runs as the authenticator, which may always switch back – RESET ROLE on the transaction is enough – and it holds the pool. Treat it as you would a SECURITY DEFINER function: code you wrote and reviewed, not something the client controls.

Fails as REST fails: a connection that cannot be had from the pool in time is logged at error and answered 500 (PGRST500), and a session the database refuses – a role that does not exist, a pre-request function that raises – is answered as the database’s error.

Trait Implementations

impl State for AppState

type Db = Pool<Postgres>

The database requests run on.

type SchemaCache<'a> = RwLockReadGuard<'a, SchemaCache>

A borrow of the schema cache, held for as long as a request needs it.

fn db(&self) -> &PgPool

The database requests run on.

async fn schema_cache(&self) -> RwLockReadGuard<'_, SchemaCache>

The schema cache.

fn config(&self) -> &AppConfig

Configuration.

fn jwt_config(&self) -> &JwtConfig

How tokens are verified.

fn jwt_cache(&self) -> Option<&JwtCache>

The cache of verified tokens, where one is configured.

fn default_schema(&self) -> &str

The schema a request names when it names none.

fn schemas(&self) -> &[String]

The schemas the API exposes.