fix: atomic audio save with error handling and filesystem health endpoint

[jamiepine]

Summary

• Atomic writes for save_audio() — writes to .tmp then os.replace() to prevent corrupted/partial WAV files on interrupted writes
• Errno-specific error handling in /generate — catches BrokenPipeError, ENOENT (dir not found), EACCES (permission denied), ENOSPC (disk full) with clear user-facing messages
• New /health/filesystem endpoint — probes directory existence & write permissions for generations, profiles, and data dirs, reports disk free/total space, flags unhealthy if <500 MB free

Cherry-picked and expanded from #178 (@Vaibhavee89).

Changes

• backend/utils/audio.py — atomic write via temp file + os.replace(), cleanup on failure
• backend/main.py — error handling around save_audio call, new /health/filesystem endpoint
• backend/models.py — DirectoryCheck and FilesystemHealthResponse pydantic models

Summary by CodeRabbit

Release Notes

• New Features

  • Added filesystem health monitoring endpoint that reports per-directory status and overall disk space information.

• Bug Fixes

  • Enhanced error reporting for audio saving operations to provide specific, actionable error messages when failures occur.
  • Improved reliability of audio file saving with better handling of disk-related and I/O errors.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

A new filesystem health endpoint was added to monitor per-directory existence, writability, and disk usage. Audio saving was enhanced with atomic write operations and errno-specific error handling. Two new Pydantic models were introduced to structure filesystem health responses.

Changes

Cohort / File(s)	Summary
Filesystem Health Endpoint backend/main.py	Added /health/filesystem endpoint that checks three directories for existence and writability, computes disk usage, and returns structured health status. Enhanced audio saving error handling with BrokenPipeError and OSError catching, inspecting errno values for ENOENT, EACCES, ENOSPC to provide specific HTTP 500 responses.
Filesystem Health Models backend/models.py	Added two new Pydantic models: DirectoryCheck (path, exists, writable, error) and FilesystemHealthResponse (healthy, disk_free_mb, disk_total_mb, directories list).
Audio Storage Enhancement backend/utils/audio.py	Refactored save_audio to perform atomic writes using temporary files, ensuring parent directories exist, with failure cleanup and robust OSError handling.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Endpoint as /health/filesystem
    participant FileSystem as File System
    
    Client->>Endpoint: GET /health/filesystem
    
    rect rgba(100, 150, 200, 0.5)
    Note over Endpoint,FileSystem: Directory Checks
    Endpoint->>FileSystem: Check /data existence
    Endpoint->>FileSystem: Check /outputs existence
    Endpoint->>FileSystem: Check /temp existence
    end
    
    rect rgba(100, 150, 200, 0.5)
    Note over Endpoint,FileSystem: Writability Tests
    Endpoint->>FileSystem: Create temporary file in /data
    Endpoint->>FileSystem: Delete temporary file
    end
    
    rect rgba(100, 150, 200, 0.5)
    Note over Endpoint,FileSystem: Disk Usage Computation
    Endpoint->>FileSystem: Query disk free space
    Endpoint->>FileSystem: Compute /data directory usage
    end
    
    Endpoint->>Client: Return FilesystemHealthResponse (healthy status, disk metrics, per-directory checks)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hops through filesystems, checking with care,
Atomic writes ensure data stays there,
Health blooms bright in directories three,
Error messages flow so naturally,
Storage robust and disk space so fair,
Better systems beyond compare! 🌿

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the two main changes: atomic audio save with error handling and a new filesystem health endpoint.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/atomic-save-error-handling

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}