Skip to content
calternal docs

calternal_plugin::user_settings

Per-User preferences in <home>/.calternal/settings.json.

Several Plugins own sections of this one file. Updates edit the latest complete JSON object and use a checked replace, so a retry keeps a change from another Plugin. Per-User locks cover only the in-memory edit; fsync and other disk work happen after the guard is dropped.

Source: crates/calternal-plugin/src/user_settings.rs

Enums

Section titled “Enums”

UpdateError

Section titled “UpdateError”
pub enum UpdateError<E>

Keep an edit error distinct from a storage or concurrency error.

Variants

  • Settings(UserSettingsError)
  • Edit(E)

Implements: Debug, Clone, Copy, PartialEq, Eq

Source: crates/calternal-plugin/src/user_settings.rs:30

UserSettingsError

Section titled “UserSettingsError”
pub enum UserSettingsError

Why the User settings file could not be read or updated.

Variants

  • Unavailable: The Home or the file could not be accessed.
  • InsufficientStorage: A write would exceed the User quota or server free-space reserve.
  • NotAnObject: The file exists but is not a JSON object or is too large to parse.
  • Changed: Repeated concurrent changes prevented this update from committing.

Implements: Debug, Clone, Copy, PartialEq, Eq

Source: crates/calternal-plugin/src/user_settings.rs:17

Functions

Section titled “Functions”

read

Section titled “read”
pub fn read(root: &Root, user: &str) -> Result<(Map<String, Value>, bool), UserSettingsError>

Read the settings object. The flag is true when the file exists.

Source: crates/calternal-plugin/src/user_settings.rs:74

read_section

Section titled “read_section”
pub fn read_section(
    root: &Root,
    user: &str,
    key: &str,
) -> Result<Option<Value>, UserSettingsError>

Read one top-level section. None means the file or section is absent.

Source: crates/calternal-plugin/src/user_settings.rs:80

update

Section titled “update”
pub async fn update<E>(
    root: &Root,
    user: &str,
    mut edit: impl FnMut(&mut Map<String, Value>) -> Result<(), E>,
) -> Result<bool, UpdateError<E>>

Merge one or more settings and commit only when the JSON value changed.

edit can run more than once. A failed compare means another writer saved a newer file, so the next attempt reads that file and applies the edit on top. The short lock does not span directory creation, file writes or fsync. Return true only when this call installed new bytes.

Source: crates/calternal-plugin/src/user_settings.rs:95

write

Section titled “write”
pub async fn write(
    root: &Root,
    user: &str,
    settings: Map<String, Value>,
    existed: bool,
) -> Result<(), UserSettingsError>

Replace the whole object when the caller already owns a coordinated edit. Plugin-owned section changes should use update so checked retries keep changes that another Plugin committed after the caller’s read.

Source: crates/calternal-plugin/src/user_settings.rs:158

write_section

Section titled “write_section”
pub async fn write_section(
    root: &Root,
    user: &str,
    key: &str,
    value: Value,
) -> Result<(), UserSettingsError>

Replace one top-level section and preserve concurrent changes to others.

Source: crates/calternal-plugin/src/user_settings.rs:201

Constants

Section titled “Constants”

MAX_SETTINGS_BYTES

Section titled “MAX_SETTINGS_BYTES”
pub const MAX_SETTINGS_BYTES: usize

Settings files larger than this are refused before JSON parsing.

Source: crates/calternal-plugin/src/user_settings.rs:12