vios-deep-storage-mgmt git:20260603.14e198cA

Immutable. This exact content is served forever at /api/v1/blob/ffda69696e021cb5.

---
description: "Deep reference: Storage management module -- aging, capacity, snapshots, clips, timelines, protected files"
globs: "src/modules/storage_management/**"
alwaysApply: false
---

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Storage Management Module

## Key Classes

| Class | File | Role |
|-------|------|------|
| StorageManagement | `storage_management.h` | Main module: aging, capacity, file APIs, UnifiedStorageManager |
| VideoGeneratorTaskManager | `VideoGeneratorTaskManager.h` | Async video generation tasks |
| AsyncVideoStreamHandler | `AsyncVideoStreamHandler.h` | Chunked HTTP streaming for in-progress videos |

## Storage Monitoring and Aging (StorageMonitorTask, lines 459-578)

Runs every `storage_monitoring_frequency_secs` via Bosma scheduler:
1. `storageCapacity = min(userDiskCapacity, actualStorageCapacity)`
2. `configuredThreshold = capacity * storage_threshold_percentage / 100`
3. Trigger: `availableDiskSpace < targetFreeSpace` OR `currentRecordSize >= threshold`
4. `deleteOldMediaFiles(bytesToDelete)`: batch query oldest unprotected records (`ORDER BY start_time ASC`), skip cloud-scanned and protected, delete via `UnifiedStorageManagerUtils::deleteFile()`, repeat up to 2 attempts

## Snapshot/Clip via Media Adaptor

1. `handleMediaFileDownload()` -> `makeVideoFile()` (storage_management_utils.cpp)
2. If `IMediaInterface` exists: `fetchClip(ClipRequest, ClipResponse)` via media adaptor (e.g. VmsMedia gRPC)
3. Fallback: GStreamer pipeline (ClipReaderProducer / CloudStreamProducer)

## Protected Recordings

- `addFileInProtectList(filePath, remove)` / `addFilesInProtectList(filePaths, protect)`
- DB flag `file_protection_value == "1"` prevents aging deletion
- API: POST `/api/v1/storage/file/protect`

## API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `/api/v1/storage/configuration` | Config |
| `/api/v1/storage/size` | Used storage size |
| `/api/v1/storage/file/protect` | Protect/unprotect files |
| `/api/v1/storage/aging` | Manual aging |
| `/api/v1/storage/capacity` | Check capacity |
| `/api/v1/storage/timelines` | All recording timelines |
| `/api/v1/storage/file` | File CRUD (download, delete, upload) |
| `/api/v1/storage/file/{streamId}/path` | File paths by sensor+time |
| `/api/v1/storage/file/{streamId}/list` | Paginated file list |
| `/storage/*` | Media URL streaming |

## Thread Safety

`m_storageMutex` for `m_currentUsedStorage`; `m_muxerMutex` for `checkandCreateFreeSpaceInStorage`