LLD: ATM¶

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from decimal import Decimal
from enum import Enum
from threading import Lock
from typing import Optional
import uuid


# ---------------------------------------------------------------------------
# Money-holding entities
# ---------------------------------------------------------------------------

class InsufficientFundsError(Exception): ...
class DailyLimitExceededError(Exception): ...


class Account:
    def __init__(self, account_id: str, balance: Decimal, daily_limit: Decimal):
        self.account_id = account_id
        self.balance = balance
        self.daily_limit = daily_limit
        self.daily_withdrawn = Decimal("0")
        self._lock = Lock()                    # guards balance + daily_withdrawn together

    def debit(self, amount: Decimal) -> None:
        """Raises without mutating anything if either check fails — check-then-act, one lock."""
        with self._lock:
            if self.daily_withdrawn + amount > self.daily_limit:
                raise DailyLimitExceededError(
                    f"withdrawing {amount} would exceed daily limit {self.daily_limit}"
                )
            if amount > self.balance:
                raise InsufficientFundsError(f"balance {self.balance} < requested {amount}")
            self.balance -= amount
            self.daily_withdrawn += amount

    def deposit(self, amount: Decimal) -> None:
        """Add new money without changing withdrawal-limit accounting."""
        with self._lock:
            self.balance += amount

    def reverse_debit(self, amount: Decimal) -> None:
        """Compensate a specific failed withdrawal, including its limit consumption."""
        with self._lock:
            self.balance += amount
            self.daily_withdrawn -= amount


@dataclass
class Card:
    card_number: str
    account: Account
    correct_pin_hash: str
    is_retained: bool = False

    def pin_matches(self, pin: str) -> bool:
        # a real implementation hashes with a salt; simplified here for focus on the state machine
        return self.correct_pin_hash == pin


# ---------------------------------------------------------------------------
# Cash dispensing
# ---------------------------------------------------------------------------

class Denomination(Enum):
    FIFTY = 50
    TWENTY = 20
    TEN = 10
    FIVE = 5


class DenominationUnavailableError(Exception): ...
class InsufficientCashError(Exception): ...


