Загрузки и превью ссылок

Сохранение и загрузка документов остаются маленьким маршрутом в вашем собственном приложении, там же, где уже живёт ваша проверка прав. Именно этот маршрут остаётся записью. Он попадает в ваши резервные копии, и его вы чистите, когда человек просит удалить свои данные.

Совместное редактирование добавляет одну движущуюся часть. Пока люди редактируют вместе, сервис держит рабочую копию открытого документа в хранилище, которое вы ему укажете. Раз в несколько секунд он записывает набранное обратно в ваш маршрут.

Потеря рабочей копии стоит максимум нескольких секунд ещё не записанных изменений. Следующее открытие начнётся заново с вашего маршрута.

Эти же несколько секунд дают задержку и в обратную сторону. Ваша запись отстаёт от того, что видят люди в документе. Поэтому выгрузка, отчёт или другой сервис, читающий вашу базу, видит документ на момент последней записи. Только что нажатой клавиши он не видит.

Обратную запись, которую ваш маршрут отклонил, сервис не выбрасывает, а повторяет с растущей задержкой. Документ, чья последняя обратная запись ещё не легла, остаётся загруженным, пока она не ляжет, даже когда из него все вышли. Поэтому короткий сбой на вашей стороне стоит времени, а не правок.

Этот ритм принадлежит только рабочей копии. Зарегистрируйте журнал операций, и рабочей копии у документа не останется вовсе. Как именно, говорит запись ниже про безопасный повтор внешней правки.

С журналом правка становится надёжной в журнале. Запись у вашего маршрута обновляется опубликованной контрольной точкой. Это происходит при выгрузке комнаты из памяти и при остановке сервиса, а не по таймеру. Задержка выше тогда уже не несколько секунд, и её цену называет запись про границу отката.

Собственную опцию редактора persistence нельзя сочетать с collaboration. Это пара колбэков загрузки и сохранения, которыми одиночный редактор общается с вашим маршрутом.

Редактор отклоняет такую пару сразу при создании и говорит, что убрать. Иначе у документа окажется два владельца, которые пишут одну и ту же запись из двух мест.

В обмен ничего не теряется. Сервис загружает документ из вашего маршрута документов и записывает его обратно туда же. Значит, это всё равно ваш маршрут, только вызывает его сервис, а не браузер.

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

Не записывайте то, что они вам отдают, обратно в свою запись. Теперь это работа сервиса, а второй пишущий только мешает ему.

Читайте это и в обратную сторону. Опция persistence записывает весь JSON документа целиком с задержкой. Когда сохранения накапливаются, уходит только самая свежая порция.

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

Там, где важна надёжность сохранения, выбирайте совместное редактирование. А что там значит «сохранено», говорит запись про состояние сохранения ниже.

Пока люди редактируют вместе, рабочая копия лежит в папке, названной в --collab-dir. Она может лежать и под префиксом S3 из --collab-s3-prefix. В ней содержимое документов, поэтому читать её публично нельзя.

Загруженные файлы задуманы так, чтобы их отдавать любому по ссылке. Рабочая копия предназначена только самому сервису. По той же причине сервис отказывается класть её внутрь каталога загрузок: всё, что там лежит, раздаётся наружу.

Две вещи про папку, названную в --collab-dir.

• Файл, который сервис не может прочитать, переименовывается рядом с суффиксом .unreadable-.
  • Документ после этого загружается заново с вашего маршрута, так что один испорченный файл никогда не заклинивает документ.
• Временные файлы, оставшиеся от процесса, который умер посреди записи, удаляются при запуске сервиса.

Где бы рабочая копия ни лежала, копия в формате, который этот сервис не читает, роняет открытие, а не толкуется наугад. Формат назван в журнале, и такой файл нужно убрать, прежде чем документ снова откроется.

Два обещания про POST /sync/{doc}/edit выполняются, только если у сервиса есть журнал операций.

• Повтор с тем же Blok-Idempotency-Key возвращает первый результат, а не применяет правку второй раз.
• Использование того же ключа для другой работы отклоняется с 409.

Рабочая копия журналом не является. Ни папка, названная в --collab-dir, ни префикс, названный в --collab-s3-prefix, не хранят историю того, что в них лежит. Получить журнал можно двумя способами.

• На автономном хосте добавьте --collab-journal или задайте BLOK_COLLAB_JOURNAL=true.
  • Встроенный журнал хранится на локальном диске, рядом с рабочей копией в --collab-dir.
  • Флагу нужен --collab. Вместе с --collab-s3-prefix он отклоняется: второй экземпляр, работающий с тем же бакетом, не увидит журнал на диске этой машины.
  • Поэтому он обслуживает один экземпляр. Внутри приложения тот же переключатель называется options.CollabJournal.
• Для нескольких экземпляров напишите хранилище сами.
  • Внутри собственного приложения на ASP.NET Core реализуйте ICollabOperationStore поверх хранилища, которому вы уже доверяете транзакции.
  • Зарегистрируйте его через AddBlokServer(...).UseCollabOperationStore<YourStore>().
  • Зарегистрированное вами хранилище заменяет встроенное.

В обоих случаях первое открытие каждого документа берёт его рабочую копию за отправную точку журнала, а затем удаляет её. Ничего из того, что держала рабочая копия, не теряется.

