Framework.Effects (Framework v0.5.0)

View Source

Effects & Idempotency implementation.

Handles effect declarations, idempotency key mapping, and Oban job enqueueing. Effects are enqueued inside the same DB transaction and visible only after commit.

Guarantees

  • Post-commit: effects enqueued inside same DB transaction
  • At-least-once: execution retries with backoff until success or dead-letter
  • Idempotent by construction: deterministic idempotency keys mapped to unique job keys
  • Outcome independence: visible outcomes decided at commit, effects never fabricate success

Supported effect types

  • :webhook - HTTP POST with idempotency key
  • :email - Email sending with template and model
  • :emit_operation - Emit operation back into the system

Summary

Functions

enqueue_effects(effects, correlation_ids)

Enqueue effects as Oban jobs within the current transaction.

get_max_attempts()

Gets the configured max_attempts for effects.

get_uniqueness_period()

Gets the configured uniqueness period for effect deduplication.

get_worker_module()

Gets the configured worker module for effects processing. Defaults to Framework.Effects.Worker for backward compatibility.

map_idempotency_to_external_id(idempotency_key, request_id)

Map idempotency keys to external_id for Oban uniqueness.

validate_effect(effect)

Validate and normalize a single effect declaration.

validate_effects(effects)

Validate and normalize effect declarations from operation plans.

Functions

enqueue_effects(effects, correlation_ids)

Enqueue effects as Oban jobs within the current transaction.

This function is called from Framework.Kernel.commit/2 to ensure effects are enqueued inside the same DB transaction.

get_max_attempts()

Gets the configured max_attempts for effects.

get_uniqueness_period()

Gets the configured uniqueness period for effect deduplication.

get_worker_module()

Gets the configured worker module for effects processing. Defaults to Framework.Effects.Worker for backward compatibility.

map_idempotency_to_external_id(idempotency_key, request_id)

Map idempotency keys to external_id for Oban uniqueness.

Mapping rules

  • {:by_request} → {kind, external_id := request_id}
  • {:by_natural_key, key} → {kind, external_id := key}

validate_effect(effect)

Validate and normalize a single effect declaration.

Returns normalized effect map or raises on validation errors.

validate_effects(effects)

Validate and normalize effect declarations from operation plans.

Returns {:ok, normalized_effects} | {:error, reason}