Persistent KV Store

Relevant source files

The following files were used as context for generating this wiki page:

• README_en.md
• FEATURES.md
• packages/shared/src/index.js
• apps/desktop/src/ui/plugins-smart.js
• apps/desktop/src-tauri/Cargo.toml

The Persistent KV Store provides a durable data layer for the Zephyr application, primarily serving the Prism Engine. It stores configuration data, plugin states, and script variables in a local database file named kv_store.db to ensure information persists across application restarts. This system enables plugins and smart selection logic to maintain historical context and user preferences.
Sources: README_en.md:79, FEATURES.md:88

Architecture and Data Flow

The Persistent KV Store operates through a multi-layered architecture involving the native frontend, a shared IPC (Inter-Process Communication) bridge, and a Rust-based backend.

System Interaction Flow

The frontend triggers KV operations through specific JavaScript functions that invoke Rust commands via Tauri's IPC mechanism. The backend manages the lifecycle of the kv_store.db file, performing atomic reads and writes.

The diagram shows the communication path from the UI modules to the physical storage layer.
Sources: apps/desktop/src/ui/plugins-smart.js:154-213, packages/shared/src/index.js:246-251

API and IPC Commands

The system exposes a standardized set of commands to manipulate stored data. These commands are defined in the shared package to maintain consistency between the frontend and backend.

Command Constant	IPC String	Description
KV.GET	kv_get	Retrieves a value associated with a specific key.
KV.SET	kv_set	Creates or updates a key-value pair in persistent storage.
KV.DELETE	kv_delete	Removes a specific key and its value from the store.
KV.KEYS	kv_keys	Returns a list of all keys currently stored in the database.

Sources: packages/shared/src/index.js:246-251

User Interface Integration

The Zephyr Desktop UI provides a management interface for the KV Store within the Plugins and Smart settings pages. Users can inspect, modify, or clear stored data manually.

Management Functions

The UI implementation in plugins-smart.js handles the following operations:

• Discovery: Fetches all keys via kv_keys to populate the management list.
• Inline Editing: Provides a prompt to update JSON-formatted values for specific keys via kv_set.
• Deletion: Removes individual entries using kv_delete.
• Bulk Clearing: Iterates through all keys to perform a full storage reset.

UI Implementation Detail

async function loadKvStore() {
    const container = document.getElementById('kv-store-list');
    const keys = await prism.kvKeys();
    const entries = [];
    for (const key of keys.slice(0, 100)) {
        const value = await prism.kvGet(key);
        entries.push({ key, value });
    }
    // Renders keys and truncated JSON values to the UI
}

Sources: apps/desktop/src/ui/plugins-smart.js:154-203

Technical Implementation Details

The backend utilizes high-performance Rust crates to manage state and storage. The application configuration in Cargo.toml indicates the use of dashmap for concurrent in-memory access and clash-prism-smart for engine-specific persistence logic.

• Storage Backend: The data is persisted in kv_store.db.
• Concurrent Access: The system supports safe concurrent access, likely utilizing dashmap for caching or thread-safe state management in the Rust core.
• Data Format: Values are handled as JSON-compatible structures, allowing complex objects to be stored alongside simple strings or numbers.

Sources: FEATURES.md:88, apps/desktop/src-tauri/Cargo.toml:50-60

Conclusion

The Persistent KV Store is a critical utility within the Prism Engine that bridges the gap between volatile script execution and permanent configuration. By providing a simple yet robust Key-Value API, it enables advanced features like plugin persistence, smart node selection history, and cross-session state management, all while maintaining a minimal footprint through SQLite-based storage.