Skip to content

Home

Jump to bottom
Ralf Lang edited this page Aug 5, 2021 · 2 revisions

Kronolith Refactoring Wiki

This wiki is simply a notepad for refactoring Kronolith H6

Horde LLC wants their wiki as the primary source of information and wants to render shipped documentation out of wiki content. However, I cannot spam their wiki with notes (yet) unrelated to their upstream version.

In Scope

  • Backends of calendars and events
  • Import/Export
  • CalDAV and WebDAV access
  • interapp api
  • management of side effects (iTip/RSVP, notification, alarm, history, out-of-scope properties)
  • making the UI a user of the new API (even if not using all the capabilities).

Out of scope for now

  • UI changes in general
  • Support of new features through the UI

Standards and mode

Refactored code lives in src/ and is namespaced, PSR-4, PSR-12.

Code in src/

  • MUST NOT directly consume globals unless wrapped in a referencing object
  • MUST NOT consume and use the injector internally unless specific reasons exist
  • SHOULD provide interfaces unless there may only ever be one variant
  • MUST either register with the injector or allow autowiring from the constructor
  • SHOULD NOT fall back into the Kronolith:: shortcuts - use traits or composition
  • SHOULD provide parameter and return types unless forced by external definitions (mixed for calendarId)

Refactoring should only touch lib/ code without breaking existing functionality

  • once src/ has a suitable replacement
  • For integrating with well-known classes (Application, Api, Ajax_Application_Handler, ...)
  • May turn lib/ code into a wrapper or derived/extended class if its use cases are replaced

Model

We use a terminology influenced by CalDAV and Icalendar.

CalendarFinder

A CalendarFinder knows how to retrieve a calendar by an external ID from any of its registered CalendarProviders

CalendarCreator

A CalendarCreator knows how to create a new calendar or update an existing calendar.

CalendarProvider

A CalendarProvider is a driver for calendars. A calendar provider might be readonly by concept or by user permission. A calendar provider SHOULD provide a change history. A calendar provider might serve content which was changed outside of kronolith's control A calendar provider MAY provide ResourceCalendars and ResourceGroupCalendars

If a calendar is writable, the provider must ensure not to drop any content it does not care for. It may either provide for storing all unwanted or unknown properties and components itself of save a copy to Kronolith_Icalendar_Storage.

Calendar and WritableCalendar

A Calendar is any collection of calendaring items: Events, Tasks, (...) which might be read through Kronolith. A WritableCalendar is a Calendar which might be changed through Kronolith.

Event

A Kronolith Event resembles an iCalendar VEVENT.

  • An event must have a uid.
  • An event may or may not have attendees.
  • An event may or may not have alarms.
  • Events must save unrecognized imported components or properties and return them unchanged on export.
  • An event may reference resources which are not known in kronolith
  • An event may reference attendees which are not known in kronolith
  • An event may have an organizer which is not known in kronolith or different from the calendar owner

Task

A Task resembles a VTODO

  • Tasks are handled by nag or anything implementing the tasks API
  • In Kronolith context, nag tasklists are calendars which store only tasks

ResourceCalendar

A ResourceCalendar manages the availability and booking of a Resource. A booked resource is an event inside a ResourceCalendar A ResourceCalendar should normally be changed by changing the events booking the resource. For administrative reasons, resources may actively cancel their attendance/booking.

ResourceGroupCalendar

A ResourceGroupCalendar aggregates multiple ResourceCalendars.

PSR-14 Event Dispatching

Changes to Calendar events are implemented as PSR-14 Events/Messages (Event Dispatching).

Kronolith gets a ListenerProvider and processing of changes is implemented as a cascade of Events/Messages

  • An Event is PUT (created or updated)

    • Access Check
    • Check if it is a CREATE or UPDATE
    • Get Diff
    • Identify new, modified or removed alarms, tags, attendees, resources and shoot appropriate new events

  • An Event is DELETEd (removed)

EventHandlers may have registered listeners which react on messages.

DELETEing an event would require an iTip listener to notify all attendees (unless it is configured to stay silent).

EventComparison

An EventComparison takes two events or two versions of an event and tells how they differ. This is useful to discern if an update warrants certain side effects. For example, if a new version of an event is only acknowledging a reminder/alert, this should not trigger an update for all attendees. The EventComparison only provides the facts, not the conclusion.

Clone this wiki locally