Struct QueryContext 

#[non_exhaustive]
pub struct QueryContext {
    pub auth: AuthContext,
    pub request: RequestMetadata,
    /* private fields */
}

Context for query functions (read-only database access).

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.

auth: AuthContext

request: RequestMetadata

Implementations

impl QueryContext

pub fn new(db_pool: PgPool, auth: AuthContext, request: RequestMetadata) -> Self

Create a new query context.

pub fn with_env( db_pool: PgPool, auth: AuthContext, request: RequestMetadata, env_provider: Arc<dyn EnvProvider>, ) -> Self

Create a query context with a custom environment provider.

pub fn set_kv(&mut self, kv: Arc<dyn KvHandle>)

Attach a KV store handle. Called by the runtime before handing the context to the handler.

pub fn kv(&self) -> Result<&dyn KvHandle>

Access the KV store.

Returns an error if the runtime did not supply a KV handle (this should not happen in production; it can only occur in unit tests that construct a bare QueryContext without going through the runtime).

pub fn db(&self) -> ForgeDb

Database handle with automatic db.query tracing spans.

Works directly with sqlx compile-time checked macros:

sqlx::query_as!(User, "SELECT * FROM users")
    .fetch_all(ctx.db())
    .await?

pub fn db_conn(&self) -> DbConn<'_>

Get a DbConn for use in shared helper functions.

Returns a pool-backed DbConn that can be passed to functions accepting DbConn<'_> for cross-context reuse.

pub async fn list_items(db: DbConn<'_>) -> Result<Vec<Item>> { ... }

#[forge::query]
pub async fn get_items(ctx: &QueryContext) -> Result<Vec<Item>> {
    list_items(ctx.db_conn()).await
}

pub fn user_id(&self) -> Result<Uuid>

Get the authenticated user’s UUID. Returns 401 if not authenticated.

pub fn tenant_id(&self) -> Option<Uuid>

Get the tenant ID from JWT claims, if present.

pub fn claim(&self, key: &str) -> Option<&Value>

Look up a custom JWT claim by name. Reserved JWT claims (iss, aud, nbf, jti, sub, iat, exp, roles) are filtered out by AuthContext::claim to prevent injection via #[serde(flatten)]. Shortcut for self.auth.claim(key).

Trait Implementations

impl AuthenticatedContext for QueryContext

fn user_id(&self) -> Result<Uuid>

Returns the authenticated user’s UUID, or Unauthorized if the request is not authenticated or the subject is not a UUID.

fn tenant_id(&self) -> Option<Uuid>

Returns the tenant ID from the tenant_id JWT claim, if present.

impl EnvAccess for QueryContext

fn env_provider(&self) -> &dyn EnvProvider

fn env(&self, key: &str) -> Option<String>

fn env_or(&self, key: &str, default: &str) -> String

fn env_require(&self, key: &str) -> Result<String>

fn env_parse<T: FromStr>(&self, key: &str) -> Result<T>

where T::Err: Display,

fn env_parse_or<T: FromStr>(&self, key: &str, default: T) -> Result<T>

where T::Err: Display,

Returns the default when unset; errors only if the variable is set but unparseable.

fn env_contains(&self, key: &str) -> bool

impl HandlerContext for QueryContext

fn db(&self) -> ForgeDb

Database handle with automatic db.query tracing spans.

fn db_conn(&self) -> DbConn<'_>

Unified connection handle for shared helper functions.