Для окончательного удаления нужен ещё один интерфейс. Ваше хранилище должно также реализовать ICollabOperationPurgeStore. Иначе PurgeDocumentAsync бросит NotSupportedException раньше, чем что-либо удалит. Встроенный журнал его уже реализует.

Без журнала сервис работает только с рабочей копией. Внешняя правка тогда ведёт себя как любой другой повторяемый запрос. Она применяется, получает 204 и применяется ещё раз, если вы отправите её дважды.

С журналом каждое принятое изменение попадает в журнал раньше, чем о нём узнает кто-либо ещё. Поэтому изменение, дошедшее до вкладки, это изменение, пережившее падение процесса. А правку, которую журнал не может зафиксировать, сервис отклоняет с 503 и никому не передаёт, вместо 204 за сохранение, которого не было.

К хранилищу, которое вы пишете сами, сервис предъявляет строгие требования.

• Нужен один живой писатель на документ.
• Нужно чтение, видящее каждую более раннюю фиксацию.
• Данные должны быть надёжно записаны до возврата из вызова.
• Проверка дубля и присвоение номера идут одним шагом.
• Любая ошибка должна быть брошена наружу, а не проглочена.

Полный список README пакета сервера приводит рядом с рабочей регистрацией.

Регистрация хранилища операций почти необратима, и так с каждым документом. У документа с журналом рабочей копии нет вовсе. Целиковый JSON у вашего эндпоинта обновляется только в трёх случаях: опубликованная контрольная точка, выгрузка комнаты из памяти и остановка с выгрузкой. На каждом окне правок он не обновляется.

Считайте это потолком, а не обещанием. Насколько запись свежа на самом деле, показывает проверка ниже.

Между этими моментами журнал опережает всё остальное, поэтому последние подтверждённые сервисом правки лежат там, куда сборка без вашего хранилища заглянуть не может. Снимите регистрацию хранилища или вернитесь на сборку, у которой его никогда не было, и документ откроется из того, что у него ещё осталось.

• У документа, который был с журналом с самого начала, рабочей копии нет.
  • Он заново загружается с вашего эндпоинта и возвращается в состояние последней принятой эндпоинтом записи.
  • Каждая подтверждённая с тех пор операция остаётся в вашем журнале, и никто её не отдаёт.
• Первое открытие под журналом берёт рабочую копию документа за отправную точку, а затем удаляет её.
• Документ, который работал под --collab-dir или --collab-s3-prefix и с регистрации хранилища ни разу не открывался, до сих пор держит рабочую копию того дня.
  • Непустая рабочая копия побеждает при открытии, и ваш эндпоинт не опрашивается.
  • Такой документ вернётся в состояние на день переключения, без ошибки и без единой строки в логе.

Blok не держит рядом с журналом вторую целиковую копию документа, чтобы возврат был мгновенным. Записью является журнал, а JSON лишь его проекция.

Перед откатом сделайте так.

• Остановите сервис с выгрузкой: она сбрасывает запись каждой открытой комнаты.
  • Самостоятельный хост делает это при штатной остановке.
  • Приложение внутри своего процесса вызывает ICollabRoomManager.DrainAsync.
• Затем проверьте по каждому документу, что последняя принятая эндпоинтом обратная запись несёт Blok-Doc-Sequence, равный durable-through в голове вашего журнала на той же Blok-Doc-Lineage.
  • Всё, чего до него не хватает, откат теряет.
• Каждый документ, которому не хватило, откройте его один раз на новой сборке.
  • Достаточно подключения только на чтение.
  • Потом повторите остановку с выгрузкой и проверку.
  • Загрузка комнаты с журналом помечает запись как должную, а у документа, чей процесс упал с непереданной записью, комнаты для выгрузки просто не было.
• Только после этого запускайте старую сборку, не впуская клиентов, пока это делаете.

Комната, поднятая из рабочей копии, версии документа ещё не знает. Её первая обратная запись уходит без Blok-Doc-Version, поэтому вашему эндпоинту нечем ответить 409. Один символ, набранный одним человеком до того, как ляжет reset, запишет документ дня переключения поверх той записи, которую вы только что проверили.

В конце вызовите по одному POST /sync/{doc}/reset для каждого документа, у которого рабочая копия была ещё до регистрации хранилища. Он опустошает копию, и следующее открытие берёт документ с вашего эндпоинта. Клиентов впускайте после того, как вернётся последний reset, и не раньше.

Дорога вперёд тоже односторонняя. Зарегистрируйте хранилище снова, и при открытии победит журнал, так что всё набранное, пока работала старая сборка, в него не попадёт.

Пока документ открыт для совместного редактирования, побеждает рабочая копия. Изменение, записанное прямо в ваши записи, будет затёрто, как только сервис в следующий раз запишет документ обратно. Поэтому снаружи есть два пути, и для обоих нужен пропуск на запись для этого документа.

Чтобы изменить несколько блоков, вызовите POST /sync/{doc}/edit со списком того, что вставить, обновить или удалить. Так удобно переключить статус из рабочего процесса или заполнить поле фоновой задачей.

• Изменение попадает в документ.
• За мгновения оно появляется у всех во вкладках.
• Оно записывается в ваши записи, как любая другая правка.

