Bringing Itinera into existing code

/// What the payment's steps ask of the bank.
pub trait Payments: Send + Sync {
    fn charge(&self, card: &str, amount: i64) -> Result<String, Declined>;
    fn renewed_card(&self, card: &str) -> Option<String>;
}

/// The bank's client, as it was, behind the steps' trait.
impl Payments for Bank {
    fn charge(&self, card: &str, amount: i64) -> Result<String, Declined> {
        Bank::charge(self, card, amount)
    }

    fn renewed_card(&self, card: &str) -> Option<String> {
        Bank::renewed_card(self, card)
    }
}

/// Charges the amount to the card, and gives back the receipt.
#[derive(Step)]
struct Charge {
    #[input]
    card: String,
    #[input]
    amount: i64,
}

#[step]
impl Charge {
    fn run(
        self,
        #[service] payments: &dyn Payments,
        #[contributor] mut contributor: Contributor<'_>,
    ) -> Result<Outcome, Error> {
        match payments.charge(&self.card, self.amount) {
            Ok(receipt) => {
                contributor.contribute("receipt", receipt);
                Self::succeed()
            }
            Err(Declined::ExpiredCard) => Self::fail("card-expired"),
            Err(Declined::Refused) => Self::fail("declined"),
        }
    }
}

/// Repairs a charge whose card had expired: it asks the bank for the card that replaced it.
#[derive(RescueStep)]
struct RenewCard {
    #[input]
    card: String,
    #[reason]
    reason: Reason,
}

#[rescue_step]
impl RenewCard {
    fn run(
        self,
        #[service] payments: &dyn Payments,
        #[contributor] mut contributor: Contributor<'_>,
    ) -> Result<RescueOutcome, Error> {
        if self.reason.code() != "card-expired" {
            return Self::fail("not-repairable");
        }
        let Some(card) = payments.renewed_card(&self.card) else {
            return Self::fail("not-renewed");
        };
        contributor.contribute("card", card);
        Self::succeed()
    }
}

/// Writes every successful charge to the shop's audit trail.
#[derive(Default)]
struct Audit;

#[step_policy(name = "audit")]
impl Audit {
    #[on_step_success]
    fn charged(
        &self,
        #[from_workflow] amount: i64,
        #[from_step] receipt: String,
    ) -> Result<Option<OnSuccess>, Error> {
        audit::record(&format!("charged {amount}, receipt {receipt}"));
        Self::carry_on()
    }
}

/// Writes to the shop's log when a step fails, and when a rescue step repairs it.
#[derive(Default)]
struct Log;

impl Reporter for Log {
    fn report(&mut self, event: &Event) -> Result<(), Error> {
        match &event.body {
            EventBody::StepFailed { step, reason, .. } => log::info(&format!(
                "payment {}: {} failed, {}",
                event.journey_id,
                step.step,
                reason.code()
            )),
            EventBody::StepRescued { step, rescue, .. } => log::info(&format!(
                "payment {}: {} repaired by {rescue}",
                event.journey_id, step.step
            )),
            _ => {}
        }
        Ok(())
    }
}

/// Charges an order, renewing a card that has expired, and audits the charge.
#[workflow(name = "payment", reporters = [Log])]
#[with_step(Charge, name = "charge", rescue = RenewCard, policies = [Audit])]
pub struct Payment;

#[workflow]
impl Payment {
    /// Names each journey after its order.
    #[id_generator]
    fn order_number(&self, data: &DataBag) -> Result<String, Error> {
        Ok(data.required("order")?)
    }

    /// The bank, as it is configured today.
    #[provider(key = "payments")]
    fn bank(&self) -> Result<Provided<dyn Payments>, Error> {
        Ok(provide!(Bank {
            this_year: 2026,
            limit: 1000,
        }))
    }
}

/// What a payment starts with.
#[derive(InitialData)]
pub struct Due {
    pub order: String,
    pub card: String,
    pub amount: i64,
}

/// What a payment gives back.
#[derive(Output)]
pub struct Paid {
    pub receipt: String,
}

/// An order, as the shop's website hands it over.
pub struct Order {
    pub order: &'static str,
    pub customer: &'static str,
    pub card: &'static str,
    pub price: i64,
    pub discount: Option<i64>,
    pub weight: i64,
}

/// Why a checkout did not complete.
#[derive(Debug)]
pub enum CheckoutError {
    OutOfStock,
    PaymentDeclined(Declined),
    NotShipped,
    PaymentNotRun(String),
}

impl fmt::Display for CheckoutError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::OutOfStock => write!(f, "out of stock"),
            Self::PaymentDeclined(Declined::ExpiredCard) => write!(f, "card expired"),
            Self::PaymentDeclined(Declined::Refused) => write!(f, "payment declined"),
            Self::NotShipped => write!(f, "no carrier could take it"),
            Self::PaymentNotRun(why) => write!(f, "the payment did not run: {why}"),
        }
    }
}

/// Why the payment workflow could not say how the payment went.
fn not_run(error: impl fmt::Display) -> CheckoutError {
    CheckoutError::PaymentNotRun(error.to_string())
}

impl From<Declined> for CheckoutError {
    fn from(declined: Declined) -> Self {
        Self::PaymentDeclined(declined)
    }
}

/// The shop, with everything it talks to.
pub struct Shop {
    pub warehouse: Warehouse,
    pub main: Carrier,
    pub backup: Carrier,
    pub messages: Messages,
}

impl Shop {
    /// Reserves, charges and ships an order, and tells the customer how it went.
    pub fn checkout(&self, order: &Order) -> Result<String, CheckoutError> {
        log::info(&format!("checkout {}", order.order));
        let shipped = self.reserve_charge_and_ship(order);
        match &shipped {
            Ok(tracking) => self.messages.tell(
                order.customer,
                &format!("order {} is on its way: {tracking}", order.order),
            ),
            Err(error) => {
                log::warn(&format!("checkout {} failed: {error}", order.order));
                self.messages.tell(
                    order.customer,
                    &format!("order {} could not be completed", order.order),
                );
            }
        }
        shipped
    }

    fn reserve_charge_and_ship(&self, order: &Order) -> Result<String, CheckoutError> {
        self.warehouse
            .reserve(order.order)
            .map_err(|_| CheckoutError::OutOfStock)?;
        let amount = order.price - order.discount.unwrap_or(0);
        self.pay(order.order, order.card, amount)?;
        shipping::ship(&self.main, &self.backup, order.order, order.weight)
            .ok_or(CheckoutError::NotShipped)
    }

/// Charges an order's card through the payment workflow, and gives back the receipt.
fn pay(&self, order: &str, card: &str, amount: i64) -> Result<String, CheckoutError> {
    let instance = Payment::builder()
        .initial_data(Due {
            order: order.to_owned(),
            card: card.to_owned(),
            amount,
        })
        .create()
        .map_err(not_run)?;
    let result = local_executor_for!(Payment)
        .run(instance)
        .map_err(not_run)?;
    match &result.status {
        JourneyStatus::Succeeded { .. } => {
            let paid: Paid = result.output().map_err(not_run)?;
            Ok(paid.receipt)
        }
        JourneyStatus::Failed {
            failure: Failure::Failure(reason),
            ..
        } if reason.code() == "card-expired" => Err(Declined::ExpiredCard.into()),
        JourneyStatus::Failed { .. } => Err(Declined::Refused.into()),
        _ => Err(CheckoutError::PaymentNotRun(
            result.status.kind().to_string(),
        )),
    }
}