# FileHandling Subtopology — Software Design Document (SDD)

The **FileHandling subtopology** packages the core file-transfer services commonly needed in F´ deployments: **file uplink** (ground → flight), **file downlink** (flight → ground), **on-board file management**, and parameter management via filesystem. By providing these as a pre-wired subgraph, integration engineers avoid repetitive wiring and get a consistent, reusable baseline for file operations.

## 1. Requirements

| ID                   | Description                                                                                                     | Validation |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- |
| SVC-FILEHANDLING-001 | The subtopology shall provide **file uplink functionality** to receive and reconstruct files from ground.       | Inspection |
| SVC-FILEHANDLING-002 | The subtopology shall provide **file downlink functionality** to segment and transmit files to ground.          | Inspection |
| SVC-FILEHANDLING-003 | The subtopology shall provide **on-board file management functionality** (e.g., list, remove, hash, mkdir).     | Inspection |
| SVC-FILEHANDLING-004 | The subtopology shall provide **parameter management** via the filesystem.                                      | Inspection |
| SVC-FILEHANDLING-005 | The subtopology shall support **configurable instance properties** (IDs, queue sizes, stack sizes, priorities, CPU affinities). | Inspection |
| SVC-FILEHANDLING-006 | The subtopology shall expose **rate-group connection points** for any rate-drive components it contains.        | Inspection |


## 2. Design & Core Functions

### 2.1 Instance Summary

| Instance name  | Type (Svc)     | Kind   | Purpose (core function)                                 |
| -------------- | -------------- | ------ | ------------------------------------------------------- |
| `fileUplink`   | `FileUplink`   | Active | Ingest deframed file packets; reconstruct files.        |
| `fileDownlink` | `FileDownlink` | Active | Read files; segment into packets for downlink.          |
| `fileManager`  | `FileManager`  | Active | Local file operations.                                  |
| `prmDb`        | `PrmDb`        | Active | Filesystem based parameter management.                  |

### 2.2 Configuration Hooks inside the Subtopology

* Uses **instance properties** (IDs, queue sizes, stack sizes, priorities, CPU affinities) defined in `FileHandlingConfig` for these static instances (see §4).

### 2.3 Required Inputs for Operation

* **Rate Groups**: Connect scheduler outputs to the **Run** (scheduling) ports of `fileDownlink`.
* **Communication/Framing Stack**: Wire file-packet ports between FileHandling and your COM/framing subtopology (e.g., `ComCcsds`, `ComFprime`, `FramingFprime`, `FramingCcsds`) to complete uplink/downlink paths.

> [!WARNING]
> **This subtopology is not configured to be secure by default.** For backwards compatibility, it
> intentionally does **not** configure the file-access sandboxes of its components, leaving them
> fail-open: `fileUplink` may write, `fileDownlink` may read, and `prmDb` (`PRM_LOAD_FILE`) may
> load from **any absolute path accessible to the process** via ground command. Security-conscious
> deployments **must** call the following from topology setup code:
>
> * `FileHandling::fileUplink.configure(<directory>)` — restrict uplinked file writes.
> * `FileHandling::fileDownlink.configure(<directory>)` — restrict downlink reads (note: the
>   `configure(cooldown, cycleTime, fileQueueDepth)` overload called by this subtopology does
>   **not** set a sandbox).
> * `FileHandling::prmDb.configureLoadSandbox(<directory>)` — restrict `PRM_LOAD_FILE` reads
>   (note: `prmDb.configure(<file name>)` sets the store-file name and is **not** a load sandbox).

### 2.4 Limitations

Focused on **file transfer and on-board file ops** only. It does **not** provide general uplink/downlink routing for non-file traffic, framing/deframing for non-file data, or broader CDH services.

## 3. Usage

### 3.1 Example Usage

```fpp
topology Flight {
  instance FileHandling.Subtopology

  param connections instance FileHandling.prmDb

  # Schedule the active/queued file components (example)
  connections RateGroups {
    rg.RateGroupMemberOut[0] -> FileHandling.Subtopology.fileDownlinkRun
  }

  connections ComCcsds_FileHandling {
    # File Downlink <-> ComQueue
    FileHandling.Subtopology.fileDownlinkBufferSendOut -> ComCcsds.Subtopology.bufferQueueIn[ComCcsds.Ports_ComBufferQueue.FILE]
    ComCcsds.Subtopology.bufferReturnOut[ComCcsds.Ports_ComBufferQueue.FILE] -> FileHandling.Subtopology.fileDownlinkBufferReturn
    
    # Router <-> FileUplink
    ComCcsds.Subtopology.fileUplinkOut                    -> FileHandling.Subtopology.fileUplinkBufferSendIn
    FileHandling.Subtopology.fileUplinkBufferSendOut     -> ComCcsds.Subtopology.fileUplinkReturnIn
  }
}
```

## 4. Configuration

> Configure **only the instance properties** for the static instances owned by the subtopology. All knobs live under:
> `Svc/Subtopologies/FileHandling/FileHandlingConfig/FileHandlingConfig.fpp`. The generated constants header for this module (e.g., `FppConstantsAc.hpp`) reflects these settings. ([FPrime][2])

### 4.1 Component properties (`FileHandlingConfig.fpp`)

* **Base ID** — Base identifier for the subtopology; component IDs are offset from this base.
* **Queue sizes** — Queue depths for `fileUplink`, `fileDownlink`, `fileManager`.
* **Stack sizes** — Task stacks for active components (`fileUplink`, `fileDownlink`).
* **Priorities** — RTOS priorities for the active/queued components as applicable.
* **CPU affinities** — Core pinning for active component tasks; defaults to `TASK_DEFAULT` (no pinning).
* **Paths** — File paths used by the subtopology; `Paths.prmDbFile` sets the `prmDb` parameter storage file (default `PrmDb.dat`).

> These knobs tailor runtime footprint and scheduling without modifying the subtopology wiring.

---

## 5. Traceability Matrix

| Requirement ID       | Satisfied by                               |
| -------------------- | ------------------------------------------ |
| SVC-FILEHANDLING-001 | `fileUplink` — `Svc.FileUplink`            |
| SVC-FILEHANDLING-002 | `fileDownlink` — `Svc.FileDownlink`        |
| SVC-FILEHANDLING-003 | `fileManager` — `Svc.FileManager`          |
| SVC-FILEHANDLING-004 | `prmDb` — `Svc.PrmDb`                      |
| SVC-FILEHANDLING-005 | `FileHandlingConfig` (instance properties) |
| SVC-FILEHANDLING-006 | Run/scheduling connection specifiers       |