Запрос выполняется целиком: если отклонена хотя бы одна его часть, не применяется ничего. Каждой правке нужен ещё и заголовок Blok-Idempotency-Key длиной от 1 до 128 печатных символов ASCII.

• При журнале операций повтор с тем же ключом и тем же запросом возвращает первый результат и не применяет правку заново.
• Использование того же ключа для другой работы возвращает 409.
• Ответ 204 приходит после надёжной фиксации.
  • Он несёт заголовки ответа Blok-Doc-Lineage и Blok-Doc-Sequence.
• Если эта фиксация не может завершиться, сервис возвращает 503 и не передаёт изменение дальше.

Сервис, работающий только с рабочей копией, ключ не дедуплицирует и никогда не отвечает 409 на его повторное использование. Повтор ведёт себя там как обычный повтор запроса, а его ответ 204 по-прежнему запускает существующий путь повторов обратной записи. В любом случае ваши собственные записи отстают на задержку обратной записи.

Правку можно и защитить. Отправьте If-Match: "<lineage>:<sequence>", записав оба значения ровно так, как их печатают эти два заголовка ответа. Тогда правка применится, только пока документ всё ещё в этом состоянии.

• Другое состояние даёт 412, и ничего не применяется. Ответ 412 несёт текущие Blok-Doc-Lineage и Blok-Doc-Sequence, так что можно повторить тот же ключ со свежим тегом.
• Уже зафиксированный ключ по-прежнему возвращает свой первый результат, даже если его тег устарел.
• У сервиса, работающего только с рабочей копией, нет состояния для проверки, поэтому любой If-Match даёт 428, и ничего не применяется.
• Список, *, слабый тег или любая другая форма дают 400.

Чтобы прочитать документ перед правкой, вызовите GET /sync/{doc}/state. Он возвращает живой документ в JSON, включая правки, сделанные мгновение назад, и для него достаточно пропуска на чтение этого документа. При журнале операций он также отправляет Blok-Doc-Lineage, Blok-Doc-Sequence и ETag: "<lineage>:<sequence>" для того самого состояния, которое отражает. Верните этот ETag в If-Match, и правка применится, только если в промежутке ничего не изменилось.

Готовьтесь к двум отказам. Оба дают 422 и ничего не применяют.

• Попытка поместить блок под родителя, у которого нет списка потомков.
• after, которого нет в списке потомков этого родителя.

В ответе названы и шаг, и блок:

• collab: op 0: block "p1" has no children list, so nothing can be placed under it.
• collab: op 0: block "b7" is not in the document order, so nothing can be placed after it.

Вставки применяются одна за другой к документу в его текущем виде. Поэтому две вставки с одним и тем же after окажутся в обратном порядке. Чтобы дописать их по порядку, свяжите их в цепочку, где каждая называет предыдущую.

Чтобы заменить документ целиком, при миграции или исправлении по обращению, сначала сохраните свою версию в собственные записи. Затем вызовите POST /sync/{doc}/reset.

• Сервис выбрасывает рабочую копию.
• Он заново загружает документ из вашего эндпоинта.
• Затем он говорит всем открытым вкладкам отбросить то, что у них было, и взять новую версию.

Никому ничего закрывать не нужно ни в том, ни в другом случае. Редактировать документ, который ни у кого не открыт, тоже можно: сервис загрузит его для этого случая.

Ещё одно закрывает зазор между вашим сохранением и сбросом. Как только ваш эндпоинт ответит версией, каждая обратная запись несёт в заголовке Blok-Doc-Version последнюю, которую он дал. Этот заголовок и есть ваш инструмент оптимистичной блокировки.

Повышайте версию при собственном сохранении и отвечайте на устаревший PUT кодом 409. Сервис считает это неудавшейся обратной записью и повторяет её. Отказ держится, пока сброс не загрузит вашу версию. Так запись, уже ушедшая по проводу в момент вашего сохранения, не ляжет поверх неё.

Ваше приложение определяет права, корзину, восстановление, сроки хранения и окончательное удаление. Blok даёт операции перепроверки доступа, очистки и локального раздела, но не предоставляет UI настроек доступа.

Для отзыва доступа следующие строки C# являются псевдокодом приложения. Внедрите ICollabRoomManager как rooms, а ICollabDocumentPurger как purger. Сначала зафиксируйте права, затем попросите Blok перепроверить активные подключения.

• await host.CommitRevocationAsync(documentId, userId);
• await rooms.RecheckAccessAsync(documentId);

Вкладка с отозванным доступом закрывается с 4403 forbidden. Разрешённые участники остаются подключёнными и могут писать дальше. Новые подключения тоже должны читать уже зафиксированные права. Вызовите RecheckAccessAsync в каждом экземпляре сервиса, обслуживающем документ. Не используйте reset для изменения прав.

Корзина сохраняет ID документа, содержимое, рабочую копию и журнал на срок хранения вашего приложения. Восстановление меняет только состояние и доступ в приложении. Ни одно действие не вызывает очистку.

Для окончательного удаления следующие строки C# являются псевдокодом приложения. Сначала надёжно сохраните запрет на открытие документа, затем очистите данные сервиса.

