Skip to content
calternal docs

calternal-location

Store each User’s Saved places in byte-preserving Places.md and match fixes.

Only the server writes the file through Root; edits preserve unknown Markdown and prose. This boundary follows issue #391 and DESIGN §47.

Source: crates/calternal-location/src/lib.rs

Structs

Section titled “Structs”

Coordinates

Section titled “Coordinates”
pub struct Coordinates

No doc comment.

Fields

  • pub latitude: f64
  • pub longitude: f64

Implements: Clone, Copy, Debug, PartialEq, Serialize, Deserialize

Source: crates/calternal-location/src/lib.rs:19

PlaceReference

Section titled “PlaceReference”
pub struct PlaceReference

No doc comment.

Fields

  • pub id: String
  • pub name: String

Implements: Clone, Debug, PartialEq, Eq

Source: crates/calternal-location/src/lib.rs:35

SavedPlace

Section titled “SavedPlace”
pub struct SavedPlace

No doc comment.

Fields

  • pub id: String
  • pub name: String
  • pub latitude: f64
  • pub longitude: f64
  • pub radius_m: u32

Implements: Clone, Debug, PartialEq, Serialize, Deserialize

Source: crates/calternal-location/src/lib.rs:26

SavedPlaces

Section titled “SavedPlaces”
pub struct SavedPlaces

No doc comment.

Fields

  • pub version: u8
  • pub places: Vec<SavedPlace>

Implements: Clone, Debug, PartialEq, Serialize, Deserialize, Default

Source: crates/calternal-location/src/lib.rs:42

Enums

Section titled “Enums”

StoreError

Section titled “StoreError”
pub enum StoreError

No doc comment.

Variants

  • Unavailable
  • InsufficientStorage
  • Invalid
  • TooLarge
  • Changed

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-location/src/lib.rs:57

UpdateError

Section titled “UpdateError”
pub enum UpdateError<E>

No doc comment.

Variants

  • Storage(StoreError)
  • Edit(E)

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-location/src/lib.rs:66

Functions

Section titled “Functions”

find_place

Section titled “find_place”
pub fn find_place(
    root: &Root,
    user: &str,
    coordinates: Coordinates,
) -> Result<Option<PlaceReference>, StoreError>

Resolve a device coordinate to this User’s nearest matching Saved place. Other Plugins can use this small read API without parsing Places.md or opening Home paths themselves.

Source: crates/calternal-location/src/lib.rs:85

load

Section titled “load”
pub fn load(root: &Root, user: &str) -> Result<SavedPlaces, StoreError>

Read Saved places from the User’s Places.md through Root (#910; DESIGN §47). A missing file gives an empty version-1 collection. Invalid, oversized, or unreadable content returns a storage error; it is not replaced.

Source: crates/calternal-location/src/lib.rs:74

log_places_enabled

Section titled “log_places_enabled”
pub fn log_places_enabled(settings: &serde_json::Map<String, serde_json::Value>) -> bool

True when one authenticated User setting enables both Location and Log place recording. Missing or malformed values fail closed.

Source: crates/calternal-location/src/lib.rs:96

match_place

Section titled “match_place”
pub fn match_place(places: &SavedPlaces, coordinates: Coordinates) -> Option<PlaceReference>

Select the nearest Saved place whose radius contains the fix (#910). Invalid fix coordinates give no match. Equal distances use the smaller place ID. Callers must supply validated Saved places, as load does (DESIGN §47).

Source: crates/calternal-location/src/lib.rs:184

update

Section titled “update”
pub async fn update<E>(
    root: &Root,
    user: &str,
    mut edit: impl FnMut(&mut Vec<SavedPlace>) -> Result<(), E>,
) -> Result<SavedPlaces, UpdateError<E>>

Apply an edit to Saved places and preserve unrecognized file bytes (#910). Validate the result before a checked Root write; an unchanged result needs no write. A concurrent change retries from fresh bytes up to 64 times, so edit must tolerate repeated calls and must not have external side effects (DESIGN §47). Exhausted retries return Changed.

Source: crates/calternal-location/src/lib.rs:114

valid_coordinates

Section titled “valid_coordinates”
pub fn valid_coordinates(value: Coordinates) -> bool

Require finite coordinates within inclusive latitude ±90 and longitude ±180 degrees (#910; DESIGN §47). This check does not round the fix.

Source: crates/calternal-location/src/lib.rs:680

validate_place

Section titled “validate_place”
pub fn validate_place(place: &SavedPlace) -> Result<(), StoreError>

Validate one user supplied Saved place before it enters a Home file.

Source: crates/calternal-location/src/lib.rs:637