Skip to content
calternal docs

calternal_plugin_calendar::view

Calendar projections read rebuildable Index rows from their owning Plugins.

Date windows are bounded before queries run. File and Note data is filtered by the caller’s Home and live Share roots. The endpoint does not walk the Data directory; Notes and file mtimes use date indexes. Task source paths and declared Plugin-owned Markdown stay out of generic file Activity; typed Notes and Tasks keep their own Calendar projections (#606, #662). Request timing exposes selected operations without User data (#549). Files thumbnail checks use the same renderer kind as worker jobs, so equal content hashes keep separate document previews (#510 / DESIGN §39). Notes writers publish Log rows before acknowledgement (#653). Range and year reads use those committed WAL rows without taking the Notes guard. Range and Year Log rows use the shared imported-time projection (#724).

Source: crates/plugins/calendar/src/view.rs

Structs

Section titled “Structs”

CalendarDay

Section titled “CalendarDay”
pub struct CalendarDay

No doc comment.

Fields

  • pub date: String
  • pub activity_count: u64
  • pub log_count: u64
  • pub event_count: u64
  • pub note_count: u64
  • pub bookmark_count: u64
  • pub file_count: u64
  • pub photo_count: u64
  • pub logs: Vec<CalendarLog>
  • pub events: Vec<ExternalCalendarEvent>
  • pub notes: Vec<CalendarNote>
  • pub bookmarks: Vec<CalendarNote>
  • pub files: Vec<HourlyFiles>
  • pub photos: Vec<HourlyPhotos>
  • pub cover_photo: Option<CalendarPhoto>: The most recently modified photo, chosen as a stable day cover.

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:256

CalendarFile

Section titled “CalendarFile”
pub struct CalendarFile

No doc comment.

Fields

  • pub owner_id: String
  • pub item_id: Option<String>
  • pub path: String
  • pub name: String
  • pub thumbnail_hash: Option<String>: Source hash for a supported Files thumbnail. Missing while a file type has no renderer or its Index entry has no content hash.
  • pub thumbnail_kind: Option<String>: Non-media renderer family; None keeps the historical media URL.
  • pub media_type: String
  • pub modified_at: String

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:339

CalendarLog

Section titled “CalendarLog”
pub struct CalendarLog

No doc comment.

Fields

  • pub id: Option<String>
  • pub start: String
  • pub end: Option<String>
  • pub title: String
  • pub tags: Vec<String>
  • pub attachments: Vec<CalendarLogAttachment>
  • pub timezone: Option<String>: Missing only on legacy Log lines that predate capture-zone indexing.
  • pub place: Option<CalendarLogPlace>: Saved place recorded on this Log entry, without its coordinates.

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:276

CalendarLogAttachment

Section titled “CalendarLogAttachment”
pub struct CalendarLogAttachment

No doc comment.

Fields

  • pub kind: String
  • pub text: String
  • pub target: String
  • pub embed: bool
  • pub item_id: Option<String>: Files item ID of the target, for /f/<item-id> links. None when the target is not indexed or the viewer cannot see it.
  • pub note_id: Option<String>: The target Note’s calternal-id, for /n/<id> links.
  • pub media_type: Option<String>: Indexed media type of the target file.
  • pub thumbnail_hash: Option<String>: Source hash for a supported Files thumbnail.
  • pub thumbnail_kind: Option<String>: Non-media renderer family for the shared Files thumb route (#510/#547).
  • pub display_name: Option<String>: User-facing attachment label, such as a photo’s place or capture time.
  • pub full_name: Option<String>: Full indexed file name shown by the shared tooltip.
  • pub missing: bool: True when the target is a local file with no live Files, Note or Task row.

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:297

CalendarLogPlace

Section titled “CalendarLogPlace”
pub struct CalendarLogPlace

Saved-place identity and name captured on one Log entry, without coordinates.

Fields

  • pub id: String
  • pub name: String

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:291

CalendarNote

Section titled “CalendarNote”
pub struct CalendarNote

No doc comment.

Fields

  • pub id: String
  • pub title: String
  • pub path: String
  • pub time: String: Note modification time, or bookmark save time, in the requested zone.
  • pub url: Option<String>: Original page address for a bookmark or clip.
  • pub site: Option<String>: Page host for a bookmark or clip.
  • pub description: Option<String>: Page description for a bookmark or clip.
  • pub favicon: Option<String>: Favicon address supplied at capture time.

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:322

CalendarPhoto

Section titled “CalendarPhoto”
pub struct CalendarPhoto

No doc comment.

Fields

  • pub owner_id: String
  • pub item_id: Option<String>
  • pub path: String
  • pub name: String
  • pub thumbnail_hash: Option<String>: Source BLAKE3 hash. The Files thumb route uses it to find the derived image.
  • pub media_type: String
  • pub modified_at: String

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:354

CalendarRange

Section titled “CalendarRange”
pub struct CalendarRange

No doc comment.

Fields

  • pub from: String
  • pub to: String
  • pub tz: String
  • pub days: Vec<CalendarDay>

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:248

CalendarTagCount

Section titled “CalendarTagCount”
pub struct CalendarTagCount

One Event tag prefix and the number of distinct visible Events below it.

Fields

  • pub tag: String
  • pub count: u64

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:408

CalendarYear

Section titled “CalendarYear”
pub struct CalendarYear

No doc comment.

Fields

  • pub year: i32
  • pub tz: String
  • pub days: Vec<CalendarYearDay>

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:382

CalendarYearDay

Section titled “CalendarYearDay”
pub struct CalendarYearDay

No doc comment.

Fields

  • pub date: String
  • pub activity_count: u64
  • pub log_count: u64
  • pub event_count: u64
  • pub event_tag: Option<String>: First Event’s first category, for the compact Year and mini-month dot.
  • pub event_color: Option<String>: First URL subscription’s chosen colour for its compact Event marker.
  • pub note_count: u64
  • pub bookmark_count: u64
  • pub file_count: u64
  • pub photo_count: u64
  • pub photo_day: bool
  • pub cover_photo: Option<CalendarPhoto>

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:389

ExternalCalendarEvent

Section titled “ExternalCalendarEvent”
pub struct ExternalCalendarEvent

CalDAV and URL subscriptions project typed Events into Calendar views. date is already projected into the requested calendar time zone.

Fields

  • pub date: String: Local calendar day in the requested time zone.
  • pub id: String: Provider-owned stable Event identity.
  • pub title: String: Event title.
  • pub tags: Vec<String>: Provider categories in their iCalendar order.
  • pub start: Option<String>: RFC 3339 start time, or None for an all-day Event.
  • pub end: Option<String>: RFC 3339 end time, or None for an all-day Event.
  • pub instance_start: Option<String>: Full occurrence boundaries; all-day values use exclusive YYYY-MM-DD dates.
  • pub instance_end: Option<String>
  • pub location: Option<String>: Place supplied by the Event provider.
  • pub timezone: String: Time zone stored by the Event provider.
  • pub provider: String: Provider display name.
  • pub source_id: Option<String>: Stable source layer ID for a read-only URL subscription.
  • pub color: Option<String>: User-selected layer colour for a URL subscription.
  • pub read_only: bool: True when the source is an external URL and cannot be edited in place.
  • pub all_day: bool: Whether this Event occupies the all-day lane.
  • pub recurring: bool: Whether this source Event has recurrence rules or date overrides (#536).

Implements: Clone, Debug, Deserialize, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:54

HourlyFiles

Section titled “HourlyFiles”
pub struct HourlyFiles

No doc comment.

Fields

  • pub hour: String
  • pub utc_offset: String
  • pub count: u64
  • pub items: Vec<CalendarFile>

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:366

HourlyPhotos

Section titled “HourlyPhotos”
pub struct HourlyPhotos

No doc comment.

Fields

  • pub hour: String
  • pub utc_offset: String
  • pub count: u64
  • pub items: Vec<CalendarPhoto>

Implements: Clone, Debug, Serialize, ToSchema

Source: crates/plugins/calendar/src/view.rs:374

ProjectionError

Section titled “ProjectionError”
pub struct ProjectionError(pub &'static str);

A projection read failed. The message is safe to log; it holds no user data.

Implements: Debug, std::fmt::Display, std::error::Error

Source: crates/plugins/calendar/src/view.rs:853

Enums

Section titled “Enums”

ExternalEventError

Section titled “ExternalEventError”
pub enum ExternalEventError

Why a provider could not return cached Calendar Events.

Variants

  • DatabaseBusy: SQLite reported transient lock contention.
  • Failed: A stored row or provider operation failed for another reason.

Implements: Clone, Copy, Debug, PartialEq, Eq

Source: crates/plugins/calendar/src/view.rs:95

Traits

Section titled “Traits”

ExternalEventProvider

Section titled “ExternalEventProvider”
pub trait ExternalEventProvider: Send + Sync

Provide cached CalDAV and subscribed Events for a User and local date range.

ExternalEventProvider::events

Section titled “ExternalEventProvider::events”
fn events<'a>(
        &'a self,
        user_id: &'a str,
        from: NaiveDate,
        to: NaiveDate,
        timezone: Tz,
    ) -> ExternalEventFuture<'a>;

Return Events grouped by the requested time zone’s local calendar day.

Source: crates/plugins/calendar/src/view.rs:103

Type aliases

Section titled “Type aliases”

ExternalEventFuture

Section titled “ExternalEventFuture”
pub type ExternalEventFuture<'a> = Pin<
    Box<dyn Future<Output = Result<Vec<ExternalCalendarEvent>, ExternalEventError>> + Send + 'a>,
>;

A typed extension point for the derived CalDAV Event cache.

Source: crates/plugins/calendar/src/view.rs:89

Functions

Section titled “Functions”

data_scope_user

Section titled “data_scope_user”
pub fn data_scope_user(principal: &PluginRequestContext) -> Option<&str>

The caller’s own User ID when the session has the data scope and no resource scope that names another User. Every per-user projection (the Calendar views and Analytics) authorises through this one check, which delegates to the shared PluginRequestContext::data_user.

Source: crates/plugins/calendar/src/view.rs:796

iana_timezone

Section titled “iana_timezone”
pub fn iana_timezone(value: &str) -> Result<Tz, &'static str>

Parse an IANA time-zone name of at most 128 bytes.

Source: crates/plugins/calendar/src/view.rs:831

install_external_event_provider

Section titled “install_external_event_provider”
pub fn install_external_event_provider(provider: Arc<dyn ExternalEventProvider>)

Install the instance’s CalDAV cache adapter. Until an adapter is installed, both Calendar endpoints return an empty typed Event list.

Source: crates/plugins/calendar/src/view.rs:119

local_day_window

Section titled “local_day_window”
pub fn local_day_window(day: NaiveDate, timezone: Tz) -> Option<(i64, i64)>

The UTC seconds [start, end) of one local day. A day that a DST change shortens or lengthens keeps its real length (23 or 25 hours).

Source: crates/plugins/calendar/src/view.rs:842

own_days

Section titled “own_days”
pub async fn own_days(
    db: &Db,
    user: &str,
    from: NaiveDate,
    to: NaiveDate,
    timezone: Tz,
) -> Result<Vec<CalendarDay>, ProjectionError>

The Calendar day projection of the caller’s OWN data: Log entries (with their times and tags), Events, Notes, bookmarks, files and photos, grouped by local day in timezone. Share roots are not read, so a summary never counts another User’s items.

This is the same projection /calendar/range serves (one set of rules for what a day contains), without the share grants. The window must be at most MAX_PROJECTION_DAYS long.

Source: crates/plugins/calendar/src/view.rs:871

strict_date

Section titled “strict_date”
pub fn strict_date(value: &str) -> Result<NaiveDate, &'static str>

Parse a strict YYYY-MM-DD local date (ASCII digits only, year 0001 or later, round-trips exactly). The error is a client-safe message.

Source: crates/plugins/calendar/src/view.rs:806

webhook_candidates

Section titled “webhook_candidates”
pub async fn webhook_candidates(
    root: Root,
    db: Db,
    user: &str,
    from: NaiveDate,
    to: NaiveDate,
    timezone: Tz,
) -> Result<Vec<ExternalCalendarEvent>, ExternalEventError>

Read owned webhook candidates with the same recurrence and provider policy as Calendar views (#491, DESIGN §55). The caller supplies its verified User.

Source: crates/plugins/calendar/src/view.rs:133

Constants

Section titled “Constants”

MAX_PROJECTION_DAYS

Section titled “MAX_PROJECTION_DAYS”
pub const MAX_PROJECTION_DAYS: i64

The longest window, in days, that one projection call reads.

Source: crates/plugins/calendar/src/view.rs:849