• await host.CommitPermanentTombstoneAsync(documentId);
• var result = await purger.PurgeDocumentAsync(documentId, token => host.CanPurgeAsync(operatorUser, documentId, token));

После фиксации запрета авторизация приложения и маршрут документов GET/PUT должны отклонять этот ID даже при наличии журнала. Результат DocumentOpenElsewhere означает, что документ открыт в другом экземпляре; закройте там работу и повторите очистку. Частичный сбой закрывает доступ в этом процессе; сохраните запрет в приложении и повторите очистку. После проверки правил отдельно удалите каноническую запись страницы и указатель в родителе. Никогда не используйте повторно непрозрачный ID страницы.

Без журнала остановите работу с документом в каждом экземпляре сервиса и надёжно запретите GET/PUT у маршрута документов. Блокировка только внутри одного процесса не защитит другой экземпляр или перезапуск. Метка удаления в журнале не даст заново загрузить старое содержимое даже при устаревшем ответе GET.

Для выхода или смены аккаунта следующие строки TypeScript являются псевдокодом приложения. Импортируйте inspectOfflineScope и forgetOfflineScope из @bloklabs/core. Функции showDiscardWarning и closeEditorsAndSwitchScope реализует ваше приложение.

• const report = await inspectOfflineScope(oldScope);
• showDiscardWarning(report);
• await closeEditorsAndSwitchScope(oldScope);
• await forgetOfflineScope(oldScope, { discardPending: true });

Проверьте ожидающие отправки правки, пригодные к переносу обновления и карантин до явного удаления всего локального раздела. Сначала закройте или переключите каждую активную вкладку, иначе она создаст раздел снова. Заблокированное или неудачное удаление не является успехом. Уже отключённое от сети устройство нельзя удалить удалённо, пока оно не подключится снова.

Удаление данных сервиса не означает физическое стирание резервных копий, реплик или версий S3. Эти копии покрывает политика хранения вашего приложения.

Сервис обращается к вашему маршруту документов в двух случаях. Он загружает документ, когда его открывают впервые, и записывает изменения обратно, пока люди редактируют.

Если маршрут требует входа, а он должен, положите ожидаемое им значение заголовка в переменную окружения BLOK_DOC_ENDPOINT_AUTH, вместе с Bearer и всем остальным. Сервис отправляет его дословно при каждом вызове. Ваш маршрут, ваша схема авторизации, строить ничего нового не нужно.

Одно правило про само значение: оно должно быть в одну строку. Разрыв строки внутри не даёт сервису запуститься, и он прямо об этом сообщает. Обычная причина, это хвостовой перевод строки от echo или из файла. Заголовок с таким символом просто выпал бы из каждого вызова, и нигде ничего бы не проявилось.

То же значение можно передать флагом --doc-endpoint-auth, но сервис предостерегает от этого: флаг кладёт учётные данные в список процессов машины.

Когда документ открывает первый человек, сервис запрашивает его у вашего маршрута документов. Для документа, который вы ещё ни разу не сохраняли, ответьте 200 с null (или { "data": null }). Это значит «пока ничего», и редактор начнёт с пустого документа.

Ответ 404, 5xx или недоступный маршрут считаются сбоем, а не «новым документом». Редактор показывает уведомление о переподключении, и никто не может начать редактировать.

Пустой документ, посеянный поверх записи, которая просто не загрузилась, позже перезаписал бы её. Это же означает, что опечатка в пути --doc-endpoint громко упадёт при первом открытии, а не тихо опустошит ваши документы.

Сервис записывает поля rich text на ваш эндпоинт документов сегментами. GET /sync/{doc}/state отвечает так же. Раньше data.text был строкой HTML вроде a <b>b</b>. Теперь это список вроде [{ "text": "a " }, { "text": "b", "marks": { "bold": true } }].

• Ваш эндпоинт должен принимать сегменты, когда сервис записывает документ обратно.
• Отдавать HTML он может и дальше. Сервис по-прежнему принимает HTML от вашего эндпоинта и от POST /sync/{doc}/edit, а обратно пишет сегменты.
• Встроенные поля text у paragraph, header, quote, toggle и list всегда rich.

Поля rich text ваших собственных инструментов нужно перечислить. На автономном хосте передайте --rich-text-fields в виде JSON, например {"callout":["title"]}, или задайте BLOK_RICH_TEXT_FIELDS. Внутри приложения тот же список называется options.RichTextFields. Перечислите ровно то, что объявляет richTextFields каждого инструмента на клиенте.

Обновляйте сервис и редактор вместе. Документ, сохранённый старым сервисом, переводится в новый формат при первом открытии. Старый редактор отказывается работать с новым сервисом. Новый редактор так же отказывается работать со старым.

Загруженный файл отдаётся с того имени хоста, на которое вы его положили, а браузер доверяет странице именно по имени хоста. Поэтому, если загруженные файлы отдаются с того же хоста, что и приложение, чужой файл может вести себя как одна из ваших страниц. Он может прочитать сессию авторизованного пользователя и обратиться к вашему API от его имени.

Сервис отправляет Content-Disposition: attachment и X-Content-Type-Options: nosniff, поэтому браузер скачивает такой файл, а не выполняет его. Но полностью вопрос закрывает только вынос загруженных файлов на отдельный хост: uploads.myapp.com или собственный адрес бакета S3.

