21

Download Types

Scott E. Graves edited this page 2025-08-14 19:55:45 -05:00

Table of Contents

• 📥 Repertory Download Types
• 🔹 Mode Overview
• 🧠 How selection works (current behavior)
• 🛠 Choosing the right mode
• ⚙️ Example Config

📥 Repertory Download Types

Repertory supports three file access modes: default, direct, and ring_buffer.

Set your preference with the PreferredDownloadType option in config.json.

⚠️ Important clarification
As of the current implementation, default and ring_buffer behave the same for normal file opens:

• Repertory attempts ring-buffer mode first
• Falls back to direct if ring buffer isn't viable
• Promotes to cached read/write on a write
  In the future, default may switch to a different selection mechanism. Choose ring_buffer if you want to lock in today's behavior.

---

🔹 Mode Overview

Mode	Description	Access Type
default	Currently equivalent to ring_buffer for normal files: tries ring-buffer mode first; if not viable, falls back to direct. If a write occurs, the file is promoted to a fully cached read/write file. Note: This may change in the future.	Read-only until promotion → Read/Write
ring_buffer	Uses a fixed-size buffer file (default 512 MiB) in the buffer/ directory. Attempted first (for normal files) and falls back to direct if not viable. Promotes to cached read/write on write.	Read-only until promotion → Read/Write
direct	Streams directly from the provider without a disk cache file. Does not attempt ring buffer. Promotes to cached read/write on write. Lowest disk usage for read-only workloads.	Read-only until promotion → Read/Write

---

🧠 How selection works (current behavior)

When a path is opened, Repertory chooses a mode with these rules:

1. Early overrides → cached immediately

   • Opening a directory
   • Opening a zero-byte file
   • Opening an in-progress item
   • A complete local cache already exists for the file

2. Provider is read-only → direct

3. Preference for normal files

   • PreferredDownloadType = direct → direct (never tries ring buffer)
   • PreferredDownloadType = default → try ring_buffer, else direct
   • PreferredDownloadType = ring_buffer → try ring_buffer, else direct

4. Ring-buffer viability checks

   • File must be handleable under RingBufferFileSize (chunk size ≈ 8 MiB; ring size = RingBufferFileSize / chunk)
   • buffer/ directory must exist (created if needed)
   • The buffer drive must have at least RingBufferFileSize free
   • If any check fails → direct

5. Write promotion

   • If a file opened read-only (direct / ring_buffer) is later written to, Repertory replaces the open handle with a cached read/write file.
   • Writes are uploaded only after the file is fully downloaded.
   • If interrupted, uploads resume after remount.

---

🛠 Choosing the right mode

• Pick ring_buffer if you want to lock in today's adaptive behavior (bounded disk usage with automatic fallback to direct and promotion to cached on write).
• Pick default if you're okay with the current ring_buffer-first behavior and want to follow any future improvements to the selection strategy automatically.
• Pick direct if you:
  • Want minimal disk usage and never want ring buffer used automatically.
  • Are doing read-only streaming and are fine with promotion to cached only if/when a write happens.

---

⚙️ Example Config

{
  "PreferredDownloadType": "default"
}