Development chronicle — mb638 to mb639 · Actionable update diagnostics, real fallback URLs and stricter remote VERSION validation

Mediabot already knew how to check GitHub before an update.

The problem was what happened when that check failed.

An operator could see:

local: 3.4dev-20260814_010040 | github: Undefined
Cannot check: version could not be determined

That said almost nothing.

mb638 makes those failures visible. mb639 then makes sure the fallback URLs, timeout budget and configured override behave exactly as advertised.

No database schema change was required.

🦉 mb638 — The remote check explains itself

The bot can now distinguish HTTPS support problems, HTTP/TLS/network failures, proxy responses, empty VERSION files, invalid content and timeouts.

Instead of a bare Undefined, an operator can receive something useful such as:

Cannot check: GitHub version unavailable - HTTP 599 (SSL connect attempt failed)

The first IRC response is therefore already useful for diagnosis.

🔄 Two legitimate GitHub routes

Without an explicit override, Mediabot can try:

raw.githubusercontent.com
        ↓ failure
github.com/.../raw/.../VERSION

This helps when a firewall, proxy, IPv6 route or hosting policy affects only one endpoint.

⚙️ A real configuration override

The update configuration accepts:

[update]
VERSION_URL=https://mirror.example/VERSION
VERSION_TIMEOUT=8

VERSION_URL now genuinely means use this source.

It no longer means “try this first, then quietly fall back to the built-in GitHub URLs”.

Unset, Mediabot uses its normal GitHub sources.

Configured, Mediabot uses the configured source only.

⏱️ mb639 — Give the fallback time to happen

The audit found that two URLs could be configured internally while the asynchronous worker still had roughly the timeout budget of only one request.

If URL 1 consumed the full timeout, the worker could die just before URL 2 was attempted.

mb639 sizes the worker budget according to the number of selected URLs:

worker timeout
    >=
number of URLs × timeout per URL
    + safety margin

The fallback now exists in runtime, not merely in source code.

🧾 HTTP 200 is not enough

A proxy or captive portal can return 200 OK with an HTML page.

That must never become a Mediabot version.

Remote content is therefore accepted only when it actually parses as a valid Mediabot VERSION value.

The contract is now:

HTTP success
+
valid VERSION syntax
=
usable remote version

🧹 No stale failure reason

The diagnostic state is cleared before every check.

A previous:

HTTP 599

cannot contaminate a later successful request.

Each update check reports its own result.

🧪 Regression coverage

The final focused set covers:

138  getVersion HTTP behaviour
207  HTTP guard regression
539  non-blocking async version check
814  IRC update command
818  remote fetch diagnostics
819  timeout / override / VERSION truth guards

The final targeted validation completed green before commit.

🏰 Final parchment

The update owl used to return empty-clawed and refuse to explain what happened.

Now it can say whether the road was blocked, TLS failed, the gate returned an error, the parchment was empty, the parchment was fake, or the journey simply took too long.

If one normal road to GitHub is closed, it has enough time to try the second.

And when an administrator explicitly gives it another destination, it goes there and nowhere else.

A castle that can rebuild itself should also know how to explain why the supply road failed.