extract: report a failing close() of a destination file as a warning

[ThomasWaldmann]

What

extract_item() writes the file content through a buffered writer, so the content of a small file (up to the buffer size, usually 4 KiB) only reaches the OS when the buffer gets flushed: at the truncate()/flush() after the chunk loop - and again at close() if that flush failed, because the data is still buffered then.

The first failure happens inside a backup_io block and becomes a BackupOSError, i.e. a warning for that file. The second one came from the implicit close of with fd:, outside of any backup_io block, so it escaped as a plain OSError and aborted the whole extraction with a traceback ("Local Exception", rc 2). Reproduced with a file size limit (ulimit -f), a full disk behaves the same with ENOSPC:

  File "borg/archive.py", line 1031, in extract_item
    fd.truncate(pos)
OSError: [Errno 27] File too large

The above exception was the direct cause of the following exception:
  ...
borg.helpers.errors.BackupOSError: truncate_and_attrs: [Errno 27] File too large

During handling of the above exception, another exception occurred:
  ...
  File "borg/archive.py", line 1010, in extract_item
    with fd:
OSError: [Errno 27] File too large

Big files are not affected: a chunk larger than the buffer is written directly, and after a failed direct write nothing is left in the buffer. So the abort needs a file whose creation succeeds while its data write fails, i.e. it depends on how the filesystem behaves at the boundary. Verified with a real full disk (a ramdisk, no error injection), extracting an archive of 20000 files of 4 KiB:

• APFS: file creation still succeeds when the volume is full and the data write fails. master aborted with the traceback above (rc 2) after 14272 files; with this PR the run continued to the end with a warning per file (rc 1).
• HFS+: when the volume is full, creating the file (or its directory) already fails with ENOSPC inside backup_io, so there master just warned as well. ext4 and tmpfs create inodes without needing data blocks, so they should behave like APFS (not verified).

How

Close the file explicitly:

• under backup_io("close") when everything else succeeded (close(2) itself can fail, e.g. on NFS), so a failure there is a warning for that file, like any other IO error on it;
• with a failing close ignored when an exception is already in flight: the file's failure is reported by that exception, and a repository error or a KeyboardInterrupt must not be turned into a per-file warning.

Tests

Two tests in extract_cmd_test.py patch open() in borg.archive to return a buffered writer (like open() does) over a raw file whose writes fail like on a full disk, resp. whose close fails: every file gets its warning and the run ends with the specific exit code. Without the fix, the first one aborts with the OSError escaping from the close.

Found while auditing borg extract for memory growth (#10331 is the other finding from that).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.75%. Comparing base (95856d4) to head (41d3bc7).
⚠️ Report is 7 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #10332   +/-   ##
=======================================
  Coverage   87.74%   87.75%           
=======================================
  Files         103      103           
  Lines       18817    18823    +6     
  Branches     2905     2905           
=======================================
+ Hits        16511    16518    +7     
  Misses       1602     1602           
+ Partials      704      703    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.