class CashDispenser:
    def __init__(self, inventory: dict[Denomination, int]):
        self.inventory = inventory
        self._lock = Lock()

    def _plan(self, amount: Decimal) -> dict[Denomination, int]:
        """Greedy largest-denomination-first breakdown. Doesn't mutate inventory —
        callers must confirm the plan then commit it atomically (see dispense())."""
        remaining = int(amount)
        plan: dict[Denomination, int] = {}
        for denom in sorted(Denomination, key=lambda d: -d.value):
            available = self.inventory.get(denom, 0)
            take = min(remaining // denom.value, available)
            if take:
                plan[denom] = take
                remaining -= take * denom.value
        if remaining != 0:
            # either the ATM is out of the right mix, or the amount isn't representable
            # at all (e.g. $15 with only $20/$50 bills on hand)
            raise DenominationUnavailableError(
                f"cannot represent {amount} with available denominations"
            )
        return plan

    def can_dispense(self, amount: Decimal) -> bool:
        with self._lock:
            try:
                self._plan(amount)
                return True
            except DenominationUnavailableError:
                return False

    def reserve(self, amount: Decimal) -> dict[Denomination, int]:
        """Atomically remove a note plan from available inventory before account debit."""
        with self._lock:
            plan = self._plan(amount)
            for denom, count in plan.items():
                self.inventory[denom] -= count
            return plan

    def release(self, plan: dict[Denomination, int]) -> None:
        """Return a reservation when debit or physical dispensing fails."""
        with self._lock:
            for denom, count in plan.items():
                self.inventory[denom] = self.inventory.get(denom, 0) + count

    def dispense_reserved(self, plan: dict[Denomination, int]) -> dict[Denomination, int]:
        """Hand an already-reserved note plan to the hardware layer."""
        # A real adapter can raise CashDispenseHardwareError here. Inventory was
        # reserved before the debit, so no competing withdrawal can consume it.
        return plan


# ---------------------------------------------------------------------------
# The debit-then-dispense operation, with compensation on hardware failure
# ---------------------------------------------------------------------------

class CashDispenseHardwareError(Exception):
    """Raised by the (simulated) dispenser hardware layer — jam, out of paper track, etc.
    Distinct from InsufficientCashError/DenominationUnavailableError, which are checked
    BEFORE the debit and never leave money in a torn state."""


def perform_withdrawal(account: Account, dispenser: CashDispenser, amount: Decimal) -> dict[Denomination, int]:
    """The 'hard part' of this exercise: money must be neither lost nor duplicated.

    Ordering is deliberate:
      1. Atomically reserve a concrete note plan, removing the TOCTOU gap between
         "can dispense" and "dispense" while concurrent withdrawals are running.
      2. Debit the account — if debit fails, release the reserved notes.
      3. Physically dispense. If this throws, the debit already happened, so we must
         credit the account back (the compensating action) before propagating the error,
         rather than leaving the customer's money gone with no cash in hand.

    This is intentionally NOT a distributed two-phase commit — it's a single process,
    so the compensation step is a plain synchronous call, not a saga with its own
    persistence. The real-world equivalent (ATM crashes between debit and credit-back)
    is why production ATMs log the debit to durable storage BEFORE calling the dispenser,
    so a reconciliation job can find and reverse orphaned debits after a restart — noted
    here, not built, since durable logging is infrastructure, not a class-design concern.
    """
    try:
        plan = dispenser.reserve(amount)          # step 1 — notes cannot be stolen by another withdrawal
    except DenominationUnavailableError as exc:
        raise InsufficientCashError(f"ATM cannot dispense {amount} with current cash on hand") from exc

    try:
        account.debit(amount)                     # step 2 — funds committed to leaving
    except Exception:
        dispenser.release(plan)                   # debit rejected; make the notes available again
        raise

    try:
        return dispenser.dispense_reserved(plan)  # step 3 — physical dispense
    except CashDispenseHardwareError:
        dispenser.release(plan)                   # hardware delivered nothing, so restore both resources
        account.reverse_debit(amount)             # compensating action — undo step 2 exactly
        raise                                     # surface the failure; caller ends the session, doesn't retry blindly


# ---------------------------------------------------------------------------
# The State pattern: one class per ATM state
# ---------------------------------------------------------------------------

class Operation(Enum):
    WITHDRAW = "withdraw"
    DEPOSIT = "deposit"
    BALANCE_INQUIRY = "balance_inquiry"


class IllegalATMOperationError(Exception): ...


class ATMState(ABC):
    """Every state implements the full verb set. A verb that makes no sense in a given
    state raises rather than silently no-op-ing — a caller pressing 'withdraw' with no
    card inserted should get a clear error, not a UI that mysteriously does nothing."""

    @abstractmethod
    def insert_card(self, atm: "ATM", card: Card) -> None: ...

    @abstractmethod
    def enter_pin(self, atm: "ATM", pin: str) -> None: ...

    @abstractmethod
    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None: ...

    @abstractmethod
    def eject_card(self, atm: "ATM") -> None: ...


class IdleState(ATMState):
    def insert_card(self, atm: "ATM", card: Card) -> None:
        if card.is_retained:
            raise IllegalATMOperationError("this card has been retained by an ATM; cannot be used")
        atm.current_card = card
        atm.pin_attempts = 0
        atm.set_state(HasCardState())

    def enter_pin(self, atm: "ATM", pin: str) -> None:
        raise IllegalATMOperationError("no card inserted")

    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None:
        raise IllegalATMOperationError("no card inserted")

    def eject_card(self, atm: "ATM") -> None:
        raise IllegalATMOperationError("no card to eject")


class HasCardState(ATMState):
    MAX_PIN_ATTEMPTS = 3

    def insert_card(self, atm: "ATM", card: Card) -> None:
        raise IllegalATMOperationError("a card is already inserted")

    def enter_pin(self, atm: "ATM", pin: str) -> None:
        assert atm.current_card is not None
        if atm.current_card.pin_matches(pin):
            atm.pin_attempts = 0
            atm.set_state(AuthenticatedState())
            return
        atm.pin_attempts += 1
        if atm.pin_attempts >= self.MAX_PIN_ATTEMPTS:
            atm.current_card.is_retained = True
            retained_card, atm.current_card = atm.current_card, None
            atm.set_state(OutOfServiceState(reason=f"card {retained_card.card_number} retained"))
        # else: stay in HasCardState, caller re-prompts for PIN

    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None:
        raise IllegalATMOperationError("PIN not yet verified")

    def eject_card(self, atm: "ATM") -> None:
        atm.current_card = None
        atm.set_state(IdleState())


class AuthenticatedState(ATMState):
    def insert_card(self, atm: "ATM", card: Card) -> None:
        raise IllegalATMOperationError("a card is already inserted and authenticated")

    def enter_pin(self, atm: "ATM", pin: str) -> None:
        raise IllegalATMOperationError("already authenticated")

    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None:
        atm.set_state(TransactionInProgressState())
        try:
            atm.run_transaction(operation, amount)
        finally:
            # whether the transaction succeeded or raised, the card stays in and the
            # session returns to Authenticated so the customer can do another operation
            atm.set_state(AuthenticatedState())

    def eject_card(self, atm: "ATM") -> None:
        atm.current_card = None
        atm.set_state(IdleState())


class TransactionInProgressState(ATMState):
    """A deliberately narrow state: while a transaction is executing, every verb is
    rejected outright (including eject_card) rather than allowed to interleave with
    a debit/dispense sequence already underway."""

    def insert_card(self, atm: "ATM", card: Card) -> None:
        raise IllegalATMOperationError("transaction in progress")

    def enter_pin(self, atm: "ATM", pin: str) -> None:
        raise IllegalATMOperationError("transaction in progress")

    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None:
        raise IllegalATMOperationError("a transaction is already in progress")

    def eject_card(self, atm: "ATM") -> None:
        raise IllegalATMOperationError("cannot eject card mid-transaction")


class OutOfServiceState(ATMState):
    """Entered on card retention or a technician-triggered fault. No card-facing verb
    succeeds here — the machine needs a technician reset (set_state back to Idle),
    modeled as an operational action outside the customer-facing verb set."""

    def __init__(self, reason: str):
        self.reason = reason

    def insert_card(self, atm: "ATM", card: Card) -> None:
        raise IllegalATMOperationError(f"ATM out of service: {self.reason}")

    def enter_pin(self, atm: "ATM", pin: str) -> None:
        raise IllegalATMOperationError(f"ATM out of service: {self.reason}")

    def select_operation(self, atm: "ATM", operation: Operation, amount: Optional[Decimal] = None) -> None:
        raise IllegalATMOperationError(f"ATM out of service: {self.reason}")

    def eject_card(self, atm: "ATM") -> None:
        raise IllegalATMOperationError(f"ATM out of service: {self.reason}")


class ATM:
    """The context object. Holds shared state (current card, dispenser, PIN attempt
    count) and delegates every customer-facing call to current_state — ATM itself
    contains no branching on 'what step are we at.'"""

    def __init__(self, cash_dispenser: CashDispenser):
        self.cash_dispenser = cash_dispenser
        self.current_state: ATMState = IdleState()
        self.current_card: Optional[Card] = None
        self.pin_attempts = 0

    def set_state(self, state: ATMState) -> None:
        self.current_state = state

    def insert_card(self, card: Card) -> None:
        self.current_state.insert_card(self, card)

    def enter_pin(self, pin: str) -> None:
        self.current_state.enter_pin(self, pin)

    def select_operation(self, operation: Operation, amount: Optional[Decimal] = None) -> None:
        self.current_state.select_operation(self, operation, amount)

    def eject_card(self) -> None:
        self.current_state.eject_card(self)

    def run_transaction(self, operation: Operation, amount: Optional[Decimal]) -> None:
        assert self.current_card is not None
        account = self.current_card.account
        if operation is Operation.WITHDRAW:
            assert amount is not None
            perform_withdrawal(account, self.cash_dispenser, amount)
        elif operation is Operation.DEPOSIT:
            assert amount is not None
            account.deposit(amount)
        elif operation is Operation.BALANCE_INQUIRY:
            pass  # read-only; ATM class or caller reads account.balance directly