opensim-addon-modules-exp/modules/OpenSimConcurrentFlotsamAssetCache/MIGRATION.MD

# MIGRATION

This document highlights conditions and considerations when migrating to ConcurrentFlotsamAssetCache. It focuses on cache behavior, configuration, and operational impacts.

## English

## 1. Preconditions and Compatibility
- Runtime: Requires a modern .NET/Mono environment matching your OpenSim build. Ensure File.Replace and optional overwrite move behavior are supported on your platform.
- Storage: Ensure the cache directory is on a filesystem that supports reliable atomic renames/replaces. On networked storage, semantics may differ.
- Permissions: The process must have read/write/create/delete permissions for the cache directory (including subfolders and temporary files).
- Time attributes: LastAccessTime updates are used (throttled). If your filesystem mounts with noatime or ignores access time updates, cleanup behavior will rely more on periodic scans.

## 2. Cache Directory Layout
- Tiered structure: Files are distributed into tiered subdirectories based on ID prefixes. Ensure:
    - CacheDirectoryTiers ≥ 1 and ≤ 3.
    - CacheDirectoryTierLength between 1 and 4.
- Moving from Core: If you have an existing core cache, you can:
    - Keep the directory but allow the new module to repopulate progressively, or
    - Start with a clean directory to avoid mixing formats.
- Backups: If enabling atomic replace backups (.bak), allow extra disk space and optionally schedule cleanup.

## 3. File Format and Serialization
- Versioned binary format with size caps for strings and data to guard against corruption and out-of-memory.
- Existing files in unknown/old formats will be skipped and may be deleted upon read failure to allow fresh caching.
- Ensure Deserialize caps (max string length, max data size) fit your asset profile. Too small values may reject valid assets; too large may increase memory pressure.

## 4. Memory and Weak Reference Cache
- WeakReference layer avoids strong memory retention of assets but speeds repeated hits.
- Optional memory cache increases RAM usage but reduces I/O latency. Size is indirectly controlled by expiration.
- Garbage Collection: Weak references can expire at any time; logic assumes this and falls back gracefully.

## 5. Negative (Miss) Cache
- Enabled by default to reduce upstream/load on repeated misses.
- Bounded with pruning. Tune NegativeCacheMaxEntries and NegativeCacheTimeout for your workload.
- If you expect assets to appear shortly after a miss, consider shorter timeouts to reduce false negatives.

## 6. In-flight De-duplication (Upstream Single-Flight)
- Concurrent requests for the same missing asset will share one upstream fetch.
- If upstream is unstable/slow, consider monitoring and shorter negative TTL on failures to avoid request stampedes.
- Ensure upstream IAssetService is not self-referential to avoid loops.

## 7. Write Behavior and Disk Load
- Per-file write gate prevents concurrent writes to the same asset file.
- Optional multi-worker writer can increase throughput but may spike IOPS. Validate your storage performance before increasing concurrency.
- Atomic replace/move minimizes partial files. On platforms not supporting overwrite move, a delete+move fallback is used.

## 8. Cleanup and Expiration
- Periodic cleaner removes files based on LastAccessTime and optionally cleans stale .bak files.
- Scene-aware protection prevents deletion of assets referenced by active scenes or defined as default assets.
- If your environment disables access times, ensure FileCacheTimeout is appropriate and consider manual “touch” commands.

## 9. Configuration Migration Tips
- Start conservatively:
    - Keep FileWriterConcurrencyWorker at 1 initially.
    - Use default deserialize caps unless you know your asset size profile.
    - Enable NegativeCache with moderate limits.
- Observe logs and hit-rate reports; adjust:
    - Backoff attempts/delays if you see contention on writes.
    - Negative cache size/timeouts if you see persistent misses or late arrivals.
- Commands are available to inspect status, clear caches, and trigger cleanup.

## 10. Operational Safety
- Always test on a staging region with a copy of your cache directory.
- Ensure reliable backups when enabling FileReplaceKeepBackup; monitor .bak cleanup schedules.
- Monitor “in-flight joins” (if exposed) to detect stampedes and upstream pressure.

---

## Deutsch

## 1. Voraussetzungen und Kompatibilität
- Laufzeit: Moderne .NET/Mono-Umgebung entsprechend dem OpenSim-Build. Prüfen, ob File.Replace und optionales Overwrite-Move auf Ihrer Plattform unterstützt werden.
- Storage: Der Cache-Ordner sollte auf einem Dateisystem liegen, das atomare Umbenennungen/Ersetzungen zuverlässig unterstützt. Auf Netzwerkshares können sich Semantiken unterscheiden.
- Berechtigungen: Lese/Schreib/Erstell-/Löschrechte für Cache-Verzeichnis inkl. Unterordnern und temporären Dateien sind erforderlich.
- Zeitstempel: LastAccessTime-Updates werden (gedrosselt) genutzt. Bei noatime/ignorierten Access-Times stützt sich die Bereinigung stärker auf periodische Scans.

