systems settings and path access

Settings and path access

Active contributors: Douwe de Vries

Purpose

The settings and path access system keeps desktop preferences durable while limiting file operations to paths granted through dialogs or explicit confirmation. It protects the Tauri command shell from reading or writing arbitrary paths without user involvement.

Directory layout

Path	Role
src-tauri/src/settings/model.rs	Defines AppSettings, schema version, defaults, and sanitization.
src-tauri/src/settings/store.rs	Loads and saves settings JSON at the platform config path with atomic replacement.
src-tauri/src/path_access.rs	Tracks granted input files and output files with canonicalized or normalized paths.
src-tauri/src/commands/files.rs	File picker commands, output picker command, and open-output-location command.
src-tauri/src/commands/settings_commands.rs	Tauri commands for loading and saving settings.
frontend/src/hooks/usePersistentSettings.ts	React hook for loading, optimistic saving, and reconciling settings.

Key abstractions

• AppSettings stores theme, overwrite behavior, sample counts, output suffix, remembered directories, and Local AI model preferences.
• SETTINGS_SCHEMA_VERSION forces loaded settings onto the current schema and handles legacy suffix migration.
• SettingsStore abstracts the settings file path and returns sanitized settings after save.
• PathAccess stores granted input and output files in process-local sets protected by a mutex.
• Input grants use canonical existing files; output grants normalize by canonical parent and reject unsafe existing leaves such as symlinks.
• usePersistentSettings keeps optimistic UI settings while guarding against stale async save responses.

How it works

sequenceDiagram
    participant UI as React settings and file controls
    participant Settings as usePersistentSettings
    participant Tauri as Tauri commands
    participant Store as SettingsStore
    participant Access as PathAccess

    UI->>Settings: mount
    Settings->>Tauri: load_settings
    Tauri->>Store: load_settings()
    Store-->>Settings: sanitized AppSettings
    UI->>Tauri: pick_input_csv(initialDirectory)
    Tauri->>Access: grant_input_file(pickedPath)
    Access-->>UI: canonical input path
    UI->>Settings: update setting
    Settings->>Tauri: save_settings(settings)
    Tauri->>Store: save_settings()
    Store-->>Settings: authoritative AppSettings

Loading

The frontend loads settings on mount and applies updates optimistically. Backend sanitization clamps sample counts, normalizes Local AI model names, keeps the current schema version, and supplies defaults when the settings file is missing. File picker commands add grants to PathAccess; commands that receive manual paths either require existing grants or ask for confirmation through shared dialog helpers.

Integration points

• Frontend workflow state consumes settings for sample counts, preview counts, output suffixes, last directories, overwrite behavior, and Local AI request shape.
• Tauri command shell manages PathAccess and SettingsStore in src-tauri/src/main.rs.
• Background jobs uses output grants before starting retained anonymization.
• Release tooling validates config and metadata but does not persist runtime settings.
• frontend/src/defaults.ts must remain aligned with src-tauri/src/settings/model.rs.

Entry points for modification

• Add a new persisted setting in src-tauri/src/settings/model.rs, frontend/src/types.ts, and frontend/src/defaults.ts.
• Change settings migration or on-disk behavior in src-tauri/src/settings/store.rs.
• Change file grant rules, symlink rejection, or path normalization in src-tauri/src/path_access.rs.
• Change picker behavior or output-location opening in src-tauri/src/commands/files.rs.
• Change optimistic save reconciliation in frontend/src/hooks/usePersistentSettings.ts.

Key source files

• src-tauri/src/settings/model.rs
• src-tauri/src/settings/store.rs
• src-tauri/src/path_access.rs
• src-tauri/src/commands/files.rs
• src-tauri/src/commands/settings_commands.rs
• frontend/src/hooks/usePersistentSettings.ts