fix(server): stream the backup as an async iterator so it doesn't time out

[vpetersson]

Issues Fixed

Fixes issue #3073 — "Unable to Get backup since recent updates" (download dialog appears, body sits at 0 B, then times out on Pi 3B+/Pi 4B running v2026.06.3).

Description

The streaming backup added in #3005 never actually streamed under ASGI. StreamingHttpResponse only streams an asynchronous iterator; handed the synchronous stream_backup() generator, Django 5.2's __aiter__ falls into its sync-iterator branch and does await sync_to_async(list)(...) — draining the whole generator (building the entire tar.gz, buffered chunk-by-chunk in a RAM list) before the first response byte goes out. The headers (and so the browser download prompt) ship immediately, then the body stays at 0 B for the multi-minute build and the browser aborts. This is the exact failure #3005 set out to fix, plus an OOM risk on a 1 GB Pi with a multi-GB library.

The unit tests only called the helper directly, so they never traversed Django's ASGI __aiter__ and didn't catch it.

Fix:

• Add astream_backup(), an async wrapper that pulls each chunk from the existing producer/pipe generator via sync_to_async(next, thread_sensitive=False) so bytes flow as the archive is built and the memory footprint stays flat. thread_sensitive=False keeps the blocking pipe read off Django's single shared sync executor.
• On client disconnect Django aclose()s the async generator; we close the underlying sync generator so the producer thread stops taring instead of leaking.
• Point the download view at astream_backup() (so response.is_async is True and Django takes its real streaming path).
• Add a regression test that drives aiter(StreamingHttpResponse(...)) — the real ASGI consumption path — and round-trips through recover().

Checklist

• I have performed a self-review of my own code.
• New and existing unit tests pass locally with my changes.
• I have done an end-to-end test for Raspberry Pi devices (Pi 4B — see verification comment).
• I have tested my changes for x86 devices.
• I added a documentation for the changes I have made (when necessary).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes backup downloads timing out under ASGI by ensuring the backup stream is an async iterator, so Django’s ASGI streaming path sends bytes as the archive is produced (instead of buffering the entire generator in memory first).

Changes:

• Add astream_backup() as an async wrapper around the existing stream_backup() generator.
• Update the settings backup download view to use astream_backup() so ASGI truly streams.
• Add a regression test that iterates StreamingHttpResponse via the ASGI aiter(...) consumption path and validates recovery.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/test_backup_helper.py	Adds an ASGI-path regression test validating async streaming + recover() round-trip.
src/anthias_server/lib/backup_helper.py	Introduces astream_backup() async generator wrapper using sync_to_async to pull chunks.
src/anthias_server/app/views.py	Switches the backup download endpoint from stream_backup() to astream_backup() and updates docstring.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vpetersson]

On-device verification (Raspberry Pi 4 Model B Rev 1.5, 4 GB)

Built the pi4-64 server image from this branch, deployed it to a Pi 4 testbed, populated the device to 835 MB / 17 assets (uploaded sample videos via the real /api/v2/file_asset + /api/v2/assets flow), and drove the actual POST /settings/backup/ web endpoint with a real CSRF token, sampling the downloaded file size every second.

Before (current master image blank-3f05ead-pi4-64, the broken sync path):

t= 0s..68s  size=0          ← dead air: whole ~877 MB archive built in RAM first
t=69s       size=157 MB     ← then dumped all at once
t=71s       size=757 MB
TTFB=0.012s  TOTAL=72.0s  SIZE=877 MB  HTTP=200

The body sat at 0 bytes for 69 seconds (TTFB only reflects the headers — which is why the browser shows a download dialog that then stalls). The full archive was also held in RAM. On a multi-GB library this dead air exceeds the browser's request timeout → exactly issue #3073.

After (this branch, astream_backup()):

t= 1s  size=5.9 MB
t=10s  size=103 MB
t=30s  size=316 MB
t=60s  size=646 MB
t=81s  size=873 MB   (done)
TTFB=0.013s  TOTAL=82.1s  SIZE=877 MB  HTTP=200

Bytes flow from the first second and grow steadily (~11 MB/s) for the whole build — the browser sees continuous progress and never stalls, and server memory stays flat. The streamed archive passes gzip -t and tar tzf (contains .anthias/anthias.db, .anthias/anthias.conf, anthias_assets/), and the server logs show no "StreamingHttpResponse must consume synchronous iterators" warning — confirming Django took the async streaming path.

Testbed restored to its original image and asset library afterwards.

• End-to-end tested on a Raspberry Pi (Pi 4B).

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.