## 2. Cache-Verzeichnisstruktur
- Gestufte Struktur: Dateien werden anhand von ID-Präfixen in Unterordner verteilt. Sicherstellen:
    - CacheDirectoryTiers ≥ 1 und ≤ 3.
    - CacheDirectoryTierLength zwischen 1 und 4.
- Migration vom Core:
    - Entweder vorhandenes Verzeichnis beibehalten und neu befüllen lassen oder
    - Mit leerem Verzeichnis starten, um Formatmischungen zu vermeiden.
- Backups: Bei aktivierten .bak-Backups atomarer Replaces genügend Speicherplatz einplanen und Cleanup einrichten.

## 3. Dateiformat und Serialisierung
- Versioniertes Binärformat mit Größenlimits für Strings und Daten (Schutz vor Korruption/OOM).
- Unbekannte/alte Dateien werden ggf. übersprungen und bei Lesefehler gelöscht, damit sie neu gecacht werden können.
- Deserialize-Limits (max. Stringlänge, max. Datengröße) an das Asset-Profil anpassen. Zu klein -> valide Assets abgelehnt; zu groß -> mehr Speicherlast.

## 4. Memory- und Weak-Reference-Cache
- WeakReference-Schicht verhindert harte Speicherbindung und beschleunigt wiederholte Zugriffe.
- Optionaler Memory-Cache erhöht RAM-Bedarf, reduziert aber I/O-Latenz. Größe indirekt über Ablaufzeit gesteuert.
- GC: Weak-Referenzen können jederzeit verfallen; Logik fällt sauber auf andere Ebenen zurück.

## 5. Negative-(Miss)-Cache
- Standardmäßig aktiv zur Entlastung des Upstreams bei wiederholten Misses.
- Begrenzt und mit Pruning. NegativeCacheMaxEntries und NegativeCacheTimeout passend zum Workload wählen.
- Erwarten Sie kurzzeitige Verfügbarkeit nach einem Miss, wählen Sie kürzere Timeouts, um falsche Negative zu reduzieren.

## 6. In-Flight-De-Dup (Upstream-Single-Flight)
- Gleichzeitige Anfragen für dasselbe fehlende Asset teilen sich einen Upstream-Fetch.
- Bei instabilem/slow Upstream Monitoring einplanen und ggf. kürzere Negative-TTL bei Fehlern, um Stampedes zu vermeiden.
- Sicherstellen, dass der Upstream-IAssetService nicht auf sich selbst verweist (Loop vermeiden).

## 7. Schreibverhalten und Plattenlast
- Pro-Datei-Schreibsperre verhindert parallele Writes derselben Datei.
- Optional mehrere Writer möglich, erhöht Durchsatz, kann aber IOPS-Spitzen verursachen. Speichertauglichkeit vorab prüfen.
- Atomare Replace/Moves minimieren Teil-Dateien. Falls Overwrite-Move nicht unterstützt, wird Delete+Move als Fallback genutzt.

## 8. Bereinigung und Ablauf
- Periodische Bereinigung entfernt Dateien anhand LastAccessTime und optional alte .bak-Dateien.
- Szenenbewusster Schutz verhindert Löschen aktiv referenzierter oder als Default definierter Assets.
- Wenn Access-Times deaktiviert sind, FileCacheTimeout passend wählen und ggf. manuelles „Touch“ nutzen.

## 9. Konfigurations-Migrationstipps
- Konservativ starten:
    - FileWriterConcurrencyWorker anfangs auf 1 belassen.
    - Standard-Deserialize-Limits verwenden, sofern das Asset-Größenprofil unbekannt ist.
    - Negative-Cache aktiviert mit moderaten Grenzen.
- Logs und Hit-Rate-Reports beobachten; anpassen:
    - Backoff/Delays bei Write-Contention.
    - Negative-Cache-Größe/Timeouts bei häufigen Misses oder verspäteten Assets.
- Befehle stehen zur Statusprüfung, Cache-Leerung und Bereinigung bereit.

## 10. Betriebssicherheit
- Migration zunächst auf Staging-Region mit Kopie des Cache-Verzeichnisses testen.
- Bei aktivierten FileReplaceKeepBackup verlässliche Backups und .bak-Cleanup überwachen.
- „In-flight joins“ (falls verfügbar) beobachten, um Stampedes und Upstream-Druck zu erkennen.****