Пять вещей в редакторе читают уже сохранённый файл обратно.

• Аудиоплеер скачивает дорожку, чтобы нарисовать её волну.
• Блок изображения скачивает GIF, прежде чем превратить его в видео, и SVG, чтобы узнать его настоящий размер.
• Файловый блок скачивает документ, чтобы показать превью.
• Кнопка скачивания картинки берёт саму картинку, чтобы браузер сохранил её, а не открыл.

Как только загруженные файлы отдаются с отдельного хоста, каждый такой запрос становится кросс-доменным. Браузер отклонит его, если в ответе нет Access-Control-Allow-Origin для вашего приложения.

Все они написаны так, чтобы тихо сдаться, а не сломать блок. Поэтому ошибки вы не увидите.

• Плеер останется без волны.
• GIF останется неподвижной картинкой.
• SVG будет неправильного размера.
• Превью так и не появится.
• Скачивание откроет файл вместо сохранения.

Blok нигде не скажет почему. Разрешите origin вашего приложения на бакете или хосте, с которого отдаются файлы.

Загрузка в S3-совместимое хранилище написана и покрыта тестами. Но эти тесты сверяют запрос с нашим собственным прочтением спецификации. На настоящем бакете, в AWS или где-то ещё, она ни разу не запускалась. Прежде чем на неё полагаться, попробуйте на одноразовом бакете.

Если хранилище отклонит запрос, сервис передаст его объяснение как есть. Вы увидите ровно то сообщение, которое прислало само хранилище.

Любой запрос с заголовком Origin должен совпасть с одним из адресов, перечисленных в --allow-origin, и так в любом режиме проверки. В режимах none и proxy запрос без Origin, но помеченный Sec-Fetch-Site: cross-site, тоже отклоняется. Обычный серверный запрос с бэкенда, в котором нет ни того, ни другого заголовка, по-прежнему работает.

Режим ticket всегда требует разрешённый Origin. Предварительные (preflight) запросы подчиняются тому же списку.

POST /upload-by-url требует Content-Type: application/json. Параметры вроде charset=utf-8 допустимы. Другие типы содержимого, включая application/problem+json, получают 415 ещё до того, как сервис пойдёт по ссылке.

Сервис ограничивает, как часто вызывающий может заставить его сходить по ссылке.

• Если --rate-limit не указан, режим ticket разрешает 60 запросов в минуту на вызывающего.
• В остальных случаях лимит равен 0, то есть выключен.
• Любое явно заданное значение должно быть нулём или больше.

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

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

Пропуск всегда говорит, кто им владеет и можно ли ему писать. Для загрузок и превью ссылок сервис читает только это.

Эти маршруты не ограничивают владельца одним документом. Поэтому пропуск, выданный человеку с одной открытой страницей, работает для любой загрузки и любого превью с этой страницы, пока пропуск жив.

Совместное редактирование строже.

• Пропуск для совместного редактирования называет ещё и документ, который можно открыть, и сервис сверяет это имя на входе.
  • Пропуск, который не называет документа или называет другой, разворачивают.
• Он обязан называть и пользователя, потому что лимит подключений и поминутная норма считаются по этому имени.
  • Пропуск для совместного редактирования с пустым пользователем отклоняют, а не сваливают в общую кучу с прочими безымянными.

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

Пропуск для загрузки проверяется на каждом запросе, поэтому ему хватает нескольких минут жизни. Пропуск для совместного редактирования проверяется один раз, в момент открытия соединения, а соединение затем живёт дольше него. Значит, пропуск должен быть жив в моменты подключения и переподключения редактора.

Около 30 минут дают нужный баланс.

• Это достаточно коротко, чтобы утёкший пропуск быстро устарел.
• И достаточно долго, чтобы проснувшийся ноутбук или моргнувшая сеть не падали из-за пропуска, умершего в промежутке.

Отзыв доступа устроен так же. Он срабатывает при следующем переподключении, а не посреди соединения.

В режиме ticket, где браузер приносит пропуск, один человек может держать до восьми открытых подключений совместного редактирования к одному документу. Каждая вкладка считается за одно. Девятое отклоняется с ответом «too many connections» (HTTP 429), пока одно из них не закроется.

Пропуск для совместного редактирования обязан называть пользователя. Пропуск, который никого не называет, разворачивают на входе с ответом «pass names no user» (код закрытия 4401).

За прокси все такие пропуска делили бы один лимит и одно окно частоты. Если сервис работает внутри вашего приложения ASP.NET и ваша проверка входа назвала пользователя, считается именно он.

За вашим приложением или прокси, то есть в режимах none и proxy отдельно запущенного сервиса, лимита нет вовсе. Там никто не называет человека. Все подключения приходят с одного адреса прокси, а общий лимит душил бы всех разом.

Если ограничение там нужно, поставьте его в прокси, где вы уже знаете, кто авторизован.

Лимит выше считает одного человека. Этот потолок считает всех вместе и действует в любом режиме авторизации.

