Repository navigation
feat: expand Collaborative with integrations, extensions and production tooling - #3
Conversation
What: add a deployment guide and preserve existing env files in local setup instructions. Why: operators need a clear path for Compose variants, configuration, backups, and safe upgrades.
What: add a local development map and link it from the contributor guide. Why: new contributors need the correct build, test, and migration entry points.
What: add request, storage, and plugin flow diagrams to the architecture guide. Why: make the Core, UI, Kit, and internal MCP boundaries easier to follow.
What: document package setup, HTTP routes, UI pages, permissions, model handlers, and checks; fix the calculator guide link. Why: give extension authors a working path that follows the current Kit contract.
What: document assistant tools, permissions, model handlers, and the internal MCP request path. Why: clarify which handlers are exposed and how caller access is enforced.
What: link the HTTP reference to SDK setup, pagination, relation writes, errors, and access rules. Why: help API users find the relevant typed client examples and limits.
What: add the Asmblyr wordmark and rewrite the README around current features, setup, architecture, and limits. Why: give visitors a clear entry point while keeping beta and deployment constraints visible.
What: link deployment, development, extension, assistant, and brand pages from the docs home and sidebar. Why: make the new guidance discoverable in the documentation site.
What: add structured bug report and pull request templates. Why: prompt for reproduction, verification, documentation, and safe diagnostic details.
Что сделано: Core теперь всегда возвращает details в JSON-ошибках; SDK сохраняет этот объект в ApiError. Контракт, проверки и HTTP-справка обновлены. Зачем: клиенты могут разбирать ошибки единым способом, сохраняя requestId, без раскрытия внутренних данных.
Что сделано: добавлены типы envelope, presence, record changes, field locks и состояния соединения; типы экспортируются из contracts. Зачем: Core, UI и SDK используют один публичный протокол без расходящихся локальных интерфейсов.
Что сделано: добавлены RealtimeBus, внутрипроцессная и PostgreSQL-реализации, а запись истории публикует минимальные события внутри своей транзакции. Зачем: подписчики разных процессов получают только относящиеся к ним события после commit; значения и закрытые поля записи не попадают в уведомление.
Что сделано: новая additive-миграция хранит временные блокировки по коллекции, записи и полю; Core проверяет права, атомарно выдаёт lease и удаляет истёкшие или освобождённые блокировки. Добавлены unit-проверки маршрутизации и входных данных. Зачем: редакторы видят активную работу друг друга без постоянных locks и без блокировки всей записи.
Что сделано: Core регистрирует SSE-поток и HTTP-операции с блокировками, проверяет права при подключении и доставке, обновляет presence, ограничивает очередь и очищает ресурсы при закрытии. Зачем: live-события доходят до разрешённых подписчиков с безопасной очисткой соединений и leases.
Что сделано: SDK получил connect, scoped subscribe, typed event listeners, состояние соединения и операции с field locks. Реализованы reconnect с backoff/jitter, восстановление подписки, дедупликация и cleanup; добавлены тест и пример. Зачем: приложения могут пользоваться Collaborative Live через публичный SDK без собственной реализации SSE-протокола.
Что сделано: добавлены сценарии двух пользователей для обновления и удаления записи, запрета подписки, конфликтующих и истёкших locks; файлы включены в штатные Core suites. Зачем: поведение и permission boundaries можно проверить на одноразовой PostgreSQL-базе через scripts/test.mjs. В текущей среде база недоступна, поэтому интеграционные сценарии ещё не запускались.
Что сделано: Next.js проксирует SSE и lock-запросы с существующей cookie-сессией; браузер делит одно соединение на scope и обновляет presence по событиям вместо пятисекундного опроса. Зачем: live-присутствие работает с текущей авторизацией UI и не создаёт лишние соединения или polling.
Что сделано: таблица подписывается на свою коллекцию, объединяет близкие сигналы обновления и показывает активных участников. Зачем: пользователи видят сохранённые изменения коллег без ручного обновления страницы и без опроса сервера.
Что сделано: редактор записи отслеживает live-события, показывает состояние соединения и уведомления, получает/продлевает/освобождает locks при фокусе поля и подписывает имена активных редакторов. Добавлены строки локализации. Зачем: коллеги понимают, кто редактирует поле, и замечают чужое сохранение до попытки перезаписать его.
Что сделано: UI использует локальный Geist WOFF2 и включает текст лицензии шрифта. Зачем: production build больше не зависит от доступности Google Fonts в момент сборки.
Что сделано: каталог маршрутов и генератор OpenAPI получили stream/locks с параметрами, ответами и требованиями доступа; опубликованные OpenAPI и список маршрутов пересозданы. Зачем: интеграторы видят точный HTTP-контракт, а документация отражает проверку прав и единый формат ошибок.
Что сделано: README, feature matrix и сайт документации описывают presence, live updates, field locks, conflict flow, reconnect, permissions, SDK и схему архитектуры. Добавлена атрибуция локального шрифта. Зачем: пользователи и разработчики могут запустить и интегрировать функцию, понимая её реальные границы без неподтверждённых обещаний.
Resolve the 7e3df67 merge while preserving the 13 focused Live commits. Keep Core's browser session and credential limits alongside the realtime event bus. Remove Live's obsolete Next.js API proxy routes, route browser SSE and locks directly to Core, and align deployment, SDK and route documentation with the shared /api origin. Add an integration check for cookie authentication and origin enforcement. Verified: build, typecheck, lint, format, docs build, UI unit, SDK tests and Core unit rerun. Core-presence integration requires a local PostgreSQL admin URL unavailable in this environment.
|
Проверил изменения на коммите
Проверки: прошли Тестирование выполнено в отдельной копии с временным локальным PostgreSQL через штатный disposable-DB harness. Полная сборка контейнеров и весь набор тестов в рамках этого ревью не запускались. |
Bring upstream/main through 1e90bed into the Collaborative Live PR branch so PR Asmblyr#3 can merge cleanly. Preserve Live and upstream locale entries, and regenerate the combined 226-route catalog. The three upstream migrations remain unchanged. Verified the merged tree builds before committing; review fixes are kept as separate follow-up changes.
Close registered SSE responses in Fastify preClose so Core shutdown can finish while clients remain connected. Reject streams still opening during shutdown and remove them from the registry on disconnect. Authenticate before parsing the realtime query to preserve the protected-route 401 contract. Send the current presence snapshot after lease renewal so expired participants disappear without a separate leave event. Add integration checks for active-stream shutdown and silent presence expiry; CI runs them through the disposable PostgreSQL harness.
Report form changes synchronously to the editor and recheck them when a background read resolves. Apply a clean snapshot and remount the form in one synchronous commit so input that starts during the request is never discarded. Advance the draft conflict baseline with each accepted snapshot, preventing false ITEM_CHANGED responses after a clean auto-refresh. Preserve an existing baseline on initial load and cover the A-to-B-to-C expectedValues sequence in a unit test.
Document that accepted clean snapshots advance expectedValues, while edits started during a read keep the current form. Explain periodic presence snapshots and SSE draining during Core shutdown so the public behavior matches the review fixes.
Give Core five seconds to drain an active stream on a loaded runner. The unreferenced timeout does not keep the test process alive after shutdown succeeds.
|
Исправил все пять замечаний к |
|
Исправил два оставшихся замечания повторного ревью в 0d73210:
Добавлены три UI regression-теста: поздняя подписка, сброс старого presence после disconnect и освобождение общего потока. SDK-тест проверяет доставку одного и того же reconnect-события обоим видам обработчиков. До исправлений проверки воспроизводили ошибки, после исправлений проходят. Локально прошли 147 UI-тестов, 27 SDK-тестов, сборка пакетов, штатные typecheck/lint/format, проверка типов UI-тестов с ES2022, генерация и проверка документации (226 маршрутов), Полный GitHub CI завершился успешно: verify и container — зелёные. Прошли 501 серверный тест (3 специальных сценария штатно пропущены: отдельный LavinMQ, нагрузочный тест и visual review environment), 147 UI-тестов, 27 SDK-тестов, сборка, проверка пакетов, запуск пары Core/UI-контейнеров и валидация Helm chart. PR слит в |
2 participants
Кратко
Этот PR существенно расширяет текущую beta-версию Collaborative и улучшает готовность проекта к реальному использованию, разработке расширений и self-hosted развёртыванию.
Основной фокус — усиление базовой архитектуры платформы, интеграций, developer experience и документации.
Что изменено
@asmblyr-collaborative/kit, SDK, CLI и публичные контракты.Зачем
Цель изменений — перевести Collaborative из состояния раннего прототипа в более целостную, расширяемую и удобную для разработки beta-платформу.
После этих изменений становится проще:
Дополнительно
PR получился достаточно объёмным и затрагивает несколько связанных частей проекта, однако изменения сохраняют текущую архитектурную концепцию Collaborative и развивают существующую платформу без введения отдельной параллельной модели.
Особенно полезен feedback по архитектуре, API-контрактам и модели расширений / интеграций.