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:
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:
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:
if value is not None and not args.dry_run:
producer.produce(source, key=last.key(), value=value)
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.