Files
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

8.1 KiB
Raw Permalink Blame History

予定・タスク共通CalDAV接続

2026-09-27追記:organizer.tasks 0.10.0でMKCALENDARによるVTODOリスト作成を追加。共通直下のUUIDはVEVENTまたはVTODOリストを表し、種別でハンドラを選ぶ。予定本文の読み込みで判定しない。

2026-09-26実装。organizer.calendar 0.2.0/organizer.tasks 0.9.0。01:33 JSTに本番両インスタンスへ反映済み。反映・検証記録。

2026-09-27追記:OneTask向け互換モードを実装、10:01 JSTに本番反映。通常は引き続きcalendar-accessを宣言せず、明示ONで発行した資格情報のみ接続判定互換のため宣言する。完全なRFC準拠ではない。実機の同期完了は未確認。

1. 接続と認証

共通接続先は /_/api/v1/caldav/。slash有無ともリダイレクトせずPROPFINDを処理する。rootはcurrent-user-principal/principal-URL/calendar-home-setを返す。Depth 1は許可された予定カレンダー(VEVENT)と個人タスクコレクション(VTODO)を返す。予定とタスクを同じICSリソースに混在させない。

対象 URI
共通home/principal /_/api/v1/caldav/
予定 /_/api/v1/caldav/{calendarUUID}/
個人タスク /_/api/v1/caldav/tasks/default/
既存タスク専用home(維持) /_/api/v1/caldav/tasks/
接続資格情報の発行/一覧 POST/GET /_/api/v1/caldav-credentials
失効 DELETE /_/api/v1/caldav-credentials/{id}

予定/タスク両画面の⇄ボタンから共通設定を開く。発行時に対象 tasks(タスクのみ)、calendar(予定のみ)、all(両方)とread/write、有効期間を明示選択する。初期選択は開いた画面の対象で、両方を自動付与しない。

Basicのユーザー名は資格情報ID、パスワードは発行時のみ表示するランダム値。従来と同様、秘密値はSHA-256のみ保存し、閉じたダイアログからも消去する。通常ログインセッションでのみ発行/失効できる。DAV資格情報をWikiやJSON APIのログインとして利用することはできない(匿名公開APIを非ログイン扱いで参照できることとは別)。HTTPSを使う。

既存の資格情報と旧管理APIは維持。organizer_dav_scopesに対応行がない資格情報は必ずtasksとして扱う。既存資格情報を予定アクセス付きに更新するAPIは設けず、新規発行と旧資格情報の明示失効で切り替える。新規の予定/共通秘密値はpw_dav_、既存互換タスク秘密値はpw_taskdav_。古いバイナリはpw_dav_を拒否するため、切り戻し時にも予定限定資格情報がタスク権限へ化けない。

2. 認可

  • 資格情報をドメイン/所有者/期限/失効状態に結び、principalとdomain membershipの状態も確認する。
  • Scopeは対象種別の上限であり、他人のカレンダーを共有する権限ではない。既存のカレンダーowner/member/publicポリシーを別途適用する。
  • 共通homeの探索結果はscopeと有効な拡張機能で絞る。片方の拡張が無効でも、他方の接続設定・探索は動く。
  • 予定の書き込みは資格情報のwrite許可、active状態、カレンダーのCanWriteを全て必要とする。外部ソース由来カレンダーは従来通り書き込み不可。
  • 予定変更時はカレンダーmetadata lock内でACLと資格情報の失効・期限・write・scopeを再確認する。タスクは既存のDB transaction内再確認を維持する。
  • API・DAV応答はprivate/no-store。通常の匿名公開予定の読取経路は維持し、無効なBasic資格情報を匿名扱いにフォールバックしない。

3. 予定のresource名と正本

Web作成分は従来のbase64url(UID).icsを維持。CLIが作成する任意の安全なASCIIファイル名(英数字・.・_・-、末尾.ics、最大700 bytes)を受理する。UIDとファイル名は別の識別子。

