Skip to content

v0.4.0

@nshkrdotcom nshkrdotcom tagged this 19 Dec 08:03
Implement ItemBatcher feature for grouping scatter items into batches,
enabling more efficient execution patterns for batch APIs, ECS tasks,
and other scenarios where processing items in groups is preferable to
individual execution.

This feature mirrors AWS Step Functions ItemBatcher semantics, allowing
scatter operations to be batched before execution while maintaining
full barrier coordination and gather aggregation.

Batching Strategies:

  - Fixed size: max_items_per_batch for simple N-item batches
  - Size-based: max_bytes_per_batch with size_fn for payload-aware batching
  - Grouping: group_by with max_items_per_group for pre-grouped batching
  - Custom: batch_fn for user-defined batching logic

DSL Additions:

  batch_options do
    max_items_per_batch 20
    batch_input fn deps -> %{region: deps.region.id} end
    on_item_error :fail_batch
  end

Context Enhancements:

  When executing batched scatter instances, the context now includes:
  - batch_index: zero-based index of the current batch
  - batch_count: total number of batches created
  - batch_items: list of items assigned to this batch
  - batch_input: shared context evaluated once at scatter start

Architecture:

  - BatchOptions struct encapsulates all batching configuration with
    validation and JSON serialization for database persistence
  - Batcher module handles all batching strategies with consistent
    empty-batch filtering and batch context generation
  - ScatterBatchWorker provides Oban-based distributed execution with
    rate limiting, concurrency control, and failure threshold checking
  - Barrier schema extended with batching_enabled, batch_count, and
    batch_options fields for coordination state
  - Result schema extended with batch_index, batch_items, and batch_input
    for per-batch execution context

Telemetry:

  New events for batch lifecycle monitoring:
  - [:flowstone, :scatter, :batch_create]
  - [:flowstone, :scatter, :batch_start]
  - [:flowstone, :scatter, :batch_complete]
  - [:flowstone, :scatter, :batch_fail]

Testing:

  Comprehensive test coverage including:
  - BatchOptions validation and serialization
  - All batching strategies (fixed, size-based, grouped, custom)
  - Batch context generation
  - ScatterBatchWorker execution and failure handling
  - Integration with existing scatter barrier coordination

Also includes:
  - Migration 0012_add_item_batcher_fields.exs for schema changes
  - Example item_batcher_example.exs demonstrating usage patterns
  - Documentation updates to README and design docs
  - Minor fix to failure/parallel examples to write expected errors to stderr
Assets 2
Loading