Keep NOAA image cards on screen through network blips

[turbo5000c]

Description

Fixes the reported symptom where NOAA image tiles go blank whenever the Home Assistant host has a momentary network problem:

ERROR [custom_components.noaa_it_all.image] Error fetching aurora forecast image:
  Cannot connect to host services.swpc.noaa.gov:443 ssl:default [Timeout while contacting DNS servers]
ERROR [custom_components.noaa_it_all.image] Error fetching geoelectric field image: ... [Network unreachable]

The upstream failure is genuinely external, but the picture disappearing was a bug in this integration — four of them, in fact:

1. b"" is a hard error. All seven async_image() methods returned b"" on any failure and cached nothing. Core's _async_get_image() does if image_bytes := await entity.async_image(), so empty bytes are falsy, it raises HomeAssistantError, and ImageView turns that into an HTTP 500. One blip destroyed a perfectly good image because nothing was kept.
2. entity_picture was overridden to the raw NOAA URL, so the browser fetched services.swpc.noaa.gov directly rather than /api/image_proxy/. The card broke whenever the browser couldn't reach NOAA, and it made any cache inside async_image() unreachable for normal dashboard cards.
3. Timeouts were misclassified. A ClientTimeout expiry raises asyncio.TimeoutError, which is not an aiohttp.ClientError, so it fell through to the catch-all arm and logged Unexpected error fetching .... REQUEST_TIMEOUT = 30 also exceeded HA's ~10s image-proxy budget, so an in-request fetch could never use its budget.
4. Every transient blip logged at ERROR, which is wrong for a cloud_polling integration.

Fixes 1 and 2 are not independent. Removing the entity_picture override without a background refresher would leave image_last_updated permanently None → entity_picture stays None → the proxy is never called → async_image() never runs. The picture would be blank always, not just during outages.

What changed

• The seven near-identical entity classes (~70 duplicated lines each) collapse into a NoaaImageEntity base that fetches on a 10-minute timer, keeps the last successful bytes in memory, and serves them from there. A failed fetch touches nothing — not the bytes, not image_last_updated, not the ETag. That invariant is the fix. Subclasses keep only name, unique ID, device info, URL, content type and a log label.
• The fetch leaves the HTTP request path entirely, so a slow NOAA can't blow the proxy budget and concurrent dashboard clients don't each start their own request. The first fetch is scheduled rather than awaited during setup, so an unreachable NOAA can't hold up the config entry.
• entity_picture falls back to the upstream URL until the first successful fetch — in that window there's nothing cached to serve, and a browser on a working network can still render when HA's resolver can't, which is exactly the reported failure.
• Transient errors (timeouts, DNS failures, resets, disconnects) are classified together and the log level is staged by outage duration: debug while a cached frame is still being served, one warning at ~30 min, error at ~1 hour and periodically after, info on recovery. A non-transient failure (404, non-image content type) still warns immediately.
• Sends the integration's User-Agent; revalidates with ETag/Last-Modified so background polling stays cheap; sets the real content type per source (five of seven were not JPEG — two PNG, two GIF); caps response size; replaces deprecated datetime.utcnow().

Behaviour changes worth knowing

• Entity state moves from unknown to an ISO-8601 timestamp that advances when the bytes change — so "this image has gone stale" is now templatable.
• entity_picture becomes /api/image_proxy/... after the first fetch. Normal picture-entity / image cards are unaffected and get better; anything reading the raw NOAA URL out of the attributes will see a change.
• The integration now fetches all seven images every 10 minutes whether or not anyone is looking, where previously the browser fetched on render. Conditional requests collapse most of that to a 304.
• Known limitation, recorded in the changelog: two configured offices means two entities fetching byte-identical geoelectric/aurora images. A shared per-URL fetcher is the follow-up.

Type

• Bugfix
• Feature
• Documentation
• Other

Checklist

• Follows Home Assistant custom integration structure
• Passes flake8 checks (max-line-length=120) — clean on custom_components/noaa_it_all/ and tests/
• Manifest is valid and complete — version bumped 0.5.2 → 0.5.3
• README updated if required — the image-entities tip described the old "URL resolved once, never polled" behaviour and is now wrong; rewritten

Tests

744 passed, 21 subtests passed.

async_image() had zero coverage before this change, which is why the b"" bug survived in seven places. Added: the cache surviving each failure mode (connection error, asyncio.TimeoutError, server disconnect, HTTP 5xx, non-image content type, empty body, oversized body), first-ever failure returning None rather than b"", unchanged bytes not advancing the timestamp, 304 handling, the log-escalation ladder, conditional request headers, timer scheduling and cancellation, and the per-source content types.

The startup regression guard from c7ed6e6 (module-wide ban on the async_write_ha_state string) is retargeted, not dropped. Its real intent was "no state write on a path Home Assistant can reach before entity_id is assigned"; the background refresher now legitimately publishes state, so the string check is replaced by an AST check that the call may only appear inside the guarded _write_state_if_added helper, plus behavioural tests that a refresh landing before the entity is added is a no-op.

The test harness stubs Home Assistant with MagicMock modules, so this also adds stubs for homeassistant.helpers.event and homeassistant.util.dt, real aiohttp exception classes (mocked ones can't be used in an except clause), and an ImageEntity fake whose entity_picture mirrors upstream's None-until-image_last_updated semantic — the semantic the fallback exists to work around.

Manual verification still to do on a live instance

1. Restart HA; confirm the seven image.* entities show an ISO timestamp state and an /api/image_proxy/... picture.
2. Block egress to services.swpc.noaa.gov and force a refresh — the tiles must keep showing the last image, with at most a WARNING and no ERROR for the first couple of cycles.
3. Restore connectivity; confirm the INFO recovery line and that image_last_updated advances.

---

Generated by Claude Code