CLI由来のUID→filenameはcalendar.jsonのdav_namesとして保持する。新規resource予約と月別ICSを同じmanifest置換でcommitする。DBだけのaliasにはせず、索引再構築・カレンダー設定変更でも保持する。削除時は対応aliasも削除する。同じcalendar内のUID重複、filename衝突、既存UIDの差替えを拒否する。

既存のWeb用canonical URLも引き続き解決する。WebビューアはfilenameをUIDとしてbase64 decodeする前提を廃止し、既存JSONイベントAPIの?resource={filename}でサーバー側解決する。?uid=も維持。ETag一致時には本文を取り直さない。

新規PUTはIf-None-Match: *を推奨するが、chroncal互換で完全な新規identityに限り条件なし作成も可能。既存更新にはIf-Match(未指定428、不一致412)を必須とし、並行作成でも上書きしない。DELETEは予定の削除、タスクのアーカイブという既存の意味を維持する。

4. 取得上限と互換性

  • 従来のtime-range付きREPORTとETagを利用したWeb表示を維持する。
  • 初回同期用の全件calendar-query(VCALENDAR全体、またはVEVENT指定)を追加。metadata lock内で完全なsnapshotを取得し、最大10,000 resource/32 MiBを超えれば507で全体を失敗させる。黙った切り捨てはしない。
  • PROPFIND Depth 1による予定resource列挙、全項目calendar-data選択にも対応。無制限Depth、部分projection、未対応filterは拒否する。
  • 1 resource上限256 KiB、multigetは200 href、DAVリクエストは20秒上限。既存のtime-range上限370日も維持する。
  • sync-collection/sync-tokenは未対応。405を返し、chroncalはcalendar-queryへフォールバックする。完全なCalDAV適合を示すcalendar-accessは広告しない。
  • 新規予定のiCalendar対応範囲は従来のまま:単独VEVENT、UTC DATE-TIMEまたはDATE。TZID/VTIMEZONE、浮動時刻、繰り返し、VALARMは書き込み未対応。chroncalの--timezoneで出力されるVTIMEZONEも拒否する。情報を黙って欠落させる変換はしない。

5. 検証と運用

隔離したfixture、HOME、XDG、DB、資格情報のみでchroncal 0.10.0の共通探索、予定とタスクの取得、予定作成/CLI編集/Web変更取得/削除、タスク作成/完了/Web変更取得/アーカイブを検証。vdirsyncer/Todomanの既存タスク回帰も実施する。

権限scope、旧資格情報の移行既定値、read-only、失効、アカウント停止、拡張無効化、既存上書き拒否、並行作成、ACL取消、DB索引再構築、取得上限、Webのresource解決を試験する。ブラウザでは予定・タスク両方の設定UI、発行/失効/秘密値消去と、CLI filenameの予定描画を確認する。

本番の外部取り込みカレンダーの本文を調査・試験に利用しない。反映確認はhealth、未認証の経路、静的資産、エラーログ件数に限定する。

6. 後続TODO・切り戻し

  • losslessなTZID/VTIMEZONE、繰り返し・例外、アラームのDAV書込契約。正本を拡張する際は外部ICS取り込みの投影と混同しない。
  • sync-token/tombstone/変更journalによる大規模差分同期。
  • 資格情報ごとのcalendar ID制限、カレンダー作成・属性変更のDAV対応。
  • macOS/iOS等のGUI CalDAVクライアント実機検証。
  • 旧バイナリは追加DB表を無視できるが、calendar manifestを更新すると未知のdav_namesを失う。CLIで予定を作成した後は、旧バイナリでカレンダーを編集しない。緊急切り戻しではカレンダー拡張を無効化して修正版を待つか、整合したDBと正本のバックアップ復元を別途承認の上で行う。DBのみ復元し正本を過去に戻したつもりにしない。