coschema.
Publiczne repozytorium
Edytor diagramów do pracy w kilka osób naraz, z kursorami na żywo, edycją offline, cofaniem tylko własnych zmian i symulatorem sieci, który sprawdza, że każdy klient kończy z tym samym, poprawnym diagramem.
Dwa edytory obok siebie. Ada przechodzi offline, oboje edytują, łącze wraca i kopie się scalają. Potem kursory na żywo i tryb śledzenia.
Demo otwiera stronę /demo. Pokój działa w twojej przeglądarce, więc nic nie trafia na serwer. Nagranie z repozytorium, bez dźwięku.
Po co to zrobiłem.
Diagramy to moja codzienna praca. Pracuję nad oprogramowaniem, które generuje schematy jednokreskowe stacji elektroenergetycznych wysokiego napięcia: Angular i rysowanie diagramów na froncie, Java i Quarkus za nim. W prawdziwych zespołach kilka osób edytuje ten sam diagram w tym samym czasie.
Chciałem zmierzyć się z trudnymi częściami współpracy: utrzymać poprawny graf, gdy dwie osoby zmieniają go naraz, cofać tylko własne edycje i czysto scalać pracę offline. Edytor da się też obsłużyć klawiaturą i ogłasza czytnikom ekranu zmiany innych osób, bo wspólne płótna rzadko to potrafią.
Sprawdź w demo.
Na stronie demo są dwa edytory, Ada i Bruno, każdy za własnym symulowanym łączem z opóźnieniem, jitterem, utratą pakietów i przełącznikiem offline.
- Praca offline
- Zaznacz „Network offline” u Ady, edytuj po obu stronach i odznacz. Kopie się scalą i skończą identyczne.
- Zła sieć
- Podnieś suwakami opóźnienie, jitter albo utratę pakietów jednego edytora albo wybierz Slow, Lossy lub Chaotic dla obu. „Make a mess” odcina łącza, edytuje te same węzły po obu stronach i po chwili przywraca łącza, więc konflikt jest prawdziwy.
- Cofanie tylko swojego
- Przesuń węzeł u Ady, zmień jego etykietę u Bruna i cofnij u Ady. Wraca pozycja, etykieta zostaje.
- Kursory i śledzenie
- Kliknij odznakę drugiej osoby nad płótnem, żeby śledzić jej widok. Własne przesunięcie widoku kończy śledzenie.
- Klawiatura
- Kliknij węzeł, a potem: N i P chodzą po węzłach, strzałki je przesuwają, Enter edytuje etykietę, a znak zapytania pokazuje wszystkie skróty.
- Eksport
- Przyciski SVG i PNG na pasku narzędzi zapisują cały diagram.
Trzy trudne miejsca.
Każda decyzja ma w repozytorium swój ADR, razem z alternatywami, które przegrały.
Poprawny graf przy odczycie.
Jedna osoba łączy krawędź z węzłem, a druga w tym samym czasie ten węzeł usuwa. Wspólny dokument może trzymać taki niepoprawny stan, a widok pochodny, który nigdy nic nie zapisuje, go ukrywa. Żaden klient niczego nie naprawia, więc nie ma burzy poprawek.
Cena: ukryte krawędzie zostają w dokumencie, dopóki węzeł nie wróci albo ktoś ich nie usunie.
Przegrały naprawy na każdym kliencie (N klientów usuwa tę samą krawędź, a każda naprawa może walczyć z cofaniem) i naprawy tylko na serwerze (serwer staje się drugim autorem dokumentu, a przywrócony węzeł zastałby swoje krawędzie już usunięte).
ADR 0007 na GitHubieCofam tylko swoje.
Każdy klient ma własny menedżer cofania, który śledzi tylko lokalne zmiany, a przeciągnięcie to jeden krok, niezależnie od liczby ruchów wskaźnika. Pozycja i etykieta to osobne klucze, więc cofnięcie mojego przesunięcia nie cofa późniejszej zmiany etykiety kogoś innego.
Cena: jeśli ktoś przesunął ten sam węzeł po mnie, moje cofnięcie nic nie robi, bo moja zmiana została już nadpisana. Test przypina to zachowanie.
Przegrały wspólny stos cofania, który cofa cudzą pracę, i ręcznie pisane operacje odwrotne: więcej kodu i błędy przy współbieżności dokładnie w tych przypadkach, które mają testy.
ADR 0008 na GitHubieSVG zamiast canvasa.
5000 węzłów w SVG przy 60 klatkach na sekundę: jedna transformacja świata, indeks siatki, który daje stabilne okno widoczności, trzy poziomy szczegółów i przegląd całej sceny poniżej powiększenia 0,25. Benchmark powstał pierwszy, a pierwszy renderer go nie przeszedł przy powiększeniu pokazującym całą scenę, więc renderer się zmienił.
Cena: elementów poza oknem nie ma w DOM, więc wyszukiwanie na stronie i tryb przeglądania czytnika ekranu ich nie widzą. Model klawiatury działa na danych, nie na DOM, i przewija do węzła z fokusem.
Przegrały canvas i WebGL, szybsze w dużej skali, ale SVG jest dostępne z natury, z elementami, które przyjmują fokus i ARIA. Przegrało też samo content-visibility, które pomaga w układzie strony, ale nie zmniejsza liczby widoków Angulara.
ADR 0014 na GitHubie
Liczby.
Tylko to, co zmierzyły skrypty z repozytorium.
- 5000
- Przebiegów symulatora zbieżności z różnymi ziarnami, 0 nieudanych, w 90,9 s. Symulowana sieć przeniosła 1 756 564 wiadomości, zgubiła 12 715 i zdublowała 6418. Po uzdrowieniu sieci każdy dokument jest porównywany bajt po bajcie.
- 18 ms
- p95 od puszczenia przycisku u piszącego do zmienionych pikseli u czytającego. Dwa konteksty przeglądarki w jednym pokoju, 200 edycji, magazyn w pamięci. Z PostgreSQL 15 ms. Cel: poniżej 200 ms.
- 60 fps
- Przesuwanie sceny z 5000 węzłów: mediana i najgorszy z trzech przebiegów na każdym z ośmiu poziomów powiększenia, od 1 do 0,05.
- 3987
- Operacji na sekundę, które utrzymał jeden proces Node z PostgreSQL, przy p95 dostarczenia 15,77 ms. Przy 8000 oferowanych p95 przekroczyło 200 ms. To liczby dla jednego procesu.
- 1012
- Testów jednostkowych: 661 w pakietach, serwerze i skryptach i 351 w edytorze. Do tego 40 testów integracyjnych z PostgreSQL i 41 testów Playwright. Pokrycie linii: 98,75% w pakietach i serwerze, 96,85% w edytorze.
- 100
- Dostępność w Lighthouse na /, /r/test i /demo, w ustawieniach desktop i mobile, bez żadnego nieudanego audytu.
Zmierzone na laptopie: Intel Core i7-12700H, 20 rdzeni logicznych, 15,5 GiB RAM, Linux pod WSL2, Node 24.21, headless Chromium 153, PostgreSQL 18.6. Przeglądarka działała na localhoście, więc to liczby dla tej maszyny.
Pliki z wynikami w bench/resultsCzego nie ma.
Z listy dodatków zbudowałem tylko eksport SVG i PNG. Testy nigdy nie wypadały.
- Wersje z przywracaniem
- Dokument Yjs nie ma powrotu do stanu dla wszystkich, więc przywrócenie byłoby różnicą zastosowaną jako nowe edycje. To najtrudniejsza część.
- Komentarze do węzłów
- Druga wspólna struktura, z własnymi regułami poprawności po usunięciu węzła i własnym modelem dostępności.
- Serwis autoryzacji w Quarkusie
- Serwer synchronizacji sprawdza JWT kluczem deweloperskim. Osobny serwis w Javie to praca na całe repozytorium i nie mówi nic nowego o współpracy.
- Uchwyty rozmiaru i punktów krawędzi
- Model danych i symulator już je obsługują. Edytor nie ma uchwytów, którymi można by je przesunąć.
- Kilka serwerów na pokój
- Pokój należy do jednego procesu serwera. Kilka instancji potrzebowałoby kierowania ruchu po pokoju albo warstwy pub/sub.
- Firefox, WebKit i czytnik ekranu
- Testy end to end i liczby z przeglądarki pochodzą z Chromium. Nikt jeszcze nie słuchał edytora z NVDA ani VoiceOver.
Co dalej.
Najpierw warstwa pub/sub, żeby kilka serwerów dzieliło pokoje, potem wersje, potem brakujące uchwyty edycji, a potem testy z NVDA i VoiceOver. W samym edytorze najpierw dodałbym przeciąganie widoczne na żywo: dziś inni widzą skok węzła dopiero, gdy puścisz przycisk.
ADR 0025: czego nie zbudowałemTechnologie
- Angular
- TypeScript
- Signals
- Node.js
- WebSockets
- Docker
- GitHub Actions
- Obsługa klawiaturą
- Zarządzanie fokusem
Artykuł na blogu, po angielsku: How I test that collaborative edits converge
Porozmawiajmy o roli.
Napisz, jaki to zespół, jaki produkt i jaki stack.