Blog
EngineeringFor engineers

A device list with no "add one" button

TV access at a hostel is a list of device addresses on the Wi-Fi controller, and the controller only lets us replace the whole list at once. Here is how we stop two purchases from erasing each other.

Lodge Internet · 14 November 2026 · 6 min read

Two students at the same hostel pay for TV access in the same minute. Both payments clear. Both devices should go on the hostel's allow list. If we were careless, one of them would end up on it, and nothing anywhere would say so.

How TV access is enforced

A TV subscription is enforced on the hostel's Wi-Fi controller, not by us. Each controller can hold two groups of MAC addresses: an allow list, whose devices get access, and a deny list, for devices whose subscription lapsed. backend/app/services/mac_groups.py is the only code that reads or writes those groups, and backend/app/services/tv_access.py sits above it and knows which hostel belongs to which controller.

The catch is in how the controller edits a group. There is no call that adds one address, and none that removes one. The controller's own dashboard sends the entire group back with the entry inserted or missing, and that is the only way to change it. Every edit is a read, a change in memory, and a write of the whole list.

The lost update

Put two purchases side by side.

  1. Purchase A reads the allow list.
  2. Purchase B reads the same allow list.
  3. A writes the list plus device A.
  4. B writes the list plus device B, built from its earlier read.

Device A is gone. B's write didn't remove it on purpose. It wrote back a copy that never had it. Both purchases saw a successful write, so nothing in the logs looks wrong. The first anyone hears of it is a student whose TV won't connect.

Lock, re-read, write, verify

Every change to a group goes through one function, apply_change, and it always does the same four things:

async def apply_change(controller, *, add=None, remove=None):
    async with group_lock(controller):
        groups = await load_groups(controller)        # fresh, inside the lock
        entries = with_change(groups, add, remove)
        await write_group(controller, entries)        # the whole list

    after = await load_groups(controller)             # read it back
    if not change_is_there(after, add, remove):
        raise MacGroupError("the write did not stick")

The lock is a short one, per controller, held only across two HTTP calls. A purchase that finds it taken waits instead of failing, because nobody should lose a paid subscription because someone else bought at the same moment.

The re-read happens inside the lock. Whatever the purchase knew before it arrived doesn't matter. It edits the list as it is now.

The verification happens after the lock is released. A slightly stale read there is harmless, and holding the lock for another round trip would only make everyone else wait longer. If the address isn't where it should be, the change is reported as a failure, not a success.

Two smaller rules sit inside that. A write is never retried blindly: in the code's own words, a blind retry on a write could double-apply. And if Redis, where the lock lives, is unreachable, the change still goes ahead. Refusing a paid subscription over a lock outage would be worse, and the verification after the write is the check that still holds without the lock.

Matching a group by shape

The groups on our controllers were set up by hand, over time, by different people. The same group goes by different names on different controllers, with different capitalisation and extra words. Matching one exact string would break the first time someone renamed a group.

So classify_group matches by shape instead. A group counts if it is the MAC-address type (which on its own excludes the controller's built-in groups) and its name, folded to lower case with punctuation stripped, mentions allowing or denying:

def classify_group(group):
    if group.get("type") != MAC_GROUP_TYPE:
        return None
    name = normalised(group.get("name"))
    # Deny is checked first: a name that says both is ambiguous,
    # and denying is the safer reading.
    if "deny" in name or "denied" in name or "block" in name:
        return DENY
    if "allow" in name or "allowed" in name or "permit" in name:
        return ALLOW
    return None

If two groups on one controller both look like the allow list, we stop and say so. Guessing between them could put a device on the wrong list, so a person has to rename one.

A list that can't be empty

The controller refuses to save a group with no entries in it. That sounds like tidiness, but it matters for revoking. When a subscription ends, we take the device off the allow list. If that device was the only entry, the write would be refused, and the one person whose access had lapsed would keep it.

So when a write would leave a group empty, we put a reserved placeholder in it: an address that can never belong to a real device, labelled so nobody deletes it. It goes in only when the list would otherwise be empty, it comes out on the next real write to that group, and load_groups filters it out so no other code ever sees it.

Revoking is also ordered on purpose. The device comes off the allow list first, then goes on the deny list. Not every controller has a deny list yet. On those, access is still removed, which is the half that matters, and the missing deny list is reported.

Four ways in, one way to grant

A TV subscription can start in four places: the website's checkout, a bank transfer through the bot, a card payment confirmed by Paystack's webhook, and a customer adding their device's address after paying.

Those paths didn't always agree. The bot path used to create the subscription record and stop there. The payment cleared, the record said "pending activation", and it stayed that way, with no error anywhere to notice. The bot's confirmation message had its own copy of the wording and told every customer to wait for activation, whatever had actually happened.

Now three of the four go through resolve_purchase in tv_access.py. It takes a hostel, a device address and a name, and always returns one of three outcomes:

  • active: the device is on the allow list, and the dates are set.
  • blocked, with the reason: the device is on the deny list, the hostel has no controller, or the grant failed. An admin is told.
  • pending activation: there is no device address yet. This is the only case where "we'll activate it" is still true.

It never writes anything itself. The caller merges the outcome into its own record, so "active" can only ever mean the device was actually granted. The wording the bot sends comes from the same place, so it describes what really happened.

The website's checkout is the exception, and on purpose. It also handles extending a subscription that is already running on the same device, and resolve_purchase has no idea what an extension is. So that route calls the same two steps itself: the deny-list check, then tv_access.grant. Every path, including the admin's repair action, ends in the same grant, and the grant ends in apply_change.

The trade-offs

The lock serialises every change on a controller, so purchases behind the same controller queue behind each other for a moment. That costs a short wait, which is a fair price for not losing a device.

The lock wait is bounded. If it runs out, we log it and go ahead, and rely on the verification. Verification catches a lost write. It doesn't repair one. It turns the purchase into "blocked, with a reason", so an admin can fix it by hand.

Every write sends the whole list. As lists grow, so do the writes. It's fine for the size of a hostel, and something to watch if a controller ever serves far more devices.

What's still open

The website's checkout still has its own copy of the grant sequence. Teaching resolve_purchase about extensions would let it join the other three.

The controller and our subscription records are two sources of truth that can drift: a manual edit on the controller, or a grant that failed. We compare them and flag paid subscriptions whose device is on no allow list. Closing that gap automatically, rather than flagging it, is the next step.

For what this looks like from the customer's side, see Getting your TV online at your hostel.

Last checked against the product on 14 November 2026.

More in Engineering