OrchidIntervention.Operate behaviour (orchid_intervention v0.2.0)

Copy Markdown View Source

Declares how an intervention type merges external data into a DAG step's output.

Every intervention type (:override, custom modules like MyApp.Operate.Offset)
must implement this behaviour. The callbacks inform the Hook whether the step
can be short-circuited and how caching keys should be derived.

Built-in Implementations

Custom Implementations

Pass the module atom directly as the intervention type:

%{"signal" => {MyApp.Operate.Offset, offset_param}}

The module must implement all callbacks in this behaviour.

Summary

Callbacks

data_enable()

Declares which data sources are relevant for cache key derivation.

merge(inner_data, intervention_data)

Performs the actual merge of step output with intervention data.

Functions

resolve_module(mod)

Resolves an intervention type atom to its Operate implementation module.

short_circuit?(mod)

Whether this intervention type can short-circuit step execution.

Callbacks

data_enable()

@callback data_enable() :: {boolean(), boolean()}

Declares which data sources are relevant for cache key derivation.

Returns {use_inner_result?, use_intervention_data?}.

Examples:

  • :override → {false, true} — inner data changes don't invalidate cache
  • A hypothetical :offset → {true, true} — both matter

merge(inner_data, intervention_data)

@callback merge(
  inner_data :: Orchid.Param.payload() | nil,
  intervention_data :: Orchid.Param.payload()
) :: {:ok, Orchid.Param.payload()} | {:error, term()}

Performs the actual merge of step output with intervention data.

  • inner_data is the step's computed payload (or nil when short-circuiting).
  • intervention_data is the resolved intervention payload.

Must return {:ok, merged_payload} or {:error, reason}.

Functions

resolve_module(mod)

@spec resolve_module(OrchidIntervention.intervention_type()) :: module()

Resolves an intervention type atom to its Operate implementation module.

Built-in atoms are mapped internally; any other atom is assumed to be
a module that implements this behaviour directly.

short_circuit?(mod)

@spec short_circuit?(module()) :: boolean()

Whether this intervention type can short-circuit step execution.

Derived from data_enable/0: when inner result is not needed (use_inner? = false), the step can be bypassed and the intervention data used directly.