# Realtime Framework: aplikacje bez własnego serwera API

Wspólna baza realtime zamiast brokera kolejek i serwera API. Interfejs zapisuje zadanie, niezależny proces je przejmuje, a wynik sam wraca na ekran.

## W skrócie

- Typ: Własny framework Kol.ski
- Dla kogo: Zespoły budujące panele, formularze i automatyzacje z procesami na własnych maszynach
- Zakres: Model architektury, kontrakty danych, wzorce workerów
- Stan: Używany produkcyjnie, wersja 1.0 kontraktu w przygotowaniu

## Wyzwanie

Panel operacyjny, formularz czy narzędzie audytowe potrzebują trzech rzeczy naraz: interfejsu pokazującego stan na żywo, procesów wykonujących pracę na różnych maszynach i sposobu, żeby jedno rozmawiało z drugim. Klasyczna odpowiedź to serwer API, kolejka z brokerem i kanał websocket: trzy systemy do utrzymania, zanim powstanie pierwsza funkcja.

> Kto to teraz wykonuje i czy jeszcze żyje?

W klasycznym układzie odpowiedź na to pytanie wymaga osobnego monitoringu. Tutaj miała wynikać z samej architektury.

## Rozwiązanie

Cały system opiera się na jednej bazie Firebase Realtime Database z trzema gałęziami. Każdy uczestnik, człowiek w przeglądarce i proces na serwerze, jest aktorem: obserwuje dane, przejmuje pracę i zapisuje wynik.

### Zadania

Interfejs albo automat zapisuje zadanie w gałęzi `queue`. Worker przejmuje je jednym zapisem: pierwszy skuteczny wygrywa, pozostali widzą, że zadanie jest zajęte.

### Stan

Gałąź `data` trzyma aktualny stan, na który patrzą jednocześnie interfejs i procesy. Wynik pojawia się na ekranie bez odpytywania.

### Aktorzy

W gałęzi `actors` każdy proces i każda otwarta karta raportuje tożsamość, wersję, możliwości i sygnał życia. Widać, kto działa i na jakim kodzie.

### Uprawnienia

Każdy worker ma własne poświadczenia i tylko te uprawnienia, których wymaga jego zadanie. Nie ma jednego klucza do wszystkiego.

## Rezultat

| Liczba | Znaczenie |
| --- | --- |
| 3 | gałęzie bazy na cały system: zadania, stan, aktorzy |
| 3 | hosty w pierwszej próbie: serwer, laptop i Raspberry Pi |
| 0 | brokerów kolejek i własnych serwerów API |
| 30 | sekund to najdłuższa przerwa między sygnałami życia procesu |

### Co działa

- Pierwsza próba na trzech hostach: każdy widział pozostałe i wykonał skierowane do niego zadania.
- Panele operacyjne, w których kliknięcie w interfejsie uruchamia pracę na zdalnej maszynie, a postęp widać na żywo.
- Formularze publiczne szyfrujące dane w przeglądarce: do bazy trafia szyfrogram, a worker odszyfrowuje go dopiero przy wykonaniu. Tak działa formularz kontaktowy tej strony.
- Długie zadania analityczne, które publikują postęp częściowy: etap, bieżący element i licznik.
- Wspólny rdzeń workerów: przejmowanie zadań, sygnał życia, raportowanie wersji i wiersz poleceń w jednej bibliotece.

### Przed nami

- Jednolity cykl życia zadania we wszystkich workerach, z ponawianiem i odzyskiwaniem pracy po awarii procesu.
- Archiwum zdarzeń obok bazy realtime, która trzyma stan bieżący, a nie pełną historię.
- Test porównawczy z gotowymi platformami kolejek i przepływów pracy.

Realtime Framework nie zastępuje silników trwałego wykonania, takich jak Temporal. Tam, gdzie długi proces musi zostać odtworzony krok po kroku po awarii, to one są właściwym wyborem.

## Z czego się składa

Części systemu nie rozmawiają ze sobą bezpośrednio. Jedynym punktem styku jest baza i jej kontrakt danych.

| Część | Co robi | Technologia |
| --- | --- | --- |
| Interfejs | Statyczna strona z logowaniem, która czyta stan i zapisuje zadania prosto do bazy | Firebase Hosting, Firebase Auth, JavaScript |
| Baza realtime | Trzy gałęzie i reguły dostępu: jedyne miejsce, przez które przechodzą zadania i wyniki | Firebase Realtime Database, reguły bezpieczeństwa |
| Workery | Osobne procesy na serwerach, maszynach wirtualnych i urządzeniach brzegowych, każdy z własną rolą i poświadczeniami | Go, Python, PM2, systemd |
| Rdzeń | Wspólna biblioteka workerów: kolejka, sygnał życia, wersja, konfiguracja i wiersz poleceń | Go, JSON |

## Wnioski

- Wersja w sygnale życia musi pochodzić z builda. Wpisana ręcznie zestarzała się po cichu i kilka procesów raportowało numer, którego nie miało.
- Przejęcie zadania to zapis, nie zdjęcie z kolejki. Jedno pole statusu zamiast przenoszenia rekordów upraszcza obserwację i szukanie błędów.
- Interfejs jest aktorem, nie klientem. Kiedy karta przeglądarki ma tożsamość i sygnał życia, ludzi i procesy widać w jednym rejestrze.
- Baza realtime to stan, nie archiwum. Historia i audyt wymagają osobnej warstwy, zaplanowanej od początku.

## Budujesz panel albo automatyzację?

Projektujemy aplikacje z podglądem na żywo i procesami na własnych maszynach, bez ciężkiego backendu. Napisz, co chcesz zbudować.

[Porozmawiajmy o projekcie](mailto:hi@kol.ski) · [Zarezerwuj 30 minut](https://calendar.app.google/CJxZPq3FqabCDMS59) · [Projekty](https://kol.ski/pl/projekty)