С включённым --collab отдельно запущенный сервис держит не больше 1024 открытых подключений совместного редактирования на процесс. Поэтому поток подключений, которые открыли и просто держат открытыми, не займёт все подключения, какие процесс вообще способен держать. Сервис ведёт этот счёт сам.

Сверх потолка новое подключение отклоняется с ответом «too many connections on this server» (HTTP 503), пока одно из открытых не закроется. Отказ приходит ещё до загрузки документа, поэтому ради подключения, которое всё равно не заработает, у вашего маршрута ничего не запрашивается.

Внутри вашего приложения ASP.NET потолка нет, пока вы не зададите CollabMaxConnections, где 0 означает «без потолка». Ставьте туда то же число, что и в MaxConcurrentUpgradedConnections у Kestrel. Kestrel остаётся страховкой снизу и отказывает позже и менее внятно: он сначала даёт документу загрузиться, а потом отвечает 500.

Пока документ открыт, его рабочую копию держит в памяти ровно один процесс сервиса. Каждое подключение к этому документу должно попадать именно в него.

Два процесса, открывшие один и тот же документ, вели бы каждый свою копию и по очереди затирали бы в хранилище работу друг друга. Поэтому лишние процессы помогают только тогда, когда каждый документ принадлежит одному из них.

Разделить их просто, потому что идентификатор документа стоит прямо в адресе подключения. Маршрутизируйте по идентификатору документа, чтобы каждый запрос с путём /sync/{doc} попадал в один и тот же процесс. Подойдёт любое детерминированное правило, от «идентификаторы с a по m идут в первый процесс» до хеша идентификатора.

• Вызов сброса живёт под тем же путём, поэтому он автоматически приходит в процесс, которому принадлежит документ.
• Каждый процесс несёт свою долю документов со своим потолком подключений.
• Все они могут делить одну папку или бакет хранилища и один эндпоинт документов, потому что никакие два из них никогда не открывают один документ.
• Загрузки и превью ссылок ничего не держат в памяти, поэтому такие запросы могут идти в любой процесс.

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

Сервис не ограничивает, сколько документов один человек держит открытыми. Он не ограничивает, до какого размера может вырасти документ. Он не ограничивает и то, как часто неизвестный id документа заставляет сервис запрашивать исходную версию у вашего маршрута документов.

Это ваши записи и ваши правила. Если такие ограничения нужны, поставьте их в своём бэкенде, там же, где уже живёт проверка прав.

Сервис ограничивает только само соединение, и делает это пятью способами.

• Одно сообщение не больше 1 МиБ. Сообщение крупнее закрывает соединение.
• Браузер может перестать принимать сообщения, например при зависшей вкладке или пропавшей сети.
  • Он закрывается, как только ожидающие его сообщения превысят 8 МиБ.
  • При переподключении он догоняет остальных.
  • Внутри вашего приложения ASP.NET оба числа вместе сдвигает CollabMaxMessageBytes.
• Соединение, которое заваливает сервис, закрывается с ответом «inbound rate exceeded» (код 1008), и редактор переподключается.
  • Заваливает означает больше примерно 50 сообщений в секунду после того, как всплеск в 100 исчерпан.
  • Ещё это значит чаще 60 раз в минуту просить прислать весь документ заново или просить всех присутствующих объявиться заново.
  • И это значит дробить одно сообщение на нелепое число кусков. Норма тут шестнадцать кусков плюс ещё один на каждые 64 байта сообщения. Поэтому поток пустых кусков обрывается на семнадцатом.
• Присутствие считается ещё и в байтах, примерно 128 КиБ в секунду на соединение после всплеска примерно в 512 КиБ.
  • За поток присутствия соединение закрывают точно так же.
  • Внутри вашего приложения ASP.NET эти числа задают CollabInboundFramesPerSecond, CollabInboundBurstFrames, CollabInboundResyncsPerMinute и CollabInboundAwarenessBytesPerSecond.
  • Значение 0 отключает любую из этих скоростей.
• Открытие соединения тратит тот же поминутный бюджет --rate-limit, что и любой другой маршрут.

Кроме этих пяти границ открытое соединение ничем не ограничено. Предел размера сообщения сервис сообщает редактору при подключении. Поэтому редактор сам отказывается отправить слишком большое, а не оказывается за это отключён.

Одно правило про форму, а не про размер. Провод синхронизации двоичный, поэтому текстовое сообщение закрывает соединение с ответом «binary frames only» (код 1003). Редактор Blok таких не шлёт, значит это закрытие означает, что с маршрутом говорит что-то другое.

Сервис проверяет форму того, что присылает пропуск на запись, но не смысл. Из-за этого насквозь проходят три вещи, и о них стоит знать.

• Одинокий суррогат превращается на проводе в U+FFFD. Это половина пары UTF-16, которую при наборе не получить, а скриптом можно. Дальше символ замены читает каждая реплика, включая собственную копию того же браузера после перезагрузки.
• Обновление может ничего не интегрировать, потому что изменения, от которых оно зависит, так и не пришли. Такое обновление не отклоняется. Оно ретранслируется и сохраняется, как любое другое.
  • Снаружи повторная доставка и законно пришедшее не по порядку изменение выглядят одинаково. Поэтому тот, кто шлёт их без конца, растит рабочую копию, пока документ не будет выгружен из памяти, и больше ничто это не ограничивает.
