fix: add post-processing step to fix MP4 duration metadata (#100)

## Summary

Fixes two issues:
1. MP4 files recorded by the recording endpoints don't display the full
video length when downloaded (duration extends as videos are played)
2. Concurrent `Stop()` calls could corrupt recordings due to multiple
SIGINTs being sent to ffmpeg

## Problem

### Duration Metadata
The recording uses **fragmented MP4** format (`-movflags
+frag_keyframe+empty_moov`) for data safety during recording. This
format:
- Writes an empty `moov` atom at the start (without duration
information)
- Streams fragments incrementally as it records
- Is great for crash safety, but causes players to calculate duration on
playback

### Concurrent Stop Race Condition
When multiple goroutines called `Stop()` concurrently (e.g., from
duplicate HTTP requests), each would send SIGINT to ffmpeg. Multiple
SIGINTs cause ffmpeg to terminate immediately without flushing buffers,
resulting in corrupted/empty MP4 files.

## Solution

### Post-Processing (Duration Fix)
Add a **post-processing step** that remuxes the fragmented MP4 into a
standard MP4 with proper duration metadata after recording stops:
- `finalizeRecording()` method - Remuxes using `ffmpeg -c copy -movflags
+faststart`
- No re-encoding (fast operation)
- Moves the `moov` atom to the start with correct duration
- Uses temp file to safely replace the original

### Concurrent-Safe Stop (Race Condition Fix)
Use `sync.Once` to ensure shutdown and finalization only run once:
- `stopOnce` - Ensures shutdown signals are only sent once (prevents
duplicate SIGINTs)
- `finalizeOnce` - Ensures finalization only runs once
- Wait for process exit before proceeding to finalization

### API Changes
- `DownloadRecording`: Returns `202 Accepted` with `Retry-After: 5` if
recording is being finalized
- `DeleteRecording`: Returns `400` if recording is being finalized; now
synchronous instead of async

## Changes

### Recorder (`server/lib/recorder/ffmpeg.go`)
- Add `finalizeRecording()` to remux fragmented MP4 to standard MP4
- Introduce `ErrRecordingFinalizing` and `finalizing` state
- Gate `Recording()`/`Delete()` to return error while finalizing
- Make shutdown/finalization idempotent via `sync.Once` (`stopOnce`,
`finalizeOnce`)
- Wait for process exit before finalizing
- `Stop()` always attempts finalization after graceful shutdown
- `ForceStop()` attempts finalization with warning-only on failure

### API (`server/cmd/api/api/api.go`)
- `DownloadRecording`: Return `202` with `Retry-After: 5` if finalizing
- `DeleteRecording`: Synchronous delete; return `400` if finalizing

### Tests (`server/lib/recorder/ffmeg_test.go`)
- Set explicit `outputPath` and adjust expectations for new finalization
behavior

## Testing

Tested with concurrent stop script:
go run ./scripts/concurrent_stop_test/main.go -url http://localhost:444
-concurrency 5 -iterations 10Results: **10/10 passed** with 5 concurrent
stop calls per iteration.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds FFmpeg post-processing to finalize MP4 duration metadata and
singleflight-guards Stop/finalize; API now waits for finalization on
download and returns 409 on delete during finalization.
> 
> - **Recorder (FFmpeg)**:
> - Add `finalizeRecording()` remux step (faststart) and finalize
automatically on natural exits; expose `WaitForFinalization`.
> - Introduce `ErrRecordingFinalizing`; gate `Recording()`/`Delete()`
until finalization completes.
> - Use `singleflight` to dedupe concurrent `Stop()` and finalization;
`Stop()` always attempts finalize; `ForceStop()` tries finalize but
warns on failure.
> - Update `waitForCommand()` to trigger finalization;
`FFmpegManager.StopAll()` now calls `Stop()` for all.
> - **API**:
>   - `StopRecording`: always invoke `Stop()` even if not recording.
> - `DownloadRecording`: if finalizing, wait and then serve; still
returns `202` when in-progress and tiny file.
> - `DeleteRecording`: make synchronous; return `409 Conflict` when
finalizing; log improvements.
> - **OpenAPI/Client**:
> - Add `409 Conflict` response to `DELETE /recording/delete`;
regenerate `oapi` client/server stubs and embedded swagger.
> - **Tests**:
> - Update recorder tests to set explicit `outputPath` and assert new
finalization/force-stop behaviors.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d3e043f. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: hiroTamada

server/cmd/api/api/api.go

@@ -129,10 +129,10 @@ func (s *ApiService) StopRecording(ctx context.Context, req oapi.StopRecordingRe
 	if !exists {
 		log.Error("attempted to stop recording when none is active", "recorder_id", recorderID)
 		return oapi.StopRecording400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{Message: "no active recording to stop"}}, nil
-	} else if !rec.IsRecording(ctx) {
-		log.Warn("recording already stopped", "recorder_id", recorderID)
-		return oapi.StopRecording200Response{}, nil
 	}
+	// Always call Stop() even if IsRecording() is false. Recordings that exit naturally
+	// (max duration, max file size, etc.) finalize automatically, but Stop() is still
+	// needed to update scale-to-zero state and ensure clean shutdown.
 
 	// Check if force stop is requested
 	forceStop := false
@@ -182,12 +182,34 @@ func (s *ApiService) DownloadRecording(ctx context.Context, req oapi.DownloadRec
 
 	out, meta, err := rec.Recording(ctx)
 	if err != nil {
-		log.Error("failed to get recording", "err", err, "recorder_id", recorderID)
-		return oapi.DownloadRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to get recording"}}, nil
+		if errors.Is(err, recorder.ErrRecordingFinalizing) {
+			// Wait for finalization to complete instead of asking client to retry
+			log.Info("waiting for recording finalization", "recorder_id", recorderID)
+			ffmpegRec, ok := rec.(*recorder.FFmpegRecorder)
+			if !ok {
+				log.Error("failed to cast recorder to FFmpegRecorder", "recorder_id", recorderID)
+				return oapi.DownloadRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "internal error"}}, nil
+			}
+			// WaitForFinalization blocks until finalization completes and returns the result
+			if finalizeErr := ffmpegRec.WaitForFinalization(ctx); finalizeErr != nil {
+				log.Error("finalization failed", "err", finalizeErr, "recorder_id", recorderID)
+				return oapi.DownloadRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to finalize recording"}}, nil
+			}
+			// Finalization complete, retry getting the recording
+			out, meta, err = rec.Recording(ctx)
+			if err != nil {
+				log.Error("failed to get recording after finalization", "err", err, "recorder_id", recorderID)
+				return oapi.DownloadRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to get recording"}}, nil
+			}
+		} else {
+			log.Error("failed to get recording", "err", err, "recorder_id", recorderID)
+			return oapi.DownloadRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to get recording"}}, nil
+		}
 	}
 
 	// short-circuit if the recording is still in progress and the file is arbitrary small
 	if rec.IsRecording(ctx) && meta.Size <= minRecordingSizeInBytes {
+		out.Close() // Close the file handle to prevent descriptor leak
 		return oapi.DownloadRecording202Response{
 			Headers: oapi.DownloadRecording202ResponseHeaders{
 				RetryAfter: 300,
@@ -224,15 +246,18 @@ func (s *ApiService) DeleteRecording(ctx context.Context, req oapi.DeleteRecordi
 		return oapi.DeleteRecording400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{Message: "recording must be stopped first"}}, nil
 	}
 
-	// fine to do this async
-	go func() {
-		if err := rec.Delete(context.Background()); err != nil && !errors.Is(err, os.ErrNotExist) {
+	if err := rec.Delete(ctx); err != nil {
+		if errors.Is(err, recorder.ErrRecordingFinalizing) {
+			log.Info("recording is being finalized, client should retry", "recorder_id", recorderID)
+			return oapi.DeleteRecording409JSONResponse{ConflictErrorJSONResponse: oapi.ConflictErrorJSONResponse{Message: "recording is being finalized, please retry in a few seconds"}}, nil
+		}
+		if !errors.Is(err, os.ErrNotExist) {
 			log.Error("failed to delete recording", "err", err, "recorder_id", recorderID)
-		} else {
-			log.Info("recording deleted", "recorder_id", recorderID)
+			return oapi.DeleteRecording500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to delete recording"}}, nil
 		}
-	}()
+	}
 
+	log.Info("recording deleted", "recorder_id", recorderID)
 	return oapi.DeleteRecording200Response{}, nil
 }