Trait StateMigration

Source

pub trait StateMigration:
    Send
    + Sync
    + 'static {
    type FromWorkflow: Workflow;
    type ToWorkflow: Workflow;

    // Required methods
    fn source_workflow_id(&self) -> &WorkflowId;
    fn target_workflow_id(&self) -> &WorkflowId;
    fn migrate(
        &self,
        state: <Self::FromWorkflow as Workflow>::State,
    ) -> Result<<Self::ToWorkflow as Workflow>::State, String>;
}

Expand description

A typed, one-directional migration from one workflow version to another.

Implement this trait for each FV-to-FV transition your deployment requires. The migrate function is called once per in-flight process stream and must be pure (no I/O, no clock access, no global state).

§Additive-only changes (same state type)

When both FVs share the same State type (only new optional fields added), the migration can be a no-op:

fn migrate(&self, state: SharedState) -> Result<SharedState, String> {
    Ok(state)
}

§Structural changes (different state types)

When the state layout changed incompatibly (renamed variant, removed field, changed discriminant), use different FromWorkflow::State and ToWorkflow::State types. The Rust compiler will enforce that every field is explicitly mapped:

fn migrate(&self, old: OldState) -> Result<NewState, String> {
    match old {
        OldState::Initiated(data) => Ok(NewState::Initiated(NewInitiatedData {
            ems_id:    data.ems_id,
            malo_id:   data.malo_id,
            initiated: data.initiated_at,  // renamed field
        })),
        OldState::Completed => Ok(NewState::Completed),
    }
}

Required Associated Types§

Source

type FromWorkflow: Workflow

The old workflow definition whose events are stored in matched streams.

Source

type ToWorkflow: Workflow

The new workflow definition that continues execution after migration.

Required Methods§

Source

fn source_workflow_id(&self) -> &WorkflowId

The WorkflowId (name + old BDEW FV) that identifies streams to migrate.

Source

fn target_workflow_id(&self) -> &WorkflowId

The WorkflowId (name + new BDEW FV) stamped into the migrated snapshot.

Source

fn migrate( &self, state: <Self::FromWorkflow as Workflow>::State, ) -> Result<<Self::ToWorkflow as Workflow>::State, String>

Map the fully-replayed old state to the new state type.

Called once per matched stream. Must be pure.

§Errors

Return Err(human_readable_reason) when the state cannot be migrated. The runner records the failure in MigrationReport::errors and continues with remaining streams — a single bad stream does not abort the entire migration.