Календарь (CalDAV)

CalDAV — это стандартный протокол доступа к календарю поверх HTTP. Он есть у Nextcloud и ownCloud, у Яндекс.Календаря, у iCloud, у Fastmail, у большинства корпоративных серверов (SOGo, Zimbra, Radicale). Смысл для платформы простой: один протокол вместо десятка проприетарных API — воркфлоу, написанный на Nextcloud, переезжает на другой сервер сменой адреса в подключении, а не переписыванием графа.

Единица данных в CalDAV — не «строка в базе», а файл: одно событие это документ iCalendar (.ics), лежащий по своему адресу внутри коллекции-календаря. Отсюда всё остальное на этой странице: у события есть href (путь), есть etag (версия), а изменение — это чтение файла, правка и запись обратно.

Что хранит подключение

Подключение заводится в Настройки → Интеграции, вид — CalDAV. Общая механика подключений (секреты, права, приоритет порта над полем) описана в обзоре интеграций; здесь — только то, что специфично для календаря.

Список Провайдер заполняет базовый URL за вас: Nextcloud, ownCloud, Яндекс.Календарь, iCloud, Fastmail и «Другой (вручную)». Для Nextcloud и ownCloud спрашивается только хост — путь /remote.php/dav/ дописывается сам. Логин и пароль пресет не трогает никогда: это единственное, что знаете только вы.

Режим обнаружения отвечает на вопрос «как найти ваши календари по этому адресу». «Автоматически (PROPFIND)» — стандартный путь: спросить у сервера текущего пользователя, у пользователя — его домашнюю коллекцию календарей, у коллекции — список календарей внутри. Если сервер отвечает не по канону, есть два ручных обхода: указать домашнюю коллекцию или сразу конкретный календарь. Ручной режим не «строже» — он просто пропускает шаги обнаружения, которые у вашего сервера не работают.

URL календаря по умолчанию стоит заполнить почти всегда. Ноды, которым нужен адрес коллекции, при пустом поле берут его отсюда — иначе один и тот же длинный URL приходится вставлять в каждую ноду графа.

Отдельного выбора календаря из списка в форме сегодня нет: адреса коллекций узнаются нодой Список календарей — она возвращает href и отображаемое имя каждого календаря. Один раз запустили, скопировали нужный href в подключение, дальше про адреса можно забыть.

Одиннадцать нод

Девять из них — обычные шаги графа с портом calendar_store. Десятая, Инструмент календаря, отдаёт те же операции агенту — у неё тот же порт, но входа запуска нет. Одиннадцатая, Конфигурация CalDAV, шагом графа не является вовсе: у неё нет ни входа запуска, ни порта calendar_store — она сама этот порт и питает.

Все они берут подключение одинаково: либо нода Конфигурация CalDAV проводом данных в порт calendar_store, либо выбор подключения прямо в форме ноды. Порт сильнее поля. Порт при этом обязательный: граф, где не подключён ни порт, ни поле, редактор пометит предупреждением, а запуск и деплой отклонит — чтобы отказ пришёл до того, как оплаченный запуск дойдёт до половины.

Чтение: сначала запрос, потом адреса

Порядок работы с CalDAV всегда один и тот же, и он неочевиден: сначала спрашиваем диапазон дат, из ответа получаем адреса, по адресам берём подробности.

Адрес события — это то, что вернул запрос: nodes.<нода запроса>.output.events[0].href. Придумывать его самому не нужно и нельзя — он назначен сервером.

Запись: href, etag и защита от чужой правки

Записывающих нод три, и различаются они не «силой», а тем, что именно они перезаписывают.

Записать событие пишет объект целиком. Пустой etag означает «создать» (или «перезаписать не глядя»), непустой — «записать, только если событие с тех пор не менялось». Тело события собирается двумя способами: из полей формы (название, начало, конец, место, описание, участники, правило повторения) либо сырым документом iCalendar, если нужного поля в форме нет. Сырой документ, если он непустой, всегда выигрывает у полей — это сделано ради уже сохранённых графов: они несут сырое тело и не знают про переключатель.

Изменить событие — это чтение-правка-запись: нода сама забирает текущий .ics, подменяет заполненные поля и пишет обратно. Пустое поле означает «не трогать», а не «стереть». Так меняют время встречи, не потеряв список участников и вложенные данные, которых в форме нет.

Удалить событие снимает объект по адресу; etag необязателен и здесь.

Различие последней строки и остальных — не косметика. Детерминированный отказ (устаревший etag, пустой адрес) повторять бессмысленно, и движок его не повторяет; сетевой сбой повторяется до трёх раз. Каждый код доезжает до ветки on_error как error_code, так что на «событие удалили» можно ответить одним способом, а на «сервер лёг» — другим. Подробнее — Ошибки.

Свободные слоты: занятость против запроса

Занятость календаря отвечает на вопрос «когда человек занят», не показывая, чем. Ответ — список интервалов начало/конец, без названий, участников и описаний. Это и есть причина, по которой нода существует отдельно от запроса: на многих серверах свободно-занятое доступно тем, кому содержимое календаря не показывают, и такой ответ безопасно отдать в чат клиенту.

Считать свободные окна нода не умеет — она отдаёт занятые. Инвертировать интервалы (взять рабочий день, вычесть занятое, оставить куски нужной длины) сегодня надо самому: нодой кода или моделью. Отдельной ноды «предложи три слота» нет.

Планирование: приглашения, и почему они работают не везде

Планирование в календаре отправляет участникам приглашение (REQUEST), ответ на приглашение (REPLY) или отмену (CANCEL). Технически это запись документа iCalendar в особую коллекцию — «исходящие» вашего аккаунта, а рассылку писем участникам делает уже сам сервер.

Отсюда два жёстких условия. Во-первых, в подключении должен быть заполнен URL исходящих. Во-вторых, сервер должен уметь планирование вообще: у iCloud и Google CalDAV его нет. Платформа знает это заранее и отказывает сразу, называя провайдера, вместо того чтобы отправить запрос и получить невнятный 403, который читается как «неверный пароль». Приглашения через эти сервисы отправляются их собственными средствами, а не по CalDAV.

Календарь как инструмент агента

Инструмент календаря — та же дюжина операций, но вызывает их модель. Это разница между графом «на каждый вопрос свой маршрут» и диалогом «запиши меня на вторник после обеда», где модель сама решает: посмотреть занятость → выбрать окно → создать событие → сказать человеку, что получилось.

В форме ноды перечислены двенадцать операций галочками. Девять включены по умолчанию — все, кроме трёх планирующих (приглашение, ответ, отмена). Причина та же, что выше: без адреса исходящих и на неподдерживающем провайдере они падают на каждом вызове, а инструмент, который гарантированно не работает, хуже отсутствующего — модель тратит на него раунд и бюджет вызовов. Больше того: даже включённые галочкой планирующие инструменты не будут показаны модели, если подключение их не тянет. Это осознанно — пусть модель выберет путь, который может сработать.

Где это обычно рвётся

Что дальше