74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# NuQloud Master Calendar plan
|
||
|
||
## Goal
|
||
|
||
Provide each authenticated Nextcloud user a single, read-only CalDAV calendar
|
||
named **NuQloud Master Calendar**. It dynamically combines every calendar the
|
||
user can read and has enabled. A personal setting can restrict it to calendars
|
||
the user can edit. The master collection is hidden by default in the Nextcloud
|
||
Calendar grid so local calendars remain the editable, non-duplicated view.
|
||
|
||
## Scope for the first release
|
||
|
||
- Use the Nextcloud Calendar provider API, so the virtual calendar appears in
|
||
the existing Calendar app and at the standard CalDAV endpoint.
|
||
- Include native, shared, and subscribed calendars returned by the DAV
|
||
providers. Disabled calendars are excluded.
|
||
- Default to `all`; allow `editable` as the personal source filter.
|
||
- Mark the master collection as disabled by default for the Nextcloud Calendar
|
||
grid. It remains discoverable and fully readable through CalDAV clients.
|
||
- Expose a read-only collection. Creating, updating, deleting, and sharing
|
||
through the master calendar are intentionally unavailable.
|
||
- Namespace virtual event UIDs and resource filenames by source calendar. This
|
||
prevents collisions when two source calendars use the same UID while keeping
|
||
recurrence instances from one source together.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
CalDAV client -> standard Nextcloud CalDAV home -> MasterCalendarProvider
|
||
-> MasterCalendar (read-only)
|
||
-> native + subscription providers
|
||
-> accessible source calendars
|
||
```
|
||
|
||
The app registers a direct CalDAV provider and declares the required `dav` app
|
||
type. This avoids the public calendar manager, whose search result format is
|
||
incompatible with a virtual CalDAV collection. It asks the DAV app's native and
|
||
subscription providers for source calendars; those provider classes are
|
||
implementation details, so the app explicitly targets Nextcloud 32–34 and
|
||
must be rechecked for future major versions.
|
||
|
||
## Permissions and privacy
|
||
|
||
- The provider receives the authenticated principal from Nextcloud; no route
|
||
or CalDAV request accepts a user ID.
|
||
- Source events are obtained through Nextcloud's existing permission-aware DAV
|
||
providers. A removed share disappears on the next request/sync.
|
||
- `editable` requires `ICalendarIsWritable::isWritable()`. Ownership is not
|
||
used as a substitute for actual permission.
|
||
- The master collection itself advertises read-only permissions. It never
|
||
chooses a destination calendar for an edit.
|
||
|
||
## Validation and rollout
|
||
|
||
1. Run PHP lint and the static validation script included with the app.
|
||
2. Create `NuQloud/nuqloud-master-calendar` in Gitea and push this folder as
|
||
its repository root.
|
||
3. Run `./recreate-devprod.sh --nossl` (or the deployment's normal recreate).
|
||
The updated scripts clone the repository into `custom_apps` and enable it.
|
||
The updater scopes Git's safe-directory exception to this app checkout for
|
||
the one fast-forward command, so a Nextcloud-owned app directory does not
|
||
require a global Git configuration change.
|
||
4. In Nextcloud personal settings, select the source mode. Add the normal
|
||
CalDAV account URL to a test client and select only **NuQloud Master
|
||
Calendar**. Verify all/shared/subscribed calendars, disabled calendars,
|
||
editable-only filtering, recurrence, and share revocation.
|
||
|
||
## Deferred work
|
||
|
||
- Per-calendar include/exclude overrides.
|
||
- Writable routing policy and conflict handling.
|
||
- Incremental sync tokens/ETags tuned for large calendar sets.
|
||
- Automated integration tests against supported Nextcloud releases.
|