Module 5 solutions

Solution 1: Ship phase_count in both deploy orders

The solution notebook is in code/module-05/exercise-1/solution/.

Approach. Make the field optional, with null as its default:

code/module-05/exercise-1/solution/phase-count-both-orders.ipynb
PHASE_COUNT_FIELD = {"name": "phase_count", "type": ["null", "int"], "default": None,
                     "doc": "phases the charger uses; null = not reported (firmware before 4.3)"}
registry accepts v2 under FULL: True
gateway first works: True   (billing read 20 new readings)
billing first works: True   (phase_count of an old reading: None)

With the start version ("type": "int", no default), the registry refuses version 2, and a version 2 reader fails on old readings: No default value for field phase_count.

Why it works. FULL means both directions must work. An old reader skips a field it doesn't know, so a new field never hurts it: the gateway can go first. A new reader needs a value for the field in old readings, and that value comes from the default: billing can go first only if there is one. In Avro a union's default must match its first type, so null comes first in ["null", "int"].

"type": "int", "default": 3 would pass all three checks, and still be wrong. Every old reading would claim to come from a 3-phase charger, and the grid report would compute per-phase loads from an invented number. null says what's true, "not reported", and forces the code reading phase_count to handle that case.

Solution 2: A replay tool with a dry run

The solution tool and notebook are in code/module-05/exercise-2/solution/.

Approach. Classify each parked record, cheapest test first:

code/module-05/exercise-2/solution/replay_dlq.py
        try:
            deserialize(msg.value(), context)          # decodes: a good reading parked by mistake
            return "resend", msg.value()
        except SerializationError:
            pass
        try:
            legacy = json.loads(msg.value())           # a complete 3.9 payload: repair it
        except ValueError:
            return "unreadable", None                  # cut short: nothing to repair

The repair converts the legacy fields and units into a meter reading and serializes it with the registered schema. Sending and committing happen only on a real run, and the commit only once everything is sent:

code/module-05/exercise-2/solution/replay_dlq.py
        if value is not None and not args.dry_run:
            producer.produce(source, key=last.key(), value=value)
code/module-05/exercise-2/solution/replay_dlq.py
    if not args.dry_run and last is not None:
        if producer.flush(30):
            raise SystemExit("not everything was sent; nothing committed, run again")
        consumer.commit(message=last, asynchronous=False)  # handled up to here, even the unreadable ones

Output:

  would replay: resend=15 repaired=20; left for a person: unreadable=10
dry run sent nothing: True
  replayed: resend=15 repaired=20; left for a person: unreadable=10
  replayed: resend=0 repaired=0; left for a person: unreadable=0
replayed 35 readings: True
second run replayed nothing: True
repaired legacy readings: 20, with the right power: 20

Why it works. A good reading decodes, so it goes back unchanged. That includes the readings the "park every error" worker parked during the outage. A legacy payload fails the Avro decode but is valid JSON, so it can be converted: power in watts becomes power_kw, energy_wh becomes energy_kwh. A payload that was cut short is neither, and no code can recover the missing half, so it stays in the dead-letter topic for a person, with its headers.

The dry run reads and classifies everything but sends nothing and commits nothing, so the real run afterwards starts from the same place. The real run commits the dead-letter offsets only after flush() confirms every record was stored. If it dies halfway, the next run replays the same records again, which is at-least-once. Duplicate readings are harmless if the consumers are idempotent (lesson 3.2). Committing past the unreadable records is deliberate: they've been seen and reported, and replaying them again can't help.

The tool sends records back to the topic named in their dlq.source.topic header, so one tool serves every dead-letter topic that uses the same headers. Repaired readings use auto.register.schemas=false with use.latest.version=true: a replay tool should never invent a new schema version.