billing.py

Script · code/module-09/billing.py

Download billing.py

"""Billing, written to be tested (lesson 9.2).

The charge calculation is a plain function with no Kafka in it, so unit tests check it in
milliseconds. BillingService wraps it in lesson 7.1's transactional loop. It receives its consumer
and producer from outside, so a test can hand it fakes, or real clients connected to a Kafka in a
test container. A session event it can't read goes to a dead-letter topic, in the same transaction
as the charges, with lesson 5.3's dlq.* headers.

    from billing import BillingService, charge_for
    charge_for({"session_id": "ses-1", "charger_id": "BL-N03-04", "energy_kwh": 52.5}, "0.49")
    # -> amount_eur "25.73": 52.5 kWh x 0.49 EUR = 25.725, rounded half up to the cent
"""
import json
from datetime import datetime, timezone
from decimal import ROUND_HALF_UP, Decimal

from confluent_kafka import OFFSET_BEGINNING, TopicPartition

CENT = Decimal("0.01")


def charge_for(stopped, price_eur_per_kwh):
    """The charge for one finished session: energy x price, rounded half up to the cent.

    Decimal, not float: 52.5 x 0.49 is 25.725 exactly, and the tariff terms say half up, 25.73.
    In binary floating point it's 25.724999..., which round() turns into 25.72.
    """
    amount = Decimal(str(stopped["energy_kwh"])) * Decimal(str(price_eur_per_kwh))
    return {"session_id": stopped["session_id"], "charger_id": stopped["charger_id"],
            "energy_kwh": stopped["energy_kwh"], "price_eur_per_kwh": str(price_eur_per_kwh),
            "amount_eur": str(amount.quantize(CENT, rounding=ROUND_HALF_UP))}


class BillingService:
    """Reads session events and writes one charge per finished session.

    Each batch is one transaction: its charges, its dead-lettered records and the consumer's new
    position become visible together, or not at all.
    """

    def __init__(self, consumer, producer, charges_topic, price_eur_per_kwh, dlq_topic=None):
        self.consumer, self.producer = consumer, producer
        self.charges_topic, self.dlq_topic = charges_topic, dlq_topic
        self.price = price_eur_per_kwh

    def run_batch(self, max_records=100, timeout=1.0):
        """Process one batch in one transaction. Returns (charges written, records parked)."""
        records = [r for r in self.consumer.consume(max_records, timeout) if not r.error()]
        if not records:
            return 0, 0
        self.producer.begin_transaction()
        try:
            charged = parked = 0
            for record in records:
                try:
                    event = json.loads(record.value())
                    if event["type"] != "session_stopped":
                        continue
                    charge = charge_for(event, self.price)
                except (ValueError, KeyError, TypeError) as error:   # bad JSON, a missing or wrong field
                    if self.dlq_topic is None:
                        raise
                    self.park(record, error)
                    parked += 1
                    continue
                self.producer.produce(self.charges_topic, key=charge["session_id"], value=json.dumps(charge))
                charged += 1
            self.producer.send_offsets_to_transaction(self.consumer.position(self.consumer.assignment()),
                                                      self.consumer.consumer_group_metadata())
            self.producer.commit_transaction()
            return charged, parked
        except Exception:
            self.producer.abort_transaction()
            self.rewind()
            raise

    def park(self, record, error):
        """Send a record billing can't read to the dead-letter topic, with where it came from and why."""
        headers = [("dlq.error.class", type(error).__name__), ("dlq.error.message", str(error)),
                   ("dlq.source.topic", record.topic()), ("dlq.source.partition", str(record.partition())),
                   ("dlq.source.offset", str(record.offset())),
                   ("dlq.parked.at", datetime.now(timezone.utc).isoformat(timespec="seconds"))]
        self.producer.produce(self.dlq_topic, key=record.key(), value=record.value(), headers=headers)

    def rewind(self):
        """After an abort, go back to the last committed position, so the batch is read again."""
        for tp in self.consumer.committed(self.consumer.assignment(), timeout=10):
            self.consumer.seek(TopicPartition(tp.topic, tp.partition, tp.offset if tp.offset >= 0 else OFFSET_BEGINNING))