Struct GearCtx 

pub struct GearCtx { /* private fields */ }

Implementations

impl GearCtx

pub fn new( gear_name: impl Into<Arc<str>>, instance_id: Uuid, config_provider: Arc<dyn ConfigProvider>, client_hub: Arc<ClientHub>, cancellation_token: CancellationToken, ) -> Self

Create a new gear-scoped context with all required fields.

Attach a database entrypoint with with_db (feature db).

pub fn with_db(self, db: DBProvider<DbError>) -> Self

Attach the per-gear database entrypoint.

pub fn gear_name(&self) -> &str

pub fn instance_id(&self) -> Uuid

Returns the process-level instance ID.

This is a unique identifier for this process instance, shared by all gears in the same process. It is generated once at bootstrap.

pub fn config_provider(&self) -> &dyn ConfigProvider

pub fn client_hub(&self) -> Arc<ClientHub>

Get the ClientHub for dependency resolution.

pub fn cancellation_token(&self) -> &CancellationToken

pub fn db(&self) -> Option<DBProvider<DbError>>

Get a gear-scoped DB entrypoint for secure database operations.

Returns None if no database is configured for this gear.

Security

The returned DBProvider<toolkit_db::DbError>:

• Is cheap to clone (shares an internal Db)
• Provides conn() for non-transactional access (fails inside tx via guard)
• Provides transaction(..) for transactional operations

Example

let db = ctx.db().ok_or_else(|| anyhow!("no db"))?;
let conn = db.conn()?;
let user = svc.get_user(&conn, &scope, id).await?;

pub fn db_required(&self) -> Result<DBProvider<DbError>>

Get a database handle, returning an error if not configured.

This is a convenience method that combines db() with an error for gears that require database access.

Errors

Returns an error if the database is not configured for this gear.

Example

let db = ctx.db_required()?;
let conn = db.conn()?;
let user = svc.get_user(&conn, &scope, id).await?;

pub fn config<T: DeserializeOwned>(&self) -> Result<T, ConfigError>

Deserialize the gear’s config section into T.

This reads the gears.<name>.config object for the current gear and deserializes it into the requested type.

Errors

Returns ConfigError if the gear config is missing or deserialization fails.

pub fn config_or_default<T: DeserializeOwned + Default>( &self, ) -> Result<T, ConfigError>

Deserialize the gear’s config section into T, or use defaults if missing.

This method uses lenient configuration loading: if the gear is not present in config, has no config section, or the gear entry is not an object, it returns T::default(). This allows gears to exist without configuration sections in the main config file.

It extracts the ‘config’ field from: gears.<name> = { database: ..., config: ... }

Example

#[derive(serde::Deserialize, Default)]
struct MyConfig {
    api_key: String,
    timeout_ms: u64,
}

let config: MyConfig = ctx.config_or_default()?;

Errors

Returns ConfigError if deserialization fails.

pub fn config_expanded<T>(&self) -> Result<T, ConfigError>

where T: DeserializeOwned + ExpandVars,

Like config(), but additionally expands ${VAR} placeholders in fields marked with #[expand_vars].

Errors

Returns ConfigError if the gear config is missing, deserialization fails, or environment variable expansion fails.

pub fn config_expanded_or_default<T>(&self) -> Result<T, ConfigError>

where T: DeserializeOwned + Default + ExpandVars,

Like config_or_default(), but additionally expands ${VAR} placeholders in fields marked with #[expand_vars] (requires #[derive(ExpandVars)] on the config struct).

Gears that do not need environment variable expansion should use config_or_default().

Example

#[derive(serde::Deserialize, Default, ExpandVars)]
struct MyConfig {
    #[expand_vars]
    api_key: String,
    timeout_ms: u64,
}

let config: MyConfig = ctx.config_expanded_or_default()?;

Errors

Returns ConfigError if deserialization fails or if environment variable expansion fails.

pub fn raw_config(&self) -> &Value

Get the raw JSON value of the gear’s config section. Returns the ‘config’ field from: gears. = { database: …, config: … }

pub fn without_db(&self) -> GearCtx

Create a derivative context with the same references but no DB handle. Useful for gears that don’t require database access.

Trait Implementations

impl Clone for GearCtx

fn clone(&self) -> GearCtx

Returns a duplicate of the value.

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

Performs copy-assignment from source.