• Всё, что приходит через документ, другой браузер или запрос edit, может поместить блок в контейнер, чей childTools его запрещает. Редактор ставит блок туда, куда говорит документ, и пишет в лог предупреждение с именами потомка и контейнера. Он его не понижает, потому что понижение записалось бы обратно и зациклилось бы с другим участником.

Единственное, что насквозь не проходит, это блок, в котором читающая сторона не может разобраться. Блок, чей id или type не текст, в сохранённый документ не попадает. Не попадает и блок, чей data не набор полей. В лог по каждому уходит предупреждение с его именем.

Значение, вложенное глубже 256 уровней, сохраняется как null. Редактор и сервис поступают здесь совершенно одинаково. Поэтому то, что сохраняет браузер, и то, что сервис записывает в ваши записи, совпадает блок в блок.

Документ открывается только для чтения и остаётся таким, пока не придёт первая синхронизация. Редактор никогда не начинает со своей собственной копии. Два браузера, каждый со своей копией, после синхронизации удвоили бы каждый блок.

Как только первая синхронизация пришла, документ становится редактируемым. Это верно, пока пропуск даёт право на запись и пока ваше приложение само не поставило редактор в режим чтения.

Дальше поведение намеренно несимметрично. Если соединение оборвалось, документ остаётся редактируемым. Набранное копится в этой вкладке. Оно уходит, как только вкладка переподключится. Так туннель или уснувший ноутбук не замораживают страницу под руками.

О каждом шаге редактор сообщает событием collaboration:status. Шаги такие: connecting, connected, offline, пока он продолжает переподключаться, и error. error значит, что он остановился насовсем и сам уже не переподключится.

Событие несёт список присутствующих, поэтому индикатор вы рисуете свой, в том виде, который уже принят в вашем продукте. Blok его за вас не рисует.

Ни одно из этих четырёх состояний не говорит, что работа сохранена. Они описывают сокет, а не очередь за ним. Что именно принято, говорит следующая запись.

Connecting, connected и offline описывают сокет. Ни одно из них не говорит, что работу приняли. То же событие collaboration:status несёт второй блок, который об этом говорит: save.

Его state принимает одно из пяти значений.

• saved значит, что ничего не ждёт.
• pending значит, что правки стоят в очереди в этой вкладке и ещё не подтверждены.
  • Подключённая сессия тоже сообщает pending, потому что поднятый сокет ещё не означает сохранение.
• blocked значит, что локальная очередь сломалась и отправлять больше ничего нельзя, с причиной local-storage-failed.
  • Редактирование останавливается до конца сессии.
• quarantined значит, что правки вынули из очереди и уже никогда не отправят, а quarantinedOperations их считает.
  • При включённой опции офлайна они остаются в копии этого браузера.
  • Без неё остаётся только этот счётчик.
• unavailable значит, что о надёжном сохранении сказать нечего вовсе.
  • Так отвечает сервис без журнала операций, с причиной legacy-protocol, как только он об этом сообщил.

Рядом с состоянием pendingOperations и pendingBytes показывают размер очереди. serverSequence говорит, куда журнал положил последнюю подтверждённую правку. Это десятичная строка, потому что потолок не помещается в число JavaScript.

• Рисуйте connected вместе с pending как «сохраняю», а saved как сохранено.
• Рисуйте quarantined как ошибку, о которой человеку надо сказать.
• Рисуйте unavailable как отсутствие индикатора сохранения, а не как зелёную галочку.

Событие несёт это независимо от того, менялось ли соединение. Состояние сохранения, изменившееся само по себе, публикует событие. Одинаковая нагрузка не публикует ничего. Вскоре после готовности редактора приходит один повтор, поэтому поздно подписавшийся слушатель тоже узнаёт, как обстоят дела.

Одна оговорка про счётчики: локальная очередь, которую вообще не удаётся прочитать, показывает ноль строк. Поэтому ноль при blocked означает «неизвестно», а не «ничего не ждёт».

Граница точная. Правка считается сохранённой, когда сервис зафиксировал её в вашем журнале операций. Эта запись должна вернуться раньше, чем правку покажут кому-то ещё.

• Отправка в сокет это не она.
• Увиденное соседом изменение это не она.
• И обратная запись целикового JSON в ваш маршрут тоже не она: она случается позже и может отвалиться сама по себе.

Поэтому же этот путь нужен и одному человеку. Одиночный редактор, направленный на сервис, получает ту же очередь, тот же журнал и ту же квитанцию, что и десять человек. Индикатор и здесь надо читать из save.

Без журнала операций всё это недоступно. Ни один флаг его не включает, поэтому обычный сервис договаривается о старом протоколе и всю сессию сообщает unavailable.

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

Включённая в редакторе опция офлайна это меняет. Она хранит копию документа в этом браузере. После перезагрузки работа подхватывается и уходит при следующем подключении.

По умолчанию опция выключена. Она записывает содержимое документа в хранилище браузера посетителя. Это решение о ваших данных, а не о редакторе.

Про копию важно знать две вещи.

• До первой удачной синхронизации не сохраняется ничего. Поэтому редактор, который так и не достучался до сервиса, всё равно не может начать со своей собственной копии.
• Копия выбрасывается, как только сервис сообщает, что его история больше не совпадает, например после сброса. Так устаревшую копию невозможно принять за живой документ.

