Struct MutationContext 

pub struct MutationContext {
    pub auth: AuthContext,
    pub request: RequestMetadata,
    /* private fields */
}

Context for mutation functions (transactional database access).

Fields

auth: AuthContext

Authentication context.

request: RequestMetadata

Request metadata.

Implementations

impl MutationContext

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

Create a new mutation context.

pub fn with_dispatch( db_pool: PgPool, auth: AuthContext, request: RequestMetadata, http_client: CircuitBreakerClient, job_dispatch: Option<Arc<dyn JobDispatch>>, workflow_dispatch: Option<Arc<dyn WorkflowDispatch>>, ) -> Self

Create a mutation context with dispatch capabilities.

pub fn with_env( db_pool: PgPool, auth: AuthContext, request: RequestMetadata, http_client: CircuitBreakerClient, job_dispatch: Option<Arc<dyn JobDispatch>>, workflow_dispatch: Option<Arc<dyn WorkflowDispatch>>, env_provider: Arc<dyn EnvProvider>, ) -> Self

Create a mutation context with a custom environment provider.

pub fn with_transaction( db_pool: PgPool, tx: Transaction<'static, Postgres>, auth: AuthContext, request: RequestMetadata, http_client: CircuitBreakerClient, job_info_lookup: JobInfoLookup, ) -> (Self, Arc<AsyncMutex<Transaction<'static, Postgres>>>, Arc<Mutex<OutboxBuffer>>)

Returns handles to transaction and outbox for the caller to commit/flush.

pub fn is_transactional(&self) -> bool

pub async fn conn(&self) -> Result<ForgeConn<'_>>

Acquire a connection compatible with sqlx compile-time checked macros.

In transactional mode, returns a guard over the active transaction. Otherwise acquires a fresh connection from the pool.

let mut conn = ctx.conn().await?;
sqlx::query_as!(User, "INSERT INTO users ... RETURNING *", ...)
    .fetch_one(&mut *conn)
    .await?

pub fn pool(&self) -> &PgPool

Direct pool access for operations that cannot run inside a transaction.

pub fn http(&self) -> HttpClient

Get the HTTP client for external requests.

Requests go through the circuit breaker automatically. When the handler declared an explicit timeout, that timeout is also applied to outbound HTTP requests unless the request overrides it.

pub fn raw_http(&self) -> &Client

Get the raw reqwest client, bypassing circuit breaker execution.

pub fn set_http_timeout(&mut self, timeout: Option<Duration>)

Set the default outbound HTTP request timeout for this context.

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

pub fn require_subject(&self) -> Result<&str>

pub fn set_token_issuer(&mut self, issuer: Arc<dyn TokenIssuer>)

Set the token issuer for this context.

pub fn set_token_ttl(&mut self, ttl: AuthTokenTtl)

Set the token TTL configuration (from forge.toml [auth]).

pub fn issue_token(&self, claims: &Claims) -> Result<String>

Issue a signed JWT from the given claims.

Only available when HMAC auth is configured in forge.toml. Returns an error if auth is not configured or uses an external provider (RSA/JWKS).

let claims = Claims::builder()
    .user_id(user.id)
    .duration_secs(7 * 24 * 3600)
    .build()
    .map_err(|e| ForgeError::Internal(e))?;

let token = ctx.issue_token(&claims)?;

pub async fn issue_token_pair( &self, user_id: Uuid, roles: &[&str], ) -> Result<TokenPair>

Issue an access + refresh token pair for the given user.

Stores the refresh token hash in forge_refresh_tokens and returns both tokens. Use rotate_refresh_token() to exchange a refresh token for a new pair, and revoke_refresh_token() to invalidate one.

TTLs come from [auth] in forge.toml:

• access_token_ttl (default “1h”)
• refresh_token_ttl (default “30d”)

pub async fn rotate_refresh_token( &self, old_refresh_token: &str, ) -> Result<TokenPair>

Rotate a refresh token: validate the old one, issue a new pair.

The old token is atomically deleted and a new access + refresh pair is returned. Fails if the token is invalid or expired.

pub async fn revoke_refresh_token(&self, refresh_token: &str) -> Result<()>

Revoke a specific refresh token (e.g., on logout).

pub async fn revoke_all_refresh_tokens(&self, user_id: Uuid) -> Result<()>

Revoke all refresh tokens for a user (e.g., on password change or account deletion).

pub async fn dispatch_job<T: Serialize>( &self, job_type: &str, args: T, ) -> Result<Uuid>

In transactional mode, buffers for atomic commit; otherwise dispatches immediately.

pub async fn dispatch_job_with_context<T: Serialize>( &self, job_type: &str, args: T, context: Value, ) -> Result<Uuid>

Dispatch a job with initial context.

pub async fn cancel_job( &self, job_id: Uuid, reason: Option<String>, ) -> Result<bool>

Request cancellation for a job.

pub async fn start_workflow<T: Serialize>( &self, workflow_name: &str, input: T, ) -> Result<Uuid>

In transactional mode, buffers for atomic commit; otherwise starts immediately.

Trait Implementations

impl EnvAccess for MutationContext

fn env_provider(&self) -> &dyn EnvProvider

Get the environment provider.

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

Get an environment variable.

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

Get an environment variable with a default value.

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

Get a required environment variable.

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

where T::Err: Display,

Get an environment variable and parse it to the specified type.

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

where T::Err: Display,

Get an environment variable and parse it, with a default.

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

Check if an environment variable is set.