Для включения нужно ещё одно: offlineScope, устойчивый идентификатор того, кто вошёл в систему. Хранилище принадлежит браузеру, а не человеку. Именно этот идентификатор не даёт копии одного человека попасть к другому.

Редактор откажется запускаться, если опция офлайна включена, а offlineScope не задан. Так копии без владельца просто не появится.

Сделайте этот идентификатор непрозрачным и устойчивым: одна и та же строка при каждом входе этого человека и на каждом устройстве. Всё, что меняется, например пропуск или идентификатор сессии, при каждом обновлении страницы заводит новый раздел. Он оставляет позади все прежние копии вместе с офлайновыми правками.

И сама копия не резервная копия. Blok никогда не просит браузер её беречь, поэтому браузер, которому не хватает места, может выбросить её никого не спросив. Очистка данных сайта делает то же самое намеренно.

Если вы не включаете опцию офлайна, совет остаётся прежним. Пока редактор пишет, что он офлайн, оставьте вкладку в покое и дайте ей переподключиться.

Правки в разных блоках сливаются чисто, и правки в разных полях одного блока тоже. Один человек переименовывает заголовок, другой отмечает пункт списка задач: они не сталкиваются, и ничего не теряется.

Внутри одного поля всё грубее. Двое, печатающих в одном абзаце одновременно, не получат переплетения букв. Остаётся то изменение, которое записалось последним, второе пропадает.

Notion ведёт себя так же, как и любой редактор, который синхронизирует поля целиком, а не по символам. Слияние по символам будет в следующей фазе. На практике двое редко печатают в одном предложении сразу, а присутствие как раз и нужно, чтобы это было видно заранее.

Присутствие Blok рисует сам.

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

Когда человек перестаёт двигаться, курсор начинает пульсировать. Наведите на кружок, чтобы увидеть полное имя. На самом курсоре имени нет, поэтому документ с четырьмя людьми не превращается в стену из имён.

И то и другое берётся из отображаемой личности, которую вы передаёте в опции collaboration редактора. Это имя и необязательный цвет для аватара, кружка и курсора этого человека.

Если не передать, человек всё равно появится: он получит космический силуэт (комету, ракету, спутник). Силуэт идёт с подписью на языке читателя. Так никто не остаётся пустым кружком, и двое в одном документе никогда не носят один силуэт.

Это только оформление. Оно не связано с отдельной опцией user, которая проставляет, кто последним правил блок.

Одна отвечает на вопрос «чей это курсор», другая на вопрос «кому засчитать эту правку». Задавайте любую, обе или ни одной.

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

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

А вот форму он проверяет. Сообщение о присутствии, которое браузеры-получатели не смогут разобрать, обрывает им сеанс, поэтому каждое обходится целиком, и состояние каждого человека обязано быть корректным JSON.

• Негодное состояние отбрасывается и попадает в журнал.
• Третье негодное с одного соединения закрывает его с ответом «malformed awareness» (код 1008), и редактор переподключается как обычно.

Чего не проверяют никогда, так это что именно присутствие утверждает. Любой участник, в том числе с пропуском только на чтение, может объявить любое имя и любую позицию. Пропуск защищает содержимое документа: кто может открыть документ и кто может его менять, проверяется на входе.

Присутствие это знак вежливости для людей в комнате, а не проверка личности. Никогда не стройте на нём права доступа или журнал действий.

Документ передаёт присутствие не более чем для 256 человек одновременно. К присутствию относятся аватары и курсор, который показывает, где сейчас печатает каждый.

Сверх этого обновления присутствия отбрасываются, а не передаются дальше, и сервис пишет об этом строку в свой журнал. Это просто отбрасывание: людная комната никому не стоит соединения, в отличие от сообщения о присутствии, которое сервис вообще не может разобрать.

Редактирования это не задевает. Все продолжают печатать, и каждое изменение по-прежнему сливается и доходит до ваших записей как обычно. То есть если документ когда-нибудь станет настолько людным, сломается видимость людей друг для друга, а не их работа.

Это ухудшение только присутствия, а не предел на число тех, кто может править один документ. Настройки для этого числа нет. Оно зафиксировано внутри сервиса.

Идентификатор документа едет в адресе соединения (/sync/{doc}) и внутри пропуска, и они должны совпадать символ в символ. Отсюда главное правило: идентификатор должен быть одним сегментом пути.

Буквы, цифры, дефисы, подчёркивания и точки безопасны. Слэш, даже закодированный, отклоняется на входе с понятным сообщением «document ids must be a single path segment». Он не падает позже как пропуск, который загадочным образом называет другой документ.

Используйте собственные непрозрачные id. Если ваши записи адресуются путями, сопоставьте каждому пути токен на своей стороне и отдавайте редактору токен.

Отдельный хост говорит по обычному HTTP. Он не терминирует TLS и не занимается сертификатами. Развёртывание, смотрящее в интернет, должно стоять за обратным прокси или хостинг-платформой, которая принимает HTTPS и передаёт HTTP по внутреннему или loopback-соединению. Никогда не передавайте пропуск по открытому интернет-трафику.